02 — Architecture

The four bricks and how they compose. This is the load-bearing diagram for everything else.

The picture

┌─────────────────────────────────────────────────────────────────────┐
│  Creator's machine                                                  │
│                                                                     │
│   ┌────────────────────┐         ┌────────────────────┐             │
│   │  BKA authoring app │  ──→    │  Private GitHub    │             │
│   │  (browser, 4G)     │  reads/ │  repo              │             │
│   │  - composer        │  writes │  - drafts/         │             │
│   │  - media library   │         │  - working state   │             │
│   │  - publish button  │         │  - SQLite mirrors  │             │
│   └──────────┬─────────┘         └────────────────────┘             │
│              │ publish action                                       │
│              ↓                                                      │
│   ┌────────────────────┐         ┌────────────────────┐             │
│   │  Public GitHub     │  ──→    │  GitHub Releases   │             │
│   │  repo (small)      │  push   │  (binary assets:   │             │
│   │  - metadata        │         │   video, audio,    │             │
│   │  - feed.json       │         │   large images)    │             │
│   │  - asset URLs      │         └────────────────────┘             │
│   └──────────┬─────────┘                                            │
│              │ push triggers                                        │
│              ↓                                                      │
│   ┌────────────────────────────────────────────┐                    │
│   │  Cloudflare Pages (creator's own account)  │                    │
│   │  - viewer-template build                   │                    │
│   │  - serves /feed.json + posts + media URLs  │                    │
│   │  - custom domain bound here                │                    │
│   └────────────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────────────┘
                                  ↑
                                  │ visitors browse
                                  │ + indexer pulls /feed.json on cadence
                                  ↓
            ┌─────────────────────────────────────────────────┐
            │  BKA indexer (one tiny Cloudflare Worker — the  │
            │  ONLY central thing in the whole architecture)  │
            │  - pulls registered creator feeds on a cadence  │
            │  - holds metadata only (titles, summaries,      │
            │    tags, sub-IDs, feed URLs) — never content    │
            │  - serves /api/discover queries via BabyAI      │
            │    specialist LoRAs (content / taste / fresh)   │
            │  - never proxies content; only points at it     │
            └─────────────────────────────────────────────────┘

The creator's machine has full sovereignty. The indexer is the smallest possible bridge so creators can be found without being enrolled. Visitors hit creators directly; the indexer is consulted only for "what should I see next."

The four bricks

Each brick was independently proven in the binary-blender app stack before being composed here.

Brick 1: Per-creator content storage (GitHub repos)

• Each creator gets two repos in their own GitHub account:
  • <user>-bka-private (private) — the working DB
  • <user>-bka-public (public) — the published archive
• The BKA app reads/writes the private repo freely. The public repo only receives commits from the publish action.
• GitHub Releases on the public repo hold binary assets (video, audio, large images). Public repo body stays small + fast.

Reference proof: Foundry/community use the same PUT /repos/.../contents/... flow. Andon-loop-demo proves the per-app-repo pattern. See 05_TWO_REPO_MODEL.md for specifics.

Brick 2: Per-creator content serving (Cloudflare Pages)

• Each creator's public repo connects to a Cloudflare Pages project in their own CF account.
• Push to public repo → CF Pages builds the viewer-template against the metadata → site updates.
• Custom domain optional (*.pages.dev works free; creators with their own domain bind it via CF dashboard).
• Static assets served from CF's edge cache. HTTP range requests for media work natively — no streaming server.

Reference proof: All binary-blender apps deploy this way. The viewer-template itself is a 4G-stack-built static SPA.

Brick 3: Portable identity (Google SSO)

• Google Identity Services across all binary-blender apps including BKA.
• The same Google JWT works in BKA (for indexer registration / cross-creator interactions) as in Foundry / Community.
• The creator's audience doesn't need Google — they subscribe via email or RSS without authentication.

Reference proof: Community worker validates Google JWT against Google's public certs for issue/comment attribution. Same code reused here.

Brick 4: Cross-creator discovery (BabyAI federated indexer)

• ONE central Cloudflare Worker — the indexer.
• Pulls registered creators' /feed.json on a cadence (federation pattern, pull not push).
• Holds metadata only: titles, summaries, tags, sub-IDs, feed URLs. Never content body or media.
• Discovery queries (/api/discover) route to BabyAI specialist LoRAs (content-matching, taste-matching, freshness).
• Creators register their feed by making one API call from BKA after first publish. They can unregister at any time.

Reference proof: The community worker's shape (Google JWT gate + bot PAT + small route surface) is the template. The "metadata only" constraint is the unique BKA extension.

See 07_DISCOVERY_LAYER.md for full detail.

What lives where

The footprint we own is intentionally tiny: indexer, BabyAI. Everything else is creator-owned.

The publish lifecycle (one happy-path walkthrough)

1. Creator opens BKA. Already signed into Google. Already has private + public repos provisioned (one-time wizard).
2. Composer: writes a post in markdown. Saves periodically to private repo via Contents API.
3. Adds a video. BKA uploads the video to GitHub Releases on the public repo (via Releases API), gets back a release-asset URL.
4. Clicks Publish. BKA:
   • Generates a small metadata file (posts/<slug>.json or similar) for the public repo
   • Commits it to public via Contents API
   • Regenerates /feed.json to include the new post
   • Commits feed.json update
5. Cloudflare Pages auto-builds (git integration). 30-60 seconds later, the post is live on the creator's site.
6. Optionally: BKA pings the indexer with "I just published, please re-pull my feed soon" (the indexer would have pulled within its normal cadence anyway).
7. Visitors land via direct URL, RSS, indexer discovery, or syndication.

The creator's only manual step is "write the post and click Publish." Everything else is automated.

Why this composes cleanly

The four bricks are independently swappable:

• Storage could swap to GitLab / Codeberg / Gitea with the same two-repo pattern
• Serving could swap to Netlify / Vercel / their own static host
• Identity could swap to a different OAuth provider
• Discovery could swap to a different indexer or be omitted entirely

Each creator can choose their substrate independently of other creators. The federation discipline doesn't require every creator to use the exact same setup — just to expose a /feed.json the indexer can pull.

This is what "YOU are the platform" looks like when you take it seriously.