stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity
0629411966
dorfteich/docs/architecture/roadmap.md
Claude Fable 5 0629411966 Add architecture documentation, ADRs, and operations concept 
Initial deliverable of the architecture phase: 16 ADRs (stack, CRDT
collaboration, plugin sandbox, import/export, backups, CI/CD), data
model, permission model, real-time collaboration and plugin concepts,
deployment/operations/security documentation, and the milestone roadmap
that the implementation issues are derived from.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-04 14:36:16 +02:00

5.2 KiB
Raw Blame History

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 LEISINGER. Exit criterion: a commit to main automatically reaches dorfteich-test.101010.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.

Deliberately after M9 (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).