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

The tables below show the installed stack, checked against package.json, pnpm-lock.yaml (importers: resolved versions), and the Compose/Dockerfiles on 2026-09-09. The original stack recommendation from 2026-06/07 lives unchanged in .planning/research/STACK.md; regenerating this block from that file would reintroduce the recommended-but-not-installed numbers below as if they were current.

Monorepo & Package Management

Technology	Installed Version	Purpose
pnpm	9.15.0	Package manager — 60-80% disk reduction via content-addressable store, strict dependency isolation, workspace protocol for internal packages
Turborepo	2.9.18	Build orchestration — incremental builds, parallel execution, task dependency graph, caching

Frontend

Technology	Installed Version	Purpose
Next.js	15.5.19	Frontend framework — App Router, React Server Components. A newer major (16.2.x) was recommended but not adopted; see "Recommended But Not Adopted" below
React	19.2.7	UI library
TypeScript	5.9.3	Type safety
Tailwind CSS	4.3.1	Styling — CSS-first config, OKLCH colors, built-in dark mode via .dark selector
next-themes	0.4.6	Theme switching — dark/light mode with system preference detection
next-intl	4.13.0	Internationalization
react-grid-layout	2.2.3	Dashboard grid — drag & drop + resize, responsive breakpoints
Zustand	5.0.14	Client state — UI state (sidebar toggle, theme, user prefs)

Backend

Technology	Installed Version	Purpose
NestJS	11.1.27	API framework — modular architecture, dependency injection, guards, interceptors
Express	5.2.1	HTTP server (via @nestjs/platform-express)
Prisma	6.19.3	ORM. A newer major (7.8.x) was recommended but not adopted; see "Recommended But Not Adopted" below
PostgreSQL	postgres:16-alpine	Database — Row-Level Security for multi-tenancy, JSONB for module config

Authentication & Authorization

No identity provider is deployed. The installed system is a self-built login stack:

Technology	Installed Version	Purpose
@nestjs/jwt	11.0.2	Issues and validates the session JWT
passport + @nestjs/passport	0.7.0 / 11.0.5	Login and JWT authentication strategies (not module-to-module API-key auth — that was an earlier, since-corrected description of this package's purpose)
argon2	0.44.0	Password hashing
ldapts	8.1.8	LDAP/AD directory binding for user sync

Desktop Wrapper

Technology	Installed Version	Purpose
Tauri	2.11.1 (CLI 2.11.3)	Desktop app wrapper. apps/desktop is scaffolding only as of docs/anleitung-entwicklung.md

Infrastructure & DevOps

Technology	Version	Purpose
Node.js	node:24-alpine	JS runtime for both apps/api and apps/web production images (apps/api/Dockerfile, apps/web/Dockerfile)
Docker	29.8.0 (host property, measured on the dev machine, 2026-09-09)	Not pinned by this repository
Docker Compose	v5.5.1 (host property, measured on the dev machine, 2026-09-09)	Not pinned by this repository
Nginx Proxy Manager	external	Reverse proxy managed by host infrastructure — Tessera containers do not include a reverse proxy
Gitea	existing	Version control, already in place

Testing

Technology	Installed Version	Purpose
Vitest (apps/api)	3.2.6	Unit/integration tests
Vitest (apps/web)	4.1.9	Unit/integration tests — a different major than apps/api, not yet aligned
Testing Library (@testing-library/react)	16.3.2	Component tests

Developer Experience

Technology	Installed Version	Purpose
Biome	2.5.0	Linting + formatting — replaces ESLint + Prettier

Recommended But Not Adopted

The following was recommended in the original 2026-06/07 stack research (.planning/research/STACK.md) but is not part of the running system. Listed here, outside the tables above, so nothing in this section is mistaken for something that is actually built:

• Identity provider: Keycloak 26.6.x plus nest-keycloak-connect were recommended for authentication and multi-tenant realm federation. Not built — no Keycloak service in any Compose file, no package in the lockfile. What runs instead is the self-built stack in the Authentication & Authorization table above.
• Cache / session store: Redis 7.x was recommended. Not installed — no service, no package.
• Server state library: TanStack Query 5.101.x was recommended. Not installed.
• Component library: shadcn/ui CLI v4 was recommended. Not used — no components.json, no components/ui directory.
• E2E test runner: Playwright 1.x was recommended as a project dependency. Not installed as one — browser checks run through the Playwright MCP tool, which is not a dependency of this repository and has no playwright.config.* here.
• Git hooks: Husky 9.x and lint-staged 15.x were recommended. Not installed — no .husky directory.
• Next.js major version: 16.2.x was recommended; the installed major is 15.5.19 (see Frontend table above). No statement here about whether an upgrade is planned.
• Prisma major version: 7.8.x was recommended; the installed major is 6.19.3 (see Backend table above). No statement here about whether an upgrade is planned.

Alternatives Considered

The table below reflects the decision record from 2026-06, at the time the stack was chosen. Its "Recommended" column documents what was picked back then — it is not a statement about what is installed today; see the tables above for that.

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 — in active use, see apps/api/src/prisma/prisma-tenant.extension.ts
• 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@15, @nestjs/core@11)
• Prisma: Pin exactly — schema changes require matched versions (currently 6.19.3)
• Tailwind: Follow latest within major — utility additions are non-breaking (currently 4.3.x)

Sources

Consulted for the original 2026-06/07 stack recommendation — sources for that decision, not evidence of the current installed state (see the tables above for that):

• 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.