Architecture¶

FreeDocStore is a small set of independent surfaces around one contract: GitHub is the source of truth, static builds are the publication artifact.

Topology¶

                        ┌──────────────────────────────┐
                        │  KB repo (one per KB)        │
                        │  FreeDocStore/<kb-id>        │
                        │  docs/*.md + zensical.toml   │
                        └────────────┬─────────────────┘
              push to main           │
                                     ▼
                        GitHub Actions (deploy.yml)
                        zensical build --strict
                        + source metadata injection
                                     │
                                     ▼
                        Cloudflare Pages project <kb-id>
                        https://<kb-id>.pages.dev/
                                     ▲
   registry.json lists every KB     │ reads
                                     │
  ┌──────────────┐   ┌──────────────┴───┐   ┌───────────────────┐
  │ Product site │   │ MCP worker       │   │ Chrome extension  │
  │ freedocstore │   │ mcp.freedocstore │   │ (side panel on    │
  │ .online      │   │ .online/mcp      │   │ published pages)  │
  └──────────────┘   └──────────────────┘   └───────────────────┘
  ┌──────────────┐   ┌──────────────────┐
  │ Console app  │──▶│ API worker       │──▶ GitHub API / OpenAI (BYOK)
  │ console.*    │   │ api.freedocstore │
  └──────────────┘   └──────────────────┘

Components¶

Component	Source	Deployment
Product site	`site/` in the platform repo	Cloudflare Pages at `freedocstore.online`; also serves `registry.json`
Creator console	`apps/editor/` (React)	Cloudflare Pages at `console.freedocstore.online`
API worker	`workers/api/`	Cloudflare Worker at `api.freedocstore.online`
MCP worker	`workers/mcp/`	Cloudflare Worker at `mcp.freedocstore.online`
Chrome extension	`extension/`	Chrome Web Store (MV3, side panel)
Templates	`templates/`	Copied into KB repos (deploy workflow, section generators)
KB repos	one repo per KB under the `FreeDocStore` org	GitHub Actions → per-KB Cloudflare Pages project

Data stores¶

FDS_API_KV — per-user console workspace state (KB drafts, active KB, settings) and encrypted BYOK secrets. Shared by the API worker and the MCP worker, so MCP tools can see the same workspace the console shows.
OAUTH_KV — OAuth request state and token grants for the MCP worker's OAuth 2.1 provider.
Registry — site/registry.json in the platform repo, served from the product site. The platform repo stores registry metadata only; no KB content lives in the platform repo.

Principles¶

GitHub is the source of truth; every published page traces back to a Markdown file in a KB repo.
Static builds are the publication artifact; there is no server-side rendering of KB content.
Each KB gets its own Cloudflare Pages project and can attach custom domains.
MCP exposes read/search/propose tools first; write tools operate as the signed-in GitHub user, never as a shared bot.
Private KB features belong to ProDocStore, not FreeDocStore.