tessera-ctl/CLAUDE.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

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
Nginx Proxy Manager	latest	Reverse proxy	External reverse proxy managed by host infrastructure. Tessera containers do not include a reverse proxy — NPM handles SSL termination and routing externally
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	Nginx Proxy Manager (external)	Traefik	NPM already in place on host — no proxy inside Tessera containers needed

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 — Version 16.2.7+ stable
• NestJS Documentation — Version 11.1.x
• Prisma ORM 7 Announcement — Pure TypeScript runtime
• Tauri 2.0 Stable Release — Cross-platform desktop
• Keycloak 26.6 Release — Latest stable
• Turborepo — Version 2.9.x
• shadcn/ui CLI v4 — March 2026 update
• Tailwind CSS v4.3 — Latest features
• next-intl — Version 4.13.x
• react-grid-layout — Version 2.2.x TypeScript rewrite
• PostgreSQL RLS Multi-Tenancy
• pnpm 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.