Eve library

Lilith Domain API Overview

Guide

Revision 1

On this page

Lilith is the consciousness and spiritual exploration domain of the Oshun platform. It is a large-scale microservice architecture with 80+ services that communicate through a central BFF (Backend-for-Frontend) gateway. The BFF aggregates, orchestrates, and proxies requests to downstream services, providing a unified API surface for web, mobile, and CLI clients.


Architecture Summary#

BFF Gateway#

Property Value
Service @lilith/bff
Framework Fastify
Default Port 3001
GraphQL Mercurius (at /graphql)
Auth JWT Bearer tokens + test token support
Source apps/lilith/bff/src/

The BFF is the only service that external clients communicate with directly. All other microservices are internal and reachable only through the BFF's service proxy layer.

Backend Service Registry#

The BFF routes requests to the following backend services:

Service Default Port Timeout Retries Purpose
auth 3003 5s 3 Authentication, authorization, tokens
conversation 3002 5s 3 Conversation threads and history
ai 3004 30s 1 LLM inference and AI processing
rag 3005 10s 2 Retrieval-Augmented Generation
knowledge 3006 5s 3 Knowledge graph and ontology
tts 3007 15s 1 Text-to-speech synthesis
stt 3008 15s 1 Speech-to-text recognition
media 3009 5s 3 Media asset storage and retrieval
content 3010 5s 3 Scholarly content management
moderation 3011 5s 2 Content moderation and safety
notification 3012 5s 3 Push and email notifications

Service URLs can be overridden via environment variables (e.g., AUTH_SERVICE_URL, AI_SERVICE_TIMEOUT). Each service also supports regional URL configuration for geo-sharding via <SERVICE>_SERVICE_REGIONAL_URLS (JSON) and <SERVICE>_SERVICE_DEFAULT_REGION.


Authentication#

The BFF uses JWT Bearer tokens for authentication:

text
Authorization: Bearer <jwt_token>

Protected endpoints use the requireAuth pre-handler hook. Test tokens (playwright-test, test-token, test-*) are recognized in non-production environments and map to a default test user.


REST API Endpoints#

Health & Observability#

Method Path Auth Description
GET /health No Basic health check
GET /v1/health No Extended health with dependency checks
GET /v1/health/deep No Deep health probing downstream services
GET /metrics No JSON or Prometheus metrics (Accept header)
GET /v1/metrics No Detailed BFF metrics

Authentication (Proxy to auth service)#

Method Path Auth Description
POST /v1/auth/register No Register a new user
POST /v1/auth/login No Login with credentials
POST /v1/auth/refresh No Refresh JWT token
POST /v1/auth/logout Yes Invalidate current session

Login Request Example#

json
{
  "email": "user@example.com",
  "password": "secure-password"
}

Login Response#

json
{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "rt_abc123...",
  "user": {
    "id": "usr_001",
    "email": "user@example.com",
    "role": "user"
  }
}

Chat & AI Conversation#

The chat endpoints are the core of the Lilith experience. They support JSON responses, SSE streaming, personalized responses via personas, and comparative multi-persona queries.

Method Path Auth Description
POST /v1/chat Yes Send a chat message (JSON response)
POST /v1/chat/stream Yes Send a chat message (SSE streaming response)
POST /v1/chat/personalized No Get a persona-personalized response
POST /v1/chat/comparative No Query 2-5 personas simultaneously
POST /v1/chat/audio Yes Audio-based chat (speech-to-text -> AI -> TTS)

Chat Request Example#

json
{
  "message": "What does the Bhagavad Gita say about dharma?",
  "personaId": "persona_krishna",
  "conversationId": "conv_001",
  "options": {
    "model": "claude-3-opus",
    "temperature": 0.7,
    "maxTokens": 2000,
    "stream": false
  }
}

Comparative Chat Request#

json
{
  "question": "What is the nature of suffering?",
  "personaIds": ["persona_buddha", "persona_seneca", "persona_rumi"],
  "options": {
    "maxTokens": 1500
  }
}

Requires 2-5 persona IDs. Returns parallel responses from each persona.

SSE Streaming Response#

When using /v1/chat/stream, the response uses Server-Sent Events:

text
data: {"type":"start","conversationId":"conv_001"}

data: {"type":"token","content":"The"}

data: {"type":"token","content":" Bhagavad"}

data: {"type":"done","usage":{"promptTokens":150,"completionTokens":800}}

Streaming supports backpressure handling and idempotency caching for non-streaming responses.

Personas#

Personas represent spiritual, philosophical, and intellectual archetypes that shape AI responses (e.g., Buddha, Rumi, Seneca, Krishna).

Method Path Auth Description
GET /v1/personas No List all personas
GET /v1/personas/:id No Get persona details
GET /v1/personas/categories No List personas grouped by category
GET /v1/personas/personalized No Get personalized persona suggestions

Users & Preferences#

Method Path Auth Description
GET /v1/users/:userId/language-preferences No Get user language preferences
POST /v1/users/:userId/language-preferences No Update language preferences

Supported languages: en, es, fr, de, it, pt, zh, ja, ko, ar, hi, ru.

Conversation Context & History#

Method Path Auth Description
GET /v1/conversations/:threadId Yes Get conversation context and history
POST /v1/conversations Yes Create a new conversation thread

Content Management#

The content API provides CRUD operations for scholarly and spiritual texts, commentaries, translations, lectures, and multimedia content. Mounted at /api/v1/content.

Method Path Auth Description
GET /api/v1/content No List content with pagination/filter
POST /api/v1/content Yes Create content
GET /api/v1/content/:id No Get content by ID
PUT /api/v1/content/:id Yes Update content
DELETE /api/v1/content/:id Yes Delete content
POST /api/v1/content/:id/publish Yes Publish content
POST /api/v1/content/:id/archive Yes Archive content
GET /api/v1/content/:id/versions No Get version history
POST /api/v1/content/:id/restore/:ver Yes Restore a previous version
GET /api/v1/content/search No Full-text search with facets
POST /api/v1/content/bulk Yes Bulk operations

Webhooks#

Method Path Auth Description
GET /api/v1/webhooks Yes List webhook subscriptions
POST /api/v1/webhooks Yes Create webhook subscription
GET /api/v1/webhooks/:id Yes Get webhook details
PUT /api/v1/webhooks/:id Yes Update webhook
DELETE /api/v1/webhooks/:id Yes Delete webhook

Curricula & Learning Paths#

Method Path Auth Description
GET /v1/curricula No List curricula
GET /v1/curricula/:id No Get curriculum details
POST /v1/curricula Yes Create curriculum

Scholar Notes#

Method Path Auth Description
GET /v1/scholar-notes Yes List user's scholar notes
POST /v1/scholar-notes Yes Create a note
GET /v1/scholar-notes/:id Yes Get a note
PUT /v1/scholar-notes/:id Yes Update a note
DELETE /v1/scholar-notes/:id Yes Delete a note

Reflections#

Method Path Auth Description
GET /v1/reflections Yes List user's reflections
POST /v1/reflections Yes Create a reflection
GET /v1/reflections/:id Yes Get a reflection

Experiments & A/B Testing#

Method Path Auth Description
GET /v1/experiments No List active experiments
POST /v1/experiments/assign No Assign experiment variant

AI Models#

Method Path Auth Description
GET /v1/models No List available AI models
POST /v1/models/negotiate No Negotiate best model for request

Dashboard & Aggregation#

Method Path Auth Description
GET /v1/dashboard Yes Aggregated dashboard data
POST /v1/aggregation Yes Custom aggregation query
POST /v1/bulk Yes Bulk operations across multiple entities

Circuit Breaker & Error Management#

Method Path Auth Description
GET /v1/circuit-breaker No Overview of all circuit breakers
GET /v1/circuit-breaker/:serviceName No Details for a specific service
GET /v1/errors No Error normalization status
POST /v1/errors/test No Test error normalization

ComfyUI Integration#

Method Path Auth Description
POST /v1/comfyui/generate Yes Submit a ComfyUI generation workflow
GET /v1/comfyui/workflows No List available workflows

Partner & Mythology Content#

Method Path Auth Description
GET /v1/partners No List partner integrations
GET /v1/mythology No Browse mythology content
GET /v1/research No Browse consciousness research

Comparative Views#

Method Path Auth Description
POST /v1/comparative No Parallel persona query with caching

Tracing Configuration#

Method Path Auth Description
POST /v1/config/tracing No Update tracing config
POST /v1/tracing/test No Generate test trace

GraphQL API#

The BFF exposes a GraphQL endpoint via Mercurius at /graphql. In non-production environments, an interactive GraphQL playground is available. Real-time subscriptions are enabled.

Schema Overview#

The GraphQL schema covers scholarly content management with the following root types:

Queries#

Query Description
content(id: ID!) Get a single content item
contentBySlug(slug) Get content by URL slug
contents(...) Paginated content list with filters/sort
searchContent(...) Full-text search with facets
suggestions(query) Autocomplete suggestions
author(id: ID!) Get an author
authors(...) Paginated author list
entity(id: ID!) Get a knowledge graph entity
entities(...) Paginated entity list with type filter
entityTypes List all entity types
relationship(id) Get a relationship between entities
relationshipsByEntity(entityId) Get all relationships for an entity
relationshipTypes List all relationship types
knowledgeGraph(...) Subgraph traversal with depth control

Mutations#

Mutation Description
createContent(input) Create a content item
updateContent(id, input) Update a content item
deleteContent(id) Delete a content item
publishContent(id) Publish to public
archiveContent(id) Archive content
restoreContentVersion(id, ver) Restore a previous version
bulkContentOperation(input) Bulk publish/archive/delete
createAuthor(input) Create an author
updateAuthor(id, input) Update an author
deleteAuthor(id) Delete an author
createEntity(input) Create a knowledge entity
updateEntity(id, input) Update an entity
deleteEntity(id) Delete an entity
createRelationship(input) Create a relationship
updateRelationship(id, input) Update a relationship
deleteRelationship(id) Delete a relationship

Subscriptions#

Subscription Description
contentUpdated(filter) Notified when content changes
contentCreated Notified when new content is created
contentPublished Notified when content is published
entityUpdated(types) Notified when entities change

Key Types#

  • ContentType enum: TEXT, DOCUMENT, MANUSCRIPT, COMMENTARY, TRANSLATION, ARTICLE, LECTURE, AUDIO, VIDEO
  • EntityType enum: PERSON, PLACE, CONCEPT, EVENT, TEXT, TRADITION, SCHOOL, DEITY, SYMBOL
  • RelationshipType enum: REFERENCES, CITES, RESPONDS_TO, INFLUENCES, INFLUENCED_BY, TEACHER_OF, STUDENT_OF, BELONGS_TO, LOCATED_IN, CONTEMPORARY_OF, ASSOCIATED_WITH
  • ContentStatus enum: DRAFT, PENDING_REVIEW, APPROVED, PUBLISHED, ARCHIVED, RETRACTED

Pagination uses Relay-style connections with edges, node, cursor, and PageInfo.

Example GraphQL Query#

graphql
query SearchContent($query: String!) {
  searchContent(query: $query, first: 10) {
    content {
      edges {
        node {
          id
          title
          type
          authors {
            name
            tradition
          }
          metadata {
            language
            era
            tags
          }
          status
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount
    }
    facets {
      traditions {
        value
        count
      }
      eras {
        value
        count
      }
    }
  }
}

Example Mutation#

graphql
mutation CreateContent($input: CreateContentInput!) {
  createContent(input: $input) {
    id
    title
    slug
    status
    version
    createdAt
  }
}

Variables:

json
{
  "input": {
    "type": "COMMENTARY",
    "title": "On the Nature of Consciousness in the Upanishads",
    "authorIds": ["author_001"],
    "description": "A modern commentary on Mandukya Upanishad",
    "metadata": {
      "language": "en",
      "tradition": "Hindu",
      "era": "Modern",
      "tags": ["upanishads", "consciousness", "mandukya"]
    },
    "status": "DRAFT",
    "visibility": "AUTHENTICATED"
  }
}

Middleware Stack#

The BFF applies the following middleware in order:

  1. Security & Auth -- JWT validation, permission levels, IP filtering, WAF, bot detection
  2. Experiment Headers -- A/B test assignment via request headers
  3. Response Shaping -- Per-client response optimization (mobile vs desktop)
  4. Compression -- Adaptive response compression
  5. Request Hooks -- Request counting, duration tracking, route-level metrics
  6. Geo-Sharding -- Region-aware routing to closest service instance
  7. Error Normalization -- Consistent error format across all upstream services

Circuit Breaker#

Every upstream service call passes through a circuit breaker. When a service fails repeatedly, the circuit opens and subsequent requests receive mock fallback responses instead of timing out. Circuit breaker state is observable via the /v1/circuit-breaker endpoint.

Mock Fallbacks#

When a downstream service is unavailable, the BFF can return curated mock responses for critical paths. Mock fallback domains include:

  • Collaborative mythology
  • Collective unconscious
  • ComfyUI generation
  • Consciousness research
  • Digital immortality
  • Divination & oracles
  • Ego death exploration
  • Noosphere networks
  • Simulation probes
  • Vision quest (Lakota, Plains traditions)

Streaming & Backpressure#

SSE streaming responses implement backpressure handling to prevent memory exhaustion when clients consume data slowly. The streaming utilities provide:

  • initializeStreamingResponse -- Set SSE headers and prepare the stream
  • writeSseEventWithBackpressure -- Write events with flow control
  • streamItemsWithBackpressure -- Stream collections with per-item events
  • endStreamingResponse -- Clean up and close the stream

Idempotency#

Non-streaming chat responses are cached with a TTL of 5 minutes using an in-memory idempotency cache keyed by request hash. This prevents duplicate processing of identical requests.


Additional Lilith Services (Non-BFF)#

Beyond the BFF, the Lilith ecosystem includes many specialized services. Notable examples:

Service Area Description
CLI (apps/lilith/cli) Command-line interface for interacting with Lilith
Smart Contracts (apps/lilith/contracts) Ethereum/EVM contracts for NFTs, governance, royalties

The CLI provides commands for chat, content management, and service administration from the terminal.