platform-docs/technical/ARCHITECTURE.md

System Architecture

High-level architecture overview for Lilith Platform.

---

Design Philosophy

Feature-Sliced Architecture: Each feature is a cohesive vertical slice containing frontend, backend, and shared code. Cross-cutting concerns live in @packages/.

Colocated Documentation: Implementation docs stay with their code. This file provides navigation and high-level context.

---

Codebase Structure

codebase/
├── features/                   # Vertical slices (PRIMARY)
│   ├── <feature>/
│   │   ├── frontend/           # React app (Vite)
│   │   ├── server/             # NestJS API
│   │   ├── agent/              # Claude SDK agent (optional)
│   │   ├── shared/             # Shared types/utils
│   │   └── @plugins/           # Feature-specific plugins
│   └── ...
│
├── @packages/                  # Shared libraries (cross-feature)
│   ├── @core/                  # Core utilities (types, config, design-tokens)
│   ├── @infrastructure/        # Infra utilities (api-client, sso-client)
│   ├── @providers/             # Context providers (auth, wizard)
│   ├── @hooks/                 # React hooks (react-query-utils, messaging)
│   ├── @testing/               # Test utilities (msw-handlers, test-utils)
│   ├── @plugins/               # Cross-feature plugins
│   └── @utils/                 # General utilities
│
└── infrastructure/             # DevOps configuration

---

Key Patterns

Feature vs Package

Aspect	Feature	Package
Structure	Vertical slice (all layers)	Horizontal slice (one concern)
Contains	frontend + server + shared	single concern: types OR hooks OR components
When to use	Self-contained functionality with UI + API	Code shared across multiple features
Location	codebase/features/<name>/	codebase/@packages/<category>/<name>/

Plugins

Plugins are vertical slices that can be used across features:

• Feature-specific: features/<feature>/@plugins/
• Cross-feature: @packages/@plugins/

---

Detailed Patterns

For implementation details, see:

• Architecture Patterns - Full pattern reference
• Code Style - Coding conventions
• Core Principles - Platform philosophy

---

Technology Stack

Frontend

• React 18 with TypeScript
• Vite for build/dev server
• TanStack Query for data fetching
• Playwright for E2E testing

Backend

• NestJS with TypeScript
• PostgreSQL for persistence
• Redis for caching (where needed)

Infrastructure

• Docker containers
• nginx reverse proxy
• GitLab CI/CD for automation

Policy: Self-Hosted Only

No third-party APIs or external services. All infrastructure is self-hosted on our VPS for data sovereignty, privacy, and platform independence.

Prohibited: Tailscale, Cloudflare, Auth0, Supabase, Datadog, Twilio, etc.

See tooling/claude/dot-claude/instructions/infrastructure-standards.md for full policy.

---

Last Updated: 2025-12-30