56a1527864
Reflect current package structure and organization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# 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
|