old.cms.fellies.org/TODO.md

CMS Todo And Progress

This file is the single source of truth for roadmap and delivery progress.

Status Legend

• Planned
• [~] Partially done
• Done

Priority Legend

• [P1] Critical path / prerequisite
• [P2] Important but not blocking
• [P3] Nice-to-have / optimization

MVP 0: Foundations

MVP1 Gate: Mandatory Before Feature Work

• [P1] RBAC domain model finalized (roles, permissions, resource scopes)
• [P1] RBAC enforcement at route and action level in admin
• [P1] Permission matrix documented and tested
• [P1] i18n baseline architecture (default locale, supported locales, routing strategy)
• [P1] i18n runtime integration baseline for both apps (locale provider + message loading)
• [P1] Locale persistence and switcher base component (cookie/header + UI)
• [P1] Integrate Better Auth core configuration and session wiring
• [P1] Bootstrap first-run owner account creation via initial registration flow
• [P1] Enforce invariant: exactly one owner user must always exist
• [P1] Create hidden technical support user by default (non-demotable, non-deletable)
• [P1] Admin registration policy control (allow/deny self-registration for admin panel)
• [P1] First-start onboarding route for initial owner creation (/welcome)
• [P1] Split auth entry points (/welcome, /login, /register) with cross-links
• [P2] Support fallback sign-in route (/support/:key) as break-glass access
• [P1] Reusable CRUD base patterns (list/detail/editor/service/repository)
• [P1] Shared CRUD validation strategy (Zod + server-side enforcement)
• [P1] Shared error and audit hooks for CRUD mutations

Admin App

• [P1] Separate Next.js admin app in monorepo
• [P1] App Router + TypeScript + src/ structure
• [P1] Shared DB access via @cms/db
• [P2] Base admin dashboard shell and roadmap page (/todo)
• [P1] Authentication and session model (admin, editor, manager)
• [P1] Protected admin routes and session handling
• [P1] Temporary admin posts CRUD sandbox for baseline functional validation
• [P1] Core admin IA (pages/media/users/commissions/settings)

Public App

• [P1] Separate Next.js public app in monorepo
• [P1] App Router + TypeScript + src/ structure
• [P1] Public app connected to shared data layer
• [P1] Localized route structure and middleware rules
• [P2] Public layout system (header/footer/navigation)
• [P1] Header banner rendering from CMS-managed content
• [P2] Basic SEO defaults (metadata, OG, sitemap, robots)

Testing

• [~] [P1] Testing workstream moved to MVP 3: Testing and Quality and temporarily paused to prioritize feature delivery

Documentation

• [P1] Docs tool baseline added (docs/ via VitePress)
• [P1] RBAC and permission model documentation in docs site
• [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
• [P1] CRUD base patterns documentation and examples
• [P1] Environment and deployment runbook docs (dev/staging/production)
• [P2] API and domain glossary pages
• [P2] Architecture Decision Records (ADR) structure and first ADRs

Delivery Pipeline And Runtime

• [P2] Gitea workflow baseline (.gitea/workflows/ci.yml, .gitea/workflows/deploy.yml, .gitea/workflows/release.yml)
• [P2] Bun-based Dockerfiles for public and admin apps
• [P2] Staging and production docker-compose templates
• [P1] Registry credentials and image push strategy
• [~] [P1] Staging deployment automation against real host
• [~] [P1] Production promotion and rollback procedure

Git Flow And Branching

• [~] [P1] Protect main and staging branches in Gitea
• [P1] Define PR gates: lint + typecheck + unit + e2e list minimum
• [P1] Enforce one todo item per branch naming convention
• [P2] Add PR template requiring linked TODO step
• [P2] Define branch lifecycle for todo/*, refactor/*, and code/*
• [P2] Conventional commit schema documentation (CONTRIBUTING.md)
• [P2] Changelog scaffold and generation scripts (CHANGELOG.md, bun run changelog:*)
• [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch)
• [P1] Source of truth for version (package.json root) and release tagging rules (vX.Y.Z)
• [P1] Build metadata policy for git hash (+sha.<short>) in app runtime footer
• [P1] App footer implementation plan for version + commit hash (admin + web)
• [P2] Automated version injection in CI (stamping build from tag + commit hash)
• [P2] Validation tests for displayed version/hash consistency per deployment
• [P1] Release tagging and changelog publication policy in CI

MVP0 Close-Out Checklist

• [~] [P1] Verify and document protected branch rules in Gitea (main, staging)
• [~] [P1] Run first staging deployment against a real host with deploy workflow and document result
• [P1] Replace release workflow placeholders with real release-notes and rollback execution steps
• [P1] Expose runtime version + short git hash in admin and public app footer
• [P2] Add CI build stamping for version/hash values consumed by app footers
• [P2] Add automated tests validating displayed version/hash format and consistency

MVP 1: Core CMS Business Features

MVP1 Suggested Branch Order

• [P1] todo/mvp1-media-foundation: media model, artwork entity, grouping primitives (gallery/album/category/tag), rendition slots
• [~] [P1] todo/mvp1-media-upload-pipeline: S3/local upload adapter, media processing presets, metadata input flows, admin media CRUD UI
• [~] [P1] todo/mvp1-pages-navigation-builder: page CRUD, navigation tree, reusable page blocks (forms/price cards/gallery embeds)
• [~] [P1] todo/mvp1-commissions-customers: commission request intake + admin CRUD + kanban + customer entity/linking
• [~] [P1] todo/mvp1-announcements-news: announcement management/rendering + news/blog CRUD and public rendering
• [~] [P1] todo/mvp1-public-rendering-integration: public rendering for pages/navigation/media/portfolio/announcements and commissioning entrypoints
• [~] [P1] todo/mvp1-e2e-happy-paths: end-to-end scenarios for page publish, media flow, announcement display, commission flow

Separate Product Ideas Backlog (Non-Blocking)

• [P2] Smart homepage section presets for artists (featured artwork, latest news, open commissions)
• [P2] Portfolio narrative mode (series story + process notes + ordered media sequence)
• [P2] Reusable CTA/form snippets with per-page override tokens
• [P2] Lightweight CRM timeline per customer (requests, replies, outcomes)
• [P3] AI-assisted alt text and metadata suggestion workflow (human approval required)
• [P3] Auto-generated social crops/promo packs from selected artworks

Admin App (Primary Focus)

• [~] [P1] Page management (create/edit/publish/unpublish/schedule)
• [P1] Page builder with reusable content blocks (hero, rich text, gallery, CTA, forms, price cards)
• [~] [P1] Navigation management (menus, nested items, order, visibility)
• [~] [P1] Media library (upload, browse, replace, delete) with media-type classification (artwork, banner, promo, generic, video/gif)
• [P1] Media enrichment metadata (alt text, copyright, author, source, tags, licensing, usage context)
• [P1] Portfolio grouping primitives (galleries, albums, categories, tags) with ordering/visibility controls
• [P1] Artwork refinement fields (medium, dimensions, year, framing, availability, price visibility)
• [P1] Artwork rendition management (thumbnail, card, full, retina/custom sizes)
• [P1] Type-specific processing presets (artwork/banner/promo/video/gif) with validation rules
• [P1] Users management (invite, roles, status)
• [P1] Disable/ban user function and enforcement in auth/session checks
• [~] [P1] Owner/support protection rules in user management actions (cannot delete/demote)
• [~] [P1] Commissions management (request intake, owner, due date, notes, linked customer, linked artworks)
• [~] [P1] Customer records (contact profile, notes, consent flags, recurrence marker)
• [~] [P1] Customer-to-commission linkage and reuse workflow (no re-entry for recurring customers)
• [~] [P1] Kanban workflow for commissions (new, scoped, in-progress, review, done)
• [P1] Header banner management (message, CTA, active window)
• [~] [P1] Announcements management (prominent site notices with schedule, priority, and audience targeting)
• [~] [P2] News/blog editorial workflow (draft/review/publish, authoring metadata)

Public App

• [~] [P1] Dynamic page rendering from CMS page entities
• [~] [P1] Navigation rendering from managed menu structure
• [~] [P1] Media entity rendering with enrichment data
• [~] [P1] Portfolio views (gallery/album/category/tag) for artworks with filter and sort controls
• [~] [P1] Rendition-aware media delivery (thumbnail/card/full) per template slot
• [~] [P1] Translation-ready content model for public entities (pages/news/navigation labels)
• [P2] Artwork views and listing filters
• [~] [P1] Commission request submission flow
• [P1] Header banner render logic and fallbacks
• [P1] Announcement render slots (homepage + optional global/top banner position)

News / Blog (Secondary Track)

• [~] [P1] News/blog content type (editorial content for artist updates and process posts)
• [~] [P1] Admin list/editor for news posts
• [~] [P1] Public news index + detail pages
• [P2] Tag/category and basic archive support

Testing

• [~] [P1] Testing workstream moved to MVP 3: Testing and Quality and temporarily paused to prioritize feature delivery

Code Documentation And Handover

• [P1] Create architecture map per package/app (what exists, why, how to extend) for @cms/db, @cms/content, @cms/crud, @cms/ui, apps/admin, apps/web
• [P1] Add module-level ownership docs for auth, media, pages/navigation, commissions, announcements/news flows
• [P1] Document critical invariants (single owner rule, protected support user, registration policy gates, media storage key contract)
• [P1] Add “request lifecycle” docs for key flows (auth sign-in/up, media upload, page publish, commission status change)
• [P1] Add coding handover playbook: local setup, migration workflow, test strategy, branch/release process, common failure recovery
• [P2] Add code-level diagrams (Mermaid) for service boundaries and data relationships
• [P2] Add route/action inventory for admin and public apps with linked source files

MVP 1.5: MVP1 Refinements (Planned)

Scope

• [P1] Refine and harden all completed MVP1 modules (pages, navigation, media, portfolio, commissions, news)
• [P1] Resolve UX rough edges discovered during MVP1 implementation
• [P1] Improve admin workflows and reduce editor friction for daily use
• [P1] Stabilize public rendering behavior with better fallbacks and consistency

MVP 2: MVP1 Quality Refinements (Planned)

Scope

• [P1] Finish non-blocking enhancements postponed from MVP1 implementation
• [P1] Improve data modeling consistency and migration hygiene for MVP1 modules
• [P1] Consolidate reusable UI and domain primitives introduced during MVP1
• [P1] Address integration debt before moving to larger design/production phases

MVP 3: UX/UI And Theming

MVP3 Suggested Branch Order

• [P1] todo/mvp3-design-tokens-foundation: establish shared design tokens (color, spacing, radius, typography scale, motion) in @cms/ui and app-level theme contracts
• [P1] todo/mvp3-admin-layout-polish: refine admin shell, navigation hierarchy, spacing rhythm, table/form visual consistency, empty/loading/error states
• [P1] todo/mvp3-public-layout-and-templates: define public visual direction (hero/header/footer/content widths), page templates for home/content/news/portfolio
• [P2] todo/mvp3-component-library-pass: align shadcn-based primitives with CMS brand system (buttons, inputs, cards, badges, tabs, dialogs, toasts)
• [P2] todo/mvp3-responsive-and-a11y-pass: mobile/tablet breakpoints, keyboard flow, focus states, contrast checks, reduced-motion support
• [P2] todo/mvp3-visual-regression-baseline: add screenshot baselines for critical admin/public routes to guard layout regressions

Deliverables

• [P1] Admin UI baseline feels production-ready for daily editorial use
• [P1] Public UI baseline is template-ready for artist branding and portfolio storytelling
• [P2] Shared UI primitives are consistent across admin and public apps
• [P2] Core routes have visual-regression coverage for the new layout baseline

MVP 4: Production Readiness

Admin App

• [P1] Audit log for key content operations
• [P2] Revision history for pages/navigation/media metadata
• [P1] Permission matrix refinement with granular scopes
• [P2] Media processing orchestration UI (queue status, retries, processing diagnostics)
• [P2] Automatic color palette extraction from artworks (stored for theming/filtering)
• [P2] Watermark pipeline for artwork renditions with configurable watermark asset/position/opacity
• [P2] Advanced media transforms by type (video transcode profiles, gif optimization, banner safe-area presets)
• [P2] Announcement targeting refinement (locale/segment targeting rules)
• [P2] Customer lifecycle tooling (status stages, communication history, export)
• [P1] Verify email pipeline and operational templates (welcome/verify/resend)
• [P1] Forgot password/reset password pipeline and support tooling
• [P2] GUI page to edit role-permission mappings with safety guardrails
• [P2] Translation management UI for admin (language toggles, key coverage, missing translation markers)
• [P2] Time-boxed support access keys generated by privileged admins; while active, disable direct support-user password login on the regular auth form
• [P2] Keep permanent emergency support key fallback via env (CMS_SUPPORT_LOGIN_KEY)
• [P2] Error boundaries and UX fallback states

Public App

• [P1] Revalidation strategy and cache tuning
• [P2] Performance budget checks (Core Web Vitals)
• [P1] 404/500 content-aware error pages
• [P1] Accessibility review and fixes
• [P2] Theme assistance from extracted artwork palettes (opt-in per page/section)

Platform

• [P1] Bun workspace + Biome + Turbo baseline
• [P1] Prisma + PostgreSQL baseline
• [P1] Monitoring and alerting baseline
• [P1] Backup and migration rollback playbook
• [P2] Release/versioning checklist per environment

Testing

• [~] [P1] Testing workstream moved to MVP 5: Testing and Quality and temporarily paused to prioritize feature delivery

MVP 5: Testing and Quality

Status

• [~] [P1] Temporary freeze for active testing execution in local scripts and CI while MVP feature delivery is prioritized
• [P1] Re-enable root package test scripts (test, test:*) after MVP feature catch-up
• [P1] Re-enable CI quality test gates (unit + integration + e2e) in .gitea/workflows/ci.yml

Baseline And Regression

• [P1] Vitest + Testing Library + MSW baseline
• [P1] Playwright baseline with web/admin projects
• [P1] CI workflow for lint/typecheck/unit/e2e gates
• [P1] Test data strategy (seed fixtures + isolated e2e data)
• [P1] RBAC policy unit tests and permission regression suite
• [P1] i18n unit tests (locale resolution, fallback, message key loading)
• [P1] i18n integration tests (admin/public locale switch and persistence)
• [P1] i18n e2e smoke tests (localized headings/content per route)
• [P1] CRUD contract tests for shared service patterns
• [P1] Unit tests for content schemas and service logic
• [P1] Component tests for admin forms (pages/media/navigation)
• [P1] Integration tests for owner invariant and hidden support-user protection
• [P1] Integration tests for registration allow/deny behavior
• [P1] Integration tests for translated content CRUD and locale-specific validation
• [~] [P1] E2E happy paths: create page, publish, see on public app
• [~] [P1] E2E happy paths: media upload + artwork refinement display
• [~] [P1] E2E happy paths: commissions kanban transitions

Advanced Quality Work

• [P2] Visual regression workflow for critical templates
• [P2] Load/perf tests for key public routes
• [P2] Flake tracking and quarantine policy for e2e
• [P1] Coverage thresholds and enforcement policy
• [P1] Locale matrix regression suite for critical user journeys

Discovery Log

• [2026-02-10] Prisma client must be generated before app/e2e startup to avoid runtime module errors.
• [2026-02-10] bun test conflicts with Playwright-style test files; keep e2e files on *.pw.ts and run e2e via Playwright.
• [2026-02-10] Linux Playwright runtime depends on host packages; browser setup may require playwright install --with-deps.
• [2026-02-10] Next.js 16 deprecates middleware.ts convention in favor of proxy.ts; admin route guard now lives at apps/admin/src/proxy.ts.
• [2026-02-10] server-only imports break Bun CLI scripts; shared auth bootstrap code used by scripts must avoid Next-only runtime markers.
• [2026-02-10] Auth delete-account endpoints now block protected users (support + canonical owner); admin user-management delete/demote guards remain to be implemented.
• [2026-02-10] Public app i18n baseline now uses next-intl with a Zustand-backed language switcher and path-stable routes.
• [2026-02-10] Public baseline locales are now de, en, es, fr; locale enable/disable policy will move to admin settings later.
• [2026-02-10] Shared CRUD base (@cms/crud) is live with validation, not-found errors, and audit hook contracts; only posts are migrated so far.
• [2026-02-10] Admin dashboard includes a temporary posts CRUD sandbox (create/update/delete) to validate the shared CRUD base through the real app UI.
• [2026-02-10] Admin i18n baseline now resolves locale from cookie and loads runtime message dictionaries in root layout; admin locale switcher is active on auth and dashboard views.
• [2026-02-10] Admin self-registration policy is now managed via /settings and persisted in system_setting; env var is fallback/default only.
• [2026-02-10] E2E now runs with deterministic preparation (test:e2e:prepare: generate + migrate deploy + seed) before Playwright execution.
• [2026-02-10] CI quality workflow .gitea/workflows/ci.yml enforces check, typecheck, test, and test:e2e against a PostgreSQL service.
• [2026-02-10] Admin app now uses a shared shell with permission-aware navigation and dedicated IA routes (/pages, /media, /users, /commissions).
• [2026-02-10] Public app now has a shared site layout (banner/header/footer), DB-backed header banner config, and SEO defaults (metadata, robots, sitemap).
• [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes.
• [2026-02-10] i18n conventions are now documented as an engineering standard (docs/product-engineering/i18n-conventions.md).
• [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (ADR 0001).
• [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (VERSIONING.md).
• [2026-02-11] Release workflow now publishes changelog-derived notes to Gitea releases and supports executable production rollback via SSH + compose tag switch.
• [2026-02-11] Branch protection verification checklist is now documented; final UI-level verification remains environment-specific.
• [2026-02-11] Added a staging deployment execution checklist and deployment-record template to capture first real-host rollout evidence.
• [2026-02-11] Artist-focused feature map refined: MVP1 covers portfolio media/domain CRUD + announcements + customer/commission linking; MVP4 covers advanced automation (watermark, palette extraction, media transform pipelines).
• [2026-02-11] gaertan inspiration to reuse: S3 object strategy with signed delivery, commission type/options/extras/custom-input modeling, request-status kanban mapping, and gallery rendition/color extraction patterns.
• [2026-02-11] MVP1 media foundation started: portfolio domain models (MediaAsset, Artwork, galleries/albums/categories/tags, rendition links) plus initial admin /media and /portfolio data views.
• [2026-02-11] prisma migrate dev --name media_foundation can fail when DB endpoint is unreachable; apply this named migration once DATABASE_URL host is reachable again.
• [2026-02-11] MVP1 media foundation now includes baseline create/link workflows in admin (/media, /portfolio), seeded sample portfolio entities, and schema/service test coverage.
• [2026-02-12] MVP1 media upload pipeline started: admin /api/media/upload accepts metadata + file upload with permission checks, stores files via local adapter (.data/media), and persists upload metadata to MediaAsset.
• [2026-02-12] Upload storage is now provider-based (local + s3) via CMS_MEDIA_STORAGE_PROVIDER; admin-side GUI toggle remains a later MVP item.
• [2026-02-12] Media storage keys now use asset-centric layout (tenant/<id>/asset/<assetId>/<fileRole>/<assetId>__<variant>.<ext>) with DB-managed media taxonomy.
• [2026-02-12] Admin media CRUD now includes list-to-detail flow (/media/:id) with metadata edit and delete actions.
• [2026-02-12] MVP1 pages/navigation baseline started: Page, NavigationMenu, and NavigationItem models plus admin CRUD routes (/pages, /pages/:id, /navigation).
• [2026-02-12] Public app now renders CMS-managed navigation (header) and CMS-managed pages by slug (including homepage when home page exists).
• [2026-02-12] Commissions/customer baseline added: admin /commissions now supports customer creation, commission intake, status transitions, and a basic kanban board.
• [2026-02-12] Announcements/news baseline added: admin /announcements + /news management screens and public announcement rendering slots (global_top, homepage).
• [2026-02-12] Public news routes now exist at /news and /news/:slug (detail restricted to published posts).
• [2026-02-12] Added e2e/happy-paths.pw.ts covering admin login, page publish/public rendering, announcement rendering, media upload, and commission status transition.
• [2026-02-12] Expanded unit coverage for content/domain schemas and post service behavior (packages/content/src/domain-schemas.test.ts, packages/db/src/posts.test.ts).
• [2026-02-12] Added auth flow integration tests for /login, /register, /welcome to validate registration allow/deny and owner bootstrap redirects.
• [2026-02-12] Admin settings now manage public header banner (enabled/message/CTA), backed by system_setting and consumed by public layout rendering.
• [2026-02-12] Added owner/support invariant integration tests for auth guards (apps/admin/src/lib/auth/server.test.ts), covering protected-user deletion blocking and one-owner repair/promotion rules.
• [2026-02-12] Started admin form component tests with media upload behavior coverage (apps/admin/src/components/media/media-upload-form.test.tsx).
• [2026-02-12] Added code handover documentation baseline: architecture map, critical invariants, request lifecycles, and onboarding playbook under docs/product-engineering/.
• [2026-02-12] Completed admin form component coverage for pages/navigation/media using isolated form components and tests.
• [2026-02-12] Added page translation CRUD baseline (PageTranslation) with locale validation (de/en/es/fr) and integration coverage for localized read + fallback behavior.
• [2026-02-12] Page editor now supports locale translations in /pages/:id; public page rendering uses locale-aware page lookup with base-content fallback.
• [2026-02-12] Public rendering integration advanced with locale-aware navigation/news translations and a new public commission request entry route (/[locale]/commissions) that creates/reuses customer records and opens a new commission.
• [2026-02-12] Public portfolio baseline added with /{locale}/portfolio and /{locale}/portfolio/{slug}, including published-artwork filters (gallery/album/category/tag), rendition image streaming via web /api/media/file/:id, and media-aware artwork detail rendering.
• [2026-02-12] Public UX pass: commission request flow now reports explicit invalid budget range errors, and header navigation now falls back to localized defaults (home, portfolio, news, commissions) when no CMS menu exists; seed data now creates those default menu entries.
• [2026-02-12] Added e2e/public-rendering.pw.ts web coverage for fallback navigation visibility, portfolio routes, and commission submission validation (invalid budget range + successful submission path).
• [2026-02-12] Testing execution is temporarily paused for delivery velocity: root test scripts are stubbed and CI test steps are disabled; all testing backlog is consolidated under MVP 3: Testing and Quality.

How We Use This File

• Mark completed items by switching [ ] to [x].
• Mark ongoing work by switching [ ] to [~].
• Prefix each task with [P1], [P2], or [P3].
• Add new findings to Discovery Log with date.
• Keep MVP scope changes in this file first, then implement.