03 — Tech Stack
BKA is built on the 4G Web Dev Stack. Everything below is either inherited from 4G, distinct to BKA, or deferred to a later sprint.
What's inherited from 4G (verbatim)
| Concern | Inherited | See |
|---|---|---|
| Runtime | Browser-only, no backend | 4G 00_PHILOSOPHY.md |
| Build | Vite 6.x + TypeScript 5.6.x | 4G 01_TECH_STACK.md |
| UI | React 18 + zustand | 4G 01_TECH_STACK.md |
| Local storage | OPFS-SQLite via @sqlite.org/sqlite-wasm |
4G 04_STORAGE.md |
| Identity | Google Identity Services (browser-only JWT) | 4G 07_AUTH.md |
| Code editor | CodeMirror 6 | 4G 01_TECH_STACK.md |
| Doc conversion | pdfjs-dist + jszip + turndown (lazy-loaded) | 4G 01_TECH_STACK.md |
| Deploy | Cloudflare Pages | 4G 08_BUILD_DEPLOY.md |
| Dep pinning | Exact pins, no ^ or ~ |
feedback memory: pin every dependency |
| Visual register | Custom — see below | (new) |
| Storage pattern | Git tree as canonical (SQLite as cache) | 4G 13_GIT_CANONICAL.md |
| BabyAI integration | Same MoE Space, same client shape | 4G 14_BABYAI_LORAS.md |
The 4G stack is the floor. BKA is one more 4G app. When in doubt, read the 4G doc with the same number first.
What's distinct to BKA
Two-repo content model
Foundry stores in a single browser-resident git tree (via Lightning-FS) backed up to ONE GitHub repo. BKA stores in TWO GitHub repos (private + public) and DOES use the same git-tree-as-canonical pattern (4G doc 13) but per-repo.
Each repo is browser-managed via isomorphic-git + GitHub Contents API + GitHub Releases API.
See 05_TWO_REPO_MODEL.md for the data model.
Creator-owned CF account integration
Foundry's worker proxy uses a single CF account that the operator (us) owns. BKA's per-creator deploy targets each creator's own CF account. This requires:
- Creator-supplied CF API token (during one-time wizard)
- Pages project provisioning via CF API
- (Optional) custom domain binding via CF API
- (Optional) R2 / D1 provisioning if creator opts into comments / subscribers
See 04_CREATOR_ONBOARDING.md for the wizard flow.
Per-creator viewer-template build
Foundry IS the site users interact with. BKA has TWO sites per creator:
- Authoring app — the BKA app the creator opens. Shared across all creators; deployed at our own CF (e.g.,
bka.binary-blender.com). - Viewer site — the creator's published archive. Built from the public repo using a template we provide; deployed at the creator's CF.
The viewer site is itself a 4G app (or a simpler static-only generator if we decide). See 09_VIEWER_TEMPLATE.md.
Discovery indexer
A small Cloudflare Worker we operate, with three concerns:
- Creator registration (which feeds to crawl)
- Crawl scheduler (pull feeds on cadence)
- Discovery API (BabyAI-routed "what should I see next")
This is the only central component. See 07_DISCOVERY_LAYER.md.
Cartoon-industrial visual register?
Per the per-audience-register feedback memory, BKA needs a register distinct from the four already named (dark IDE / light Playground / navy ERP / cartoon-industrial demo). The creator-app register should:
- Feel personal (the creator's space, not a tool)
- Feel warm (creative work, not transactional)
- Be theme-able for the viewer site (creators pick a theme)
Tentative: warm-publication register — paper-cream background, a sans-serif display font, generous typography, one accent color the creator picks. Distinct from the four existing registers; reads as "creator-publishing tool" not "developer IDE" or "factory floor."
To be finalized in a design pass. See 08_AUTHORING_APP.md.
What's reused from agicore-foundry (proven patterns)
BKA inherits substantial patterns from agicore-foundry's implementation:
| Pattern | What it does | Where in foundry |
|---|---|---|
google-auth.ts |
GIS script loader + JWT decode + sign-in/out | src/lib/google-auth.ts |
authStore.ts |
Google user persisted to localStorage | src/store/authStore.ts |
SignInGate.tsx |
Pre-auth wall | src/components/SignInGate.tsx |
UserChip.tsx |
Title-bar identity chip | src/components/UserChip.tsx |
git-store/ |
Browser-resident git ops via isomorphic-git + Lightning-FS | src/lib/git-store/ |
github-sync.ts |
GitHub Git Data API client (push/pull) | src/lib/github-sync.ts |
auto-push.ts |
Debounced background backup | src/lib/auto-push.ts |
doc-edit-stream.ts |
Streaming <edit> / <create_document> tag handler for AI-mediated doc updates |
src/lib/doc-edit-stream.ts |
activeSessionStore.ts |
Cross-app current-session pointer | src/store/activeSessionStore.ts |
chat-send.ts |
Streaming chat call with system prompt + history | src/lib/chat-send.ts |
babyai-client.ts |
Worker-proxied BabyAI calls | src/lib/babyai-client.ts |
Copy verbatim where possible. Only fork when BKA needs different behavior. The principle (per the 4G stack template doc): don't reinvent the auth + storage + chat plumbing.
What's reused from the community pattern (proven shape)
The BKA discovery worker is shaped exactly like the community worker:
- Cloudflare Worker, tiny (~200 lines)
- Origin allowlist gate for write routes
- Google JWT validation via WebCrypto + cached JWKS
- Bot PAT (with limited scope) for any privileged ops
- KV / D1 for tiny structured state
- See
_Dev/community/worker/index.tsfor the template
Reuse the shape; differ in domain (creators + feeds, not threads + comments).
What's reused from novasyn_studio (UI ideas)
Per the v0.1 BKA reference, novasyn_studio has useful UI patterns for chat-with-folders-and-tags. Worth borrowing:
- Folder + tag + search UI for organizing posts
- Side-by-side multi-provider chat for drafting
- Token-budget visualization in the composer
- Keyboard-first shortcuts
We don't take its tech stack (Electron) — only the UI patterns transfer to the 4G browser-first context.
What's borrowed from v0.1 BKA (the rough draft)
The v0.1 BKA at _Dev/novasyn_suite/benders_killer_app/ had:
- ✅ The VISION + BRAND framing (re-used verbatim — see 00_VISION.md)
- ✅ The Cloudflare wizard concept (re-used; rebuilt in browser instead of Tauri)
- ✅ The theme-able viewer site idea (re-used)
- ✅ The post composer with markdown (re-used; uses 4G chat-with-doc pattern instead)
- ❌ Tauri shell (deferred — browser-first; Tauri shell maybe later as 4G stack acquires desktop support)
- ❌ Astro generator (replaced with our own 4G-built viewer template)
- ❌ Custom SQLite schema (replaced with the 4G OPFS-SQLite pattern)
- ❌ R2 + D1 provisioning for posts (we're git-tree-as-canonical instead; R2/D1 only for comments/subscribers if creator opts in)
What's deferred
| Thing | Why deferred | Likely sprint |
|---|---|---|
| Tauri desktop shell | Browser-first ships fastest; Tauri adds packaging complexity | After v1 ships |
| Comments / subscribers | Per-creator R2/D1 provisioning has its own wizard complexity | v1.1 |
| Syndication (X / Bluesky / Mastodon push) | Each target needs its own API client + creator OAuth | v1.2 |
| Email subscriber list / send | Requires SMTP integration (CF Email Routing or external) | v1.2 |
| Multi-author / collaborator support | Single-creator is the v1 scope; multi-author changes the repo model | v2 |
| Analytics (creator-side: who's reading?) | Privacy thinking required; not just a feature add | v2 |
| Migration tools (from existing platforms) | Per-platform; substack/medium importers each need work | v2 |
Pinned dep guide (when scaffolding starts)
Same exact pins as 4G stack + agicore-foundry. Reference _Dev/agicore-foundry/package.json for the canonical set. Notably:
react: 18.3.1
react-dom: 18.3.1
zustand: 4.5.7
vite: 6.4.3
typescript: 5.6.3
@vitejs/plugin-react: 4.7.0
@sqlite.org/sqlite-wasm: 3.53.0-build1
@anthropic-ai/sdk: 0.32.1
isomorphic-git: 1.27.1
@isomorphic-git/lightning-fs: 4.6.0
buffer: 6.0.3
@cloudflare/workers-types: (current)
No ranges. Bump deliberately, not accidentally.