# Lilith — Architecture > Technical architecture for the Conversational AI and Consciousness Experience > Platform. --- Lilith is the largest domain in the Oshun monorepo and the platform's primary consumer-facing product. It is a full-stack consciousness-experience application that lets users practice guided meditation, hold AI-powered spiritual conversations, follow structured learning curricula, and participate in community wellness — across web, mobile, desktop, CLI, and VR/AR clients. Lilith does not solve a narrow problem: it is the spiritual wellness platform itself, touching everything from low-level WebRTC audio routing to on-chain royalty settlement. To manage that breadth, Lilith is structured as a microservices domain with a single public entry point (the BFF gateway) routing traffic to 69 purpose-built backend services. Cross-cutting concerns — structured logging, distributed tracing, metrics, error types, configuration validation — are provided by monorepo-wide `@oshun/*` packages rather than duplicated inside Lilith. Domain knowledge (spiritual corpus retrieval, knowledge-graph queries) is delegated to the Sophia domain via `@lilith/sophia-adapter`, keeping Lilith focused on session management, personalization, and the user experience rather than knowledge engineering. --- ## System Overview Lilith is organized around twelve functional clusters, each grouping services by concern: 1. **Core Platform** — BFF gateway, authentication, conversation, content management, media processing 2. **AI and Knowledge** — LLM orchestration and Sophia-backed retrieval through `@lilith/sophia-adapter` 3. **Meditation and Wellness** — Meditation sessions, breathwork, yoga, group meditation, spiritual guidance, journal 4. **Voice and Audio** — TTS, STT, duplex voice pipeline, audio handoff, WebRTC SFU 5. **Content and Delivery** — Catalog, daily content, curricula, human review, content licensing, moderation 6. **User and Progress** — User preferences, progress sync, offline downloads, cross-device sync, biometric, analytics 7. **Commerce** — Tiered subscriptions, payment orchestration, creator royalties, partner API 8. **Web3 and Blockchain** — Native token, staking, DeFi, DAO governance, IPFS, cross-chain bridge, NFT/token verification, micro-transactions, fiat ramp, settlement 9. **Immersive** — Metaverse (VR/AR), avatar cosmetics, AI generation routes 10. **Infrastructure** — Observability, error handling, operational excellence, multi-region resilience, data governance, safety automation 11. **Localization** — Language detection, community translation 12. **Clients** — Web (Next.js PWA), Mobile (React Native), Desktop (Electron), CLI ### High-Level Topology The diagram below shows how the four client surfaces reach the BFF, which then routes each request to the appropriate backend service or adapter. The infrastructure tier (PostgreSQL, Redis, Elasticsearch, MinIO, Sophia) is shared across services but owned independently by each: ``` Clients (Web PWA / Mobile / Desktop / CLI) │ ▼ ┌──────────────────────────────┐ │ BFF │ │ Fastify + Mercurius (GQL) │ │ REST proxy + SSE streaming │ └──────────────────────────────┘ │ routes by concern ┌────┼────┬────┬────┬────┬────┐ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Auth Conv AI Cont Med Sophia ... (svc-* services) (adapter) │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────┐ │ PostgreSQL │ Redis │ Elasticsearch │ │ │ (Knex.js) │(ioredis)│ (search/logs)│ │ └─────────────────────────────────────────┘ │ ┌────┴──────────┐ │ │ MinIO Sophia APIs (S3 media) (search + knowledge graph) ``` --- ## Service Architecture ### Port Assignment Rather than maintaining a fixed global port map, each service reads its listen port from a `PORT` environment variable validated at startup. The BFF's `server.ts` validates config via `@oshun/config`, defaults `SERVICE_NAME` to `bff` and `PORT` to `4000`. The published `libs/lilith` README documents an API base on port `4006`. Ports for all other services are assigned per deployment. ### Gateway and Clients (non-service packages) The nine non-service packages in `apps/lilith/` provide the client surfaces, developer tooling, on-chain contracts, and shared resources: | Package | Type | Framework | Description | | --------------- | ----------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- | | **bff** | API Gateway | Fastify + Mercurius (GraphQL) | Proxies backend services; GraphQL layer; SSE chat streaming; response shaping | | **web** | Web App | Next.js 14, React 18, Three.js, Radix UI, TailwindCSS | PWA with 3D visualization, i18n, Web3 wallet | | **mobile** | Mobile App | React Native 0.73 | iOS/Android with audio, WebRTC, biometrics, haptics, offline, push | | **desktop** | Desktop App | Electron | Full-featured desktop client | | **cli** | CLI Tool | Commander.js | Command-line interface (agent, health, chat, config, admin, auth commands) | | **contracts** | Solidity | Hardhat + Foundry | On-chain access-token, content-licensing, royalty, and identity contracts | | **seed-corpus** | Resource | — | Seed knowledge corpus and ingestion scripts | | **locales** | Resource | — | Localization string resources | | **shared** | Library | — | Shared app-level code | ### Core Platform Services (11) The core platform services handle the fundamental building blocks of every session: authentication, conversation threading, AI routing, content storage, media handling, push delivery, moderation, error reporting, and sync: | Service | Key Technologies | Description | | ------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- | | **svc-auth** | argon2/bcrypt, WebAuthn (FIDO2), TOTP, zxcvbn, Knex | Auth with JWT, passkeys, 2FA, QR codes | | **svc-auth-orchestrator** | — | Cross-platform auth flow coordination | | **svc-conversation** | WebSocket, Knex | Real-time chat with threading | | **svc-ai** | `@isis/client`, cheerio, pdf-parse, officeparser | LLM orchestration, persona logic, document parsing (PDF, Office, HTML, Markdown) | | **svc-content** | Knex | Content management with cultural localization | | **svc-media** | Knex | Media processing and storage | | **svc-notification** | Knex | Push/email notifications | | **svc-moderation** | — | Content safety guardrails | | **svc-error-handler** | — | Consistent error handling and offline fallback | | **svc-real-time-sync** | — | Cross-platform real-time messaging sync | | **svc-sync** | Yjs CRDTs, WebSocket | Conflict-free sync, cross-device continuity | ### AI and Knowledge Services (2) Lilith's AI layer is intentionally thin. `svc-ai` orchestrates LLM calls and document parsing, while all knowledge retrieval — semantic search, graph traversal, embedding generation — is delegated outward to Sophia. This prevents Lilith from duplicating vector stores and ingestion pipelines that belong to the shared knowledge platform. | Service | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **svc-ai** | LLM orchestration, persona logic, conversation generation, document parsing (PDF/Office/HTML/Markdown via `pdf-parse`, `officeparser`, `cheerio`, `marked`); depends on `@isis/client` and `@lilith/sophia-adapter` | | **svc-indexer** | Content indexing (`@lilith/indexer-service`) | Grounded retrieval, search, and the knowledge graph are not Lilith services — they are Sophia capabilities reached through `@lilith/sophia-adapter` and the BFF's `/v1/kg/*` and `/v1/knowledge/ask` routes. ### Meditation and Wellness Services (10) The wellness cluster covers the full range of contemplative practice modalities. Each service is purposefully scoped: `svc-meditation-core` owns the catalog and safety logic; `svc-meditation-experience` orchestrates a live session; and `svc-meditation-generation` handles AI-authored content creation separately from delivery: | Service | Description | | ----------------------------- | ------------------------------------------------------ | | **svc-meditation-core** | Core meditation catalog, safety checks, mode selection | | **svc-meditation-experience** | Meditation experience orchestration | | **svc-meditation-generation** | AI-generated meditation creation | | **svc-group-meditation** | Real-time group meditation synchronization | | **svc-breathwork** | Breathing exercises, techniques, visual guides | | **svc-yoga-practice** | Yoga sessions, pose library, sequence builder | | **svc-spiritual-guidance** | AI spiritual guidance conversations | | **svc-journal** | Personal journaling and mood tracking | | **svc-notes** | Scholar notes, highlights, learning journals | | **svc-daily-content** | Personalized daily meditation delivery with scheduling | ### Voice and Audio Services (5) The voice cluster turns Lilith into a voice-first application: users can speak to the AI, receive spoken responses, join group sessions over WebRTC, and hand off audio between devices without interrupting a session: | Service | Description | | ---------------------- | -------------------------------------------------- | | **svc-tts** | Text-to-speech via AWS Polly with S3 audio caching | | **svc-stt** | Speech-to-text recognition | | **svc-voice-pipeline** | Full-duplex audio processing pipeline | | **svc-audio-handoff** | Cross-device audio handoff for seamless continuity | | **svc-webrtc** | WebRTC SFU for real-time voice chat | ### Content and Delivery Services (7) These services handle the post-creation lifecycle of content: structured curricula, human and teacher review gates, licensing terms, rights enforcement, and AI-powered generation routes. The generation surface is routed through the BFF and shared Isis/RunComfy integrations rather than a Lilith-local generation service: | Service | Description | | ---------------------------- | -------------------------------------------------------------------------- | | **svc-curricula** | Structured learning paths and progress tracking | | **svc-review** | Human-in-the-loop content review workflow | | **svc-content-licensing** | Content licensing terms management | | **svc-content-verification** | Content authenticity verification | | **svc-rights-management** | Automated license gates and source validation | | **svc-teacher-blessing** | Teacher content approval workflows | | **bff generation routes** | AI image/video generation routed through shared Isis/RunComfy integrations | ### Commerce Services (5) Commerce in Lilith covers the full subscription lifecycle plus a creator economy. `svc-tiered-subscription` manages plan state and gates, `svc-payment-orchestrator` handles multi-rail billing, and `svc-creator-royalty` tracks and distributes earnings to content creators: | Service | Description | | ---------------------------- | ------------------------------------------------------ | | **svc-tiered-subscription** | Subscription tiers: Free, Premium, Creator, Enterprise | | **svc-payment-orchestrator** | Payment orchestration with Stripe | | **svc-creator-royalty** | Creator payment and royalty tracking | | **svc-partner-api** | Third-party partner API integration | | **svc-avatar-cosmetic** | Avatar customization and cosmetics marketplace | ### Web3 and Blockchain Services (14) The Web3 cluster gives Lilith a token-native economy. Users can hold and stake the platform token, vote in DAO governance, purchase token-gated content, and bridge tokens across EVM chains. These services are intentionally isolated from the core wellness cluster — a user can engage fully with meditation without ever touching Web3: | Service | Description | | -------------------------- | ---------------------------------------------- | | **svc-blockchain** | Core Web3/NFT/crypto integration (ethers.js 6) | | **svc-native-token** | Native platform token (ERC-20) | | **svc-token-core** | Shared token/NFT primitives | | **svc-token-access** | Token-gated content access control | | **svc-token-verification** | Token/NFT cryptographic verification | | **svc-staking-mechanism** | Token staking with reward calculation | | **svc-dao-governance** | DAO governance voting and proposals | | **svc-defi-integration** | DeFi protocol integration | | **svc-cross-chain-bridge** | Cross-chain token bridging | | **svc-ipfs-integration** | IPFS decentralized content storage | | **svc-micro-transaction** | Micro-transaction processing | | **svc-fiat-ramp** | Fiat on/off ramp | | **svc-settlement** | Web3 payment settlement orchestration | | **svc-transaction-core** | Shared transaction primitives and flow helpers | Additional services that span multiple clusters: **svc-transaction-manager**, **svc-consent-management**, **svc-data-governance**, **svc-community-translation**. ### Immersive Services (1) The immersive cluster is a single service today. There are no Veilborn or tabletop-RPG services in the codebase: | Service | Description | | ----------------- | ------------------------------------ | | **svc-metaverse** | 3D VR/AR immersive meditation spaces | ### Infrastructure Services (4) These services maintain the health, safety, and resilience of the entire Lilith fleet. They do not serve user features directly but underpin every other cluster: | Service | Description | | ------------------------------- | -------------------------------------------------- | | **svc-observability** | SLO definitions, error budgets, alerting | | **svc-operational-excellence** | Operational excellence automation | | **svc-multi-region-resilience** | Active/active multi-region with automatic failover | | **svc-safety-automation** | AI safety evaluation and red-team automation | --- ## Library Architecture ### 9 Shared Libraries `libs/lilith/` contains nine packages that provide Lilith-specific shared infrastructure. Cross-cutting concerns (config, errors, logging, metrics, tracing, testing, types) are provided by monorepo-wide `@oshun/*` packages rather than duplicated here — for example `@lilith/service-lib` declares `@oshun/tracing`, `@oshun/logging`, `@oshun/metrics`, `@oshun/errors`, and `@oshun/types` as direct dependencies. ``` libs/lilith/ common/ @lilith/common Audit logger, CSPRNG IDs, HTTP status, language detection, session store, server/service templates continuous-video-policy/ @lilith/continuous-video-policy Crisis-frame, narrative-cadence, persona-cap, sensitive-topic, strobe policy checks event-handlers/ @lilith/event-handlers Cross-domain event subscriptions with WebSocket fan-out event-publisher/ @lilith/event-publisher Typed domain-event publishing to @oshun/event-bus fastify-core/ @lilith/fastify-core Fastify service bootstrap, health routes, error handler, middleware registry partner-sdk/ @lilith/partner-sdk External partner SDK with auth flows sdk/ @lilith/sdk TypeScript client + generated OpenAPI types service-lib/ @lilith/service-lib LilithLogger, type-safety validator, typed test helpers sophia-adapter/ @lilith/sophia-adapter Knowledge-access, knowledge-graph, embedding adapters bridging Lilith to Sophia ``` ### Key Library Details **`@lilith/fastify-core`** is the Fastify bootstrap layer shared by all `svc-*` services. `createServiceServer(options)` returns `{ app, start, shutdown }`. The package exports `quickStart`, health routes (`registerHealthRoutes`, `createHealthHandler` — Kubernetes liveness/readiness), error handling (`registerErrorHandler`, `createErrorResponse`, `createErrorHelper`), a `MiddlewareRegistry`, and a typed error hierarchy: `ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServiceUnavailableError`. **`@lilith/service-lib`** exports `LilithLogger` (the structured logger used by the BFF and other services), a type-safety validator/suggestions module, and typed test helpers. Its runtime dependencies bundle all the common infrastructure that individual services would otherwise have to wire separately: `fastify`, `@fastify/cors`, `@fastify/websocket`, `ioredis`, `pg`, `@elastic/elasticsearch`, `axios`, `ajv` + `ajv-formats`, `aws-sdk`, `jsonwebtoken`, `isomorphic-dompurify`, `validator`, and `semver`. **`@lilith/sophia-adapter`** is the bridge between Lilith's domain objects and Sophia's knowledge APIs. Three adapters handle distinct concerns: `KnowledgeAccessAdapter` (content bundles and access policies), `KnowledgeGraphAdapter` (entity and relation graph), and `EmbeddingAdapter` (vector search). Failures raise `SophiaAdapterError`. This adapter is the **only** mechanism through which Lilith reads from or writes to Sophia's knowledge platform — the boundary enforces clean separation of the wellness experience surface from the knowledge corpus management surface. **`@lilith/event-publisher` / `@lilith/event-handlers`** provide typed publishing and cross-domain subscription over `@oshun/event-bus` (Redis Streams). See the specifications document for the full event catalog. --- ## Data Flow ### Primary Request Flow All client traffic enters through the BFF. The BFF validates auth, shapes responses, and routes to the appropriate `svc-*` service or directly to the Sophia adapter. Services independently read and write their own PostgreSQL schemas via Knex.js: ``` Client (Web / Mobile / Desktop) │ ▼ BFF GraphQL (Mercurius) + REST proxy Response shaping, SSE chat streaming │ ┌────┼────┬────┬────┬────┐ ▼ ▼ ▼ ▼ ▼ ▼ Auth Conv AI Cont Med Sophia ... (svc-* services) (adapter) │ │ │ ▼ ▼ ▼ Postgres Redis Elasticsearch Sophia (Knex) (ioredis) (search/logs) APIs │ MinIO (S3) Elasticsearch (media) (search/logs) ``` ### AI Conversation Flow When a user sends a message, the request flows through the BFF's SSE streaming route, which fans out to `svc-conversation` for persistence, `svc-ai` for generation, and `svc-moderation` for safety screening before the response reaches the client: 1. User sends a message via the BFF's SSE streaming route. 2. The BFF forwards the message to `svc-conversation`, which creates the message record and dispatches the AI request. 3. `svc-ai` queries the Sophia knowledge APIs via `@lilith/sophia-adapter` for grounded context, then calls the LLM provider via `@isis/client`. 4. In parallel, `svc-moderation` safety-checks the response. 5. The approved response streams back through SSE to the client. ``` User sends message │ ▼ BFF (SSE streaming route) │ ▼ svc-conversation (creates message, dispatches to AI) │ ├──► svc-ai │ │ │ ├──► Sophia knowledge APIs (via @lilith/sophia-adapter, │ │ BFF /v1/kg/* and /v1/knowledge/ask routes) │ │ │ └──► LLM provider (via @isis/client) │ └──► svc-moderation (safety check) │ ▼ Response streamed via SSE → Client ``` ### Voice Conversation Flow Voice conversations run the same AI path as text, but with audio ingress and egress layers wrapping it. `svc-webrtc` handles the browser/mobile audio transport, while `svc-stt` and `svc-tts` translate between audio and text at each end: 1. User speaks; audio arrives at `svc-webrtc` (WebRTC SFU). 2. `svc-voice-pipeline` receives the duplex audio stream. 3. `svc-stt` converts speech to a text transcript. 4. The transcript enters the AI conversation flow (as above). 5. The AI's text response is synthesized to audio by `svc-tts`. 6. Audio is returned to the user; `svc-audio-handoff` manages cross-device continuity if the user switches devices mid-session. ``` User speaks │ ▼ svc-webrtc (WebRTC SFU) │ ▼ svc-voice-pipeline (duplex audio) │ ├──► svc-stt → text transcript │ │ │ ▼ │ [AI conversation flow as above] │ │ │ ▼ └──► svc-tts → audio response │ ▼ Audio returned to user │ svc-audio-handoff (cross-device continuity) ``` ### Meditation Session Flow A meditation session involves more downstream side-effects than a conversation: once the session completes, progress data, journaling prompts, streak notifications, and royalty credits all fire in parallel: 1. User initiates a session; `svc-meditation-core` performs safety checks and selects the appropriate mode. 2. Based on mode: GUIDED sessions fetch pre-recorded audio from MinIO; AI_GENERATED sessions request content from `svc-meditation-generation` (which calls `svc-ai`); GROUP sessions join a synchronized `svc-group-meditation` session; VOICE sessions route through `svc-voice-pipeline`. 3. While the session is active, biometrics are tracked via `svc-biometric`. 4. On session completion, several downstream effects trigger concurrently: - `svc-progress-sync` updates streaks and achievements. - `svc-journal` fires a post-session journaling prompt. - `svc-notification` sends a streak alert if a milestone was reached. - `svc-creator-royalty` credits the content creator if licensed content was used. ``` User starts session │ ▼ svc-meditation-core (safety check, mode selection) │ ├── GUIDED: fetch audio from MinIO ├── AI_GENERATED: request from svc-meditation-generation → svc-ai ├── GROUP: join synchronized svc-group-meditation session └── VOICE: route through svc-voice-pipeline │ ▼ Session active → biometrics tracked via svc-biometric │ Session complete │ ├──► svc-progress-sync (update streaks, achievements) ├──► svc-journal (post-session prompt) ├──► svc-notification (streak alert if milestone) └──► svc-creator-royalty (if licensed content) ``` --- ## Cross-Domain Integration Lilith does not call other domains directly over HTTP for domain events. Instead, all inter-domain signalling runs through `@oshun/event-bus` (Redis Streams), with `@lilith/event-publisher` for outbound events and `@lilith/event-handlers` for inbound subscriptions. The Sophia adapter is the sole exception: it uses direct HTTP calls because knowledge retrieval requires synchronous request-response semantics rather than fire-and-forget events. The table below summarizes all active integration points. The direction column shows which domain initiates the communication; the channel column shows how it crosses the domain boundary: | Integration | Direction | Channel | Purpose | | ---------------- | -------------- | ------------------------ | -------------------------------------------------------------------- | | Lilith → Hathor | Outbound event | `@oshun/event-bus` | Meditation / progress events for narrative + world systems | | Lilith → Isis | Outbound event | `@oshun/event-bus` | Meditation / generation / teacher-interaction events | | Lilith → Sophia | Outbound event | `@oshun/event-bus` | Meditation / journal / progress events for the knowledge platform | | Lilith ↔ Sophia | Outbound HTTP | `@lilith/sophia-adapter` | Knowledge access, knowledge-graph queries, embeddings | | Bellona → Lilith | Inbound event | `@oshun/event-bus` | Build-completed / export-ready notifications fanned out to clients | | Isis → Lilith | Inbound event | `@oshun/event-bus` | Generation job progress / completion / failure / asset notifications | | Sophia → Lilith | Inbound event | `@oshun/event-bus` | Index-updated notifications; invalidate cached search results | | Yemaya → Lilith | Inbound event | `@oshun/event-bus` | Project-updated notifications fanned out to connected clients | Lilith's generation surface is routed through the BFF (`isis-generation-routes.ts`, `/v1/capability/generation/*`) and `svc-ai`'s `@isis/client` dependency rather than a Lilith-local generation service. This boundary keeps high-GPU generation workloads inside Isis, which owns the RunComfy and ComfyUI execution infrastructure. --- ## Observability and Infrastructure ### Distributed Tracing Services are instrumented with OpenTelemetry via the monorepo `@oshun/tracing` package, which is a direct dependency of `@lilith/service-lib`. Every service built on `@lilith/fastify-core` therefore inherits tracing automatically. Traces are exported to Jaeger. `svc-observability` owns SLO definitions and trace collection. ### Metrics Prometheus metrics are exposed via the monorepo `@oshun/metrics` package. Representative metrics collected across the fleet include: - Request rate, error rate, and latency (by route and service) - Queue depth and job processing times - Cache hit/miss rates - LLM token usage and latency - Session completion rates ### Logging All services log structured JSON to stdout, collected by the Elasticsearch stack via `svc-observability`. Log levels: `error`, `warn`, `info`, `debug`. ### SLO Definitions `svc-observability` manages SLO definitions that define the platform's reliability contract with users: - API gateway availability (>99.9%) - AI conversation response latency (p99 < 3 s) - Meditation session start latency (p99 < 500 ms) - Payment processing success rate (>99.5%) --- ## Deployment Architecture ### Container Strategy Each service (`apps/lilith/svc-*`) builds to its own Docker image. The shared library stack is compiled into each service image at build time, so services are self-contained and deployable independently without shared runtime dependencies. ### Scaling Strategy Different service categories have fundamentally different scaling requirements. Stateless API services scale horizontally behind a load balancer; stateful services that maintain WebSocket connections need sticky sessions or shared Redis state; GPU-intensive generation workloads run on dedicated GPU node pools; and blockchain services are kept single-instance to avoid transaction ordering conflicts: | Tier | Service Examples | Scaling Approach | | ---------------- | ---------------------------------------------------- | ------------------------------------- | | Stateless API | bff, svc-auth, svc-content | Horizontal, load balanced | | Stateful streams | svc-conversation, svc-group-meditation | Sticky sessions or shared Redis state | | GPU-intensive | svc-meditation-generation, Isis generation workloads | GPU node pools | | Background | svc-indexer | Queue-depth-based autoscaling | | Blockchain | svc-blockchain, svc-settlement | Single instance with Redis mutex | ### Multi-Region Resilience `svc-multi-region-resilience` implements active/active multi-region failover, keeping the platform available even during regional outages: - Redis Sentinel or Cluster for cache/queue resilience - PostgreSQL streaming replication with automatic failover - Cross-region MinIO replication for media assets --- ## Technology Stack The technology choices below reflect three priorities: developer productivity (TypeScript end-to-end, consistent Fastify bootstrap), operational simplicity (Knex for per-service schema independence over Prisma), and client reach (Next.js PWA + React Native + Electron for web/mobile/desktop from a single codebase): | Layer | Technology | Rationale | | ------------------ | ------------------------------------ | ---------------------------------------------------------------- | | API Gateway | Fastify + Mercurius | High-performance Fastify; Mercurius for GraphQL with SSE support | | Services | Fastify 4/5 + `@lilith/fastify-core` | Consistent service bootstrap, health checks, OTEL | | Database | PostgreSQL via Knex.js | Knex chosen over Prisma for per-service migration flexibility | | Cache / Queues | Redis (ioredis + BullMQ) | Fast caching, pub/sub messaging, reliable job queues | | Retrieval Platform | Sophia search + knowledge graph APIs | Shared grounded retrieval and entity graph services | | Full-Text Search | Elasticsearch | Content search and structured log aggregation | | Object Storage | MinIO (dev) / S3 (prod) | S3-compatible media storage | | Web Client | Next.js 14 + React 18 | SSR/SSG, i18n, App Router, PWA capabilities | | 3D Graphics | Three.js / BabylonJS / R3F | WebGL-based 3D visualization in browser | | Mobile | React Native 0.73 | Cross-platform iOS/Android with native capabilities | | Desktop | Electron | Native OS integration for desktop | | Web3 | ethers.js 6, wagmi/viem | EVM chain integration with typed contract calls | | Voice (TTS) | AWS Polly | Production-quality TTS with multiple voices | | Observability | OpenTelemetry + Jaeger | Distributed tracing across the service fleet | | Testing | Vitest, Playwright, Detox, Storybook | Unit, E2E (web), E2E (mobile), visual regression | --- ## Design Principles The following six principles govern architectural decisions across the Lilith domain. New services and integrations should be evaluated against each one: 1. **Service autonomy** — Each service owns its database schema and migrates independently. No cross-service foreign keys in the database layer. This allows services to be deployed, scaled, and rolled back without coordination with other services. 2. **BFF as single external entry point** — All client traffic enters through the BFF. Direct client-to-service calls are not permitted. This simplifies auth, rate limiting, and response shaping, and gives a single place to enforce cross-cutting policies. 3. **Shared library stack, independent services** — The `svc-*` services share the `@lilith/fastify-core` + `@lilith/service-lib` foundation, ensuring consistent behavior for health checks, tracing, logging, and auth across the fleet without requiring each service to wire these concerns individually. 4. **Consciousness-tuned AI** — Grounded retrieval is delegated to Sophia's search and knowledge graph stack rather than maintained as Lilith-owned microservices. This keeps the wellness corpus and retrieval logic in one shared platform while preserving Lilith's domain-specific prompting and persona logic. 5. **Privacy by design** — Journal entries and biometric data are encrypted at rest. Analytics are anonymized. Consent is required for sensitive data processing. The `svc-anonymization` service ensures analytics cannot be de-anonymized. 6. **Safety guardrails at multiple layers** — Content moderation (`svc-moderation`) runs on all AI-generated content and user messages. Session safety checks (`svc-meditation-core`) ensure meditations are appropriate for the user's stated mental state. `svc-safety-automation` runs continuous red-team evaluation of AI safety properties. ## Source Verification This architecture document was checked against the actual codebase under `apps/lilith/*` and `libs/lilith/*`: the 78 `apps/lilith/` packages (69 `svc-*` services), the 9 `libs/lilith/` libraries, library `index.ts`/ `package.json` files, the BFF route registration in `app.impl.ts`, and the Solidity sources under `apps/lilith/contracts/contracts/`. Counts, package names, the library list, and the service clusters reflect that inventory.