Roadmap and status
Status 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.
The 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.
Phase 0 — Audit and architecture
| Item | Status | Evidence |
|---|---|---|
| Stack chosen and justified | done | package.json; trade-offs in ARCHITECTURE.md §7 |
| Module boundaries | done, by convention | directory layout; no lint rule enforces the import direction |
| Data model | done | db/migrations/001_init.sql |
| Document schema as the single contract | done | src/schema/sheet.ts |
| Architecture, security and operations documentation | done | docs/ |
Acceptance: a newcomer can find where each responsibility lives and why each trade-off was made.
Phase 1 — Foundation
| Item | Status | Evidence |
|---|---|---|
| Next.js 16 App Router, React 19, TypeScript strict, Tailwind 4 | done | package.json, tsconfig.json, src/app/globals.css |
| PostgreSQL with checksummed SQL migrations | done | scripts/migrate.ts |
| Configuration through environment variables with validation | done | src/lib/env.ts, .env.example |
| Web process with timeouts and graceful stop | done | server.ts |
| Worker process with a persistent queue | done | src/worker/index.ts, generation_jobs, export_jobs |
| Health endpoint | done | src/app/api/health/route.ts |
| 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) |
| Storage abstraction | partial | Storage interface with a local driver only (src/server/storage.ts) |
| Bilingual interface (FR/EN) | done | src/i18n/, per-component dictionaries |
| CI pipeline | not done | no .github/ or other CI configuration in the repository |
Acceptance: pnpm migrate && pnpm bootstrap && pnpm build && pnpm start plus pnpm worker give a running site with /api/health answering.
Phase 2 — Administrator security
| Item | Status | Evidence |
|---|---|---|
| Passkey-only authentication with user verification | done | src/lib/auth.ts |
| Bootstrap by CLI with a one-time link in a 0600 file | done | scripts/bootstrap.ts |
| Challenge storage, binding and single use | done | webauthn_challenges, consumeChallenge |
| Server-side sessions, rotation, revocation, listing | done | sessions, createSession, settings page |
| CSRF protection on every state change | done | assertCsrf, requireAdmin |
| Re-authentication for sensitive actions | done | requireRecentAuth (passkey add/remove, recovery codes) |
| Recovery codes and limited recovery session | done | loginWithRecoveryCode |
| CLI recovery | done | scripts/setup-token.ts |
| Rate limits and progressive lock-out | done | src/lib/ratelimit.ts, assertNotLockedOut |
| Audit trail | done | audit_events, audit tab |
| Security headers and CSP | partial | all headers set; CSP keeps 'unsafe-inline' for scripts and styles (no nonces) |
| Attestation verification | not done | attestationType: "none" |
| Multiple users or roles | not done | single administrator; users.role is constrained to admin |
| Idle session timeout | done | 14 days absolute, 7 days without use (src/lib/session-store.ts) |
Acceptance: 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.
Phase 3 — Real CMS
| Item | Status | Evidence |
|---|---|---|
| Sheets with working copy, immutable revisions, revert | done | src/server/sheets.ts |
| Optimistic locking | done | sheets.version, expectedVersion |
| Publication as immutable snapshots behind a single pointer | done | publish, sheet_publications |
| Unpublish, soft delete | done | unpublish, deleteSheet |
| Statuses draft / in review / published / archived | done as labels | no review workflow attached to in_review |
| Scheduled publication | not done | no schedule column, no scheduler |
| Slugs with redirects | done | slug_redirects |
| Topics, tags | done | syncTaxonomy, topic management in settings |
French/English linked versions with hreflang |
done | sheet_localizations, sitemap |
| Public site: home, topics, search, sheet page, about | done | src/app/(site)/ |
| Full-text search, accent-insensitive, FR and EN | done | generated tsvectors, trigram index, listPublished |
| 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 |
| 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 |
| Private preview links | done | preview_tokens, /preview/<token>, images through /preview/<token>/asset/<id> |
| Asset library with type sniffing, SVG sanitising, quota, optional antivirus | done | src/server/assets.ts |
| S3/MinIO storage driver | not done | interface only; STORAGE_DRIVER refuses anything but local |
| Datasets from CSV/JSON | done | datasets, parseCsv |
| Templates: built-in and custom | done | src/templates/, templates table |
| JSON import and export | done | POST /api/admin/sheets with doc, export.json |
| Privacy-preserving view counter | done | sheet_views |
| Public read API | done | src/lib/api/publicroutes.ts |
| Dashboard | done | src/components/admin/pages/dashboard.tsx |
Acceptance: 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.
Phase 4 — Document engine
| Item | Status | Evidence |
|---|---|---|
| Sheet Document Schema v1, strict, 23 block types | done | src/schema/sheet.ts |
| Parsing, migration on read, stable serialisation | done | src/schema/index.ts |
| Patch operations and block diff | done | applyPatch, diffSheets |
| Renderer shared by site, editor, preview and export | done | src/renderer/SheetView.tsx |
| Inline syntax without HTML | done | src/renderer/inline.tsx |
| Equations with KaTeX | done | src/renderer/latex.ts, math.tsx |
| Diagram layout engine, routing, groups | done | src/renderer/diagram/layout.ts (uses @dagrejs/dagre) |
| Charts (line, area, bar, scatter, histogram) | done | src/renderer/chart/ |
| Themes, tones, fixed formats | done | src/renderer/sheet.css, themes.ts |
| Quality report gating publication | done | src/server/quality.ts |
| Exports: PDF, PNG ×1/×2/×4, per-block SVG, JSON | done | src/worker/export.ts, src/renderer/export-svg.ts |
| Whole-sheet SVG export | not done | SVG is per vector block; a whole sheet is PDF or PNG |
| PDF of a single block | not offered | refused with 422 whole_sheet_only; a single block exports as PNG or SVG |
| Cross-block interactions | not done | interactions must be empty in v1 |
Acceptance: 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.
Phase 5 — Claude studio
| Item | Status | Evidence |
|---|---|---|
| Server-side Anthropic client, streaming, cancellable | done | src/ai/client.ts |
Model selectable from the live list, default claude-opus-5-5 |
done | resolveModel, settings page |
| Effort settings | done | aiEffortGenerate, aiEffortEdit |
| Server-side refusal fallback where the model supports it | done | SERVER_FALLBACK in client.ts |
| Brief → outline → generation | done | runOutline, runGenerate, creation assistant |
| Source material: uploads and links, wrapped as data | done | extractMaterial |
| Outbound-request guard | done | src/ai/net.ts |
| Output validation with repair rounds | done | askJson |
| Normalisation of model output | done | normalizeModelDoc |
| Edits as structured patches with scope and locks | done | runEdit |
| Translation with skeleton checks | done | runTranslate, sameSkeleton |
| Reference checks (Crossref, doi.org, URL) | done | src/ai/sources.ts |
| Budgets and usage ledger | done | assertBudget, generation_usage |
| Versioned prompts | done | PROMPT_VERSION |
| Idempotent jobs | done | request keys (ON CONFLICT), and generation, translation and edit each return the revision already written for the job |
| Cost estimate before generation | partial | heuristic from the outline; countInputTokens and estimateUsd are unused |
| Web research provider | not done | no search or fetch tool; the model works from supplied material or memory |
| Tool use / agents | not done | by design |
| Automatic publication | not done | by design |
Acceptance: 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.
Phase 6 — Advanced visualisations
| Item | Status | Evidence |
|---|---|---|
| 13 built-in simulations with a pure, seeded core | done | src/sim/ |
Safe expression parser for function-plot |
done | src/sim/core/expr.ts |
| Diagram animation steps with a player | done | src/renderer/diagram/DiagramBlock.tsx |
| Diagram zoom, pan, full screen for readers | done | same file |
| Visual diagram editor (pointer, touch and keyboard paths) | done | src/components/editor/diagram/ |
| Matrices / heat maps, timelines as SVG | done | src/renderer/blocks/MatrixSvg.tsx, TimelineSvg.tsx |
| Sanitised SVG illustrations | done | src/renderer/sanitize-svg.ts, SvgTree.tsx |
| Charts from uploaded datasets | done | datasetRef, chart form |
| Static rendering of interactive blocks in print mode | done | mode="print", staticOnly |
| Reduced-motion support | done | useReducedMotion, CSS |
| Author-defined simulations or custom code | not done | by design: documents never carry code |
| Simulation state in exports other than the initial one | not done | exports capture the initial state |
Acceptance: 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.
Phase 7 — Mobile and editorial finish
| Item | Status | Evidence |
|---|---|---|
| Responsive sheets through container queries | done | .sh-frame in sheet.css |
| Phone layout of the public site | done | src/components/site/chrome.tsx |
| Phone layout of the studio and the editor (drawers, bottom bars, safe areas) | done | shell.tsx, Editor.tsx, DiagramEditor.tsx |
| Tablet layout of the editor | done | between 768 and 1023 px the block library and the outline are tabs of the right panel |
| 44 px touch targets | done | btn utilities, diagram hit-testing |
| Light and dark modes | done | globals.css, ModeToggle |
| Installable app, offline page | done | public/manifest.webmanifest, public/sw.js |
| Offline editing | not offered | the service worker never caches pages or API responses |
Accessibility basics: skip link, labels, focus styles, alt enforcement, MathML output |
done in code | not audited here |
| French typography in templates | done | frTypo in src/templates |
| Example banner for unreviewed sheets | done | metadata.example |
| Screenshots | partial | the end-to-end run writes screenshots to e2e/screenshots/ (git-ignored); they are not compared against references (no visual regression) |
| 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) |
Acceptance: a sheet reads top to bottom in document order on a phone without horizontal page scroll; every studio action is reachable on a phone.
Phase 8 — Production
| Item | Status | Evidence |
|---|---|---|
| Encrypted backups with read-back verification, an HMAC per archive checked at restore, and retention | done | scripts/backup.sh, scripts/restore.sh |
| Restore script and drill procedure | done | scripts/restore.sh, BACKUP_RESTORE.md |
| Off-site backup copy | not done | operator's responsibility; archives are written to a local directory |
| Unit tests | present | tests/unit/ (results in docs/TESTING.md) |
| Integration tests over HTTP with an Anthropic stand-in, restart, secret scan, backup → restore | present | scripts/test.sh, tests/ |
| 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) |
| CI pipeline | not done | none in the repository |
| Process manager configuration in the repository | not done | examples in DEPLOYMENT.md only |
| Docker Compose alternative | written, not run | infra/ |
| Reverse-proxy examples | written, not run | infra/Caddyfile.example, infra/nginx.conf.example |
| Error-reporting service (Sentry or similar) | not done | structured logs and the audit table only |
| Metrics endpoint | not done | dashboard tiles and SQL only |
| Operations documentation | done | OPERATIONS.md |
| 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 |
| Deployment of this installation | see DEPLOYMENT.md, "This installation" | filled in by the lead |
Acceptance: 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.
Not implemented
In one list, for whoever plans the next iteration:
- Scheduled publication. Statuses are
draft,in_review,published,archived; publishing is immediate. - S3/MinIO storage driver. The
Storageinterface has four methods; onlylocalexists. - A web research provider for the model. No search, no fetch tool.
- Error reporting (Sentry or similar) and a metrics endpoint.
- A CI pipeline file.
- Visual regression testing (screenshots are produced by the end-to-end run but not compared).
- Offline editing.
- Whole-sheet SVG export; single-block PDF (refused explicitly).
- Multiple users, roles, review workflow, comments.
- Attestation verification; nonce-based CSP (the policy keeps
'unsafe-inline'). - Cross-block interactions (
interactionsis reserved). - A field in the editor for the sharing image; drag-and-drop reordering; canvas editing of blocks nested in tabs.
- Pruning of the audit trail, job history and usage ledger.
- Running more than one worker (a single worker is assumed and stated in the code).
- Off-site backups and point-in-time recovery.
- 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). - 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.
- Asset deletion that takes old revisions into account.
- Restricting
/render/<token>to the worker: it is reachable by anyone holding a valid short-lived token. - Treating out-of-range simulation parameters as warnings: the quality report reports them as errors although rendering clamps them.