tessera-ctl/.planning/ROADMAP.md

Roadmap: Tessera

Overview

Tessera delivers a modular portal platform where tenants activate workflow modules from a marketplace, interact through a configurable dashboard, and optionally use a desktop wrapper. The roadmap builds foundation-first (Docker + DB + shell), layers in authentication and multi-tenancy, establishes the module system with a proof-of-concept module, adds marketplace and portal navigation, delivers the dashboard experience, and wraps up with desktop client and CI/CD integration.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Foundation & Portal Shell - Docker infrastructure, database with RLS, frontend shell with i18n and theming
• Phase 2: Authentication & Multi-Tenancy - User accounts, sessions, RBAC, tenant isolation per request
• Phase 3: Module System & Domaincheck - Module SDK, registry, lazy loading, and first proof-of-concept module
• Phase 4: Marketplace & Portal Navigation - Module catalog, licensing, activation, and sidebar integration
• Phase 5: Dashboard & Calendar - Configurable widget grid with drag-and-drop, core widgets, and calendar integration (completed 2026-06-24)
• Phase 6: Desktop Client & CI/CD - Tauri wrapper for Windows/Linux and automated Gitea integration
• Phase 7: DKV Fleet Module - Automated DKV invoice processing via email monitoring, PDF parsing, and Excel export with driver mapping (completed 2026-06-27)

Phase Details

Phase 1: Foundation & Portal Shell

Goal: Users can access a running portal application with responsive layout, theme switching, and bilingual interface -- the structural frame into which all features will be placed. Mode: mvp Depends on: Nothing (first phase) Requirements: INFRA-01, INFRA-02, INFRA-03, PRTAL-01, PRTAL-04, UI-01, UI-02, UI-03 Success Criteria (what must be TRUE):

1. User can access the portal in a browser served from a Docker Compose stack with PostgreSQL
2. User sees a responsive layout with header (branding area) and sidebar frame that adapts to screen size
3. User can toggle between light and dark theme and the preference persists
4. User can switch between German and English interface language
5. All UI strings are rendered through the i18n framework (no hardcoded text)

Plans: 3 plans Wave 1

• 01-01-PLAN.md -- Walking Skeleton: Monorepo + Docker Compose stack with NestJS, Next.js, PostgreSQL, Traefik

Wave 2 (blocked on Wave 1 completion)

• 01-02-PLAN.md -- Portal Shell: Design tokens, i18n (DE/EN), theme switching, responsive layout with header + sidebar

Wave 3 (blocked on Wave 2 completion)

• 01-03-PLAN.md -- Visual Verification: Human confirms portal appearance and interactions

UI hint: yes

Phase 2: Authentication & Multi-Tenancy

Goal: Users can securely log in, manage accounts, and operate within isolated tenant boundaries -- every request is scoped to the correct tenant with data fully separated at the database level. Mode: mvp Depends on: Phase 1 Requirements: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06, TNNT-01, TNNT-02, TNNT-03 Success Criteria (what must be TRUE):

1. Initial admin account is created automatically from Docker environment variables on first startup
2. Admin can create, edit, and delete user accounts with role assignment (Admin/User)
3. User can log in and log out, with session surviving browser refresh
4. Admin can create and manage tenants, and each user's data is isolated per tenant via RLS
5. Users can be imported from an LDAP/AD directory

Plans: 5 plans

Wave 1

• 02-01-PLAN.md -- Backend Auth Foundation: Prisma schema, RLS migration, JWT Passport auth, admin seed, tenant middleware

Wave 2 (blocked on Wave 1 completion)

• 02-02-PLAN.md -- Frontend Auth & CRUD: Login page, Next.js middleware, user/tenant management UI, auth-wired portal
• 02-03-PLAN.md -- Password Reset & Mail: SUS package verification, MailModule, password reset flow, force-change interceptor

Wave 3 (blocked on Wave 2 completion)

• 02-04-PLAN.md -- LDAP Integration: LDAP sync service, per-tenant config, field mapping, admin UI

Wave 4 (blocked on Wave 3 completion)

• 02-05-PLAN.md -- Visual Verification: Human confirms complete auth and multi-tenancy flow

UI hint: yes

Phase 3: Module System & Domaincheck

Goal: The platform can discover, register, and load modules dynamically -- validated end-to-end by a working Domaincheck module that users can interact with. Mode: mvp Depends on: Phase 2 Requirements: MOD-01, MOD-02, MOD-03, MOD-04, DCHK-01, DCHK-02, DCHK-03 Success Criteria (what must be TRUE):

1. Modules are registered in a database-driven registry with a versioned SDK interface
2. An admin can activate and deactivate a module without restarting the application
3. Module UIs load on demand (lazy loading) -- no bundle bloat from inactive modules
4. User can open the Domaincheck module, enter a domain, and see whether it is registered or available

Plans: 4 plans

Wave 1

• 03-01-PLAN.md -- Module SDK, Prisma Registry, Activation API

Wave 2 (blocked on Wave 1 completion)

• 03-02-PLAN.md -- Domaincheck Module: Backend DNS + Frontend UI
• 03-03-PLAN.md -- Lazy Loading, Category Pages, Expanded Module View

Wave 3 (blocked on Wave 2 completion)

• 03-04-PLAN.md -- Visual Verification: Human confirms module system

UI hint: yes

Phase 4: Marketplace & Portal Navigation

Goal: Users can browse available modules in a categorized marketplace, admins can activate modules per tenant, and activated modules appear in the sidebar for navigation. Mode: mvp Depends on: Phase 3 Requirements: MRKT-01, MRKT-02, MRKT-03, MRKT-04, PRTAL-02, PRTAL-03, PRTAL-05 Success Criteria (what must be TRUE):

1. User can browse a marketplace view showing all available modules with descriptions and categories
2. Admin can activate or deactivate modules for their tenant from the marketplace
3. Only activated modules appear in the left sidebar, grouped by category
4. User can select a module from the sidebar and it opens in the main content area
5. User can search and filter modules in the sidebar

Plans: 4 plans

Wave 1

• 04-01-PLAN.md -- Test infra (Vitest) + marketplace i18n + Marketplace page slice: card grid browse + activate (MRKT-01/02/04)

Wave 2 (blocked on Wave 1 completion)

• 04-02-PLAN.md -- Marketplace refinements: search/category/status filters, deactivation dialog, toast, Super-Admin tenant context, module detail page
• 04-03-PLAN.md -- Sidebar enhancement: Next.js Link + usePathname active state, per-module links, sidebar search, live refresh (PRTAL-02/03/05, MRKT-03)

Wave 3 (blocked on Wave 2 completion)

• 04-04-PLAN.md -- Visual Verification: Human confirms marketplace, activation, tenant context, and sidebar navigation

UI hint: yes

Phase 5: Dashboard & Calendar

Goal: Users have a personal, configurable start page with freely arrangeable widgets -- including clock, search, notes, and calendar with external calendar source integration. Mode: mvp Depends on: Phase 4 Requirements: DASH-01, DASH-02, DASH-03, DASH-04, DASH-05, DASH-06, DASH-07, CAL-01, CAL-02, CAL-03 Success Criteria (what must be TRUE):

1. User sees a configurable dashboard as their start page with a drag-and-drop grid
2. User can add, reposition, and resize widgets (clock, search bar, calendar, notes)
3. Dashboard layout is saved per user and restored on next login
4. User can configure external calendar sources (WebDAV, Exchange, ICS) in settings
5. Calendar widget shows upcoming events from selected calendar sources

Plans: 5 plans

Wave 1

• 05-01-PLAN.md -- Dashboard foundation: Prisma models, CRUD API, grid, edit-mode, clock widget, settings shell, header link, i18n (DASH-01/02/03/07)

Wave 2 (blocked on Wave 1 completion)

• 05-02-PLAN.md -- Search + Notes widgets, widget settings panel, SearchProvider backend (DASH-04/06)

Wave 3 (blocked on Wave 2 completion)

• 05-03-PLAN.md -- Calendar backend: Prisma model, AES-256-GCM crypto, source CRUD, CalDAV/ICS/Exchange providers, DB push (CAL-01/02/03, DASH-05)

Wave 4 (blocked on Wave 3 completion)

• 05-04-PLAN.md -- Calendar frontend: calendar widget, calendar settings page, API client (CAL-01/02/03, DASH-05)

Wave 5 (blocked on Wave 4 completion)

• 05-05-PLAN.md -- Visual Verification: Human confirms dashboard, widgets, calendar, settings

UI hint: yes

Phase 6: Desktop Client & CI/CD

Goal: Users can install and run Tessera as a native desktop application, and the development workflow includes automated version control via Gitea. Mode: mvp Depends on: Phase 5 Requirements: DESK-01, DESK-02, INFRA-04 Success Criteria (what must be TRUE):

1. User can install a Tauri-based desktop app on Windows or Linux
2. Desktop app connects to the existing web backend (no standalone server)
3. Code changes are automatically committed and pushed to Gitea with minimal manual intervention

Plans: 3 plans

Wave 1 (parallel — disjoint files)

• 06-01-PLAN.md -- Desktop foundation: Tauri toolchain, apps/desktop scaffold, URL-loading WebView + first-run server URL setup (DESK-01/02)
• 06-03-PLAN.md -- CI/CD: Gitea remote, act_runner, multi-stage Gitea Actions pipeline (lint+type-check -> tests -> docker build+deploy) (INFRA-04)

Wave 2 (blocked on 06-01)

• 06-02-PLAN.md -- Desktop native: tray + close-to-tray, window-state, autostart, notifications + version check, branded icon, AppImage+NSIS bundles, /health/version API (DESK-01/02)

Phase 7: DKV Fleet Module

Goal: Administrators can automatically process DKV fuel card invoices by monitoring an email inbox, parsing PDF attachments, mapping license plates to drivers, and exporting structured Excel reports via SMTP. Mode: mvp Depends on: Phase 6 Requirements: DKV-01, DKV-02, DKV-03, DKV-04, DKV-05 Success Criteria (what must be TRUE):

1. System automatically detects DKV invoice PDFs from a configured email inbox (IMAP or Exchange)
2. All transactions are parsed per vehicle with: date, service station, km reading, product, quantity, unit, net/gross amounts
3. License plate → driver mapping is importable as CSV and manually editable in the UI
4. Processed data is exported as Excel file and sent to a configurable recipient via SMTP
5. SMTP settings are configurable in general settings (shared with other modules)
6. Module configuration (inbox, sender filter, folder, recipient) is editable in the module settings UI

Plans: 6 plans

Wave 0

• 07-01-PLAN.md -- Backend foundation: deps install, Prisma models, ScheduleModule, crypto export, validated DKV PDF parser (DKV-02)

Wave 1 (blocked on Wave 0 completion)

• 07-02-PLAN.md -- Inbox-access layer: InboxProvider interface, IMAP + Exchange providers, config/vehicle/history DTOs (DKV-01)
• 07-03-PLAN.md -- Export + delivery + SMTP backend: SettingsModule (SMTP CRUD + test), DkvExportService (xlsx + prune), DkvMailService, MailModule DB-SMTP migration (DKV-04/05, D-06)

Wave 2 (blocked on Wave 1 completion)

• 07-04-PLAN.md -- Pipeline integration: DkvService orchestration, dynamic scheduler, DkvController REST, module registry seed, i18n keys (DKV-01/03/04/05)
• 07-05-PLAN.md -- Module frontend: dkv-api client, main page (history + export download + "Jetzt prüfen"), inbox settings form, vehicle CRUD + CSV import (DKV-01/03/04)
• 07-06-PLAN.md -- SMTP settings frontend: settings-api client, SMTP config form + connection test, settings-sidebar "Allgemein" category (DKV-05)

UI hint: yes

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7

Phase	Plans Complete	Status	Completed
1. Foundation & Portal Shell	2/3	In Progress	-
2. Authentication & Multi-Tenancy	2/5	In Progress
3. Module System & Domaincheck	3/4	In Progress
4. Marketplace & Portal Navigation	0/4	Not started	-
5. Dashboard & Calendar	5/5	Complete	2026-06-24
6. Desktop Client & CI/CD	2/3	In Progress
7. DKV Fleet Module	6/6	Complete	2026-06-27