diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md index a44e311..7a322fd 100644 --- a/.planning/research/STACK.md +++ b/.planning/research/STACK.md @@ -96,6 +96,13 @@ The DKV module already solved most of the infrastructure this feature needs. Thi # v1.0 Base Stack (reference — unchanged) +> **Note added 2026-09-09:** This is the stack recommendation from June/July 2026, +> preserved here unchanged. Parts of it were never adopted (Keycloak, Redis, +> TanStack Query, shadcn/ui, Playwright, Husky, lint-staged), and two items were +> adopted at an older major version than recommended (Next.js, Prisma). The +> actually installed stack, checked against `package.json`/`pnpm-lock.yaml`, is +> documented in `CLAUDE.md` under "Technology Stack". + **Researched:** 2026-06-18 **Overall Confidence:** HIGH diff --git a/CLAUDE.md b/CLAUDE.md index f35827b..ccf07a1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,84 +20,107 @@ Tessera ist eine modulare, Docker-basierte Webplattform fuer interne Workflow-Au - ## Technology Stack -## Recommended 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 | 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 | +| 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 | 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 | +| 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 | 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 | +| 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 -| 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 | +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 | 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 | +| 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 | 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 | +| 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 | 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 | +| 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 | 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 | +| 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 | @@ -120,7 +143,7 @@ Tessera ist eine modulare, Docker-basierte Webplattform fuer interne Workflow-Au - Scales to thousands of tenants without catalog bloat - Single connection pool (no per-tenant connection overhead) -- Prisma Client Extensions support RLS via session variables +- 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 @@ -146,13 +169,16 @@ Tessera ist eine modulare, Docker-basierte Webplattform fuer interne Workflow-Au ## 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`) +- **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