schalli/tessera-ctl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
46ebb4e7ceafa1dc782514e487ac820166279f48
tessera-ctl/CLAUDE.md
T
schalli c80704957a docs(claude): Versionsangaben auf den installierten Stand bringen 
- CLAUDE.md Technik-Block zeigt jetzt den installierten Stand statt der
  2026-06/07-Empfehlung: Next.js 15.5.19, Prisma 6.19.3, NestJS 11.1.27,
  Express 5.2.1, Node node:24-alpine (neu ergaenzt), Vitest je App
  (3.2.6 / 4.1.9), Docker/Compose als gemessene Wirtseigenschaft
- Authentifizierungs-Zeilen ersetzt: kein Identitaetsanbieter im Einsatz,
  sondern @nestjs/jwt, passport/@nestjs/passport, argon2, ldapts;
  @nestjs/passport-Zweckangabe korrigiert (Anmelde-/JWT-Strategien statt
  Modul-zu-Modul-API-Keys)
- Nie uebernommene Empfehlungen (Keycloak, Redis, TanStack Query, shadcn/ui,
  Playwright, Husky, lint-staged) sowie die beiden nicht aktualisierten
  Hauptversionen (Next.js, Prisma) in eigenem Abschnitt "Recommended But
  Not Adopted" statt in den Ist-Tabellen
- Herkunftsvermerk ergaenzt; Alternatives Considered/Version Pinning
  Strategy/Sources als historische Entscheidungslage gekennzeichnet;
  Multi-Tenancy Strategy verweist auf die tatsaechliche
  prisma-tenant.extension.ts
- .planning/research/STACK.md erhaelt eine Hinweiszeile, Zahlen darin
  unveraendert (datiertes Rechercheergebnis)
- Keine Abhaengigkeit aktualisiert (package.json/pnpm-lock.yaml
  unveraendert, per Gate geprueft)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FYZcd3SSmo14QTqWx2KKzU
2026-09-09 09:37:27 +02:00

240 lines
13 KiB
Markdown
Raw Blame History

<!-- 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
> 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](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 -->
Reference in New Issue View Git Blame Copy Permalink