Lilith — Technical Specifications

Technical reference for the Lilith consciousness-experience platform: package inventory, domain objects, state machines, event contracts, API surfaces, persistence, smart contracts, and configuration.

Grounding note. Every entity, enum, event, endpoint, and contract below is traceable to source under apps/lilith/* and libs/lilith/*. Where the codebase only scaffolds a capability, that is stated explicitly.

This document is the authoritative technical reference for engineers building on or maintaining Lilith. It covers the exact package inventory, type definitions, state machine transition tables, event payload shapes, API routes, database schemas, smart contracts, authentication implementation details, environment variables, and integration points — drawn directly from the source code. Where the architecture and feature docs provide context and rationale, this document provides the precise contracts.

Package Inventory#

Lilith is the largest domain in the Oshun monorepo. The code lives in two trees:

• apps/lilith/ — 78 packages: 9 non-service packages (bff, cli, contracts, desktop, locales, mobile, seed-corpus, shared, web) and 69 svc-* backend services.
• libs/lilith/ — 9 shared libraries.

Shared Libraries (libs/lilith/)#

The nine libraries provide Lilith-specific shared infrastructure. Each is a separate npm package under the @lilith/ scope:

Cross-cutting infrastructure (config, errors, logging, metrics, tracing, testing, types) is provided by monorepo-wide @oshun/* packages, not by Lilith-local libraries. @lilith/service-lib declares @oshun/tracing, @oshun/logging, @oshun/metrics, @oshun/errors, and @oshun/types as direct dependencies, so any service that imports @lilith/service-lib inherits the full @oshun/* observability stack automatically.

Backend Services (apps/lilith/svc-*)#

The 69 services group functionally as follows. Service maturity varies: some (svc-ai, svc-auth, svc-metaverse, svc-group-meditation, svc-tts) carry hundreds of source files, while several Web3 and commerce services (svc-dao-governance, svc-native-token, svc-tiered-subscription, svc-creator-royalty, svc-curricula) are single-app implementations of roughly 1,400–3,000 lines.

The following service names do not exist in the codebase: svc-veilborn-core, svc-veilborn-strategy, svc-generative-fractal, svc-comfyui, svc-rag, svc-knowledge, svc-vectordb, svc-spiritual-embeddings, svc-curator-admin. Knowledge ingestion and retrieval are delegated to Sophia through @lilith/sophia-adapter.

Shared Library Contracts#

@lilith/fastify-core#

@lilith/fastify-core is the standard bootstrap layer for all svc-* services. The primary factory is createServiceServer(options), which returns { app, start, shutdown }. A CreateServiceServerOptions object accepts a serviceName and an optional healthCheckFn returning service-specific health details. Health routes are Kubernetes-shaped (liveness/readiness).

Additional exports:

• quickStart — convenience wrapper for one-line service startup
• registerHealthRoutes, createHealthHandler — Kubernetes liveness/readiness
• registerErrorHandler, createErrorResponse, createErrorHelper — structured error handling
• MiddlewareRegistry, createMiddlewareRegistry — middleware composition

The package exports a typed error hierarchy for consistent HTTP error responses across all services:

ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, RateLimitError, ServiceUnavailableError.

@lilith/service-lib#

@lilith/service-lib is the common runtime dependency bundle for Lilith services. It exports LilithLogger (the structured logger used by apps/lilith/bff and other services), a type-safety validator/suggestions module, and typed test helpers (typed-mocks, test-helpers, test-types).

Runtime dependencies bundled in @lilith/service-lib (so individual services do not need to declare them 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#

@lilith/sophia-adapter is the sole interface through which Lilith reads from and writes to Sophia's knowledge APIs. It exposes three adapters, all configured from a shared SophiaAdapterConfig object (baseUrl, optional apiKey/bearerToken, timeout default 30000 ms, retries default 3, debug):

• KnowledgeAccessAdapter — maps Lilith ContentBundle, AccessPolicy, and AccessPass records to Sophia document/search/metadata APIs.
• KnowledgeGraphAdapter — maps LilithEntity/LilithRelation to Sophia's entity/relationship graph with entity resolution.
• EmbeddingAdapter — routes embedding and similarity-search requests to Sophia.

Failures from any adapter raise SophiaAdapterError, which carries operation, underlyingCause, and details. Static factory methods syncFailed, queryFailed, and embeddingFailed construct typed error instances for each failure mode.

Domain Objects#

The richest concrete domain model in the codebase belongs to svc-meditation-core, svc-conversation, and the bridging types in @lilith/sophia-adapter. The sections below document the exact type shapes from source.

Meditation Domain (apps/lilith/svc-meditation-core/src/types.ts)#

MeditationSession#

A MeditationSession is the central record for a user's practice attempt. It carries both the static configuration set at session creation and mutable runtime state (current stage, biometric readings, timestamps, pause accounting):

Supporting types used throughout the meditation domain:

• SessionConfig — session-creation input
• SessionSummary — reduced read model with targetDurationMinutes, actualDurationMinutes, stagesCompleted, totalBiometricReadings
• MeditationScript — voicePreset, stages, durationMinutes, tradition, intention, experienceLevel
• MeditationScriptStage, MeditationScriptSegment — narration content
• StageHistoryEntry — records entry and exit timestamps for each stage
• BiometricDataPoint — timestamped biometric reading
• SessionMetadata — voice, speed, cancel-reason, and free-form extension data

Meditation Modes (mode.ts)#

The DEFAULT_MODES constant defines exactly three session modes. The selectMeditationMode() function picks among them by preferred id, nearest session length, or experience level:

Conversation Domain (apps/lilith/svc-conversation/src/types.ts)#

The conversation domain models multi-participant threaded chat with full LLM integration. The core types form a containment hierarchy: a Conversation contains Threads; a Thread contains Messages:

• Message — id, thread_id/conversationId, role (user/assistant/system), content, metadata, created_at, parentId, tokens, model, edited, attachments, reactions.
• Thread — id, title, metadata, message_count, messages, resolved/resolvedAt/resolvedBy.
• Conversation — id, userId, title, description, model, messages, archived, pinned, tags, settings, participants, status (active/archived/deleted), messageCount.
• ConversationSettings — LLM sampling parameters: temperature, maxTokens, topP, topK, frequencyPenalty, presencePenalty, systemPrompt, stopSequences.
• Participant — userId, role (owner/member/viewer), joinedAt, lastSeenAt, permissions.
• Attachment — type (image/file/audio/video), url, name, size, mimeType.
• ChatResponse.finishReason — stop / length / tool_calls / content_filter.
• Tool / ToolCall — function-calling primitives for tool-use responses.
• Metrics read models: ConversationMetricsTotals, ConversationMetricsSnapshot, ConversationMetricsResponse, ConversationMetricsUpdate.
• IdempotencyRecord — ensures duplicate message submissions are safely deduplicated on ingest.

Knowledge-Bridge Domain (@lilith/sophia-adapter)#

These types define the objects that cross the Lilith–Sophia boundary. Lilith creates ContentBundle, AccessPolicy, and AccessPass records locally; the adapter translates them to Sophia's API format:

• ContentBundle — bundleId, contentKey, title, summary, category, tradition?, lessons[], media[], difficulty, estimatedHours, createdAt, updatedAt, status.
• AccessPolicy — policyId, bundleId, tier, accessType, expiresAt?, allowedRoles?, requiredTokens?, maxSeats?, currentSeats, price?, currency?, createdAt, status.
• AccessPass — passId, seekerAddress, seekerName, bundleId, policyId, tokenId?, transactionHash?, network?, grantedAt, expiresAt?, status, metadata.
• TokenRequirement — contractAddress, chainId, minBalance — used within AccessPolicy for on-chain token-gating.
• LilithEntity — id, type, name, properties — entities sent to the Sophia knowledge graph.
• LilithRelation — id, sourceId, targetId, type, properties? — edges sent to the Sophia knowledge graph.
• Graph result types: GraphQueryResult, GraphResultNode, GraphResultEdge, RelatedEntity (with hops and path), ResolvedEntity (with confidence and matchedFields).
• Embedding types: EmbeddingResult (vector, model, dimensions, tokenCount), SimilarityOptions (topK, minScore, filter), SimilarityResult (documentId, chunkId, text, score, metadata?).

Enumerations#

The table below lists all domain-level enums and union types, with their source file and complete value sets. These are the valid values that appear in database rows, event payloads, and API requests — use them verbatim:

State Machines#

Meditation Session State Machine#

svc-meditation-core/src/types.ts defines the transition tables that govern a MeditationSession. The machine has seven states, two of which are terminal. Understanding the valid transitions is important for any code that drives a session programmatically — sending an event from an invalid state results in an error transition rather than being silently ignored.

States: idle, preparing, active, paused, completing, completed, cancelled. completed and cancelled are terminal states with no outgoing transitions.

The STATE_TRANSITIONS table specifies which events are legal from each state:

The NEXT_STATE table is keyed by the ${state}:${event} TransitionKey and gives the resulting state for each valid transition:

Within an active session, content delivery progresses through five ordered MeditationStage values: arrival → breath → body → visualization → integration. Stage transitions are recorded in stageHistory.

Event Contracts#

Lilith integrates with the monorepo @oshun/event-bus (Redis Streams), created with sourceDomain: 'lilith'. Events cross domain boundaries without requiring direct HTTP service-to-service calls, which keeps integration loose and allows independent scaling and deployment.

Events Published by Lilith (@lilith/event-publisher)#

LilithEventTypes defines exactly ten event types. LilithEventPublisher exposes one typed publish method per event and routes each to default target domains. All publish calls accept PublishOptions, which carry correlationId, causationId, targets (override default targets), and a metadata block (serviceName, userId, sessionId, deviceType, appVersion).

The publisher defaultTargets fallback is ['hathor', 'isis', 'sophia'].

Representative payload shapes for the most information-dense event types:

LilithMeditationCompletedPayload — the richest event payload, containing session outcome data that downstream domains (Hathor for narrative progression, Sophia for knowledge indexing) rely on:

• meditationId, sessionId, userId, contentId?
• type (LilithMeditationType), theme? (LilithMeditationTheme)
• plannedDurationSeconds, actualDurationSeconds
• completionStatus (LilithCompletionStatus), completionPercentage
• teacherId?, streakCount?, totalSessionsCount?
• feedback? — rating, mood_before, mood_after, notes

LilithProgressUpdatedPayload — progress milestones consumed by Hathor for world-state progression and Sophia for user modeling:

• userId, progressType (streak/milestone/achievement/level_up)
• currentStreak, longestStreak, totalMinutes, totalSessions
• achievementId?, achievementName?, level?, experiencePoints?

LilithJournalCreatedPayload — journal metadata routed to Sophia for knowledge graph enrichment:

• entryId, userId
• type (free_form/guided/gratitude/reflection/dream/intention)
• wordCount, promptId?, linkedMeditationId?, mood?, tags?, isPrivate

Events Consumed by Lilith (@lilith/event-handlers)#

LILITH_SUBSCRIPTIONS registers eight cross-domain subscriptions. setupLilithEventHandlers() requires a fully wired LilithHandlerServices bundle (cache, metrics, notifications, scheduler, rooms, projects) and calls assertServicesWired at startup — a missing service member fails fast rather than producing silent runtime errors.

Each handler invalidates caches, broadcasts to project WebSocket rooms, sends per-user notifications, and records metrics. No handler writes to authoritative storage — these are fan-out-only side effects.

Inbound payload types (IsisAssetGeneratedPayload, SophiaIndexUpdatedPayload, BellonaBuildCompletedPayload, BellonaExportReadyPayload, YemayaProjectUpdatedPayload, IsisJobCompletedPayload, IsisJobProgressPayload, IsisJobFailedPayload) are defined in event-handlers/src/types.ts.

API Surface#

BFF — the Client Entry Point (apps/lilith/bff)#

The BFF (@lilith/bff) is the single external entry point for all clients: a Fastify server that proxies backend services, exposes GraphQL via Mercurius, and streams AI chat responses over SSE. Its server.ts defaults SERVICE_NAME to bff and PORT to 4000; both are overridable via environment variables. The published library README documents an API base of port 4006.

app.impl.ts registers the following route groups (source files live under apps/lilith/bff/src/routes/ or src/api/):

registerContentRoutes, registerGraphQLRoutes, registerWebhookRoutes, registerAuthProxyRoutes, registerChatCoreRoutes, registerContentFallbackRoutes, registerCurriculaRoutes, registerErrorManagementRoutes, registerExperimentsAndModelsRoutes, registerHealthRoutes, registerIsisGenerationRoutes, registerMendeleyOAuthRoutes, registerObservabilityRoutes, registerPaperExportRoutes, registerPartnerRoutes, registerPersonaRoutes, registerReflectionsRoutes, registerScholarNotesRoutes, registerSophiaKnowledgeRoutes, registerSophiaSearchRoutes, registerUserRoutes.

Representative REST Routes (all /v1/-prefixed)#

The BFF exposes a broad REST surface covering all product areas. All routes are prefixed with /v1/:

The BFF also exposes Mendeley OAuth routes (mendeley-oauth-routes.ts), experiment/model routes, observability routes, and a chat-audio-routes group. A comfyui-routes.ts module exists alongside isis-generation-routes.ts under src/routes/.

Chat SSE Streaming#

chat-orchestration-streaming.ts streams an AI chat response as Server-Sent Events. The event sequence follows a strict protocol that clients must handle in order:

1. start — signals the beginning of a new stream; carries stream metadata.
2. token (repeated) — one content chunk per event, accumulated into the final response.
3. citations — RAG source attributions and retrieval metadata, emitted once after all tokens.
4. done — signals end of stream; carries usage metrics and the complete assembled response.

event: start       data: {streamId, persona, correlationId, conversationId, createdAt}
event: token       data: {index, text, correlationId}        (repeated)
event: citations   data: {citations, correlationId, retrievalResults?, ragMetadata?}
event: done        data: {streamId, totalTokens, correlationId, persona, response, metrics}

The metrics field on the done event carries tokens_in, tokens_out, and latency_ms. The SDK's ChatEventName union (token, citations, audio, done, error) is the client-side counterpart for typed SSE parsing.

BFF GraphQL Schema (apps/lilith/bff/src/api/graphql/schema.ts)#

The GraphQL layer focuses on content and knowledge-graph operations, not session or meditation management. Session-oriented flows use the REST API. The schema exposes:

type Query {
  content(id: ID!): Content
  contentBySlug(slug: String!): Content
  contents(first, after, last, before, filter, sort): ContentConnection!
  searchContent(query: String!, first, after, filter): SearchResult!
  suggestions(query: String!, limit: Int): [SearchSuggestion!]!
  author(id: ID!): Author
  authors(first, after, query): AuthorConnection!
  entity(id: ID!): Entity
  entities(first, after, filter): EntityConnection!
  entityTypes: [EntityType!]!
  relationship(id: ID!): Relationship
  relationshipsByEntity(entityId: ID!): [Relationship!]!
  relationshipTypes: [RelationshipType!]!
  knowledgeGraph(entityIds: [ID!]!, depth: Int, relationshipTypes): KnowledgeGraphResult!
}

type Mutation {
  createContent / updateContent / deleteContent / publishContent / archiveContent
  restoreContentVersion / bulkContentOperation
  createAuthor / updateAuthor / deleteAuthor
  createEntity / updateEntity / deleteEntity
  createRelationship / updateRelationship / deleteRelationship
}

type Subscription {
  contentUpdated(filter): ContentUpdateEvent!
  contentCreated: ContentUpdateEvent!
  contentPublished: ContentUpdateEvent!
  entityUpdated(types): EntityUpdateEvent!
}

svc-auth API (apps/lilith/svc-auth)#

svc-auth is one of the largest services in the codebase (164 source files). All routes are /v1/auth/-prefixed. The service covers every modern authentication pattern:

• Registration / login — POST /v1/auth/register, POST /v1/auth/register-pseudonymous, POST /v1/auth/login, POST /v1/auth/login-pseudonymous, POST /v1/auth/logout.
• Tokens — POST /v1/auth/refresh, POST /v1/auth/token, POST /v1/auth/revoke, POST /v1/auth/introspect, GET /v1/auth/jwks, GET /v1/auth/validate, GET /v1/auth/userinfo.
• Passwords — POST /v1/auth/password/change, /password/confirm, /password/reset, /password/reset-request, /password/reset/validate/:token, /password/requirements; POST /v1/auth/password-reset/request, /password-reset/confirm, POST /v1/auth/change-password.
• Two-factor / MFA — POST /v1/auth/2fa/enable, /2fa/disable, /2fa/verify, /2fa/validate, GET /v1/auth/2fa/status, /2fa/backup-codes/regenerate; SMS OTP under /2fa/sms/* (enroll, request, resend, validate, verify); POST /v1/auth/mfa/toggle.
• WebAuthn — POST /v1/auth/webauthn/registration/begin, POST /v1/auth/webauthn/authenticate.
• Magic link — POST /v1/auth/magic-link, /magic-link/request, /magic-link/authenticate.
• OAuth — GET /v1/auth/oauth/providers, /oauth/authorize, /oauth/callback, /oauth/google, /oauth/github, POST /v1/auth/social/link.
• Email verification — POST /v1/auth/verify/email, GET /v1/auth/verify/email/:token, /verify/status/:email.
• Sessions — GET /v1/auth/sessions, DELETE /v1/auth/sessions/:sessionId, /sessions/revoke-all.
• Account & data rights — GET /v1/auth/profile, /v1/auth/account, /v1/auth/export, /v1/auth/audit-logs; API keys under /v1/auth/api-keys and /v1/auth/api-keys/:keyId.

svc-auth source modules cover RBAC (rbac.ts, rbac-enhanced.ts, rbac-evaluator.ts, rbac-system-roles.ts), bot detection (bot-detection-*), a WAF (waf-middleware.ts, waf-rules.ts), IP filtering, breach detection, CAPTCHA, account lockout, encryption (envelope/KMS/Vault), audit logging, data-subject-request (DSR) handling, age verification, and parental consent.

svc-conversation API#

Real-time chat with threading. Routes live under svc-conversation/src/routes/ (participants.ts, sharing.ts, index.ts); the service supports WebSocket connections and a conversation reset endpoint.

SDK Client Surface (@lilith/sdk)#

APIClient makes REST calls to ${baseUrl}/v1/.... Its methods cover all platform domains:

• Chat — chat(ChatRequest) and streamChat() → POST /v1/chat; the latter parses the SSE stream.
• Conversations — listConversations, getConversation, deleteConversation, getConversationMessages, resetConversation → /v1/conversations[...].
• Lectures and TTS — generateLecture → POST /v1/lectures; ttsSynthesize → POST /v1/tts:synthesize.
• Ingestion and notifications — ingest → POST /v1/ingest; sendTestNotification → POST /v1/notifications/test.
• Consciousness catalog — methods for reading the mythology and consciousness domain catalog, each mapping to a specific REST path:
  • listVisionQuestJournals → /v1/mythology/vision-quests
  • listEgoDeathSimulations → /v1/consciousness/ego-death-simulations
  • listCollectiveUnconsciousMaps → /v1/consciousness/collective-unconscious
  • listNoosphereNetworks → /v1/consciousness/noosphere
  • listSimulationProbes → /v1/consciousness/simulation-theory
  • listDigitalImmortalityPrograms → /v1/consciousness/digital-immortality-prep
  • listDivinationSystems → /v1/divination/oracles
  • listCollaborativeMythologyWorlds → /v1/mythology/collaborations
  • listConsciousnessResearchProjects → /v1/consciousness/research-projects
  • Each has a matching get…(slug) detail call.
• Admin — adminUpdateUserRoles, adminGetUserAuditLogs, backup/restore (createBackup, listBackups, getBackupStatus, deleteBackup, createRestore, getRestoreStatus), system (getSystemHealth, getSystemConfig, setMaintenanceMode, getMaintenanceStatus), agents/workflows, and autoscaling (getAutoscalingStatus, executeScalingAction, getGPUMetrics).

LilithApiClient is a lower-level generic client exposing get/post/put/ patch/delete. The package re-exports an auth and seamless-auth module plus a SeamlessErrorClassifier.

Persistence#

Each service owns its schema and migrates independently with Knex.js (db/migrations/ + db/knexfile.ts). There are no shared cross-service foreign keys in the database layer — this is a hard architectural constraint, not just convention. Services communicate via events and HTTP, never via database joins.

svc-auth (10 migrations)#

The auth schema covers the full user lifecycle from registration through multi-device session management. Tables:

users, user_profiles, user_sessions, refresh_tokens, oauth_connections, verification_tokens, audit_logs, webauthn_credentials, plus check-constraint and session-column migrations.

svc-conversation (8 migrations)#

The conversation schema models threaded multi-participant chat with LLM metadata. Key tables and their most important columns:

threads — id (uuid), user_id, title, summary, an enum type (general, meditation_guidance, spiritual_discussion, learning_session, reflection, counseling, q_and_a), persona_id, persona_name.

messages — id (uuid), thread_id (FK → threads, cascade), enum role (user, assistant, system, tool), user_id, content, content_html, content_parts (jsonb), enum type (text, audio, image, mixed, system_notification, tool_call, tool_result), sequence_number, parent_id (self-FK), model, model_version, prompt_tokens, completion_tokens, total_tokens.

Additional tables: message_citations, message_feedback, conversation_summaries, conversation_participants, conversation_shares.

svc-meditation-core (6 migrations)#

The meditation core schema persists session state, user progress, and scheduling. The primary table:

meditation_sessions — session_id (pk, string), user_id (uuid, indexed), completed_at, duration_minutes, actual_duration_minutes, mode, tradition, guidance_level, intention, biometric_summary (jsonb), stages_completed, rating (smallint, 1–5), notes, created_at, updated_at (with update_updated_at_column() trigger).

Additional tables: meditation_achievements, meditation_goals, meditation_streaks, meditation_schedules, plus a check-constraint migration.

svc-meditation-core ships PostgreSQL-backed storage classes — postgres-progress-storage.ts, postgres-schedule-storage.ts, postgres-streak-storage.ts — as reusable modules.

Other Stores#

Beyond PostgreSQL, Lilith uses three additional storage systems:

• Redis — caching, session storage (svc-conversation has a session/redis-store.ts alongside a memory-store.ts), pub/sub fan-out, and job queueing via BullMQ.
• Elasticsearch — content search and structured log aggregation (@lilith/service-lib ships an @elastic/elasticsearch client dependency).
• Object storage — S3-compatible (MinIO in dev, S3 in prod) for media and audio; svc-ai depends on @aws-sdk/client-s3 and s3-request-presigner.

Smart Contracts#

Smart contracts live in apps/lilith/contracts (@lilith/contracts), built with Hardhat and Foundry. The production Solidity sources under contracts/contracts/ define the on-chain access and rights infrastructure:

Upgradeable variants exist under contracts/upgradeable/ (AccessTokenUpgradeable, ContentLicenseNFTUpgradeable, CreatorRoyaltiesUpgradeable, IdentityReputationUpgradeable). A FlashLoanGuard security mixin lives under contracts/security/, and reentrancy/malicious-recipient mocks under contracts/mocks/. All production contracts inherit OpenZeppelin Ownable2Step, Pausable, ReentrancyGuard. Deployment scripts target localhost (Hardhat), Sepolia, and Polygon.

The following contract names do not exist in the codebase: LilithToken, LilithGovernance, LilithStaking, LilithNFT, LilithBridge. The on-chain surface is access-token, content-licensing, royalty, and identity-reputation — not a single named platform token contract.

Authentication#

JWT#

svc-auth issues and validates JWTs. RSA key management lives in rsa-keys.ts and jwt-security.ts/jwt-utils.ts. The service exposes a JWKS endpoint (GET /v1/auth/jwks) so other services can fetch public keys for offline validation, and an introspection endpoint (POST /v1/auth/introspect) for active token inspection. jsonwebtoken is a @lilith/service-lib dependency, so all services have JWT utilities available without additional declarations.

Passwordless and Multi-Factor#

svc-auth implements every common MFA and passwordless pattern:

• WebAuthn/FIDO2 — webauthn-routes.ts, passkeys stored in device secure enclave; phishing-resistant by design.
• TOTP — totp-service.ts, compatible with Google Authenticator and Authy.
• SMS OTP — sms-otp-service.ts, twilio-sms.ts; Twilio is the delivery provider.
• Magic links — magic-link-routes.ts; time-limited, single-use login links delivered via email.
• OAuth — oauth-service.ts, oauth-providers.ts; Google and GitHub observed as active providers.

Password security is enforced through password-validation.ts and password-requirements.ts, with password-history.ts preventing reuse and breach-detection.ts checking credentials against known breach databases.

API Keys#

API-key issuance and management are handled under /v1/auth/api-keys (api-key-routes.ts). The BFF partner routes additionally manage partner-scoped API keys under svc-partner-api.

Pseudonymous Identity#

svc-auth supports pseudonymous registration and login (pseudonymous-auth.ts, /v1/auth/register-pseudonymous, /v1/auth/login-pseudonymous) for users who do not wish to provide personally identifying information.

Configuration#

Configuration is loaded and validated at service startup using loadAndValidateConfig from @oshun/config/legacy with a baseServiceSchema. Required variables cause a fast-fail at startup rather than producing silent runtime errors when a key is missing.

Observed Environment Variables#

svc-ai additionally relies on AWS credentials for S3 access via the AWS SDK. Service ports beyond the BFF are assigned per service through the same PORT env mechanism rather than a fixed global map.

Local Infrastructure#

The dev docker-compose.dev.yml provisions all dependencies a developer needs to run Lilith locally. Core services started by default:

• PostgreSQL (pgvector/pgvector:pg16) with PgBouncer connection pooling
• Redis 7
• MinIO (S3-compatible object storage)
• Elasticsearch 8.11
• Mailpit (local email capture)
• Jaeger (distributed tracing)

Optional profiles: Qdrant (vectors), Kafka (streaming), Neo4j (graph), Prometheus and Grafana (observability dashboards).

Integration Points#

Inter-Service Communication#

Lilith services communicate through three mechanisms, each suited to different interaction patterns:

1. HTTP — synchronous request-response calls between services (Axios is bundled in @lilith/service-lib). Used when the caller needs an immediate result.
2. @oshun/event-bus (Redis Streams) — asynchronous domain events published by @lilith/event-publisher and consumed by @lilith/event-handlers. Used for cross-domain side-effects that do not require a synchronous response.
3. WebSocket — real-time bidirectional communication for chat (svc-conversation), data sync (svc-real-time-sync, svc-sync), group meditation (svc-group-meditation), and the event-handlers' client fan-out.

Cross-Domain Integration#

The BFF brokers Isis generation through isis-generation-routes.ts and the /v1/capability/generation/* routes; svc-ai depends directly on @isis/client for LLM calls.

External Providers#