Status: [ ] Not Started | [ ] In Progress | [ ] Complete | [ ] Approved
This document defines the technical architecture, technology stack, and engineering decisions. Complete this document during the Global Setup phase before creating any feature specifications.
Architecture Overview
System Architecture
[TODO: Add architecture diagram or description]
Example:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client │────▶│ API │────▶│ Database │
│ (Web) │ │ Server │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
Architecture Patterns
| Pattern | Usage | Rationale |
|---|
| [TODO] | [TODO] | [TODO] |
| [TODO] | [TODO] | [TODO] |
Technology Stack
Frontend
| Layer | Technology | Version | Purpose |
|---|
| Framework | [TODO] | [TODO] | [TODO] |
| UI Library | [TODO] | [TODO] | [TODO] |
| State Management | [TODO] | [TODO] | [TODO] |
| Styling | [TODO] | [TODO] | [TODO] |
Backend
| Layer | Technology | Version | Purpose |
|---|
| Runtime | [TODO] | [TODO] | [TODO] |
| Framework | [TODO] | [TODO] | [TODO] |
| ORM/Database | [TODO] | [TODO] | [TODO] |
| Authentication | [TODO] | [TODO] | [TODO] |
Infrastructure
| Component | Technology | Purpose |
|---|
| Hosting | [TODO] | [TODO] |
| Database | [TODO] | [TODO] |
| Cache | [TODO] | [TODO] |
| CDN | [TODO] | [TODO] |
Data Architecture
Data Models
[TODO: Define core data models]
Example:
User ──┬── owns ──▶ Workspace
└── creates ──▶ Task ──▶ belongs to ──▶ Project
Database Strategy
| Aspect | Decision | Rationale |
|---|
| Primary Database | [TODO] | [TODO] |
| Caching Strategy | [TODO] | [TODO] |
| Data Sync | [TODO] | [TODO] |
API Design
API Style
[TODO: Define API style and conventions]
Authentication & Authorization
| Aspect | Approach | Details |
|---|
| Authentication | [TODO] | [TODO] |
| Authorization | [TODO] | [TODO] |
| Token Management | [TODO] | [TODO] |
API Versioning
[TODO: Define API versioning strategy]
Security Considerations
Security Requirements
| Requirement | Implementation | Status |
|---|
| Data Encryption | [TODO] | [ ] |
| Input Validation | [TODO] | [ ] |
| OWASP Top 10 | [TODO] | [ ] |
| Authentication | [TODO] | [ ] |
Security Boundaries
[TODO: Define security boundaries]
| Metric | Target | Measurement |
|---|
| Page Load Time | [TODO] | [TODO] |
| API Response Time | [TODO] | [TODO] |
| Concurrent Users | [TODO] | [TODO] |
| Availability | [TODO] | [TODO] |
Scalability Strategy
[TODO: Define scalability approach]
Integration Points
External Services
| Service | Purpose | Integration Method |
|---|
| [TODO] | [TODO] | [TODO] |
| [TODO] | [TODO] | [TODO] |
Internal APIs
| API | Purpose | Consumers |
|---|
| [TODO] | [TODO] | [TODO] |
| [TODO] | [TODO] | [TODO] |
Development Environment
- [ ] [TODO]
- [ ] [TODO]
- [ ] [TODO]
Environment Setup
# [TODO: Add setup commands]
Technical Decisions Log
| Decision | Date | Rationale | Alternatives Considered |
|---|
| [TODO] | [TODO] | [TODO] | [TODO] |
| [TODO] | [TODO] | [TODO] | [TODO] |
Approval
| Role | Name | Date | Signature |
|---|
| Technical Lead | | | |
| Architect | | | |
| Security | | | |
Learnings & Patterns
This section captures architectural decisions and learnings from development sessions.
RxDB Schema & Migrations
| Pattern | Details | Date Added |
|---|
| Schema versioning | When bumping RxDB schema versions, the migration plugin must be enabled (migration: true in plugins config) | 2026-01-30 |
domainId handling | domainId is a server-only field injected by rxdb-server - do NOT add to client-side schemas. The forked rxdb-server uses serverOnlyFields: ['domainId'] to strip it from HTTP responses. | 2026-01-30 |
| WebSocket replication | WebSocket replication doesn't support serverOnlyFields - clients will receive domainId via WS but should ignore it | 2026-01-30 |
| Schema rebuild process | After schema changes, use ./scripts/local-env.sh rebuild to rebuild and restart containers with new schema | 2026-01-30 |
Kong Gateway & Authentication
| Pattern | Details | Date Added |
|---|
JWT iss claim required | JWT tokens MUST include iss claim - Kong uses key_claim_name: iss to look up the consumer | 2026-01-30 |
| Lua sandbox limitations | Kong's post-function Lua sandbox blocks require('cjson.safe') - use pattern matching instead for JSON parsing | 2026-01-30 |
| Multi-tenant isolation | Kong extracts domainId from JWT and sets x-domain-id header for downstream services to enforce tenant isolation | 2026-01-30 |
| Container port exposure | Services behind Kong gateway should NOT expose ports directly - all access should go through Kong | 2026-01-30 |
Ollama & Embedding Services
| Pattern | Details | Date Added |
|---|
| Batch concurrency | Batch embedding requests can overwhelm Ollama - implement concurrency limiting with a queue (e.g., max 3 concurrent) | 2026-01-30 |
| Extended timeouts | Default 30s timeout insufficient for embeddings - use minimum 120s via AbortSignal.timeout(120000) | 2026-01-30 |
| Custom fetch | Embedding service should use custom fetch wrapper with configurable timeout and retry logic | 2026-01-30 |
SurrealDB
| Pattern | Details | Date Added |
|---|
| UPSERT syntax | SurrealDB 2.x UPSERT syntax is UPSERT INTO table:$id CONTENT {...} NOT UPSERT table:$id CONTENT {...} | 2026-01-30 |
Docker & Container Management
| Pattern | Details | Date Added |
|---|
| Use local-env.sh | Always use ./scripts/local-env.sh for container management - it handles 1Password secret loading | 2026-01-30 |
| Git clone builds | Docker images built from git clone won't have uncommitted changes - push changes before building | 2026-01-30 |
| Base image pattern | Create a slim base image (Dockerfile.base) that pre-builds core library packages using nx run-many --parallel=3. Service Dockerfiles extend from this base. | 2026-01-30 |
| Nx parallel builds | Use --parallel=3 with nx run-many to limit concurrent builds and avoid memory issues while still parallelizing | 2026-01-30 |
| Slim service images | Service Dockerfiles that extend from base only need to run yarn nx build @epicdm/<service> - deps are pre-built | 2026-01-30 |
Caddy Reverse Proxy
| Pattern | Details | Date Added |
|---|
| Caddyfile global block | Global settings like email must be in a global block: { email foo@example.com } at top of file | 2026-01-30 |
| DNS before TLS | DNS must be configured and propagated BEFORE Caddy can obtain Let's Encrypt certificates | 2026-01-30 |
| Proxy mode off for certs | When using Cloudflare DNS with Caddy for TLS, keep proxy mode OFF (gray cloud) so Caddy can complete ACME challenges | 2026-01-30 |
| Shortlived certs avoided | Do not use profile shortlived in ACME config - use default cert settings for production | 2026-01-30 |
Cloudflare Deployment
| Pattern | Details | Date Added |
|---|
| Environment flag | Deployment requires explicit --env production flag for production environment | 2026-01-30 |
| Worker environments | Workers have separate staging and production environments - always verify deployment target | 2026-01-30 |
| Custom domain routing | Custom domains may route to different workers than expected - verify routing in Cloudflare dashboard | 2026-01-30 |
RAG Sync & Content Deduplication
| Pattern | Details | Date Added |
|---|
| Document ID consistency | Use document.id (internal RxDB id) for hash lookups, not event.documentId (external id). These can differ and cause deduplication failures. | 2026-01-30 |
| Volatile fields exclusion | Exclude volatile fields from content hash: updatedAt, createdAt, _rev, _meta, _deleted, _attachments, syncedAt, lastModified. Otherwise documents re-sync infinitely. | 2026-01-30 |
| Deterministic hashing | Sort object keys before hashing to ensure consistent results across runs: JSON.stringify(obj, Object.keys(obj).sort()) | 2026-01-30 |
Last Updated: 2026-01-30 Document Owner: [Name]