Repository Public
1# Roadmap and status23Status of each phase of the project brief, derived from reading the code — not from test runs, which are reported separately in `docs/TESTING.md`. "Done" means the feature exists in the code and is wired end to end; "partial" means part of it exists; "not done" means it was not found.45The items under each phase are this document's reading of what the phase covers; where the brief asked for something that is not listed here, treat it as not verified.67## Phase 0 — Audit and architecture89| Item | Status | Evidence |10|---|---|---|11| Stack chosen and justified | done | `package.json`; trade-offs in [ARCHITECTURE.md](ARCHITECTURE.md) §7 |12| Module boundaries | done, by convention | directory layout; no lint rule enforces the import direction |13| Data model | done | `db/migrations/001_init.sql` |14| Document schema as the single contract | done | `src/schema/sheet.ts` |15| Architecture, security and operations documentation | done | `docs/` |1617Acceptance: a newcomer can find where each responsibility lives and why each trade-off was made.1819## Phase 1 — Foundation2021| Item | Status | Evidence |22|---|---|---|23| Next.js 16 App Router, React 19, TypeScript strict, Tailwind 4 | done | `package.json`, `tsconfig.json`, `src/app/globals.css` |24| PostgreSQL with checksummed SQL migrations | done | `scripts/migrate.ts` |25| Configuration through environment variables with validation | done | `src/lib/env.ts`, `.env.example` |26| Web process with timeouts and graceful stop | done | `server.ts` |27| Worker process with a persistent queue | done | `src/worker/index.ts`, `generation_jobs`, `export_jobs` |28| Health endpoint | done | `src/app/api/health/route.ts` |29| Structured logs | done for what is logged | JSON lines in the worker and for web start-up and unhandled errors (`web.unhandled`, `api.unhandled`); there is no per-request log (the proxy's access log covers that) |30| Storage abstraction | partial | `Storage` interface with a `local` driver only (`src/server/storage.ts`) |31| Bilingual interface (FR/EN) | done | `src/i18n/`, per-component dictionaries |32| CI pipeline | not done | no `.github/` or other CI configuration in the repository |3334Acceptance: `pnpm migrate && pnpm bootstrap && pnpm build && pnpm start` plus `pnpm worker` give a running site with `/api/health` answering.3536## Phase 2 — Administrator security3738| Item | Status | Evidence |39|---|---|---|40| Passkey-only authentication with user verification | done | `src/lib/auth.ts` |41| Bootstrap by CLI with a one-time link in a 0600 file | done | `scripts/bootstrap.ts` |42| Challenge storage, binding and single use | done | `webauthn_challenges`, `consumeChallenge` |43| Server-side sessions, rotation, revocation, listing | done | `sessions`, `createSession`, settings page |44| CSRF protection on every state change | done | `assertCsrf`, `requireAdmin` |45| Re-authentication for sensitive actions | done | `requireRecentAuth` (passkey add/remove, recovery codes) |46| Recovery codes and limited recovery session | done | `loginWithRecoveryCode` |47| CLI recovery | done | `scripts/setup-token.ts` |48| Rate limits and progressive lock-out | done | `src/lib/ratelimit.ts`, `assertNotLockedOut` |49| Audit trail | done | `audit_events`, audit tab |50| Security headers and CSP | partial | all headers set; CSP keeps `'unsafe-inline'` for scripts and styles (no nonces) |51| Attestation verification | not done | `attestationType: "none"` |52| Multiple users or roles | not done | single administrator; `users.role` is constrained to `admin` |53| Idle session timeout | done | 14 days absolute, 7 days without use (`src/lib/session-store.ts`) |5455Acceptance: no admin route answers without a passkey session; a state change without the CSRF header or from another origin is refused; a lost device can be recovered by code or from the shell.5657## Phase 3 — Real CMS5859| Item | Status | Evidence |60|---|---|---|61| Sheets with working copy, immutable revisions, revert | done | `src/server/sheets.ts` |62| Optimistic locking | done | `sheets.version`, `expectedVersion` |63| Publication as immutable snapshots behind a single pointer | done | `publish`, `sheet_publications` |64| Unpublish, soft delete | done | `unpublish`, `deleteSheet` |65| Statuses draft / in review / published / archived | done as labels | no review workflow attached to `in_review` |66| Scheduled publication | not done | no schedule column, no scheduler |67| Slugs with redirects | done | `slug_redirects` |68| Topics, tags | done | `syncTaxonomy`, topic management in settings |69| French/English linked versions with `hreflang` | done | `sheet_localizations`, sitemap |70| Public site: home, topics, search, sheet page, about | done | `src/app/(site)/` |71| Full-text search, accent-insensitive, FR and EN | done | generated tsvectors, trigram index, `listPublished` |72| SEO: metadata, canonical, JSON-LD, Open Graph image, sitemap, robots, RSS, JSON Feed | done | `src/app/(site)/s/[slug]/`, `sitemap.xml`, `rss.xml`, `/api/public/feed` |73| Sharing image chosen per sheet | partial | `og_asset_id` is accepted by the API and used in metadata; the editor has no field for it |74| Private preview links | done | `preview_tokens`, `/preview/<token>`, images through `/preview/<token>/asset/<id>` |75| Asset library with type sniffing, SVG sanitising, quota, optional antivirus | done | `src/server/assets.ts` |76| S3/MinIO storage driver | not done | interface only; `STORAGE_DRIVER` refuses anything but `local` |77| Datasets from CSV/JSON | done | `datasets`, `parseCsv` |78| Templates: built-in and custom | done | `src/templates/`, `templates` table |79| JSON import and export | done | `POST /api/admin/sheets` with `doc`, `export.json` |80| Privacy-preserving view counter | done | `sheet_views` |81| Public read API | done | `src/lib/api/publicroutes.ts` |82| Dashboard | done | `src/components/admin/pages/dashboard.tsx` |8384Acceptance: a draft is unreachable from every public surface; publishing switches readers atomically; the published version does not change while the draft moves on; an old slug redirects.8586## Phase 4 — Document engine8788| Item | Status | Evidence |89|---|---|---|90| Sheet Document Schema v1, strict, 23 block types | done | `src/schema/sheet.ts` |91| Parsing, migration on read, stable serialisation | done | `src/schema/index.ts` |92| Patch operations and block diff | done | `applyPatch`, `diffSheets` |93| Renderer shared by site, editor, preview and export | done | `src/renderer/SheetView.tsx` |94| Inline syntax without HTML | done | `src/renderer/inline.tsx` |95| Equations with KaTeX | done | `src/renderer/latex.ts`, `math.tsx` |96| Diagram layout engine, routing, groups | done | `src/renderer/diagram/layout.ts` (uses `@dagrejs/dagre`) |97| Charts (line, area, bar, scatter, histogram) | done | `src/renderer/chart/` |98| Themes, tones, fixed formats | done | `src/renderer/sheet.css`, `themes.ts` |99| Quality report gating publication | done | `src/server/quality.ts` |100| Exports: PDF, PNG ×1/×2/×4, per-block SVG, JSON | done | `src/worker/export.ts`, `src/renderer/export-svg.ts` |101| Whole-sheet SVG export | not done | SVG is per vector block; a whole sheet is PDF or PNG |102| PDF of a single block | not offered | refused with `422 whole_sheet_only`; a single block exports as PNG or SVG |103| Cross-block interactions | not done | `interactions` must be empty in v1 |104105Acceptance: any document that validates renders without interpreting markup; the same document yields the same picture on the site and in exports; a document that fails the quality report cannot be published.106107## Phase 5 — Claude studio108109| Item | Status | Evidence |110|---|---|---|111| Server-side Anthropic client, streaming, cancellable | done | `src/ai/client.ts` |112| Model selectable from the live list, default `claude-opus-5-5` | done | `resolveModel`, settings page |113| Effort settings | done | `aiEffortGenerate`, `aiEffortEdit` |114| Server-side refusal fallback where the model supports it | done | `SERVER_FALLBACK` in `client.ts` |115| Brief → outline → generation | done | `runOutline`, `runGenerate`, creation assistant |116| Source material: uploads and links, wrapped as data | done | `extractMaterial` |117| Outbound-request guard | done | `src/ai/net.ts` |118| Output validation with repair rounds | done | `askJson` |119| Normalisation of model output | done | `normalizeModelDoc` |120| Edits as structured patches with scope and locks | done | `runEdit` |121| Translation with skeleton checks | done | `runTranslate`, `sameSkeleton` |122| Reference checks (Crossref, doi.org, URL) | done | `src/ai/sources.ts` |123| Budgets and usage ledger | done | `assertBudget`, `generation_usage` |124| Versioned prompts | done | `PROMPT_VERSION` |125| Idempotent jobs | done | request keys (`ON CONFLICT`), and generation, translation and edit each return the revision already written for the job |126| Cost estimate before generation | partial | heuristic from the outline; `countInputTokens` and `estimateUsd` are unused |127| Web research provider | not done | no search or fetch tool; the model works from supplied material or memory |128| Tool use / agents | not done | by design |129| Automatic publication | not done | by design |130131Acceptance: nothing the model returns reaches the database without passing the schema; every model-supplied reference is "unverified" until checked; a job survives a restart; a budget stops new calls; nothing is published by a job.132133## Phase 6 — Advanced visualisations134135| Item | Status | Evidence |136|---|---|---|137| 13 built-in simulations with a pure, seeded core | done | `src/sim/` |138| Safe expression parser for `function-plot` | done | `src/sim/core/expr.ts` |139| Diagram animation steps with a player | done | `src/renderer/diagram/DiagramBlock.tsx` |140| Diagram zoom, pan, full screen for readers | done | same file |141| Visual diagram editor (pointer, touch and keyboard paths) | done | `src/components/editor/diagram/` |142| Matrices / heat maps, timelines as SVG | done | `src/renderer/blocks/MatrixSvg.tsx`, `TimelineSvg.tsx` |143| Sanitised SVG illustrations | done | `src/renderer/sanitize-svg.ts`, `SvgTree.tsx` |144| Charts from uploaded datasets | done | `datasetRef`, chart form |145| Static rendering of interactive blocks in print mode | done | `mode="print"`, `staticOnly` |146| Reduced-motion support | done | `useReducedMotion`, CSS |147| Author-defined simulations or custom code | not done | by design: documents never carry code |148| Simulation state in exports other than the initial one | not done | exports capture the initial state |149150Acceptance: every number a simulation shows comes from its pure `compute`; the same seed and parameters draw the same picture; no document can supply executable code.151152## Phase 7 — Mobile and editorial finish153154| Item | Status | Evidence |155|---|---|---|156| Responsive sheets through container queries | done | `.sh-frame` in `sheet.css` |157| Phone layout of the public site | done | `src/components/site/chrome.tsx` |158| Phone layout of the studio and the editor (drawers, bottom bars, safe areas) | done | `shell.tsx`, `Editor.tsx`, `DiagramEditor.tsx` |159| Tablet layout of the editor | done | between 768 and 1023 px the block library and the outline are tabs of the right panel |160| 44 px touch targets | done | `btn` utilities, diagram hit-testing |161| Light and dark modes | done | `globals.css`, `ModeToggle` |162| Installable app, offline page | done | `public/manifest.webmanifest`, `public/sw.js` |163| Offline editing | not offered | the service worker never caches pages or API responses |164| Accessibility basics: skip link, labels, focus styles, `alt` enforcement, MathML output | done in code | not audited here |165| French typography in templates | done | `frTypo` in `src/templates` |166| Example banner for unreviewed sheets | done | `metadata.example` |167| Screenshots | partial | the end-to-end run writes screenshots to `e2e/screenshots/` (git-ignored); they are not compared against references (no visual regression) |168| Canvas drag-and-drop, canvas selection of blocks nested in tabs | not done | arrows and the tabs form instead (deletion does work at any depth) |169170Acceptance: a sheet reads top to bottom in document order on a phone without horizontal page scroll; every studio action is reachable on a phone.171172## Phase 8 — Production173174| Item | Status | Evidence |175|---|---|---|176| Encrypted backups with read-back verification, an HMAC per archive checked at restore, and retention | done | `scripts/backup.sh`, `scripts/restore.sh` |177| Restore script and drill procedure | done | `scripts/restore.sh`, [BACKUP_RESTORE.md](BACKUP_RESTORE.md) |178| Off-site backup copy | not done | operator's responsibility; archives are written to a local directory |179| Unit tests | present | `tests/unit/` (results in `docs/TESTING.md`) |180| Integration tests over HTTP with an Anthropic stand-in, restart, secret scan, backup → restore | present | `scripts/test.sh`, `tests/` |181| End-to-end browser tests | present | `scripts/e2e.sh`, `e2e/*.spec.ts`: studio journey (Chromium, virtual authenticator), studio at phone size, public pages in Chromium and WebKit/iPhone (results in `docs/TESTING.md`) |182| CI pipeline | not done | none in the repository |183| Process manager configuration in the repository | not done | examples in [DEPLOYMENT.md](DEPLOYMENT.md) only |184| Docker Compose alternative | written, not run | `infra/` |185| Reverse-proxy examples | written, not run | `infra/Caddyfile.example`, `infra/nginx.conf.example` |186| Error-reporting service (Sentry or similar) | not done | structured logs and the audit table only |187| Metrics endpoint | not done | dashboard tiles and SQL only |188| Operations documentation | done | [OPERATIONS.md](OPERATIONS.md) |189| Lighthouse (mobile, lab data only, production, measured 2026-11-17) | measured | home 100 performance / 96 accessibility / 100 best practices / 100 SEO; a sheet page 100 / 97 / 96 / 100; LCP 0.9–1.3 s, CLS 0 |190| Deployment of this installation | see [DEPLOYMENT.md](DEPLOYMENT.md), "This installation" | filled in by the lead |191192Acceptance: a backup can be restored into an empty database and directory and the application starts on it; a restart loses no session, publication or queued job; no secret appears in the client bundle or the logs.193194## Not implemented195196In one list, for whoever plans the next iteration:1971981. Scheduled publication. Statuses are `draft`, `in_review`, `published`, `archived`; publishing is immediate.1992. S3/MinIO storage driver. The `Storage` interface has four methods; only `local` exists.2003. A web research provider for the model. No search, no fetch tool.2014. Error reporting (Sentry or similar) and a metrics endpoint.2025. A CI pipeline file.2036. Visual regression testing (screenshots are produced by the end-to-end run but not compared).2047. Offline editing.2058. Whole-sheet SVG export; single-block PDF (refused explicitly).2069. Multiple users, roles, review workflow, comments.20710. Attestation verification; nonce-based CSP (the policy keeps `'unsafe-inline'`).20811. Cross-block interactions (`interactions` is reserved).20912. A field in the editor for the sharing image; drag-and-drop reordering; canvas editing of blocks nested in tabs.21013. Pruning of the audit trail, job history and usage ledger.21114. Running more than one worker (a single worker is assumed and stated in the code).21215. Off-site backups and point-in-time recovery.21316. A configurable author or site name: the author is a literal in the schema (`AUTHOR`) and the site name is text in the interface (the host name is no longer hard-coded).21417. A usage ledger that also records calls that did not complete, and a budget check during a call: rows are written for completed calls only, budgets are checked before each call (one call can overshoot), and after a server-side fallback the cost is computed at the final model's rate.21518. Asset deletion that takes old revisions into account.21619. Restricting `/render/<token>` to the worker: it is reachable by anyone holding a valid short-lived token.21720. Treating out-of-range simulation parameters as warnings: the quality report reports them as errors although rendering clamps them.218