# 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](../../tooling/claude/dot-claude/instructions/architecture-patterns.md) - Full pattern reference
- [Code Style](../../tooling/claude/dot-claude/instructions/code-style.md) - Coding conventions
- [Core Principles](../../tooling/claude/dot-claude/instructions/core-principles.md) - 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