From 4a71f1f774e22ced95c5271f9663acf47ee08dd6 Mon Sep 17 00:00:00 2001 From: Schalli Date: Thu, 18 Jun 2026 08:45:41 +0200 Subject: [PATCH] docs: create roadmap (6 phases) --- .planning/REQUIREMENTS.md | 53 +++++++++- .planning/ROADMAP.md | 115 ++++++++++++++++++++ .planning/STATE.md | 79 ++++++++++++++ CLAUDE.md | 213 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 455 insertions(+), 5 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md create mode 100644 CLAUDE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 2858b07..a5e6f1c 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -125,13 +125,56 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| (populated by roadmapper) | | | +| AUTH-01 | Phase 2 | Pending | +| AUTH-02 | Phase 2 | Pending | +| AUTH-03 | Phase 2 | Pending | +| AUTH-04 | Phase 2 | Pending | +| AUTH-05 | Phase 2 | Pending | +| AUTH-06 | Phase 2 | Pending | +| TNNT-01 | Phase 2 | Pending | +| TNNT-02 | Phase 2 | Pending | +| TNNT-03 | Phase 2 | Pending | +| PRTAL-01 | Phase 1 | Pending | +| PRTAL-02 | Phase 4 | Pending | +| PRTAL-03 | Phase 4 | Pending | +| PRTAL-04 | Phase 1 | Pending | +| PRTAL-05 | Phase 4 | Pending | +| MRKT-01 | Phase 4 | Pending | +| MRKT-02 | Phase 4 | Pending | +| MRKT-03 | Phase 4 | Pending | +| MRKT-04 | Phase 4 | Pending | +| DASH-01 | Phase 5 | Pending | +| DASH-02 | Phase 5 | Pending | +| DASH-03 | Phase 5 | Pending | +| DASH-04 | Phase 5 | Pending | +| DASH-05 | Phase 5 | Pending | +| DASH-06 | Phase 5 | Pending | +| DASH-07 | Phase 5 | Pending | +| CAL-01 | Phase 5 | Pending | +| CAL-02 | Phase 5 | Pending | +| CAL-03 | Phase 5 | Pending | +| MOD-01 | Phase 3 | Pending | +| MOD-02 | Phase 3 | Pending | +| MOD-03 | Phase 3 | Pending | +| MOD-04 | Phase 3 | Pending | +| DCHK-01 | Phase 3 | Pending | +| DCHK-02 | Phase 3 | Pending | +| DCHK-03 | Phase 3 | Pending | +| UI-01 | Phase 1 | Pending | +| UI-02 | Phase 1 | Pending | +| UI-03 | Phase 1 | Pending | +| INFRA-01 | Phase 1 | Pending | +| INFRA-02 | Phase 1 | Pending | +| INFRA-03 | Phase 1 | Pending | +| INFRA-04 | Phase 6 | Pending | +| DESK-01 | Phase 6 | Pending | +| DESK-02 | Phase 6 | Pending | **Coverage:** -- v1 requirements: 33 total -- Mapped to phases: 0 -- Unmapped: 33 +- v1 requirements: 44 total +- Mapped to phases: 44 +- Unmapped: 0 --- *Requirements defined: 2026-06-18* -*Last updated: 2026-06-18 after initial definition* +*Last updated: 2026-06-18 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..59a7058 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,115 @@ +# 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 +- [ ] **Phase 6: Desktop Client & CI/CD** - Tauri wrapper for Windows/Linux and automated Gitea integration + +## 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**: TBD +**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**: TBD + +### 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**: TBD +**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**: TBD +**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**: TBD +**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**: TBD + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation & Portal Shell | 0/TBD | Not started | - | +| 2. Authentication & Multi-Tenancy | 0/TBD | Not started | - | +| 3. Module System & Domaincheck | 0/TBD | Not started | - | +| 4. Marketplace & Portal Navigation | 0/TBD | Not started | - | +| 5. Dashboard & Calendar | 0/TBD | Not started | - | +| 6. Desktop Client & CI/CD | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..5d123fa --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,79 @@ +--- +gsd_state_version: '1.0' +status: planning +progress: + total_phases: 6 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 + percent: 0 +--- + +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-06-18) + +**Core value:** Eine zentrale Plattform, in der beliebige Workflow-Tools als Module lizenziert, aktiviert und genutzt werden koennen -- ohne zwischen verschiedenen Anwendungen wechseln zu muessen. +**Current focus:** Phase 1 - Foundation & Portal Shell + +## Current Position + +Phase: 1 of 6 (Foundation & Portal Shell) +Plan: 0 of TBD in current phase +Status: Ready to plan +Last activity: 2026-06-18 -- Roadmap created + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Roadmap]: 6 phases derived from 44 v1 requirements, standard granularity +- [Roadmap]: Research recommends NestJS + Next.js + PostgreSQL RLS + Keycloak + Tauri stack + +### Pending Todos + +None yet. + +### Blockers/Concerns + +None yet. + +## Deferred Items + +Items acknowledged and carried forward from previous milestone close: + +| Category | Item | Status | Deferred At | +|----------|------|--------|-------------| +| *(none)* | | | | + +## Session Continuity + +Last session: 2026-06-18 +Stopped at: Roadmap created, ready for Phase 1 planning +Resume file: None diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..441651e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,213 @@ + + +## Project + +**Tessera** + +Tessera ist eine modulare, Docker-basierte Webplattform fuer interne Workflow-Automatisierung und Tool-Integration. Sie bietet ein Portal mit Seitenleiste, konfigurierbarem Dashboard und einem Marketplace fuer lizenzierbare Module. Perspektivisch soll Tessera auch an externe Kunden verkauft werden — Mandantenfaehigkeit ist von Anfang an eingeplant. + +**Core Value:** Eine zentrale Plattform, in der beliebige Workflow-Tools als Module lizenziert, aktiviert und genutzt werden koennen — ohne zwischen verschiedenen Anwendungen wechseln zu muessen. + +### Constraints + +- **Infrastruktur**: Docker-basiert — alle Komponenten als Container +- **Datenbank**: PostgreSQL oder MariaDB (Entscheidung durch Claude) +- **Authentifizierung**: Initialer Admin-Account + manuelle Benutzerverwaltung + LDAP +- **Versionierung**: Automatisierte Gitea-Integration (minimaler manueller Aufwand) +- **Entwicklung**: Alles wird von Claude gebaut — Architektur muss wartbar und verstaendlich sein +- **Mandantenfaehigkeit**: Von Anfang an in der Architektur verankert + + + + + +## Technology Stack + +## Recommended Stack + +### Monorepo & Package Management + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| pnpm | 9.x | Package manager | 60-80% disk reduction via content-addressable store, strict dependency isolation prevents phantom deps, workspace protocol for internal packages | +| Turborepo | 2.9.x | Build orchestration | Incremental builds, parallel execution, task dependency graph, caching. Vercel-maintained — aligns with Next.js ecosystem | + +### Frontend + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Next.js | 16.2.x | Frontend framework | App Router with React 19, Turbopack default bundler (4x faster builds), stable Server Components, `use cache` directive, multi-tenant middleware support | +| React | 19.x | UI library | Ships with Next.js 16, React Compiler (automatic memoization), stable Server Actions | +| TypeScript | 5.5+ | Type safety | Required by all major tools, catches bugs at compile time | +| Tailwind CSS | 4.3.x | Styling | CSS-first config (no JS config file), 3.5x faster rebuilds, OKLCH colors, built-in dark mode via `.dark` selector | +| shadcn/ui | CLI v4 | Component library | Not a dependency — copies components into your project. Accessible, themeable via CSS variables, dark/light mode trivial with next-themes. Dashboard-ready components | +| next-themes | 0.4.x | Theme switching | 2-line dark mode integration with shadcn/ui, SSR-safe, system preference detection | +| next-intl | 4.13.x | Internationalization | Built for Next.js App Router, Server Component native, 457 bytes gzipped, simpler than i18next for Next.js-only projects | +| react-grid-layout | 2.2.x | Dashboard grid | TypeScript rewrite with hooks API (useGridLayout, useResponsiveLayout), drag & drop + resize, responsive breakpoints, 100% backward compat via /legacy | +| Zustand | 5.0.x | Client state | Lightweight (1.1kb), no providers needed, works with Server Components, perfect for UI state (sidebar toggle, theme, user prefs) | +| TanStack Query | 5.101.x | Server state | Caching, background refresh, optimistic updates, pagination. Use for client-side data fetching where Server Components don't suffice | + +### Backend + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| NestJS | 11.x | API framework | Modular architecture maps directly to Tessera's module system. Dependency injection, guards, interceptors, built-in microservices support. Modular monolith now, extract to microservices later if needed | +| Express | 5.x | HTTP server | Default in NestJS 11, battle-tested, massive middleware ecosystem | +| Prisma | 7.8.x | ORM | TypeScript-first, auto-generated types from schema, declarative migrations, Client Extensions for RLS multi-tenancy. v7 dropped Rust engine — 3x faster queries, 90% smaller bundles | +| PostgreSQL | 16.x | Database | Row-Level Security for multi-tenancy, JSONB for flexible module config, excellent Docker support, robust at any scale | +| Redis | 7.x | Cache & sessions | Session storage, pub/sub for real-time features, rate limiting, cache invalidation | + +### Authentication & Authorization + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Keycloak | 26.6.x | Identity provider | Native multi-tenancy via realms, LDAP/AD federation built-in, OAuth2/OIDC standard, Docker-native, admin UI included. Eliminates building auth from scratch | +| nest-keycloak-connect | latest | NestJS integration | Guards, decorators, multi-tenant realm resolvers — handles JWT validation and role extraction | +| @nestjs/passport | latest | Fallback auth | For API key auth on module-to-module communication | + +### Desktop Wrapper + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Tauri | 2.x (2.11+) | Desktop app | 5MB installer vs Electron's 150MB. Uses OS-native WebView — no bundled Chromium. Rust backend for system APIs. Windows + Linux supported. Perfect for wrapping an existing web app | + +### Infrastructure & DevOps + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Docker | 27.x | Containerization | Project constraint. Multi-stage builds for production images | +| Docker Compose | 2.x | Orchestration | Multi-service local dev and production deployment. Health checks, volume management, networking | +| Traefik | 3.x | Reverse proxy | Automatic SSL, Docker-native service discovery, routing rules via labels. Simpler than nginx for Docker-compose setups | +| Gitea | existing | Version control | Already in place. Automate via webhooks and Gitea API | + +### Testing + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Vitest | 3.x | Unit/integration tests | Fast, ESM-native, compatible with Jest API, works with both Next.js and NestJS | +| Playwright | 1.x | E2E tests | Cross-browser, auto-wait, trace viewer. Best for testing the full portal flow | +| Testing Library | latest | Component tests | DOM-based testing, framework-agnostic patterns | + +### Developer Experience + +| Technology | Version | Purpose | Why | +|------------|---------|---------|-----| +| Biome | 2.x | Linting + formatting | Single tool replaces ESLint + Prettier, 100x faster, zero-config defaults. Reduces tooling complexity | +| Husky | 9.x | Git hooks | Pre-commit formatting/linting enforcement | +| lint-staged | 15.x | Staged file linting | Only lint changed files for fast commits | + +## Alternatives Considered + +| Category | Recommended | Alternative | Why Not | +|----------|-------------|-------------|---------| +| Frontend Framework | Next.js 16 | Remix / SvelteKit | Next.js has best multi-tenant support, largest ecosystem, Vercel Platforms template as reference | +| Backend Framework | NestJS 11 | Fastify standalone / Express | NestJS module system maps perfectly to Tessera modules. DI, guards, and interceptors reduce boilerplate | +| ORM | Prisma 7 | Drizzle ORM | Prisma has gentler learning curve (built by Claude, non-programmer user), better migration safety. Drizzle is faster in serverless (irrelevant here — Docker deployment) | +| Database | PostgreSQL 16 | MariaDB | PostgreSQL has native RLS for multi-tenancy, superior JSONB support, better extension ecosystem | +| Auth | Keycloak | Custom JWT + LDAP lib | Building LDAP + multi-tenant auth from scratch is weeks of work and a security risk | +| Desktop | Tauri 2 | Electron | 96% smaller, 5x less memory. Tessera desktop is a wrapper, not a full desktop app | +| State | Zustand | Redux Toolkit | Zustand is 7x smaller bundle, no boilerplate, no providers. Redux is overkill for this project | +| i18n | next-intl | react-i18next | next-intl is built for App Router, Server Component native, simpler API | +| CSS | Tailwind 4 | CSS Modules / Styled Components | Utility-first is faster to develop, dark mode trivial, shadcn/ui requires it | +| Package Manager | pnpm | npm / yarn | pnpm has strict isolation, better disk usage, workspace support built-in | +| Monorepo Tool | Turborepo | Nx | Turborepo is simpler, aligns with Vercel ecosystem, sufficient for this project size | +| Linting | Biome | ESLint + Prettier | Single tool, 100x faster, less config. ESLint is being replaced in NestJS 12 roadmap anyway | +| Component Library | shadcn/ui | Material UI / Ant Design | shadcn gives ownership of components (no dep lock-in), built on Radix primitives, Tailwind-native | +| Dashboard Grid | react-grid-layout | Gridstack.js | React-native, TypeScript rewrite in v2, hooks API, responsive breakpoints | +| Reverse Proxy | Traefik | nginx | Docker-native service discovery, auto-SSL, config via labels not files | + +## Multi-Tenancy Strategy + +- Scales to thousands of tenants without catalog bloat +- Single connection pool (no per-tenant connection overhead) +- Prisma Client Extensions support RLS via session variables +- Simpler migrations — one schema to manage +- Cost-effective for the planned growth trajectory + +## Installation + +# Initialize monorepo + +# Frontend (apps/web) + +# Backend (apps/api) + +# Desktop (apps/desktop) + +# Tauri CLI installed via cargo or npm + +# Shared (packages/shared) + +# Types, DTOs, and constants — no runtime deps + +# Dev tools (root) + +## Docker Services (docker-compose.yml) + +## Version Pinning Strategy + +- **Major versions:** Pin to major (e.g., `next@16`, `@nestjs/core@11`) +- **Prisma:** Pin exactly — schema changes require matched versions +- **Tailwind/shadcn:** Follow latest within major — utility additions are non-breaking +- **Keycloak Docker image:** Pin to minor (e.g., `quay.io/keycloak/keycloak:26.6`) + +## Sources + +- [Next.js 16 Docs](https://nextjs.org/docs/app/guides/upgrading/version-16) — Version 16.2.7+ stable +- [NestJS Documentation](https://docs.nestjs.com/) — Version 11.1.x +- [Prisma ORM 7 Announcement](https://www.prisma.io/blog/announcing-prisma-orm-7-0-0) — Pure TypeScript runtime +- [Tauri 2.0 Stable Release](https://v2.tauri.app/blog/tauri-20/) — Cross-platform desktop +- [Keycloak 26.6 Release](https://www.keycloak.org/2026/04/keycloak-2660-released) — Latest stable +- [Turborepo](https://turborepo.dev/) — Version 2.9.x +- [shadcn/ui CLI v4](https://ui.shadcn.com/docs/changelog/2026-03-cli-v4) — March 2026 update +- [Tailwind CSS v4.3](https://tailwindcss.com/blog/tailwindcss-v4-3) — Latest features +- [next-intl](https://next-intl.dev/) — Version 4.13.x +- [react-grid-layout](https://github.com/react-grid-layout/react-grid-layout) — Version 2.2.x TypeScript rewrite +- [PostgreSQL RLS Multi-Tenancy](https://aws.amazon.com/blogs/database/multi-tenant-data-isolation-with-postgresql-row-level-security/) +- [pnpm Workspaces](https://pnpm.io/workspaces) — Workspace management + + + + + +## Conventions + +Conventions not yet established. Will populate as patterns emerge during development. + + + + +## Architecture + +Architecture not yet mapped. Follow existing patterns found in the codebase. + + + + +## Project Skills + +No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file. + + + + +## GSD Workflow Enforcement + +Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. + +Use these entry points: + +- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks +- `/gsd-debug` for investigation and bug fixing +- `/gsd-execute-phase` for planned phase work + +Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. + + + + +## Developer Profile + +> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile. +> This section is managed by `generate-claude-profile` -- do not edit manually. +