teOS/CLAUDE.md

tOS – Claude Code Guide

Projekt

Enterprise Web Operating System: Next.js 14 + NestJS 10 + Prisma + PostgreSQL 16 + Keycloak 24. pnpm-Monorepo mit Turbo (apps/web, apps/api, packages/shared).

Dev-Befehle

# Infrastruktur starten (PostgreSQL, Redis, Keycloak)
cd docker && docker compose up -d

# Apps starten
pnpm dev          # alle Apps
pnpm dev:api      # nur Backend
pnpm dev:web      # nur Frontend

# Datenbank
pnpm db:push      # Schema anwenden (dev)
pnpm db:seed      # Default-Daten (Rollen, SystemSettings)

# TypeScript-Check
pnpm --filter @tos/api exec tsc --noEmit
pnpm --filter @tos/web exec tsc --noEmit

Ports

Service	Port
Frontend	3000
Backend	3001
Keycloak	8080
PostgreSQL	5432
Redis	6379

Datenbanken

• tos_db – Keycloak (wird automatisch erstellt)
• tos_app – Anwendung (wird via docker/postgres/init.sql automatisch erstellt)
• Beide in derselben PostgreSQL-Instanz

Keycloak (Dev)

• Admin-UI: http://localhost:8080 → admin / admin123
• Realm: tOS
• Frontend-Client: tos-nextauth (NextAuth)
• Backend-Client: tos-backend (NestJS)

Architektur

Auth:

• Keycloak SSO → NextAuth (Frontend-Session) + passport-jwt RS256 via JWKS (Backend)
• JWT wird über Keycloak JWKS-Endpoint validiert – KEIN symmetrischer JWT_SECRET
• Global Guard Chain: JWT → Roles → Permissions, @Public() für opt-out

API-Kommunikation:

• Backend wickelt alle Responses in {success, data, timestamp} (TransformInterceptor)
• Frontend-api.ts unwrappt diesen Envelope automatisch
• NEXT_PUBLIC_API_URL enthält bereits /api/v1 (z.B. http://localhost:3001/api/v1)

Konfiguration:

• Integration-Credentials und SystemSettings liegen in der DB, nicht in .env
• .env enthält nur Bootstrap-Variablen (DB-URL, Secrets, Keycloak-Koordinaten)

Code-Konventionen

• Route-Pattern: page.tsx (Server Component) importiert *-content.tsx (Client Component)
• Routen: [locale]/(auth)/... = geschützt, [locale]/(setup)/... = public, /login = public
• State: Zustand für UI-State, TanStack Query für Server-State
• i18n: ASCII-Umlaute in JSON-Keys (oe, ae, ue statt ö, ä, ü)
• Installer-API-Calls: direktes fetch() mit x-setup-token Header (kein Bearer-Token)

Deployment

# Lokaler Full-Stack-Test (identisch zu Prod, vor Commit)
cd docker && docker compose -f docker-compose.local.yml up --build
# → http://localhost:3000/setup?token=local-setup-token-for-testing

# Produktions-Installation (interaktiv)
./install.sh
# → fragt Domain + SSL-Modus, generiert Secrets, startet docker-compose.prod.yml
# → SSL via Let's Encrypt (Caddy, --profile ssl) oder externer Reverse Proxy

Bekannte Issues / TODOs

• HR-Hooks nutzen noch Mock-Daten (nicht an Backend angebunden)
• Morning Meeting Endpoints nutzen DASHBOARD_VIEW Permission (Security-Gap)
• apps/api/integrations.backup/ – deaktivierte Integrations-Module (via .gitignore ignoriert)