canon architecture
A knowledge site for every product repo. You build it on your machine from the repos beside canon, then upload it to Vercel behind a sign-in. One small function finds passages for a question; no AI model is called. Canon Cloud (accounts, a database) is written but not deployed.
last verified 2026-10-30
Known cost a month
Not read
No Vercel, GitHub or Neon bill is recorded anywhere in the repo.
AI cost today
$0
The answer function returns found passages and text: null. Claude writing answers is task T018, not built.
Spaces shown
17
Product repos found beside canon at the last sync.
How it fits together
Pick something a user does to see its path and what it costs.
Not read
runs on your machine; the Vercel upload is the paid part
- pnpm build reads every product repo beside canon and copies README, wiki, features and ideas as Markdown. raw/ is never copied.
- For each repo it runs canon check and canon pipeline, then gh for open PRs and flow numbers. A gh failure only warns. A canon failure with no output stops the build.
- Next.js exports the site; Pagefind builds search; the answer function is bundled with all the docs' text.
- It deploys to production first (use --preview to stop earlier).
- Then it asks every URL as a visitor with no login. Only 401, 302, 303 or 307 pass.
Cost
Every number says where it came from.
| Service | Pays for | Today | Grows with | Basis |
|---|---|---|---|---|
| Product repos | Each repo's README, wiki, features and ideas, read from disk | $0 | Nothing | In codepackages/site/src/sync.ts, PUBLISHED list |
| Build and release | pnpm release: sync, static export, search index, upload | $0 beyond your own machine | Repos and pages: the export is 261 MB on disk | Measureddu of apps/web/out, 2026-10-30 |
| canon CLI (npm) | Runs canon check and canon pipeline for every repo during the sync | $0 | Nothing | StatedREADME.md, the CLI is free |
| GitHub | Open pull requests and flow numbers through gh; later the GitHub App and sign-in | Not read | One gh call per repo per build, up to 50 PRs each | Not known |
| Static site | Prebuilt pages, search and raw Markdown, behind Vercel sign-in | Not read | Pages uploaded and visits; plan not recorded | Not known |
| GitHub Actions | On every PR and push to main: canon check, lint, typecheck, tests, with a Postgres 17 service | $0 net in Oct 2026; $3.10 of included usage across this account | Pushes and pull requests | Measuredgh api billing usage, 2026-10-30 |
| Canon Cloud server | Sign-in, workspaces, GitHub sync. Written, not deployed | $0 until deployed | Editors and synced repos | Stated.context/tasks.md, T026 is waiting |
| Neon Postgres | Cloud's database: access, an index of main, drafts and comments. Chosen, not set up | Not read | Workspaces, pages, comments | Not known |
What breaks when something fails
| If this fails | The user sees | Their data | Basis |
|---|---|---|---|
| Product repos | A repo with no .context/README.md still shows, as an empty space with a warning. | Safe, in git | In codepackages/site/src/sync.ts, run() |
| Build and release | No new release. The last one stays live. | Safe | In codescripts/release.mjs |
| canon CLI (npm) | The build stops. If canon fails and prints nothing for one repo, the whole sync throws. | Safe | In codepackages/site/src/sync.ts, canonJson() |
| GitHub | The site builds with no open PRs for that repo and prints a warning. | Safe | In codepackages/site/src/sync.ts, openPullRequests() |
| Static site | Nobody can read the site. The repos are untouched. | Safe, a copy of the Markdown only | AssumedThe site is a built copy; no test or incident names this |
| Answer function | The answer fails with a message that search still works. Bad input gets a 400, a body over 4096 bytes is refused. | Safe, the question is not stored | In codeapps/web/src/server/answer-handler.ts |
| GitHub Actions | No checks run. Nothing here blocks a release; release.mjs does not wait for CI. | Safe | In code.github/workflows/ci.yml; scripts/release.mjs |
| Canon Cloud server | Not live, so nobody uses it yet. If GitHub /user fails at sign-in, sign-in still works and the login is recorded next time. | Not applicable yet | In codeapps/web/src/server/auth.ts, recordGithubLogin() |
| Neon Postgres | Not written down. | The page index can be rebuilt from GitHub. Drafts, comments and the audit log cannot. | Stated.context/wiki/decisions/schema.md |
Where the data goes
| Wiki, features, ideas and README of every product repo | Copied to src-data/generated, then uploaded to Vercel, behind sign-in. Private product text is on Vercel. |
| raw/ folders (verdicts, research) | Never copied. Only wiki, features, ideas and README are. |
| Who edited each page, and when | Read from git, shown in the site |
| Open PR titles and authors | Read through gh at build time, shown in the site |
| A reader's question | Sent to the answer function; not stored by its code |
| Doc bodies, comments, drafts in Cloud | Neon Postgres. The repo stays the source for docs. |
What we do not know yet
- Hosting is being migrated (owner, 2026-10-30): Cloud is moving from Vercel to Cloud Run with Neon, in wiki/decisions/stack.md and ops/deploy-cloud.md. Costs here are before the move.
- The real monthly bill: no Vercel or Neon cost is recorded (GitHub Actions was $0 net for October 2026), and the Vercel plan is not written down.
- CI does not gate the release: pnpm release builds and deploys without waiting for GitHub Actions.
- Neon and Vercel prices for Cloud are not recorded, so Cloud's cost to run is not known.
- How many times the site has been released, and what each upload cost, is not logged.