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:

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:

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.

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:

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:

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:

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:

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:

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:

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:

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:

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:

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):

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.