schalli
fc5a6f3832
Three plans for Foundation & Portal Shell phase: - 01-01: Monorepo scaffold, Docker Compose with 3-network segmentation, NestJS API, Next.js app, PostgreSQL - 01-02: Design tokens (yellow #ffed00 primary), i18n (DE/EN), theme switching, responsive portal layout - 01-03: Visual verification checkpoint for human approval Includes SKELETON.md documenting architectural decisions for subsequent phases. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.1 KiB
3.1 KiB
Walking Skeleton — Tessera
Phase: 1 Generated: 2026-06-18
Capability Proven End-to-End
A user can open a browser, see the Tessera portal shell with header, collapsible sidebar, and main content area, toggle between light and dark theme (persisted), and switch between German and English interface language -- all served from a Docker Compose stack with PostgreSQL, NestJS API, and Next.js frontend on segregated networks.
Architectural Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Monorepo | pnpm 9 + Turborepo 2.9 | Strict deps, workspace protocol, parallel builds with caching |
| Frontend | Next.js 16 App Router (standalone output) | React 19, Server Components, Turbopack, multi-tenant middleware support |
| Backend | NestJS 11 + Express 5 | Modular architecture maps to Tessera module system, DI, guards |
| Data layer | PostgreSQL 16 + Prisma 7 | RLS for multi-tenancy, TypeScript-first ORM, declarative migrations |
| Styling | Tailwind CSS 4 + shadcn/ui (CLI v4) | CSS-first config, design tokens via CSS variables, accessible components |
| i18n | next-intl 4.13 (without i18n routing) | Cookie-based locale, Server Component native, App Router built-in |
| Theme | next-themes 0.4 | SSR-safe, system preference detection, .dark class toggle |
| Client state | Zustand 5 | Sidebar toggle, UI prefs, 1.1kb, localStorage persistence |
| Deployment | Docker Compose with Traefik 3.x reverse proxy | Three-network segmentation (frontend/backend/data), health checks |
| Directory layout | apps/web, apps/api, packages/shared monorepo | Clear separation, independent Dockerfiles, shared types |
| Linting | Biome 2.x | Single tool replaces ESLint + Prettier, 100x faster |
Stack Touched in Phase 1
- Project scaffold (pnpm monorepo, Turborepo, Biome, TypeScript)
- Routing — Next.js App Router with root page (dashboard placeholder)
- Database — PostgreSQL container with Prisma schema (health check read)
- UI — Theme toggle, language switch, collapsible sidebar (interactive)
- Deployment — Docker Compose full-stack with
docker compose upcommand
Out of Scope (Deferred to Later Slices)
- Authentication and user accounts (Phase 2)
- Multi-tenancy and RLS policies (Phase 2)
- Module system and dynamic loading (Phase 3)
- Marketplace and sidebar module listing (Phase 4)
- Dashboard widgets and drag-and-drop grid (Phase 5)
- Desktop Tauri wrapper (Phase 6)
- Configurable accent color UI (Phase 2 -- infrastructure prepared via CSS variable)
- Redis cache/sessions (Phase 2)
- Keycloak identity provider (Phase 2)
- E2E tests with Playwright (deferred -- smoke tests via curl suffice for skeleton)
Subsequent Slice Plan
Each later phase adds one vertical slice on top of this skeleton without altering its architectural decisions:
- Phase 2: Authenticated user can log in, see their name, operate within tenant boundary
- Phase 3: Admin can activate a module, user can interact with Domaincheck
- Phase 4: User can browse marketplace, activate modules, navigate via sidebar
- Phase 5: User can configure personal dashboard with draggable widgets
- Phase 6: User can install and run Tessera as a native desktop app