SPB Git

Repository Public

ROADMAP.md 15.8 KB

# 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:

  1. Scheduled publication. Statuses are draft, in_review, published, archived; publishing is immediate.
  2. S3/MinIO storage driver. The Storage interface has four methods; only local exists.
  3. A web research provider for the model. No search, no fetch tool.
  4. Error reporting (Sentry or similar) and a metrics endpoint.
  5. A CI pipeline file.
  6. Visual regression testing (screenshots are produced by the end-to-end run but not compared).
  7. Offline editing.
  8. Whole-sheet SVG export; single-block PDF (refused explicitly).
  9. Multiple users, roles, review workflow, comments.
  10. Attestation verification; nonce-based CSP (the policy keeps 'unsafe-inline').
  11. Cross-block interactions (interactions is reserved).
  12. A field in the editor for the sharing image; drag-and-drop reordering; canvas editing of blocks nested in tabs.
  13. Pruning of the audit trail, job history and usage ledger.
  14. Running more than one worker (a single worker is assumed and stated in the code).
  15. Off-site backups and point-in-time recovery.
  16. 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).
  17. 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.
  18. Asset deletion that takes old revisions into account.
  19. Restricting /render/<token> to the worker: it is reachable by anyone holding a valid short-lived token.
  20. Treating out-of-range simulation parameters as warnings: the quality report reports them as errors although rendering clamps them.
Files main
Menu

Theme