Documentation Architecture & Contribution

Documentation Architecture & Contribution

This site (github-docs) is the unified public portal aggregating documentation, API specifications, and architecture guides across the ALNEAS ecosystem (eaos-workspace, tools, and web-framework).

How It Works

flowchart TD
    subgraph Upstream["Upstream Repositories"]
        SRC["TypeScript Source Code<br/>(English JSDocs)"]
        GUIDES["Markdown Guides<br/>(docs/**/*.md)"]
        MANIFEST["docs.manifest.json"]
    end

    subgraph Pipeline["Ingestion & Translation"]
        INGEST["scripts/ingest.ts<br/>(Manifest Inporter & Link Rewriter)"]
        DOCGEN["scripts/docgen.ts<br/>(Swagger-Style Card Generator)"]
        TRANSLATE["scripts/translate.ts<br/>(AI CLI: agy / codex / claude)"]
        DICT["src/data/translations/api-ja.json"]
    end

    subgraph PublicSite["Cloudflare Pages (Global Edge)"]
        EN["English Root Docs (/)"]
        JA["Japanese Docs (/ja/)"]
        EDGE["Edge Cache & _redirects"]
    end

    GUIDES --> MANIFEST --> INGEST --> EN
    SRC --> DOCGEN --> EN
    DOCGEN --> DICT --> TRANSLATE --> JA
    EN --> EDGE
    JA --> EDGE

---

Key Design Principles

1. Source of Truth (SSOT) Stays in Owning Projects

• We never write or edit technical documentation directly in generated output folders.
• Each owning project maintains its own canonical technical documentation.
• github-docs acts as a one-way aggregation hub.

2. Diátaxis Architecture

Every document belongs to one of four archetypes:

• Tutorials: Beginner-focused onboarding from 0 to 1.
• How-To Guides: Practical recipes for accomplishing specific tasks.
• Reference: Machine-precise API specifications and options (Swagger/Card format).
• Explanation: Architectural rationale, design choices, and boundaries.

3. Graceful Bilingual Parity

• English First: External contributors can contribute using English alone.
• Zero Broken Builds: Missing Japanese translations gracefully fall back to English without throwing errors.
• AI CLI Translation: Maintainers run bun run translate locally with their preferred engine (antigravity, codex, or claude) to populate Japanese mirrors.

---

Deployment Architecture: Cloudflare Pages Git Integration

This documentation portal uses Cloudflare Pages Direct Git Integration connected directly to the private GitHub repository (dataarthub/docs).

1. Automatic Builds on Commit to main

• Every commit or push to the main branch triggers an immediate, zero-config build on Cloudflare’s global edge infrastructure.
• Build Command: bun install && bun run build
• Build Output Directory: dist
• Node Runtime: Specified via .node-version (Node 24).
• GitHub Actions workflows are completely bypassed, eliminating CI minute consumption and keeping the build pipeline unified.

2. Dual Deployment Strategy (Public Showcase & Internal Portal)

The same private repository deploys to two separate Cloudflare Pages projects:

Project Target	URL / Domain	Build Configuration	Security & Access
Public Showcase	https://docs-d1x.pages.dev	bun install && bun run build (No INTERNAL env var)	Completely Public Static assets served with unlimited free bandwidth. Internal runbooks are physically excluded from the generated HTML.
Internal Portal	https://internal.alneas.org (or private Pages URL)	bun install && bun run build Environment Variable: INTERNAL=true	Zero Trust Protected (Cloudflare Access) Full superset containing public docs plus confidential operational receipts (/internal/*). Requires corporate email/SSO authentication.

---

Connecting a Project to github-docs

To register a new package or project, place a docs.manifest.json in your repository root:

{
  "$schema": "https://alneas.github.io/schemas/docs-manifest.v1.json",
  "projectId": "my-project",
  "displayName": "My New Project",
  "documents": [
    {
      "title": "Getting Started",
      "slug": "getting-started",
      "source": "docs/getting-started.md",
      "sourceJa": "docs/getting-started.ja.md",
      "archetype": "how-to"
    }
  ]
}

Verify your manifest locally before pushing:

bun --cwd ../github-docs ingest --verify --project=./docs.manifest.json