dorfteich/docs/architecture/roadmap.md

Roadmap — epics and milestones

Stories are cut so early milestones yield a running skeleton that every later story builds on, instead of opening all fronts in parallel. Each milestone below becomes a Gitea milestone; each bullet becomes one or more issues (0.5–2 implementer-days each) with the component labels shown.

Component labels: backend, frontend, collab, deployment, auth, plugins, docs, qa.

M0 — Walking skeleton (deployment, backend, frontend)

Goal: empty but deployed. Monorepo scaffold (pnpm, ESLint/Prettier, Vitest, Playwright), NestJS api with /healthz + Prisma + first migration, React SPA shell with routing + i18n scaffold (ADR 0012), Dockerfiles + Compose stack + dev overlay, Gitea Actions pipeline (lint/test/build → images → deploy Test → e2e smoke → promote Int), stage setup on the operator's host (originally the VPS 188.245.116.44; since 2026-07-11 the dedicated server ONE, one.101010.cloud). Exit criterion: a commit to main automatically reaches test.dorfteich.cloud and shows a styled "hello" shell.

M1 — Accounts & authentication (auth, backend, frontend)

Signup with e-mail verification (SMTP + mail outbox), login/logout with sessions, password reset, rate limiting, account settings (display name, locale, password change), registration mode setting, session management UI. Exit: a person can register on Test, verify, log in, reset password — in German and English.

M2 — Ponds & pages, single-user editing (backend, frontend)

Ponds CRUD (personal pond auto-created at signup; shared ponds respecting the additional-ponds quota), pond sidebar with page list + collapse + sort modes, page CRUD with TipTap editor (Yjs document persisted via REST for now — no collab server yet), image paste/upload with quota tracking, link edit/open-in-new-tab UX, page trash, Markdown copy/paste. Exit: a logged-in user manages pages in their pond with a real editor.

M3 — Real-time collaboration & history (collab, frontend, backend)

Hocuspocus server + token issuance, live sync + remote cursors + presence strip, offline (y-indexeddb + PWA shell + reconnect UX + revoked-permission path), update-log persistence/compaction, automatic + named versions, version view/diff/restore. Exit: two browsers edit one page live with visible cursors; offline edits merge; history shows and restores versions.

M4 — Organization & search (backend, frontend)

Hierarchical labels (CRUD, assignment, tree UI), label filter in sidebar, manual page ordering (fractional index, drag-and-drop), wikilinks (autocomplete node, link index, phantom links) + backlinks panel, PostgreSQL FTS behind SearchProvider + search UI with snippets. Exit: pages are organized by labels/hierarchy, [[links]] resolve, search finds only what you may read (verified with M5 in e2e later).

M5 — Permissions & quotas (auth, backend, frontend)

Full grant model (role_grants, resolution in packages/shared, API guards), pond member management UI, label-/page-scope grants + deny, public access (anonymous read routes + public HTML rendering endpoint), effective-permissions inspector, quota ladder (instance/user/pond overrides) + Site Admin quota UI, Site Admin user management. Exit: the vision's role matrix works end to end, including "all-except-label-X" and public read.

M6 — Import, export & attachments (backend, frontend)

Non-image attachments (allowlist, size limits, listing), pandoc sidecar + import .docx/.odt (fixture corpus), export Markdown / .docx / .odt, Gotenberg PDF export with pond fonts, conversion job queue + progress UI. Exit: round-trip a structured Word document per the best-effort fidelity contract; export any page as PDF.

M7 — Plugins (plugins, frontend, backend)

Plugin SDK (manifest schema, postMessage RPC, sandbox host), package validation + install via GUI + directory watcher, instance modes + per-pond activation, capability-scoped plugin API endpoints, reference plugins (section-styles-basic, toc, page-index, mermaid), export fallbacks. Exit: Site Admin uploads a ZIP on Int; a Pond Admin enables it; a mermaid diagram renders in a page and degrades to fallback in PDF.

M8 — Self-hosting & operations (deployment, backend, docs)

First-run setup wizard, legal pages feature (+ dorfteich.online texts), backup sidecar (dump + volume + prune + BASEL mirror + status), restore runbook + drill automation, health/readiness endpoints + Uptime-Kuma monitors, maintenance-job admin panel, self-hosting guide + reference compose, data export (GDPR), release process (semver tags, notes, manual Prod gate). Exit: a stranger can self-host with the guide; Prod go-live checklist is satisfiable; dorfteich.online launches at the end of M8.

M9 — Comments & notifications (backend, frontend)

Page comments (threads, resolve), watches, in-app notification center, e-mail digests via outbox, pond setting "who may comment". Exit: a Reader comments (where allowed), an Editor gets notified.

M10 — UI polish (frontend)

Resizable sidebar, full-width editor pages, icon top bar hosting the page actions and presence strip, plus a round of smaller refinements (footer connection status, dismissable dropdowns, named version contributors, substring search, label creation in the picker). Exit: everyday editing feels tidy on wide screens; all page actions live in the top bar.

M11 — Public API & MCP (backend, frontend, docs)

Nextcloud backup target with in-app restore, personal access tokens, public REST API v1 (hand-maintained OpenAPI, instance + per-pond opt-in), built-in MCP endpoint exposing the same capabilities as tools. Exit: an external tool reads and writes pages with a PAT; an MCP client connects to /api/mcp and edits collab-safely.

M12 — Page hierarchy & knowledge graph (backend, frontend, qa)

Hierarchical page tree (parentId, slugs stay flat), sidebar folder view vs. label view with pond default + per-user override, new pages nest under the open page, drag-and-drop reparenting + "Move to…" dialog, per-case delete semantics (promote children vs. trash subtree) with safe restore, API/MCP parity, pond-wide wikilink graph endpoint and an Obsidian-like knowledge-graph view with a local per-page graph panel (#106–#114). Exit: pages organize as a tree without breaking links, and the pond's wikilink structure is explorable as an interactive graph.

Deliberately unscheduled backlog

OIDC login (ADR 0007), external search engine profile (ADR 0010), plugin network allowlist (ADR 0008), admin approval for signups (ADR 0007), mobile editing, dorfteich.cloud static site (separate mini-project by kickoff decision).