schalli/tessera-ctl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity

docs: create roadmap (6 phases)

Browse Source
This commit is contained in:
Schalli
2026-06-18 08:45:41 +02:00
parent a65b639461
commit 4a71f1f774
4 changed files with 455 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+48 -5
View File
@@ -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*
.planning/ROADMAP.md
+115
View File
@@ -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 | - |
.planning/STATE.md
+79
View File
@@ -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
CLAUDE.md
+213
View File
@@ -0,0 +1,213 @@
<!-- GSD:project-start source:PROJECT.md -->
## 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
<!-- GSD:project-end -->
<!-- GSD:stack-start source:research/STACK.md -->
## 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
<!-- GSD:stack-end -->
<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions
Conventions not yet established. Will populate as patterns emerge during development.
<!-- GSD:conventions-end -->
<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture
Architecture not yet mapped. Follow existing patterns found in the codebase.
<!-- GSD:architecture-end -->
<!-- GSD:skills-start source:skills/ -->
## 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:skills-end -->
<!-- GSD:workflow-start source:GSD defaults -->
## 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.
<!-- GSD:workflow-end -->
<!-- GSD:profile-start -->
## 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.
<!-- GSD:profile-end -->