Eve library

Oshun Ecosystem — Infrastructure & Dependency Registry

Other

Revision 1

On this page

This document is the authoritative reference for every infrastructure component, cloud service, external API, third-party service, and technology dependency across the Oshun monorepo. It is intended to be readable by a new engineer who needs to understand not just what is installed but why each piece exists and how it fits into the platform as a whole.

Oshun is a large AI-powered creative and consciousness platform spanning more than twenty primary domains — from the Lilith meditation experience and Yemaya creative studio, to the Maya game engine (Neith), the Iris AI coding assistant, and the Minerva formal-education platform. The dependency surface is correspondingly broad: GPU clouds, vector databases, Rust game-engine crates, formal theorem provers, MIDI protocol engines, and everything in between all live in the same monorepo.

The primary product domains are: Lilith, Yemaya, Isis, Sophia, Hathor, Bellona, Tara, Veritas, Nyx, Arete, Maat, Iris, Maya, Psyche, Minerva, Metis, Serwaa, Nisaba, Shakti, Calliope, Uzume, and Galatea. The libs/ directory also contains additional domain and shared-utility namespaces (Aglaea, Airmid, Aja, Aphrodite, Asase, Demeter, Euterpe, Hestia, Kuanyin, Mnemosyne, Neith, Nous, Oya, Seshat, Themis, and others) which are either early-stage domains or cross-cutting support libraries. This document focuses on infrastructure dependencies rather than cataloguing every domain.

Keep this document updated as services are added or removed.

Version notation: Versions follow the same conventions as the source files they are drawn from. ^x.y.z means compatible with that minor range (npm semver caret). >=x.y.z means any version at or above that floor (Poetry lower-bound). ~x.y.z means compatible with that patch range (npm semver tilde / Terraform approximate). x.y without qualifier is an exact or pinned version. latest means the image is not pinned and will pull the most recent available tag. The primary source of truth for TypeScript package versions is pnpm-workspace.yaml (the pnpm catalog section); for Python packages it is each service's pyproject.toml; for Docker image versions it is docker/docker-compose.dev.yml and domain-specific compose files.


Table of Contents#

  1. Cloud Providers & Compute
  2. Databases
  3. Message Queues & Event Streaming
  4. Object Storage & CDN
  5. AI / ML Services
  6. Authentication & Identity
  7. Payment & Billing
  8. Monitoring & Observability
  9. Email & Notifications
  10. Containerization & Orchestration
  11. CI/CD & Build Infrastructure
  12. Language Runtimes
  13. Backend Frameworks
  14. ORM & Database Clients
  15. Frontend Stack
  16. API Standards & Protocols
  17. Testing Frameworks
  18. External Content APIs
  19. Python Service Dependencies
  20. Rust / Cargo Ecosystem
  21. Domain-Specific Infrastructure
  22. Security & Secrets Management
  23. Tooling & Build Utilities
  24. Summary Counts

1. Cloud Providers & Compute#

Oshun runs on three cloud providers serving distinct roles. AWS is the primary production cloud for all services and data. GCP provides Firebase for mobile push notifications and Vertex AI for supplemental model hosting. Azure provides an optional Azure OpenAI endpoint that can be swapped in as an alternative to the primary OpenAI API. GPU-heavy workloads — AI image and video generation, model inference — run on RunPod, a dedicated GPU cloud that gives Oshun access to A100, H100, and RTX 4090 hardware on demand.


AWS (Amazon Web Services) — Primary Cloud#

Amazon Web Services is Oshun's primary production cloud. It hosts the Kubernetes cluster that runs all domain services, the managed PostgreSQL and Redis instances those services depend on, the object storage for media and model artefacts, the message queue infrastructure, and the secrets/key management layer. Every domain from Lilith to Maat deploys into AWS.

Service What it is and how Oshun uses it
EKS (Elastic Kubernetes Service) AWS's managed Kubernetes offering. Runs all primary production domain workloads across per-domain namespaces (e.g. lilith-ns, yemaya-ns, isis-ns).
ECS (Elastic Container Service) AWS's simpler container orchestration service. Used as an alternative deployment path, activated via the deploy-ecs.yml CI workflow.
RDS AWS-managed PostgreSQL. The production host for Oshun's single PostgreSQL cluster, which stores data for all domains under per-domain schemas.
ElastiCache AWS-managed Redis. The production Redis cluster used for caching, sessions, BullMQ job queues, and rate limiting.
S3 AWS's object storage service. Stores generated media assets (images, video, audio), AI model cache files, and deployment artefacts.
CloudFront AWS's global CDN. Sits in front of S3 to deliver static assets and generated content to users with low latency worldwide.
SQS AWS Simple Queue Service. Message queueing used for decoupled inter-service task passing.
SNS AWS Simple Notification Service. Pub/sub fan-out for events that need to reach multiple subscribers simultaneously.
Lambda AWS serverless compute. Used for lightweight event-triggered functions that do not justify a persistent service.
CloudWatch AWS metrics and logging service. Collects AWS service metrics and hosts alarms for cost spikes and service failure rates.
Secrets Manager Encrypted credential store with KMS-backed encryption and automatic rotation. Holds RunPod endpoint IDs and all production API keys.
KMS AWS Key Management Service. Manages customer-managed encryption keys used to encrypt secrets, S3 buckets, and RDS at rest.
SSM Parameter Store Hierarchical configuration and secret distribution. Used alongside Secrets Manager for non-sensitive configuration values that services pull at startup.
MSK (Managed Streaming for Kafka) AWS-managed Apache Kafka cluster. The production event-streaming backbone that replaces the local Kafka container, used heavily by the Maat domain.
DynamoDB AWS's key-value NoSQL database. Used exclusively for Terraform remote state locking — not an application database.
EC2 AWS virtual machines. Used for self-hosted GitHub Actions GPU runners and any compute that does not fit into EKS.
VPC (multi-AZ) AWS Virtual Private Cloud. Provides network isolation across multiple availability zones for all Oshun workloads.

AWS SDK packages (Node.js):

  • @aws-sdk/client-cloudwatch ^3.600.0
  • @aws-sdk/client-s3 ^3.600.0
  • @aws-sdk/lib-storage ^3.600.0
  • @aws-sdk/s3-request-presigner ^3.600.0

Terraform provider: hashicorp/aws ~5.0 Primary region: us-east-1, with secondary and tertiary regions configured Relevant paths: deploy/terraform/, infra/terraform-v1/


RunPod — GPU Cloud#

RunPod is a GPU-specialised cloud platform that provides on-demand access to high-end Nvidia hardware. Oshun uses RunPod to run all AI image and video generation workloads that require GPU acceleration — specifically the ComfyUI visual workflow engine and Stable Diffusion/Flux inference endpoints that power the Isis generative factory. Running these on dedicated GPU cloud is significantly more cost-effective than provisioning GPU capacity on AWS.

Component What it is and how Oshun uses it
ComfyUI endpoint A node-based visual workflow runtime for chaining AI generation steps. Oshun runs custom ComfyUI nodes for consciousness-themed and sacred-geometry visual styles used across Lilith and Isis.
Stable Diffusion SDXL endpoint A RunPod serverless endpoint running SDXL for high-resolution image generation. Powers the Isis domain's image generation pipelines.
Flux endpoint A RunPod endpoint running the Flux model architecture for high-quality image generation, an alternative to SDXL for certain generation tasks.
Custom inference endpoints General-purpose model serving endpoints for any model not covered by the dedicated endpoints above.
Attribute Value
Hardware A100, H100, RTX 4090
Environment variables RUNPOD_API_KEY; endpoint IDs stored in AWS Secrets Manager
Docker images docker/runpod/ (base, comfyui, sd, flux, inference variants)
CI workflows .github/workflows/runpod-endpoint-*.yml
Relevant paths infra/terraform/secrets/runpod.tf, docker/runpod/

GCP (Google Cloud Platform) — Secondary#

Google Cloud Platform fills two specific gaps that AWS does not cover as well: mobile push notifications via Firebase and supplemental ML model hosting via Vertex AI.

Service What it is and how Oshun uses it
Vertex AI Google's managed ML platform. Used for hosting models that benefit from Google's TPU infrastructure or where Google-specific models are required.
Firebase Google's mobile and real-time backend service. Provides push notification delivery (APNs/FCM) for iOS and Android apps (Tara, Lilith mobile), and real-time database sync for collaborative session features.
BigQuery Google's serverless data warehouse. Configured for potential analytics use, available when large-scale event data needs to be queried.

Azure (Microsoft Azure) — Optional#

Azure's role in Oshun is narrow: it provides an alternative endpoint for OpenAI API calls. This is useful when primary OpenAI capacity is constrained or when data-residency requirements mandate using a specific Azure region.

Service What it is and how Oshun uses it
Azure OpenAI Microsoft's hosted version of OpenAI's API. Provides GPT-4 and other OpenAI models via Azure infrastructure. Can be swapped in as the OpenAI endpoint without code changes, since it uses the same OpenAI SDK.
Attribute Value
Environment variables AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT

2. Databases#

Oshun's database layer is structured around a single PostgreSQL cluster with per-domain schemas, extended with Redis for fast in-memory data, Qdrant for vector similarity search, Elasticsearch for full-text search and log aggregation, and Neo4j for graph-structured data in the Maat domain. Each domain writes to its own schema or database within the shared cluster, providing isolation without the overhead of running separate database servers per domain.


PostgreSQL — Primary OLTP#

PostgreSQL is the relational backbone of Oshun. Every domain from Yemaya to Veritas persists structured, transactional data here. The pgvector extension makes the same cluster capable of storing and querying high-dimensional embedding vectors alongside normal relational data, avoiding a separate vector database for use cases where approximate nearest-neighbour search at moderate scale is sufficient.

Attribute Value
Version 16 — image: pgvector/pgvector:pg16
ORM Prisma 5.20+ (TypeScript), SQLAlchemy (Python)
Connection pooling PgBouncer on TCP port 6432
Dev deployment Docker Compose
Prod deployment AWS RDS

Extensions:

Extension What it is and how Oshun uses it
pgvector Adds vector column types and approximate nearest-neighbour index operators to PostgreSQL. Allows embedding vectors (e.g. from text-embedding-3-large) to be stored and queried in the same database used for relational data.
pgcrypto Provides cryptographic functions (hashing, symmetric encryption) directly in SQL. Used for any column-level encryption requirements without leaving the database.
JSON/JSONB PostgreSQL's native semi-structured data types. Used for storing flexible metadata, AI generation parameters, and domain-specific configuration blobs alongside relational columns.

Domain schemas (each domain owns its own schema on the shared PostgreSQL cluster, initialised via per-domain SQL scripts in docker/init-scripts/):

Schema Domain
yemaya Creative studio
lilith Consciousness / meditation experience
isis Generative factory (AI image/video/audio pipelines)
iris AI coding assistant platform
sophia Research & knowledge
hathor Worldbuilding
bellona Build & bridge / asset export
calliope Music & composition
tara Meditation mobile app
maat Market intelligence
nisaba Ancient language & knowledge
shakti Wellness platform

Connection string env var: DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/oshun_dev


Redis — Cache, Sessions, Queues#

Redis is an in-memory data structure server used for workloads that require microsecond response times or pub/sub messaging. In Oshun it serves four distinct purposes simultaneously, separated by logical database indices: general API response caching, session token storage, the BullMQ background job queue backend, and rate-limiting counters. Logical database separation keeps these concerns from interfering with each other without requiring multiple Redis instances.

Attribute Value
Version 7-alpine
Client ioredis (Node.js), redis-py (Python)
Persistence AOF (Append-Only File) enabled
Max memory 96 MB with allkeys-lru eviction (development; production ElastiCache is sized separately)
Dev deployment Docker Compose
Prod deployment AWS ElastiCache

Logical database separation:

DB index What it stores
0 General cache — API responses, computed results, frequently read reference data
1 Sessions — user session tokens and short-lived authentication state
2 Events — pub/sub channels and Redis Streams for in-process domain event distribution
3 Job queues — BullMQ queue state for background generation, indexing, and transcoding jobs
4 Rate limiting — sliding window counters for per-user and per-IP request throttling

Connection string env var: REDIS_URL=redis://localhost:6379


Qdrant — Vector Database#

Qdrant is a purpose-built vector database optimised for high-dimensional nearest-neighbour search. Unlike the pgvector extension in PostgreSQL, Qdrant is designed exclusively for vector workloads and provides better throughput and richer filtering capabilities at scale. Oshun uses Qdrant for semantic search and memory retrieval across domains that require embedding-based lookup — most critically in Iris (hierarchical memory for the AI coding assistant), Sophia (knowledge retrieval), and Psyche (multimodal perception pipelines).

Attribute Value
Version latest in main dev compose; v1.7.4 pinned in Psyche-specific compose files
gRPC port 6334
HTTP port 6333
Storage /qdrant/storage persistent volume
Python client qdrant-client

Weaviate — Vector Database (Serwaa)#

Weaviate is an open-source, GraphQL-native vector database that can vectorise data at ingest using built-in ML modules, removing the need for a separate embedding step. In Oshun it is used specifically within the Serwaa AI assistant platform as an alternative vector store to Qdrant, particularly for configurations where integrated vectorisation simplifies the ingestion pipeline.

Attribute Value
Env vars WEAVIATE_URL, WEAVIATE_API_KEY
Used by Serwaa domain (serwaa/.env.example)

Elasticsearch — Search & Logs#

Elasticsearch is a distributed search and analytics engine built on Apache Lucene. It provides Oshun with full-text search capabilities significantly beyond what PostgreSQL's text search offers — particularly for fuzzy matching, relevance scoring, and searching across large document collections. In Oshun, Elasticsearch serves two roles: full-text content search (used in the Lilith and Sophia domains for searching meditation content and research material), and as the storage layer in the ELK Stack for centralised log aggregation.

Attribute Value
Version 8.11.0 — image: elasticsearch:8.11.0
Node.js client @elastic/elasticsearch ^8.17.0
Used by Lilith, Sophia domains (content search); ELK log aggregation stack

Development instance (docker-compose.dev.yml):

Attribute Value
JVM heap 256 MB–512 MB (-Xms256m -Xmx512m)
Security Disabled (xpack.security.enabled=false)
Cluster name Default (unnamed)

ELK Stack instance (infra/elk/docker-compose.elk.yml):

Attribute Value
Cluster name lilith-logs
JVM heap 2 GB (-Xms2g -Xmx2g)
Security Enabled (xpack.security.enabled=true, xpack.security.enrollment.enabled=true)

Neo4j — Graph Database#

Neo4j is a native graph database that stores data as nodes and relationships rather than rows and tables. It is purpose-built for traversing densely connected data — market relationships, competitive intelligence networks, entity graphs — where relational joins would become prohibitively expensive. In Oshun, Neo4j is used exclusively by the Maat domain (market intelligence platform) to model and query complex relationships between companies, markets, agents, and decisions. The production Maat configuration includes the APOC plugin (extended procedures) and the Graph Data Science (GDS) plugin for running ML algorithms directly on the graph.

Attribute Value
General dev version neo4j:5.14-community (Docker profile: graph)
Maat domain version neo4j:5.26.0-community (docker-compose.maat.yml — includes APOC + GDS plugins)
HTTP port 7474
Bolt port 7687
Maat env vars MAAT_NEO4J_URL, MAAT_NEO4J_USER, MAAT_NEO4J_PASSWORD, MAAT_NEO4J_DATABASE

DynamoDB — State Locking Only#

Amazon DynamoDB is a serverless key-value database. In Oshun it serves exactly one purpose: Terraform remote state locking. When multiple engineers or CI jobs run Terraform simultaneously, DynamoDB provides a distributed lock to prevent concurrent state mutations. It is not used as an application database.


3. Message Queues & Event Streaming#

Oshun uses three complementary messaging systems that operate at different scales and with different delivery guarantees. Kafka provides durable, high-throughput event streaming for inter-domain events that must be replayed or consumed by multiple services. BullMQ provides reliable background job processing for tasks like AI generation and media transcoding that need retry semantics and visibility. Redis Streams and NATS handle lightweight in-process or low-latency messaging where Kafka's overhead is unnecessary.


Apache Kafka — Event Streaming#

Apache Kafka is a distributed event-streaming platform designed for high throughput, durability, and replay. Unlike a traditional message queue, Kafka retains messages in ordered, append-only logs that multiple consumers can read at their own pace. In Oshun, Kafka is the backbone of the Maat domain, where market intelligence events, agent task assignments, simulation state updates, compliance alerts, and strategic decision records all flow through dedicated topics. In development Kafka runs as a Docker container; in production it is hosted on AWS MSK.

Attribute Value
Image confluentinc/cp-kafka:7.5.0
Internal broker kafka:9092
External port 29092
Auto topic creation Enabled
Replication factor 1 (development)
Prod deployment AWS MSK

Companion service: Zookeeper — confluentinc/cp-zookeeper:7.5.0 coordinates Kafka broker metadata and leader election. Node.js client: KafkaJS ^2.2.4

Configured topics:

Topic Purpose
maat.intelligence.market Carries raw market intelligence events — price signals, news items, and external data feeds consumed by the Maat intelligence service. Topic name is configurable via MAAT_TOPIC_INTELLIGENCE_MARKET (default: maat.intelligence.market).
maat.agents.tasks Distributes task assignments to Maat agent workers for parallel agent-based simulation execution.
maat.simulation.state Broadcasts simulation state snapshots so downstream consumers can observe market simulation progress in near real-time.
maat.compliance.alerts Publishes compliance alert events when the simulation or intelligence service detects regulatory or risk threshold breaches.
maat.strategy.decisions Records strategic decision events emitted by the Maat strategy service so they can be audited and replayed.

BullMQ — Background Job Queues#

BullMQ is a Node.js job queue library backed by Redis. It provides durable, prioritised queues with retry logic, dead-letter queues, and real-time job progress tracking. Oshun uses BullMQ for all long-running background tasks that originate from API requests but must not block the response — primarily AI content generation (images, video, audio) and media processing pipelines in the Isis domain.

Attribute Value
Package bullmq ^5.0.0
Backend Redis (DB 3)
Retry strategy Exponential backoff, 3 attempts

Queues — Lilith domain (libs/lilith/core/src/constants/index.ts):

Queue Purpose
email Sends transactional and notification emails via SendGrid. Enqueued by domain services that need to notify users asynchronously without blocking the request path.
push-notification Delivers mobile push notifications (FCM/APNs) to iOS and Android devices via Firebase. Used by Lilith and Tara for meditation reminders and session updates.
content-processing Handles media content processing pipelines — format conversion, metadata extraction, and thumbnail generation for uploaded and generated media assets.
moderation Asynchronously submits generated or user-uploaded content to moderation checks, flagging anything that breaches platform content policies.
analytics Processes and forwards analytics events for aggregation in the observability layer, decoupling analytics writes from the critical request path.

Queues — Isis domain (libs/isis/database/prisma/seed.ts):

Queue Purpose
generation-high High-priority AI asset generation requests — images via SDXL/Flux and audio via ElevenLabs/Cartesia. Jobs are enqueued by the Isis API and consumed by generation workers running on RunPod GPU endpoints.
upscaling Post-generation image upscaling jobs. After initial generation completes, upscaling workers enhance resolution and quality before the asset is committed to S3.
video-generation AI video generation jobs dispatched to Runway or other video model endpoints. Handles the longer-running video synthesis workloads separately from image generation.

Redis Streams — Lightweight Event Bus#

Redis Streams is a Redis data structure that functions as a persistent, ordered log of messages with consumer group semantics. Oshun uses Redis Streams as a lightweight in-process domain event bus in situations where Kafka's full overhead (separate broker, schema registry, replication) is not justified. It operates on Redis DB 2, sharing the existing Redis instance.


NATS — Lightweight Messaging#

NATS is an ultra-lightweight, high-performance publish/subscribe messaging system designed for cloud-native environments. It is used in Oshun as the event bus for the Uzume domain — the protocol and MIDI event system that handles real-time musical event routing and inter-component messaging in the Calliope music platform. NATS's low latency and simple subject-based routing make it well suited for the real-time nature of musical event streams.

Attribute Value
Client nats ^2.29.3 (Node.js)
Purpose Uzume protocol event bus and lightweight pub/sub for real-time musical event routing

4. Object Storage & CDN#

Object storage in Oshun holds the large binary assets that do not belong in a relational database: generated images and video, uploaded media, AI model weights cached between runs, and deployment artefacts. In development, MinIO provides an S3-compatible API locally so that no code changes are needed when moving to production. In production, AWS S3 serves as the storage layer with CloudFront distributing assets globally.

Service Deployment What it is and how Oshun uses it
MinIO Docker (dev) An open-source, S3-compatible object storage server. Runs locally in Docker so developers can work with bucket operations and presigned URLs without AWS credentials. API port 9000, admin console port 9001.
AWS S3 Managed (prod) Amazon's object storage service, used in production for all generated media assets, AI model weight caches, and CI/CD deployment artefacts.
CloudFront Managed (prod) Amazon's global content delivery network. Sits in front of S3 to serve generated and static assets from edge locations closest to each user, reducing latency for media-heavy domains like Isis and Yemaya.

MinIO env vars: S3_ENDPOINT=http://localhost:9000, S3_ACCESS_KEY=minioadmin, S3_SECRET_KEY=minioadmin

Maat buckets (created by docker/minio/init-maat-buckets.sh): maat-market-reports, maat-satellite-imagery, maat-financial-statements (with object locking), maat-compliance-documents (with object locking), maat-knowledge-base-artifacts — all with versioning enabled. Additional domain-specific buckets are created by application code at runtime as needed.


5. AI / ML Services#

Oshun is fundamentally an AI platform, and its AI service landscape reflects that. All AI providers are accessed through a unified abstraction layer in libs/shared/ai/src/providers/ and libs/isis/ai-providers/src/providers/, which means individual services are not coupled to specific provider SDKs. Providers can be swapped or mixed transparently depending on capability, cost, and availability. The table below covers every provider currently integrated.

Provider SDK / Package API Key Env Var What it is and how Oshun uses it
OpenAI openai ^4.0.0 (Node.js), openai>=1.58.0 (Python) OPENAI_API_KEY The primary general-purpose LLM and embedding provider. GPT-4 and GPT-4 Turbo power agent reasoning in Iris and content generation in Yemaya; DALL-E 3 provides an alternative image generation path; Whisper handles speech recognition; text-embedding-3-large generates vectors for semantic search across Sophia, Iris, and other domains.
Anthropic @anthropic-ai/sdk ^0.30.0 (Node.js), anthropic>=0.40.0 (Python) ANTHROPIC_API_KEY Claude 3.5 Sonnet, Opus, and Haiku. Used for long-context reasoning, complex content generation, and as the preferred model for Iris's multi-agent code intelligence tasks where extended context and careful reasoning matter more than raw speed.
Google AI @google/generative-ai ^0.21.0 GOOGLE_AI_API_KEY Gemini Pro and Gemini Vision. Used for multimodal generation tasks that require combining image understanding with text generation, and as an alternative inference path when cost or availability favours Google's infrastructure.
ElevenLabs elevenlabs ^1.0.3 (Python) ELEVENLABS_API_KEY Industry-leading text-to-speech and voice cloning API. Powers the AI voice narration in Lilith's meditation experience (where voice quality directly affects user experience) and the voice output engine in Psyche.
Deepgram deepgram-sdk ^3.0.2 (Python) DEEPGRAM_API_KEY Real-time and batch speech-to-text transcription. Used in Psyche for voice input processing and in Iris Voice for converting spoken developer instructions to text before passing them to the code intelligence pipeline.
Cartesia Cartesia client (Python) CARTESIA_API_KEY A real-time TTS synthesis API notable for very low first-token latency. Used in Iris Voice as an alternative to ElevenLabs where response speed is prioritised over maximum voice naturalness.
Replicate replicate ^0.34.0 REPLICATE_API_TOKEN A hosted platform for running open-source ML models. Used as an alternative inference path to RunPod for models that are available on Replicate's public model registry without requiring custom Docker images.
HuggingFace huggingface-hub (Python), transformers, sentence-transformers>=2.7.0 HF_HOME (cache) The largest repository of open-source ML models. Used to download model weights that are then served from RunPod or loaded locally, and to generate semantic embeddings via sentence-transformers for indexing content in Sophia, Iris, and Minerva.
Together AI Together client TOGETHER_API_KEY A distributed LLM inference platform that hosts popular open-source models (Llama, Mistral, etc.) at lower cost than proprietary APIs. Used in Oshun's AI abstraction layer as a cost-optimised path for high-volume inference tasks.
Groq Groq client GROQ_API_KEY A hardware-accelerated LLM inference service that achieves unusually high token throughput via custom LPU chips. Used in the AI routing layer for latency-sensitive paths where speed matters more than model capability.
Cohere Cohere client COHERE_API_KEY Provides NLP capabilities including high-quality text embeddings and reranking. Used for semantic search and document relevance reranking in Sophia and other knowledge-intensive domains.
Mistral AI Mistral client MISTRAL_API_KEY European-hosted LLM provider with cost-efficient open-weight models. Used as a fallback inference path and for tasks where European data-residency is preferred.
LiteLLM litellm>=1.34.0 (Python) — A Python library that provides a single, unified interface over more than 100 LLM providers. Used in Minerva as the abstraction layer so educational AI features are not tied to any single provider.
Stability AI RunPod endpoint — The company behind Stable Diffusion. SDXL (Stable Diffusion XL) runs as a dedicated RunPod endpoint to power image generation in the Isis generative factory.
Tavus Tavus API Tavus credentials A personalised AI video generation API that creates hyper-realistic talking-avatar videos from text. Used in the Psyche domain for AI-generated avatar video content.
Runway Runway API — A professional AI video generation and editing platform. Used in Oshun for video generation pipelines in the Isis domain, providing motion and video output alongside the image-focused SDXL/Flux endpoints.
Azure OpenAI openai SDK AZURE_OPENAI_API_KEY Microsoft's hosted OpenAI endpoint. Uses the same OpenAI SDK and API surface, making it a drop-in replacement for specific deployments where Azure infrastructure is preferred.
AWS Bedrock AWS SDK AWS_BEDROCK_ACCESS_KEY_ID, AWS_BEDROCK_SECRET_ACCESS_KEY, AWS_BEDROCK_REGION Amazon's managed AI inference service that hosts models from Anthropic, Meta, Mistral, and others via a unified AWS API. Configured as an additional inference path in Oshun, giving access to Claude on AWS infrastructure and to Bedrock-only models without leaving the AWS ecosystem. Region defaults to us-east-1.
AssemblyAI AssemblyAI SDK ASSEMBLYAI_API_KEY A speech-to-text and audio intelligence API with high accuracy, real-time transcription, and speaker diarisation capabilities. Used primarily within the Serwaa AI assistant platform as an alternative STT provider to Deepgram for transcribing meeting audio and voice inputs.

Relevant paths: libs/shared/ai/src/providers/, libs/isis/ai-providers/src/providers/


LLM Framework Abstractions#

Beyond direct provider SDKs, several higher-level frameworks manage chains of LLM calls, tool use, and orchestration logic in the Python services.

Library Language Version What it is and how Oshun uses it
LangChain Python >=0.3.0 A comprehensive framework for building LLM-powered applications, providing chains, agents, memory, and tool use abstractions. Used in Metis for structuring multi-step educational AI workflows that involve retrieval, generation, and evaluation steps.
LiteLLM Python >=1.34.0 A provider-agnostic LLM proxy library that normalises the API surface of every major LLM provider to the OpenAI interface. Used in Minerva so that theorem-proving and curriculum-generation logic can call any model without code changes.
ChromaDB Python >=0.5.0 An embedded, in-process vector database that requires no separate server. Used in Metis and in local development as a lightweight alternative to Qdrant for storing and querying document embeddings.
Model Context Protocol SDK TypeScript @modelcontextprotocol/sdk ^1.11.0 Anthropic's open standard for connecting AI models to external tools, data sources, and services. Allows Oshun's AI agents (particularly in Iris) to expose and consume MCP-compatible tool servers, enabling structured tool use that works across Claude and other MCP-aware models.

ComfyUI — Visual Workflow Runtime#

ComfyUI is an open-source, node-based workflow editor and runtime for AI image generation. Each node in a workflow performs a discrete operation (load model, sample latents, decode, upscale, apply LoRA), and the nodes are connected into a directed graph that defines the full generation pipeline. Oshun runs ComfyUI on RunPod with custom nodes developed specifically for the Lilith and Isis domains — including nodes for consciousness-themed visual styles, sacred geometry patterns, and spiritual aesthetics.

Attribute Value
Deployment RunPod GPU endpoint + Docker image
Custom nodes Consciousness, sacred geometry, spiritual styles
Docker image docker/runpod/comfyui/
Model downloads docker/runpod/base/scripts/download_models.py (CivitAI + HuggingFace)

6. Authentication & Identity#

Oshun's authentication layer handles user identity across a large number of domains and platforms — web apps, mobile apps, desktop apps, and service-to-service calls. It uses JWT tokens internally, supports OAuth 2.0 login via the most common identity providers, and manages all production secrets through HashiCorp Vault with a Kubernetes agent sidecar for automatic injection.


Internal Auth#

Technology What it is and how Oshun uses it
JWT JSON Web Tokens are compact, signed tokens used to represent authenticated identity. Oshun uses RS256 (asymmetric) or HS256 (symmetric) signed JWTs with an issuer of oshun-auth. Token claims carry subject, email, roles, and permissions, allowing services to verify requests without consulting a central auth service on every call.
jsonwebtoken ^9.0.3 The standard Node.js library for signing and verifying JWTs. Used to issue and validate access tokens in Oshun's auth service and across domain services that enforce token-based authentication.
bcrypt ^5.1.1 A Node.js native bcrypt binding for password hashing. Used to hash and verify user passwords at rest with the bcrypt adaptive algorithm, ensuring stored credentials remain secure even if the database is compromised.
bcryptjs ^2.4.3 A pure-JavaScript bcrypt implementation (no native bindings). Used as a fallback or in environments where native bcrypt bindings cannot be compiled (e.g. certain Lambda or WASM environments).
Database schema All user accounts, roles, permissions, and session records are stored in the oshun_auth schema on the shared PostgreSQL cluster.

OAuth 2.0 Providers#

Provider Env Vars What it is and how Oshun uses it
Google GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET Enables users to sign in with their Google account. Also used for Calendar integration in the Lilith domain's scheduling features.
GitHub — Allows developers to authenticate with their GitHub account. Particularly relevant for the Iris AI coding assistant, where linking GitHub identity enables repository access.
Discord — Supports login via Discord and powers community feature integrations for domains with social components.
Apple — Required for iOS apps published to the Apple App Store. Used in Lilith and Tara mobile apps.
Microsoft — Enables Microsoft account login and Teams integration for enterprise-oriented features.

HashiCorp Vault — Secrets Management#

HashiCorp Vault is an open-source secrets management platform that provides encrypted storage, dynamic secret generation, and fine-grained access control for sensitive credentials. In Oshun, Vault stores all production API keys, with a Kubernetes agent sidecar that automatically renders secrets as files or environment variables inside pods at startup. This means application code never handles raw secret values directly — they are injected at runtime.

Attribute Value
Terraform provider hashicorp/vault ~3.0
Kubernetes auth Vault agent sidecar
Secret paths /secret/lilith/api-keys, /secret/isis/providers, /secret/runpod/endpoints
Templates Vault agent template rendering for API key injection
Relevant paths infra/yemaya/docker/vault-agent/

7. Payment & Billing#

Oshun monetises through both web subscription plans and native mobile in-app purchases. Stripe handles all web-based billing. RevenueCat provides a unified receipt validation and subscription management layer across iOS and Android, normalising the differences between Apple App Store and Google Play billing APIs.

Service SDK Env Vars What it is and how Oshun uses it
Stripe stripe ^17.0.0 STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET The leading web payments platform. Powers subscription billing, one-time purchases, and invoicing for Oshun's web applications. Webhook events drive subscription state changes in the backend.
RevenueCat RevenueCat SDK — A mobile subscription management SDK that abstracts Apple App Store and Google Play billing into a single API. Used in Lilith and Tara mobile apps to manage in-app purchases, validate receipts, and sync entitlements across platforms.

Relevant paths: apps/veritas/api/src/domain/payments/stripe.ts, apps/lilith/svc-payment-orchestrator/src/stripe/


8. Monitoring & Observability#

A platform of Oshun's complexity — GPU workloads, 20+ domains, multiple cloud providers — requires comprehensive observability across metrics, traces, and logs. Oshun uses the standard CNCF observability stack: OpenTelemetry for unified instrumentation, Prometheus for metrics collection, Grafana for dashboards, and Jaeger for distributed request tracing. The ELK Stack provides centralised log aggregation. Sentry provides production error tracking.

Technology Version Port(s) What it is and how Oshun uses it
Prometheus prom/prometheus:v2.47.0 9090 An open-source time-series metrics database and pull-based monitoring system. Scrapes metrics endpoints from all Oshun services and stores them with a 7-day retention window in development (--storage.tsdb.retention.time=7d). Powers the alert rules for RunPod cost spikes and service failure rates.
Grafana grafana/grafana:10.2.0 3000 An open-source dashboard and visualisation platform. Displays Prometheus metrics in purpose-built dashboards for RunPod serverless, ComfyUI generation throughput, and per-service health. Engineers use Grafana as the primary operational view of the platform.
Jaeger jaegertracing/all-in-one:1.51 16686 (UI), 14268 (collector), 6831 (agent UDP) An open-source distributed tracing system. Collects traces from all instrumented services and allows engineers to follow a single request as it flows through multiple microservices, identifying where latency is introduced.
OpenTelemetry ^1.28.0 — A vendor-neutral observability framework that provides a single instrumentation API for traces, metrics, and logs. All Oshun services use the OTel SDK to emit telemetry, which is then exported to Jaeger (traces) and Prometheus (metrics) without any vendor lock-in.
Pino latest — A high-performance JSON logging library for Node.js. Used across all TypeScript services to emit structured, machine-readable log lines that can be ingested by the ELK Stack.
Sentry — SENTRY_DSN A hosted error tracking and performance monitoring platform. Captures unhandled exceptions with full stack traces and context, and tracks performance regressions across releases in production.
PostHog — VITE_POSTHOG_KEY An open-source product analytics platform. Used for tracking user behaviour, feature usage, and conversion funnels across Oshun's web applications. Configured in frontend builds via the Vite environment variable.
AWS CloudWatch managed — AWS's native monitoring service. Monitors AWS-managed infrastructure (RDS, ElastiCache, EKS cluster) and hosts alarms for cost spikes, database connection counts, and Lambda error rates.

OpenTelemetry packages: @opentelemetry/api, @opentelemetry/core, @opentelemetry/sdk-trace-node, @opentelemetry/sdk-trace-base, @opentelemetry/exporter-trace-otlp-http, @opentelemetry/resources, @opentelemetry/semantic-conventions, @opentelemetry/propagator-aws-xray, @opentelemetry/context-async-hooks

Relevant paths: docker/observability/


ELK Stack — Log Aggregation & Analysis#

The ELK Stack is the industry-standard centralised logging solution. Filebeat and Metricbeat ship logs and metrics from every container to Logstash, which transforms and routes them into Elasticsearch for storage and indexing. Kibana provides a search and visualisation interface over the aggregated logs. Curator manages index lifecycle, automatically deleting old indices to control storage costs. All components run at version 8.11.0. The stack is defined in infra/elk/docker-compose.elk.yml.

Component Image What it is and how Oshun uses it
Elasticsearch elasticsearch:8.11.0 Stores and indexes all log data shipped from Oshun services, making it queryable and searchable.
Logstash docker.elastic.co/logstash/logstash:8.11.0 Ingests log streams, applies transformation pipelines (parsing, enrichment, filtering), and routes processed logs into Elasticsearch.
Kibana docker.elastic.co/kibana/kibana:8.11.0 Provides the web UI for searching, filtering, and visualising log data and building operational dashboards over log aggregates.
Filebeat docker.elastic.co/beats/filebeat:8.11.0 A lightweight log shipper that tails log files and container stdout/stderr, forwarding them to Logstash for processing.
Metricbeat docker.elastic.co/beats/metricbeat:8.11.0 Collects system-level and service-level metrics (CPU, memory, Docker stats) and ships them to Elasticsearch alongside log data.
Curator untergeek/curator:8.0.4 Automates Elasticsearch index lifecycle management — creating, closing, and deleting indices on a schedule to prevent unbounded storage growth.

9. Email & Notifications#

Oshun reaches users through email, mobile push notifications, SMS, and internal team alerts. Mailpit provides a local email testing environment so developers can inspect outgoing email without sending real messages. SendGrid handles production email delivery. Firebase, Twilio, and webhook integrations cover mobile push, SMS, and team notification channels respectively.


Email#

Service Deployment What it is and how Oshun uses it
Mailpit Docker (dev) A lightweight local SMTP server and web UI. Catches all email sent by Oshun services during development and displays them in a browser interface at port 8025, so developers can verify email content and formatting without delivering real messages. SMTP port 1025.
SendGrid Cloud (prod) Twilio's transactional and marketing email platform. Handles all production email delivery for Oshun — account verification emails, password resets, subscription receipts, and any programmatic notifications across all domains.

Push Notifications & Messaging#

Service What it is and how Oshun uses it
Firebase Google's app platform provides Firebase Cloud Messaging (FCM), which delivers push notifications to iOS (via APNs) and Android devices. Used in Lilith and Tara mobile apps to notify users of meditation reminders, session completions, and content updates. Also provides real-time database capabilities for syncing session state. Node.js SDK: firebase-admin ^13.0.0.
Twilio A cloud communications platform providing programmable SMS. Used for sending SMS notifications for account security events (e.g. two-factor authentication codes) and critical platform alerts.
Slack Webhooks Incoming webhook integration with Slack. Posts deployment status messages, CI/CD pipeline results, and infrastructure alerts to internal team channels.
Discord Webhooks Incoming webhook integration with Discord. Posts community-facing notifications and domain-specific event announcements to Discord servers.

10. Containerization & Orchestration#

Every Oshun service runs in a container, and those containers are orchestrated with Kubernetes on AWS EKS. Docker provides the container runtime and image build toolchain. GitHub Container Registry stores built images. Helm and ArgoCD manage Kubernetes deployments declaratively. Istio provides the service mesh layer — mutual TLS between pods, traffic shaping, and canary deployments. Traefik handles ingress routing.


Docker#

Base Image Used For
nvidia/cuda:12.2.2-cudnn8-runtime-ubuntu22.04 GPU Dockerfile base (docker/Dockerfile.gpu) — any service that needs direct CUDA/cuDNN access
nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 RunPod GPU inference containers running PyTorch-based models
node:20-alpine All Node.js/TypeScript services — minimal footprint Alpine base
python:3.11-slim Python microservices (Psyche, Minerva, Metis, Serwaa) — slim Debian base

Registry: GitHub Container Registry (ghcr.io) Image prefix: ghcr.io/<owner>/oshun Local dev: docker/docker-compose.dev.yml


Development GUI & Admin Tools (Docker Compose profiles)#

These tools run locally via Docker Compose profiles and are never deployed to production. They provide graphical interfaces for inspecting and managing the local development databases, queues, and mail.

Tool Image Profile What it is and how Oshun uses it
PgAdmin dpage/pgadmin4:latest tools A web-based administration interface for PostgreSQL. Allows developers to browse schemas, run queries, and inspect table data across all Oshun domain schemas without needing a local database client.
Redis Commander rediscommander/redis-commander:latest tools A web-based GUI for browsing Redis key-value data. Useful for inspecting BullMQ job state, session tokens, and rate-limiting counters during development.
Kafka UI provectuslabs/kafka-ui:latest streaming A web UI for browsing Kafka topics, consumer groups, and messages. Used when developing or debugging Maat domain event streaming.
Mailpit axllent/mailpit:latest always Local SMTP server and email inspection UI. Catches all outgoing email from development services.
PgBouncer edoburu/pgbouncer:latest always A lightweight PostgreSQL connection pooler. Sits between services and PostgreSQL to multiplex many service connections into a smaller pool of actual database connections, preventing connection exhaustion.

Kubernetes (EKS)#

Oshun's production Kubernetes cluster on AWS EKS uses per-domain namespaces for isolation, with rolling, blue-green, and canary deployment strategies available depending on the risk profile of the change.

Namespace Domain
yemaya-ns Creative studio
lilith-ns Consciousness / meditation
isis-ns Generative factory
sophia-ns Research & knowledge
hathor-ns Worldbuilding
bellona-ns Build & bridge
oshun-system Shared platform services

Deployment strategies: Rolling updates (standard changes), blue-green (testing with full traffic switch), canary (production changes with staged traffic rollout)


Service Mesh & GitOps#

Technology What it is and how Oshun uses it
Istio A Kubernetes service mesh that manages all communication between pods. Provides automatic mutual TLS (mTLS) between every service, fine-grained traffic management for canary deployments, and observability hooks that feed into the Jaeger tracing system.
Helm The Kubernetes package manager. Packages Kubernetes manifests as versioned, parameterised charts that can be deployed consistently across environments with different configuration values.
ArgoCD A GitOps continuous delivery tool for Kubernetes. Watches the Git repository and automatically synchronises the cluster state to match the declared configuration. Uses ApplicationSet templates to generate per-domain and per-environment applications from a single template.
Traefik A modern reverse proxy and load balancer (v3.0). Acts as the Kubernetes ingress controller, routing external traffic to the correct domain services and handling TLS termination.

Relevant paths: deploy/argocd/apps/


11. CI/CD & Build Infrastructure#

Oshun has a comprehensive automated pipeline covering testing, security scanning, performance benchmarking, infrastructure validation, container building, and multi-environment deployment. All pipelines run on GitHub Actions. The monorepo is managed by Nx, which computes the minimal set of projects affected by any change and skips unaffected builds.


GitHub Actions#

43 workflows are defined in .github/workflows/ at the repository root. Additional domain-specific workflows exist in minerva/.github/workflows/ (~10 workflows), serwaa/.github/workflows/ (~15 workflows), and yaa/.github/workflows/ (~6 workflows), totalling 80+ workflows across the monorepo.

Workflow What it does
ci.yml Core CI pipeline — runs unit tests, ESLint linting, and TypeScript type checking for all affected packages on every pull request and push to main.
oshun-ci.yml Oshun platform-specific CI — additional checks specific to the core platform services beyond the generic CI pipeline.
iris-ci.yml CI for the Iris AI coding assistant platform — tests the conversation, memory, agent, and voice service packages.
psyche-ci.yml CI for the Psyche AI services platform — tests the Python and TypeScript packages that make up Psyche's voice, vision, and reasoning services.
tara-ci.yml CI for the Tara meditation mobile app and API — covers both the API service and the web/mobile frontend.
e2e.yml Full end-to-end test suite run against a live environment using Playwright.
oshun-web-e2e.yml End-to-end tests specifically for the Oshun web application.
oshun-web-visual-regression.yml Captures and compares screenshots of the Oshun web UI across commits to detect unintended visual changes.
container-build.yml Builds and pushes core Docker images to GitHub Container Registry.
iris-container-build.yml Builds and pushes Iris-specific Docker images (API, memory, agent, voice containers).
psyche-container-build.yml Builds and pushes the Psyche platform's specialised Docker images (reasoning, embedding, model-manager).
deploy.yml Primary staging and production deployment workflow supporting rolling, blue-green, and canary strategies via flags.
deploy-ecs.yml Alternative deployment path targeting AWS ECS rather than EKS.
iris-staging-deploy.yml Deploys the Iris platform to the staging environment.
iris-production-deploy.yml Deploys Iris to production, with required manual approval gates before execution.
iris-iac-modules.yml Validates Terraform infrastructure-as-code modules for the Iris domain.
iris-infra-drift-detection.yml Runs Terraform plan on a schedule to detect configuration drift between the live Iris infrastructure and the declared IaC state.
iris-security.yml Runs security scanning (SAST, dependency audit) across the Iris codebase.
model-sync.yml Synchronises AI model files from HuggingFace and CivitAI to the RunPod Docker images and S3 model cache.
psyche-model-management.yml Manages the lifecycle of ML models in the Psyche platform — downloading, versioning, and promoting models between environments.
oshun-web-deploy.yml Deploys the Oshun web application to its hosting environment.
oshun-web-preview.yml Creates ephemeral preview environments for pull requests to the Oshun web app.
oshun-web-lighthouse.yml Runs Lighthouse performance, accessibility, and best-practice audits against the Oshun web app on every deployment.
oshun-web-bundle-monitor.yml Measures JavaScript bundle sizes and alerts when they grow beyond defined thresholds.
oshun-web-sourcemaps.yml Uploads source maps to Sentry so production errors display readable stack traces.
oshun-mobile-release.yml Triggers an Expo Application Services (EAS) cloud build and submits the resulting binary to the App Store and Google Play.
psyche-deploy.yml Deploys the Psyche AI services platform to its target environment.
tara-api-deploy.yml Deploys the Tara API service to staging or production.
tara-web-deploy.yml Deploys the Tara web application.
tara-web-preview.yml Creates preview environments for Tara web pull requests.
terraform.yml Runs terraform validate and terraform plan on every infrastructure change, posting the plan output as a pull request comment.
runpod-endpoint-reconcile.yml Reconciles the desired RunPod endpoint configuration with the live state, creating or updating endpoints as needed.
runpod-endpoint-drift-detection.yml Detects drift between the declared RunPod endpoint configuration and what is actually running on RunPod.
runpod-endpoint-lifecycle.yml Manages the full lifecycle of RunPod endpoints — creation, scaling, hibernation, and deletion.
runpod-endpoint-image-build.yml Builds and pushes the Docker images that run on RunPod GPU endpoints.
deploy-runpod.yml Deploys updated images and configuration to RunPod endpoints.
database.yml Runs database migration CI — validates that Prisma schema changes and migration files are consistent before they reach production.
pr-quality.yml Enforces pull request quality standards — commit message format (commitlint), PR description completeness, and branch naming conventions.
benchmarks.yml Runs performance benchmarks on key algorithms and services, tracking results over time to catch regressions.
accessibility.yml Runs automated accessibility audits against UI components using axe-core and similar tools.
3d-quality-continuous-evaluation.yml Continuously evaluates the quality of 3D assets (Maya/Neith engine outputs) against defined quality metrics.
codeql.yml Runs GitHub's CodeQL static analysis for security vulnerabilities across the TypeScript and Python codebases.
release.yml Automates the release process — runs Changesets, bumps package versions, generates changelogs, and creates GitHub releases.

Runners: ubuntu-latest (standard workflows), self-hosted GPU runners (model training, GPU benchmarks) Node version: 20+, pnpm version: 10+


Build & Monorepo Tools#

Technology Version What it is and how Oshun uses it
Nx 20.8.3+ A powerful monorepo build system with a project graph that tracks dependencies between packages. Computes which packages are affected by any change and runs only the necessary builds, tests, and lints. Also provides a remote build cache so repeated CI runs skip already-computed results.
pnpm 10.25.0+ A fast, disk-efficient Node.js package manager with native workspace support. All Node.js packages in the monorepo are managed as a single pnpm workspace, with shared dependency versions declared in the pnpm-workspace.yaml catalog.
tsup — A zero-configuration TypeScript library bundler built on esbuild. Used to build all shared library packages in libs/ into distributable CommonJS and ESM outputs.
Vite 5.4+ A fast frontend build tool and development server. Used for web applications that benefit from its hot-module-replacement development experience and optimised production bundling.
Changesets 2.27.1+ A versioning and changelog management tool for monorepos. Developers add changeset files describing their changes; the release workflow consumes these to bump package versions and generate changelogs automatically.

Infrastructure as Code#

Technology Version What it is and how Oshun uses it
Terraform 1.5/1.6+ HashiCorp's declarative infrastructure-as-code tool. Defines all AWS resources (EKS, RDS, ElastiCache, S3, IAM, MSK), Kubernetes resources, Helm releases, and Vault policies in code that can be versioned, reviewed, and applied reproducibly. The primary IaC tool across all Oshun environments.
Pulumi — An alternative IaC tool that expresses infrastructure in TypeScript rather than HCL. Used in the Iris domain where the team preferred TypeScript's type system for defining infrastructure resources.

Terraform providers: hashicorp/aws ~5.0, hashicorp/kubernetes >=2.24, hashicorp/helm >=2.12, hashicorp/vault ~3.0, hashicorp/random, hashicorp/tls State backend: S3 + DynamoDB locking + KMS encryption + multi-region replication Relevant paths: deploy/terraform/, infra/terraform-v1/, infra/terraform/iris/, minerva/infra/terraform-v1/, infra/yemaya/terraform/


Code Quality#

Technology Version What it is and how Oshun uses it
ESLint 9.0+ The standard JavaScript/TypeScript linter. Enforces code style, catches common errors, and applies TypeScript-aware rules via @typescript-eslint. Runs in CI and as a pre-commit hook.
TypeScript ESLint — The TypeScript plugin for ESLint that enables type-checked lint rules — rules that require TypeScript's type information to evaluate, catching type-related issues that standard ESLint cannot detect.
Prettier 3.2.5 An opinionated code formatter that enforces consistent style (100-character line length, trailing commas) across all TypeScript, JavaScript, and JSON files. Combined with the Tailwind CSS plugin to also sort utility class names.
prettier-plugin-tailwindcss — A Prettier plugin that automatically sorts Tailwind CSS utility classes in JSX and HTML into a consistent canonical order, preventing meaningless class ordering diffs in pull requests.
Husky — A tool for managing Git hooks. Runs lint and format checks at pre-commit time so code quality issues are caught before they reach CI.
commitlint — Enforces the conventional commit message format (feat(scope):, fix(scope):, etc.) on every commit. Configured to require lowercase subject lines, which aligns with the project's commitlint rules.

12. Language Runtimes#

Oshun is a polyglot platform. TypeScript/Node.js is the default for all services. Rust is used for performance-critical systems — the Neith game engine, renderer, physics, audio, and networking code — where memory safety and zero-cost abstractions are essential. Python handles all ML/AI workloads where the ecosystem (PyTorch, HuggingFace, mediapipe) is unmatched.

Language Version Primary Use
TypeScript / Node.js TS 6.0.3, Node 20 LTS All backend services, frontend web and mobile applications, CLI tools, and the majority of the shared library ecosystem in libs/.
Rust stable The Neith custom game engine powering the Maya domain — 100+ crates covering graphics (wgpu), physics (rapier), audio (cpal/symphonia), networking (webrtc), cryptography, asset storage, and hardware abstraction. Also used in Uzume (MIDI/protocol), and Iris SDK (native bindings).
Python 3.11+ for most services; 3.12+ for Minerva (requires-python = ">=3.12" in minerva/pyproject.toml; python3.11 specified in Psyche Dockerfiles; >=3.11 in Metis and Psyche libs) Psyche platform (real-time voice/video AI with PyTorch and mediapipe), Minerva (educational AI with Lean 4, Ray, LiteLLM), Metis (educational content with LangChain), Serwaa (AI assistant), and all ML training and fine-tuning workloads.

Python package manager: Poetry Rust workspace: Cargo workspaces integrated with Nx via nx:run-commands WASM: wasm-pack for building Rust crates to WebAssembly for browser targets Native modules: napi-rs for building Rust crates as Node.js native addons


13. Backend Frameworks#

Oshun's backend services use different HTTP frameworks depending on their requirements. Fastify is the primary choice for services that need high-throughput and a rich plugin ecosystem. Hono is used for lightweight microservices and edge-deployable APIs. Express serves legacy services. FastAPI is the standard for Python microservices.

Framework Language Version What it is and how Oshun uses it
Fastify TypeScript 4.28.1+ A high-performance Node.js web framework with a schema-based request validation system and excellent plugin architecture. Used for the Lilith backend-for-frontend and primary API services where performance and extensibility are paramount.
Hono TypeScript 4.0+ An ultralight web framework designed for edge and serverless environments, with minimal overhead. Used for the Isis Generation API and other microservices that need to be lean and edge-deployable.
Express TypeScript 4.x The ubiquitous Node.js web framework. Used in legacy services that predate the Fastify/Hono adoption, maintained for compatibility.
FastAPI Python — A modern, high-performance Python web framework based on type hints and Pydantic. The standard framework for all Python microservices — Psyche, Minerva, Metis, and Serwaa all expose their APIs through FastAPI.

Fastify plugins: @fastify/cors (CORS handling), Mercurius ^14.1.0 (GraphQL adapter — local dependency in apps/lilith/bff, not in shared catalog)

Hono adapters & plugins: @hono/node-server ^1.13.7 (runs Hono on Node.js http server), @hono/zod-openapi (OpenAPI + Zod schema integration), @hono/swagger-ui (auto-generated Swagger UI), @hono/zod-validator (request validation middleware)


14. ORM & Database Clients#

Oshun uses different database access layers depending on language and use case. Prisma is the primary TypeScript ORM for its excellent type safety and migration tooling. SQLAlchemy covers all Python services. Several lower-level clients (pg, ioredis, asyncpg) handle cases where direct query control matters more than abstraction.

Library Language What it is and how Oshun uses it
Prisma TypeScript ^5.20.0 — A type-safe ORM with an auto-generated client derived from the schema definition. Provides database migrations, Prisma Studio for data inspection, and TypeScript types for every model. Used as the primary database access layer across all TypeScript domain services.
Drizzle ORM TypeScript ^0.38.4 — A lightweight, SQL-first TypeScript ORM that keeps queries close to raw SQL while providing type safety. Used as an alternative to Prisma in services where query composability and minimal runtime overhead are preferred.
drizzle-kit TypeScript The companion CLI for Drizzle ORM. Generates and runs SQL migration files from Drizzle schema definitions, provides a Studio UI for inspecting data, and handles schema introspection.
Knex.js TypeScript ^3.1.0 — A SQL query builder (not a full ORM) that provides a fluent API for constructing SQL queries and running schema migrations. Used where raw query control is needed without a full ORM.
pg TypeScript ^8.11.3 — The low-level PostgreSQL client for Node.js. Used directly when query performance or PostgreSQL-specific features require bypassing the ORM layer.
ioredis TypeScript ^5.3.2 — A full-featured Redis client for Node.js with support for connection pooling, pipelining, Lua scripting, Redis Cluster, and Sentinel. Used by all TypeScript services that interact with Redis.
minio TypeScript ^8.0.0 — The official MinIO/S3 JavaScript client. Used for all object storage operations — uploading generated assets, generating presigned URLs, managing buckets. Compatible with both local MinIO and AWS S3.
SQLAlchemy Python The de facto Python ORM. Used in async mode (sqlalchemy[asyncio]) across all Python services — Psyche, Serwaa, Metis, and Minerva — for database access.
asyncpg Python A high-performance async PostgreSQL driver for Python. Used as the async connection driver underneath SQLAlchemy's async engine across all Python services.
alembic Python The standard database migration tool for SQLAlchemy. Manages schema migrations for all Python services, ensuring database schema changes are versioned and reproducible.
qdrant-client Python The official Qdrant Python client. Used by Psyche, Minerva, and Iris Python services to store and query vector embeddings in the Qdrant vector database.

Generate migrations: pnpm db:generate Run migrations: pnpm db:migrate


15. Frontend Stack#

Oshun's frontend spans web applications, mobile apps, and desktop apps. React and Next.js power the web experience. React Native and Expo handle mobile. Tauri provides native desktop app packaging using a Rust backend with a TypeScript/React frontend — chosen because it produces significantly smaller and more secure desktop apps than Electron.


Web#

Technology Version What it is and how Oshun uses it
React 18.3+ The industry-standard declarative UI library. All Oshun web applications are built with React, using its component model and concurrent features for complex, interactive interfaces.
Next.js 14.2.21+ A React framework providing server-side rendering, static generation, file-based routing, and API routes. Used for oshun/web, iris/web/pwa, and tara/web — applications where SEO, performance, and full-stack capabilities matter.
Tailwind CSS 3.4+ A utility-first CSS framework that applies styles through small, composable class names in markup rather than separate stylesheets. Enables rapid UI development with a consistent design system.
Vite 5.4+ A next-generation frontend build tool and HMR dev server. Used for non-Next.js frontend packages where fast iteration speed is critical.
@vitejs/plugin-react 4.3.4 The official Vite plugin for React. Enables React Fast Refresh (HMR) and JSX transform in Vite-based projects. Used in all Vite-powered React applications across the monorepo.
Zustand 4.5+ A minimalist, hook-based state management library for React. Used for client-side application state that does not need to be persisted to the server — UI state, preferences, real-time session data.
TanStack Query 5.0+ A server-state management library for React. Handles data fetching, caching, background refetching, and cache invalidation, removing the need to manually manage loading/error/stale states.
GraphQL clients — Oshun's frontend applications consume GraphQL APIs via lightweight fetch-based queries. Mercurius on the Fastify backend serves the GraphQL schema used by Lilith's BFF.
Storybook — A frontend workshop for developing and documenting UI components in isolation. Used for building and maintaining Oshun's component library, with each component showcased with its variants and states.

Mobile#

Technology What it is and how Oshun uses it
React Native A framework for building native iOS and Android apps using React and JavaScript/TypeScript. Allows Oshun to share significant code between web and mobile while delivering native UI performance. Used for Lilith and Tara mobile apps.
Expo A platform built on top of React Native that simplifies development, builds, and deployment. Expo Application Services (EAS) provides cloud builds and over-the-air update delivery without requiring local Xcode/Android Studio setups.
Apple App Store Distribution platform for iOS apps. Lilith and Tara apps are submitted here via the EAS build pipeline.
Google Play Store Distribution platform for Android apps. Lilith and Tara Android releases are managed via EAS and submitted here.

Desktop#

Technology What it is and how Oshun uses it
Tauri A framework for building desktop applications with a Rust backend and a web-technology frontend (TypeScript + React). Produces small, fast, and secure desktop apps without bundling a full Chromium instance. Used for apps/iris/desktop/ (the Iris AI coding assistant desktop app) and apps/lilith/desktop/ (the Lilith meditation desktop experience).

16. API Standards & Protocols#

Oshun uses a mix of API styles and protocols, each chosen for specific communication patterns. REST with OpenAPI serves external and developer-facing APIs. gRPC handles high-performance internal service communication. GraphQL enables flexible client-driven queries. WebSocket and WebRTC power real-time interactive features. HLS streams video content.

Standard Tooling What it is and how Oshun uses it
OpenAPI 3.1 pnpm openapi:validate, pnpm openapi:diff The standard specification language for REST APIs. Oshun maintains OpenAPI specs for all external-facing APIs, enabling automated client SDK generation, documentation, and breaking-change detection via the diff command.
gRPC / Protobuf Buf 1.66.1 (buf generate, buf lint) A high-performance binary RPC framework using Protocol Buffers as the interface definition language. Used for internal service-to-service communication (e.g. Psyche's reasoning, embedding, and vision services) where low latency and strong typing matter. Buf manages the proto schema lifecycle.
GraphQL Mercurius ^14.1.0 (server, Lilith BFF) A query language for APIs that allows clients to request exactly the data they need. Mercurius serves as the GraphQL engine on top of Fastify in the Lilith backend-for-frontend. Frontend applications consume the schema via lightweight fetch-based queries.
WebSocket Socket.io (legacy), native WebSocket A persistent bidirectional communication channel over HTTP. Used for real-time collaborative features in Lilith (live session sync) and Yemaya (collaborative content creation).
WebRTC libs/neith/net/crates/neith-webrtc/ A browser-native P2P communication standard for audio, video, and data channels. Used for video/audio conferencing in Psyche and voice chat in the Lilith consciousness experience. The Neith engine provides the Rust WebRTC implementation.
HLS — HTTP Live Streaming, the standard adaptive bitrate video streaming protocol. Used in Yemaya's broadcast infrastructure to deliver video content to web and mobile clients.

Proto schema paths: libs/proto/oshun/ OpenAPI spec paths: libs/openapi/specs/


17. Testing Frameworks#

Testing across Oshun's polyglot codebase requires different frameworks for different languages and test types. Vitest is the primary TypeScript test runner. Playwright handles end-to-end browser automation and visual regression testing. testcontainers enables integration tests that run against real database and service containers in CI. pytest covers the Python services.

Framework Language What it is and how Oshun uses it
Vitest TypeScript ^1.6.1 — A Vite-native unit and integration test framework compatible with the Jest API. The primary test runner for all TypeScript packages across the monorepo. Uses @vitest/coverage-v8 for V8-based code coverage reporting.
Playwright TypeScript ^1.48.2 — A cross-browser end-to-end test automation framework. Used for full E2E test suites that exercise real browser behaviour, and for visual regression testing that compares screenshots between commits to catch UI regressions.
React Testing Library TypeScript A testing utility that encourages testing React components the way a real user would interact with them — by querying accessible elements rather than implementation details. Used for accessibility-first component tests.
testcontainers TypeScript ^10.7.0 — A library that programmatically starts and stops real Docker containers (PostgreSQL, Redis, Qdrant) inside integration tests. Allows TypeScript services to be integration-tested against real infrastructure without mocking, matching how they will behave in production.
pytest Python The standard Python test framework. Used across all Python services (Psyche, Minerva, Metis, Serwaa) for unit and integration tests.
Storybook TypeScript A frontend component development environment. Doubles as a visual testing tool — component stories are used to verify visual appearance and catch regressions in the component library.

Run unit tests: pnpm nx test <project> or npx vitest run path/to/test.ts Run E2E: pnpm e2e


18. External Content APIs#

Several Oshun domains require access to specialised external content that does not exist within the platform itself. The Nisaba ancient-language and knowledge domain needs access to historical text repositories. The ComfyUI generation pipeline needs community AI model downloads. These are narrow, domain-specific integrations maintained alongside the services that depend on them.

Service Domain Endpoint What it is and how Oshun uses it
Sefaria API Nisaba https://www.sefaria.org/api Sefaria is the largest openly licensed digital library of Jewish texts, including the Torah, Talmud, Mishnah, and extensive commentary. The Nisaba domain (ancient language and knowledge) uses this API to access historical Jewish and religious source texts for scholarly analysis and cross-linguistic study.
CDLI API Nisaba https://cdli.mpiwg-berlin.mpg.de/api The Cuneiform Digital Library Initiative is an international project that has digitised over 300,000 cuneiform tablets. Nisaba uses this API to access ancient Mesopotamian texts — among the oldest written records in human history — for linguistic and historical research.
IIIF Nisaba http://localhost:8182/iiif (dev) The International Image Interoperability Framework is a set of open standards for delivering and annotating high-resolution digital images from libraries, museums, and archives. Nisaba uses IIIF to access high-resolution scans of ancient manuscript and artefact images from participating institutions.
CivitAI ComfyUI — A community platform for sharing and downloading AI image generation models (LoRAs, checkpoints, embeddings). The RunPod base image download script pulls curated models from CivitAI to populate the ComfyUI model library with styles used in Isis and Lilith generation pipelines.

19. Python Service Dependencies#

Python is used across four major Oshun services, each with its own pyproject.toml managed by Poetry. The Python ecosystem is used specifically for ML/AI workloads where it has decisive ecosystem advantages over TypeScript: PyTorch, HuggingFace Transformers, mediapipe, Lean 4 integration, and distributed computing frameworks are all Python-first. Below are the key dependencies per service.


Minerva — Educational AI Platform (minerva/pyproject.toml)#

Minerva is Oshun's formal educational AI platform. It combines large language models with formal theorem proving (Lean 4), distributed ML training (Ray), curriculum generation, and deep NLP to power an AI-first learning experience. Its dependency list reflects this ambition: it includes both production AI tooling and research-grade ML libraries.

Package Version What it is and how Minerva uses it
fastapi >=0.115.0 Web framework for Minerva's HTTP API endpoints.
uvicorn[standard] >=0.34.0 ASGI server that runs FastAPI applications in production and development.
pydantic >=2.5.0 Data validation and serialisation library using Python type hints. Minerva uses Pydantic models extensively for request/response validation and for defining the domain model hierarchy (Course, Module, Lesson, Section).
sqlalchemy[asyncio] >=2.0.36 Async ORM for all database access in Minerva.
asyncpg >=0.30.0 High-performance async PostgreSQL driver.
alembic >=1.14.0 Database migration management.
redis >=5.0.0 Redis client for caching and session data.
openai >=1.58.0 OpenAI SDK for GPT-4 and embedding models.
anthropic >=0.40.0 Anthropic SDK for Claude models.
litellm >=1.34.0 Unified multi-provider LLM interface so Minerva's curriculum generation can call any model.
langchain >=0.3.0 LLM orchestration framework for chaining retrieval, generation, and evaluation steps in educational workflows.
sentence-transformers >=2.7.0 Generates semantic sentence embeddings for content similarity, semantic search across course material, and prerequisite matching.
scikit-learn ==1.6.1 General-purpose ML library. Used for clustering, classification, and statistical analysis in learning analytics and content recommendation.
nltk >=3.8.1 Natural Language Toolkit for text tokenisation, stemming, parsing, and other NLP preprocessing tasks.
sympy >=1.13.1,<1.15 Symbolic mathematics library. Used for algebraic manipulation, equation solving, and verifying mathematical steps in STEM content generation.
rouge-score >=0.1.2 Implements ROUGE metrics for evaluating text generation quality — used to assess the quality of AI-generated summaries and explanations.
evaluate >=0.4.0 HuggingFace's model evaluation framework. Used to benchmark educational content generation quality across standard NLP metrics.
datasets >=2.18.0 HuggingFace's dataset management library for loading, processing, and streaming training datasets used in Minerva's fine-tuning pipelines.
peft >=0.10.0 Parameter-Efficient Fine-Tuning library from HuggingFace. Enables fine-tuning large language models on educational domain data using techniques like LoRA without requiring full model training.
motor >=3.7.1 Async MongoDB driver. Used for storing unstructured educational content and activity logs.
duckduckgo-search >=8.1.1 API for performing web searches via DuckDuckGo. Used by Minerva's research agents to retrieve up-to-date information when generating curriculum content.
lean-interact >=0.10.0 A Python interface for communicating with the Lean 4 interactive theorem prover. Minerva uses Lean 4 to formally verify mathematical proofs in STEM content.
lean-dojo >=4.20.0 A machine learning framework for formal theorem proving with Lean 4. Enables training and evaluating ML models that can assist with or automate proof generation.
ray >=2.48.0 A distributed computing framework for Python. Used to scale Minerva's ML training and content generation workloads across multiple CPUs or GPUs horizontally.
dask[complete] >=2024.1.0 A parallel and distributed data processing library. Used optionally for large-scale dataset processing tasks in content generation pipelines.
cupy-cuda12x >=13.0.0 A GPU-accelerated array library with a NumPy-compatible API. Used optionally on GPU nodes to accelerate numerical computations in ML evaluation pipelines.

Dev extras: unsloth (efficient LLM fine-tuning), bitsandbytes (quantisation), trl (reinforcement learning from human feedback)


Psyche — AI Services Platform (services/psyche/pyproject.toml)#

Psyche is Oshun's real-time AI services platform, handling voice, vision, and multimodal perception. It requires the heaviest ML stack in the codebase: full PyTorch, computer vision, speech processing, and real-time AI pipelines.

Package Version What it is and how Psyche uses it
torch ^2.2.0 The core PyTorch deep learning framework. The foundation for all of Psyche's ML models — perception, voice synthesis, and reasoning engines all run on PyTorch tensors and autograd.
torchaudio ^2.2.0 PyTorch extension for audio processing. Used for audio feature extraction, speech preprocessing, and audio data augmentation in Psyche's voice pipeline.
torchvision ^2.2.0 PyTorch extension for computer vision. Used for image preprocessing, feature extraction, and visual model operations in Psyche's vision pipeline.
librosa ^0.10.1 A Python library for audio analysis. Provides spectral analysis, beat detection, and feature extraction functions used in Psyche's audio understanding pipeline.
soundfile ^0.12.1 A library for reading and writing audio files. Used to load, convert, and save audio data across various formats in Psyche's voice processing pipeline.
opencv-python ^4.9.0 OpenCV's Python bindings for real-time computer vision. Used in Psyche for face detection, image processing, and video frame analysis.
mediapipe ^0.10.9 Google's ML pipeline framework for perception tasks. Provides pre-trained, production-quality models for face landmark detection, hand tracking, and body pose estimation — used in Psyche's visual perception pipeline and in the Psyche avatar generation features.
elevenlabs ^1.0.3 ElevenLabs TTS and voice cloning SDK. The primary voice synthesis engine in Psyche's voice output pipeline.
deepgram-sdk ^3.0.2 Deepgram's speech recognition SDK. Powers Psyche's speech-to-text input processing.
boto3 ^1.34.34 AWS SDK for Python. Used for S3 uploads, Secrets Manager access, and other AWS integrations in Psyche.
aiobotocore ^2.12.0 Async version of boto3. Used when Psyche services need to interact with AWS without blocking the async event loop.
opentelemetry-api ^1.22.0 OpenTelemetry instrumentation API for distributed tracing in Psyche services.
opentelemetry-instrumentation-fastapi ^0.43b0 Automatic OpenTelemetry instrumentation for FastAPI — traces every incoming request without manual instrumentation code.
prometheus-client ^0.19.0 Prometheus metrics client. Used to expose Psyche service metrics (inference latency, request rates, model performance) on a /metrics endpoint.
grpcio ^1.60.1 gRPC framework for Python. Psyche exposes performance-critical services (reasoning, embedding) over gRPC for low-latency inter-service calls.
protobuf ^4.25.2 Protocol Buffers runtime. Used alongside grpcio for message serialisation in Psyche's gRPC services.
websockets ^12.0 Async WebSocket library. Used for real-time bidirectional communication in Psyche's voice and vision streaming services.
asyncpg ^0.29.0 Async PostgreSQL driver for Psyche's database operations.
alembic ^1.13.1 Database migration management for Psyche's schema.
orjson ^3.9.12 A fast JSON serialisation library written in Rust. Used in Psyche for high-throughput JSON serialisation where standard json or ujson would become a bottleneck.

Serwaa — AI Assistant Platform (serwaa/pyproject.toml)#

Serwaa is Oshun's AI assistant platform. It goes considerably beyond a simple chat interface: it integrates with video-conferencing platforms (Zoom, Google Meet, Microsoft Teams, Webex) to provide AI assistance inside live meetings, supports multiple speech-to-text providers, multiple embedding providers, and multiple self-hosted TTS engines. Its serwaa/.env.example reveals the full integration surface.

Core Python stack:

Package Group What it is and how Serwaa uses it
fastapi core Web framework for Serwaa's API layer.
sqlalchemy[asyncio] core Async ORM for Serwaa's database access.
websockets core WebSocket support for real-time conversational sessions.
grpcio core gRPC support for low-latency inter-service calls within the Serwaa platform.
torch ml PyTorch for running Serwaa's multimodal understanding models.
torchaudio ml Audio processing for voice-input handling in conversational flows.
opencv-python ml Computer vision for image understanding in multimodal conversations.
mediapipe ml Perception pipeline models for face and gesture understanding in live interaction features.

Serwaa-specific external integrations (configured via serwaa/.env.example):

Speech-to-text providers:

Service Env Var What it is and how Serwaa uses it
AssemblyAI ASSEMBLYAI_API_KEY A speech-to-text and audio intelligence API with high accuracy and speaker diarisation. Used in Serwaa as a fallback or alternative STT provider to Deepgram for transcribing meeting audio.

Embedding providers:

Service Env Var What it is and how Serwaa uses it
Voyage AI VOYAGE_API_KEY A specialised embedding model provider known for high-quality domain-specific embeddings. Used in Serwaa as an alternative to OpenAI embeddings for semantic memory and retrieval tasks.

Vector database (Serwaa-specific):

Service Env Vars What it is and how Serwaa uses it
Weaviate WEAVIATE_URL, WEAVIATE_API_KEY An open-source, GraphQL-native vector database with built-in ML module support (vectorisation at ingest). Used in Serwaa as an alternative vector store to Qdrant, particularly for configurations where integrated vectorisation is preferred.

Search & research:

Service Env Var What it is and how Serwaa uses it
Tavily TAVILY_API_KEY A search API purpose-built for AI agents, returning structured, concise results optimised for LLM consumption rather than HTML pages. Used by Serwaa's research agent tools to fetch real-time web information.

Video conferencing integrations:

Serwaa integrates with enterprise video-conferencing platforms to provide AI-assistant capabilities inside live meetings (transcription, summarisation, action-item extraction, real-time Q&A).

Platform Env Vars What it is and how Serwaa uses it
Zoom ZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET, ZOOM_WEBHOOK_SECRET The leading video-conferencing platform. Serwaa joins Zoom meetings as an AI participant via Zoom's App Marketplace integration.
Google Meet GOOGLE_MEET_CLIENT_ID, GOOGLE_MEET_CLIENT_SECRET, GOOGLE_MEET_WEBHOOK_SECRET Google's video-conferencing product. Serwaa integrates via Google Workspace APIs to participate in Meet calls.
Microsoft Teams TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, TEAMS_TENANT_ID, TEAMS_BOT_APP_ID, TEAMS_BOT_PASSWORD, TEAMS_WEBHOOK_SECRET Microsoft's enterprise collaboration and video platform. Serwaa is registered as a Teams bot application to attend and assist in Teams meetings.
Webex WEBEX_CLIENT_ID, WEBEX_CLIENT_SECRET, WEBEX_WEBHOOK_SECRET Cisco's enterprise video-conferencing platform. Serwaa integrates via the Webex APIs for meeting participation.
Recall.ai RECALL_API_KEY A universal meeting bot API that provides a single integration layer for joining and recording meetings across Zoom, Teams, Meet, and Webex simultaneously, without maintaining four separate native integrations. Used optionally in Serwaa to simplify multi-platform meeting participation.

Self-hosted TTS alternatives (for air-gapped or cost-sensitive deployments):

Engine Env Vars What it is and how Serwaa uses it
Orpheus ORPHEUS_API_URL, ORPHEUS_MODEL A self-hosted, open-source TTS system. Serwaa can route voice synthesis to a local Orpheus instance for environments where cloud TTS APIs are unavailable or cost-prohibitive.
F5-TTS F5_TTS_API_URL, F5_TTS_VOICE_SAMPLE A self-hosted voice-cloning TTS engine. Provides custom voice synthesis from a reference audio sample, enabling personalised AI assistant voices without cloud dependency.
Piper PIPER_API_URL, PIPER_VOICE A fast, local neural TTS engine designed for real-time speech synthesis on CPU. The lightest-weight self-hosted TTS option in Serwaa's voice stack, used for resource-constrained deployments.

Metis — Educational Platform (services/metis/pyproject.toml)#

Metis is the TypeScript port of the Minerva Python educational platform, providing a TypeScript-native curriculum model. Its Python service layer handles background task processing and provides optional LLM and vector search capabilities that complement the TypeScript core.

Package Version What it is and how Metis uses it
fastapi >=0.115.0 Web framework for Metis's Python service endpoints.
uvicorn[standard] >=0.34.0 ASGI server.
sqlalchemy[asyncio] >=2.0.36 Async ORM for database access.
asyncpg >=0.30.0 Async PostgreSQL driver.
alembic >=1.14.0 Database migrations.
celery[redis] >=5.4.0 Distributed task queue backed by Redis. Used in Metis for processing long-running content generation and curriculum export jobs asynchronously.
boto3 >=1.35.0 AWS SDK for S3 storage operations (exporting curriculum packages, storing generated assets).
langchain >=0.3.0 LLM orchestration (optional). Used when Metis needs to chain multiple LLM calls for curriculum generation workflows.
chromadb >=0.5.0 Embedded vector database (optional). Used for local-development vector search without requiring a separate Qdrant instance.
openai >=1.58.0 OpenAI SDK (optional). Used for content generation when the OpenAI provider is selected.
anthropic >=0.40.0 Anthropic SDK (optional). Used when the Claude provider is selected for content generation.

Shared Python Infrastructure Libraries#

These libraries appear across multiple Python services and form the common infrastructure layer for all Python workloads in Oshun.

Library What it is and how Oshun uses it
asyncpg A high-performance async PostgreSQL driver. The common database connectivity layer across all Python services — used directly and as the driver underneath SQLAlchemy's async engine.
alembic The standard SQLAlchemy migration tool. Each Python service manages its own migration history with Alembic, ensuring schema changes are versioned and reproducible.
celery[redis] A distributed task queue for Python. Used in Metis for background content processing jobs. Uses Redis as the broker and result backend.
grpcio / protobuf The Python gRPC and Protocol Buffers libraries. Used in Psyche and Serwaa to expose high-performance service APIs and consume other gRPC services.
orjson A fast Rust-based JSON serialisation library with a Python API. Used wherever high-throughput JSON handling is needed, particularly in Psyche's real-time pipelines.
boto3 / aiobotocore The sync and async AWS SDKs for Python. Used across Psyche, Metis, and Minerva for S3 storage, Secrets Manager access, and other AWS service interactions.
prometheus-client The official Prometheus Python client. Used to expose service metrics from all Python services on a /metrics endpoint for scraping by the Prometheus monitoring server.

20. Rust / Cargo Ecosystem#

The Rust codebase is the most technically specialised part of Oshun. It exists primarily to power Maya — the Oshun game engine and metaverse domain — through the custom Neith engine, which is built from more than 100 crates. Rust is also used in Uzume (real-time MIDI and protocol engines), and in Iris (a native SDK for tight Node.js integration). The choice of Rust over C++ is deliberate: memory safety eliminates entire classes of security and stability bugs that would be unacceptable in a long-running engine, while zero-cost abstractions ensure there is no performance penalty.


Neith Engine Core (libs/neith/core/Cargo.toml)#

The Neith engine core provides the fundamental building blocks that all other Neith crates build on: async task scheduling, message passing, compression, hashing, serialisation, and observability.

Crate Version What it is and how Neith uses it
tokio 1.x The leading async runtime for Rust. Neith's entire async task system — I/O, timers, channels — runs on Tokio.
tokio-util 0.7 Tokio utilities for async I/O framing, codec streams, and additional future combinators.
crossbeam-channel 0.5 Lock-free, multi-producer multi-consumer channels. Used for the engine's internal message passing between systems where allocation-free communication is critical.
crossbeam-deque 0.8 A work-stealing deque — the data structure at the heart of Neith's parallel task scheduler, allowing worker threads to steal work from each other's queues.
mio 1.0 Low-level non-blocking I/O event multiplexing. Provides the epoll/kqueue/IOCP abstraction underneath Tokio. Used directly in Neith's network layer.
serde 1.0 Rust's de facto serialisation framework. Neith uses serde with derive macros to serialise engine state, scene data, and network messages.
serde_json 1.0 JSON backend for serde. Used for configuration files and debug dumps.
lz4_flex 0.11 Pure-Rust LZ4 compression. Used for fast compression of network packets and asset streams where speed matters more than compression ratio.
zstd 0.13 Zstandard compression with bindings to the reference C library. Used for higher-ratio compression of stored assets and saved game data.
blake3 1.5 An extremely fast cryptographic hash function. Used for asset content addressing, cache invalidation, and integrity verification in Neith.
tracing 0.1 Rust's async-aware structured logging and tracing framework. All Neith subsystems use tracing for instrumentation, enabling full async-context-aware diagnostics.
tracing-subscriber 0.3 Configures and formats tracing output — JSON for production, pretty-printed for development.
opentelemetry 0.27 OpenTelemetry SDK for Rust. Connects Neith's tracing instrumentation to the wider Oshun observability infrastructure (Jaeger, Prometheus).
opentelemetry_sdk 0.27 The OTel SDK implementation for Rust.
opentelemetry-otlp 0.27 OTel OTLP exporter that sends telemetry data over gRPC to the OTel collector.
anyhow 1.0 Ergonomic error handling for Rust applications. Provides a convenient boxed error type that carries context through call chains.
thiserror 2.0 Macro-based derivation of std::error::Error for custom error types. Used to define Neith's typed error hierarchy.
bytes 1.9 Efficient byte buffer utilities with cheap cloning through reference counting. Used extensively in Neith's networking and serialisation code.

Maya Game Engine (libs/maya/engine-core/Cargo.toml)#

The Maya engine core is the entry point for the game engine domain. It defines the entity-component architecture, the main game loop, hot-reloading infrastructure, and the plugin system.

Crate Version What it is and how the Maya engine uses it
glam 0.29 A fast, SIMD-accelerated linear algebra library for game mathematics — vectors, matrices, quaternions, and affine transforms. The universal math type throughout the engine.
bytemuck 1.0 Safe byte casting utilities. Used extensively to convert typed data structures into raw byte slices for GPU uploads.
uuid 1.0 UUID generation with serde support. Used for globally unique entity and asset identifiers.
semver 1.0 Semantic versioning parsing and comparison. Used to manage plugin API compatibility and asset format versioning.
bitflags 2.6 A macro for defining type-safe bitfield flags. Used throughout the engine for component flags, render pass flags, and capability bitmasks.
parking_lot 0.12 Faster synchronisation primitives (Mutex, RwLock, Once) than the Rust standard library implementations. Critical for the engine's hot paths.
crossbeam-channel 0.5 Lock-free channels for inter-thread communication between the engine's main, render, and audio threads.
crossbeam-deque 0.8 Work-stealing deque for the Maya job system's parallel task scheduler.
libloading 0.8 Dynamic library loading at runtime. Enables Maya's plugin system — game code can be compiled as shared libraries and hot-loaded without restarting the engine.
notify 7.0 Cross-platform file system watching with macOS FSEvents backend. Powers Maya's asset hot-reload system, watching for file changes and triggering asset reimport.
log 0.4 The standard Rust logging facade. Provides a uniform logging API that the engine's systems use.
env_logger 0.11 An environment-variable-configured logger that implements the log facade. Used in development and testing configurations.

Uzume Protocol Engines (libs/uzume/protocol-engines/Cargo.toml)#

Uzume is Oshun's event and protocol system, powering the Calliope music domain and any system requiring real-time MIDI or event routing. Its Rust crate is unusual in that it targets multiple compilation environments simultaneously: native Node.js (via napi-rs), WebAssembly (via wasm-bindgen), and standard Rust. This allows the same protocol engine to run in server-side Node.js services, browser WebAssembly modules, and native desktop applications.

Crate Version What it is and how Uzume uses it
tokio 1.44 Async runtime for Uzume's event loop and I/O.
wasm-bindgen 0.2 The bridge between Rust and JavaScript/WebAssembly. Generates the JavaScript bindings that allow Uzume's Rust logic to be called from a browser WASM module.
js-sys 0.3 Rust bindings to the JavaScript standard library (Array, Date, Promise, etc.) for use inside WASM contexts.
serde-wasm-bindgen 0.6 Integrates serde serialisation with wasm-bindgen, allowing Rust data structures to be passed to and from JavaScript via JSON-like conversion.
napi 2.16 Framework for building Node.js native addons in Rust. Allows Uzume's MIDI and event engine to be loaded as a native .node module in the Oshun TypeScript services.
napi-derive 2.16 Derive macros that simplify exposing Rust functions and types to Node.js via the napi framework.
midir 0.10 A cross-platform MIDI I/O library for Rust. Provides real MIDI port enumeration, input listening, and output sending on macOS, Windows, and Linux — the hardware interface for Calliope's musical instrument integration.

Iris Rust SDK (libs/iris/sdk/rust/Cargo.toml)#

The Iris Rust SDK provides a native client library for interacting with the Iris AI coding assistant platform from Rust applications. This is used by the Iris desktop app (built with Tauri) and by any Rust-based tool that wants to integrate with Iris's code intelligence APIs.

Crate Version What it is and how the Iris SDK uses it
tokio 1.35 Async runtime for all SDK network operations.
reqwest 0.11 A high-level, ergonomic HTTP client for Rust with JSON and streaming support. The primary transport for all Iris API calls from the SDK.
chrono 0.4 Date and time handling for Rust. Used for request timestamping and event log entries.
futures 0.3 Core async future and stream abstractions. Used throughout the SDK's async API surface.
async-stream 0.3 A macro for writing async generators that yield items as a stream. Used to implement the SDK's streaming response types (code completion streams, conversation streams).
tokio-stream 0.1 Stream adapter utilities for the Tokio ecosystem. Used to process streaming responses from the Iris API.
backoff 0.4 Exponential backoff retry logic with jitter. The SDK uses this to automatically retry transient Iris API failures with sensible backoff behaviour.

Rust Graphics & Systems (Neith Renderer / Maya)#

These crates form the high-performance systems layer of the Neith engine — the renderer, physics simulation, audio, and network stack. Each was chosen as the best-in-class Rust solution for its domain.

Crate What it is and how Neith uses it
wgpu A safe, cross-platform GPU rendering API for Rust that implements the WebGPU standard. Provides a unified interface over Vulkan, Metal, DX12, and WebGL2 backends. Neith's renderer targets wgpu so the same rendering code runs on Windows, macOS, Linux, and in the browser as WASM.
rapier A pure-Rust physics engine providing rigid body dynamics, continuous collision detection, constraints, and joints. Used in Maya for game physics — character controllers, projectile simulation, destructible environments. Its deterministic simulation is critical for networked multiplayer.
cpal Cross-Platform Audio Library — a Rust library for real-time audio I/O that abstracts over CoreAudio, WASAPI, ALSA, and Web Audio. The foundation of Neith's audio system for all input and output.
rodio A high-level Rust audio playback library built on top of cpal. Provides audio source decoding, mixing, and spatial audio positioning for Neith's game audio engine.
symphonia A pure-Rust media container and codec library. Decodes MP3, AAC, FLAC, Vorbis, and other audio formats for Neith's asset pipeline without requiring FFmpeg or native codecs.
tonic A Rust gRPC framework built on Tokio and prost (Protocol Buffers). Used for inter-service gRPC communication in Neith's distributed server-side engine components.
axum A Rust web framework built on Tokio and Tower. Used for Rust HTTP services within the Neith ecosystem — primarily the engine's REST administration and status APIs.
webrtc A pure-Rust WebRTC implementation. Used in Neith's networking layer (neith-webrtc crate) for peer-to-peer video and audio in the Maya metaverse and for voice chat in Lilith's consciousness experience.

21. Domain-Specific Infrastructure#

Beyond the shared platform infrastructure, several domains run their own Docker Compose configurations with domain-specific service sets. This section documents the infrastructure topology of domains that have non-trivial infrastructure requirements beyond the shared stack.


Maat — Market Intelligence (docker/docker-compose.maat.yml)#

Maat is Oshun's market intelligence platform with agent-based simulation capabilities. Its infrastructure is more complex than most domains because it requires a graph database for market relationship modelling, a dedicated messaging topology on Kafka, and several specialised microservices for intelligence processing, agent orchestration, and simulation.

Service Image / Tech What it does in Maat
maat-neo4j neo4j:5.26.0-community + APOC + GDS plugins Stores the market knowledge graph — companies, sectors, relationships, events — and runs graph algorithms (centrality, community detection) via GDS on the graph data.
maat-api Custom service The API gateway for the Maat domain. Handles authentication, request routing, and exposes the REST and GraphQL interfaces consumed by the Maat frontend.
maat-intelligence Custom service The market intelligence processing service that ingests data from external sources, runs analytics, and produces intelligence events that flow to Kafka.
maat-agents Custom service The agent orchestration service that manages Maat's multi-agent simulation — distributing tasks to agent workers via Kafka and aggregating their outputs.
maat-simulation Custom service Runs the market simulation engine, consuming agent decisions and state updates to advance the simulation time step.
maat-worker Custom service Background job worker for Maat — processes long-running intelligence tasks, model runs, and data ingestion jobs from BullMQ queues.
Kafka Shared instance The event backbone for all Maat services; carries intelligence (maat.intelligence.market), agent task, simulation state, compliance, and strategy events across the 5 dedicated topics (see Section 3).

Env vars: MAAT_DATABASE_URL, MAAT_REDIS_URL, MAAT_NEO4J_URL, MAAT_KAFKA_BROKERS, MAAT_QDRANT_URL


Iris — AI Coding Assistant (docker/docker-compose.iris.yml)#

Iris is Oshun's AI coding assistant platform. Its architecture is that of a multi-service AI system: a conversation service, a hierarchical memory service (implementing a MemGPT-inspired architecture for long-context recall), an agent execution service, and an optional voice service for voice-driven development.

Service What it does in Iris
iris-api The primary API gateway. Routes incoming requests from the Iris desktop app, web PWA, and IDE plugins to the appropriate backend services.
iris-conversation Manages conversational context for each user session — turn history, context window management, and routing requests to the LLM providers.
iris-memory Implements Iris's hierarchical memory system, inspired by MemGPT. Manages tiered memory across in-context working memory, external vector store memory (Qdrant), and persistent long-term storage, enabling Iris to recall information across sessions.
iris-agent The agent execution service. Runs Iris's multi-agent workflows — code generation, refactoring, testing, and analysis tasks that require planning and sequential tool use.
iris-voice Voice services integration (profile: voice). Connects ElevenLabs (TTS), Cartesia (alternative TTS), and Deepgram (STT) to enable voice-driven development interactions.

Key Iris configuration (docker/docker-compose.iris.yml):

Env Var Default What it controls
IRIS_MEMORY_EMBEDDING_MODEL text-embedding-3-small The OpenAI embedding model used by iris-memory to generate vectors for semantic search and memory retrieval.
IRIS_MEMORY_EMBEDDING_DIMENSIONS 1536 The dimensionality of embedding vectors stored in Qdrant. Must match the output dimensions of the embedding model.

Nisaba — Language & Knowledge (libs/nisaba/)#

Nisaba is Oshun's ancient language and knowledge domain, providing scholarly access to cuneiform texts, historical Jewish literature, and other ancient primary sources. Its infrastructure dependencies are primarily external content APIs and a set of Rust-based linguistic processing crates.

Dependency What it provides for Nisaba
Sefaria API Access to the full Sefaria corpus — Tanakh, Talmud, Mishnah, midrash, and commentary — for Jewish and religious text analysis.
CDLI API Access to over 300,000 digitised cuneiform tablets from the Cuneiform Digital Library Initiative for Mesopotamian text research.
IIIF High-resolution manuscript and artefact image access from IIIF-compliant institutional repositories.
Rust language crates Custom Rust crates for linguistic processing — tokenisation, transliteration, and morphological analysis of ancient languages including Sumerian, Akkadian, and Biblical Hebrew.

Env vars: NISABA_DATABASE_URL, NISABA_REDIS_PREFIX, NISABA_SEFARIA_API_URL, NISABA_CDLI_API_URL, NISABA_IIIF_BASE_URL


Shakti — Wellness Platform#

Shakti is Oshun's wellness platform. It manages wellness content, media assets (audio meditations, video sessions), and user wellness data. Its infrastructure requirements are primarily the shared stack (PostgreSQL, Redis) with S3-backed media storage.

Env vars: SHAKTI_DATABASE_URL, SHAKTI_REDIS_PREFIX, SHAKTI_S3_BUCKET, SHAKTI_API_PORT, SHAKTI_API_HOST


Calliope — Music & Composition#

Calliope is Oshun's music and composition platform. It integrates with the Uzume MIDI/protocol engine for real-time musical event processing and provides AI-assisted composition features. Its primary infrastructure need beyond the shared stack is database storage for compositions and project state.

Env vars: CALLIOPE_DATABASE_URL


Psyche — AI Services (docker/psyche/)#

The Psyche domain has a specialised Docker infrastructure to support its compute-intensive AI workloads. It uses purpose-built container images for each service type and a separate GPU-optimised Docker Compose configuration that pins Qdrant to a specific tested version.

Dockerfile What it builds
Dockerfile.reasoning Container image for Psyche's reasoning engine service — the LLM-backed reasoning pipeline with tool use.
Dockerfile.tools Container image for Psyche's tool framework — the runtime that executes tools called by the reasoning engine.
Dockerfile.embedding Container image for Psyche's embedding service — generates vector embeddings for semantic search and memory operations.
Dockerfile.model-manager Container image for Psyche's model lifecycle management service — downloading, caching, and serving ML model weights.
Dockerfile.base Shared Python base image used by all other Psyche Dockerfiles. Contains PyTorch, mediapipe, OpenCV, and other heavy ML dependencies.
docker-compose.gpu.yml GPU-specific Docker Compose overrides. Pins Qdrant to v1.7.4 (a version tested against the GPU inference pipeline), enables Nvidia runtime, and configures GPU device access for PyTorch containers.

22. Security & Secrets Management#

Security in Oshun is implemented at multiple layers: secrets are stored in HashiCorp Vault and AWS Secrets Manager and injected into services at runtime; all inter-service communication inside Kubernetes uses mutual TLS via Istio; tokens are signed with asymmetric keys; and encryption keys are managed through AWS KMS. No service handles raw credentials directly.

Technology What it is and how Oshun uses it
HashiCorp Vault An open-source secrets management platform with granular access control, dynamic secret generation, and automatic rotation. Oshun uses Vault as the authoritative secrets store, with a Kubernetes agent sidecar injecting secrets into pods at startup via template rendering. Secret paths are namespaced per domain.
AWS Secrets Manager AWS's managed secrets service with KMS-backed encryption, automatic rotation, and multi-region replication. Stores all production API keys (RunPod, OpenAI, Anthropic, Stripe, etc.). Primary source of truth for production credentials alongside Vault.
AWS KMS AWS Key Management Service. Manages the customer-managed encryption keys (CMKs) that encrypt data at rest in Secrets Manager, S3 buckets, and RDS databases. All sensitive data storage in AWS is KMS-encrypted.
Istio mTLS Istio's service mesh enforces mutual TLS authentication between every pod in the Kubernetes cluster. No service can communicate with another without presenting a valid certificate, preventing lateral movement if a pod is compromised.
JWT (RS256/HS256) JSON Web Tokens with RS256 (asymmetric) or HS256 (symmetric) signing are used for both user authentication (issued by oshun-auth) and service-to-service authentication. The asymmetric RS256 option allows any service to verify tokens without sharing a secret key.
TLS certificates All external and internal HTTPS endpoints are protected with TLS certificates managed via Terraform, with auto-renewal configured for wildcard and internal domain certificates.

23. Tooling & Build Utilities#

This section covers development tools, build utilities, and specialised libraries that support the engineering workflow across the monorepo — from Protobuf management to AST parsing for Iris's code intelligence features.


Build & Bundling#

Tool Version What it is and how Oshun uses it
Buf 1.66.1 A modern toolchain for Protocol Buffers that provides linting, breaking-change detection, and code generation. Oshun uses buf generate to generate TypeScript and Python gRPC client/server stubs from the proto schemas in libs/proto/oshun/, and buf lint to enforce schema style rules.
tsup — A zero-configuration TypeScript library bundler based on esbuild. Produces CommonJS and ESM output bundles for all shared library packages with correct TypeScript declaration files.
wasm-pack — A tool for building and packaging Rust WebAssembly modules for the browser and Node.js. Used to build the Uzume protocol engine's WASM target and any Neith engine crates that need to run in the browser.
napi-rs — A framework for building Node.js native addons in Rust. Used to build Uzume's native Node.js module target and the Iris Rust SDK's native bindings.
Swagger UI — An interactive web interface for exploring and testing REST APIs defined with OpenAPI specifications. Used to provide developer-friendly API documentation for Oshun's HTTP services.
tsx ^4.7.0 A TypeScript execute runtime (Node.js enhancement) that allows running .ts files directly without a separate compilation step. Used for running TypeScript scripts, seeding databases, and ad-hoc tooling tasks during development without building first.
pnpm catalog — A pnpm workspace feature that centralises dependency version declarations in pnpm-workspace.yaml. All packages reference shared versions via catalog: to prevent version skew across the monorepo.

Schema Validation#

Library Version What it is and how Oshun uses it
Zod ^3.23.0 A TypeScript-first schema declaration and validation library that derives TypeScript types from schemas at compile time. Used throughout Oshun's TypeScript services for validating API request/response payloads, configuration objects, and domain events — providing both runtime safety and static type inference from a single source of truth.

Code Parsing & AST Analysis#

Iris's code intelligence features — indexing codebases, understanding symbols, generating context-aware completions, and performing automated refactoring — require parsing source code into abstract syntax trees. Oshun uses tree-sitter for multi-language incremental parsing and the Babel family for JavaScript/TypeScript AST manipulation.

Library Version What it is and how Iris uses it
tree-sitter ^0.22.0 A parser generator and incremental parsing library that can parse and re-parse source code in real time as it is edited, without re-parsing the entire file. Iris uses tree-sitter as the foundation of its multi-language code indexing system.
tree-sitter-bash — Grammar for Bash syntax. Allows Iris to parse and index shell scripts.
tree-sitter-c — Grammar for C syntax. Enables Iris to understand C source files in mixed-language repositories.
tree-sitter-cpp — Grammar for C++ syntax. Used when Iris analyses C++ code, including parts of the Neith engine codebase.
tree-sitter-rust — Grammar for Rust syntax. Allows Iris to index and understand the entire Neith engine Rust codebase.
tree-sitter-python — Grammar for Python syntax. Used to index Python service code (Psyche, Minerva, Metis, Serwaa).
tree-sitter-javascript — Grammar for JavaScript syntax.
tree-sitter-typescript — Grammar for TypeScript syntax. The most heavily used grammar in Iris, covering the majority of the Oshun monorepo.
tree-sitter-yaml — Grammar for YAML syntax. Allows Iris to understand configuration files, Kubernetes manifests, and CI workflows.
tree-sitter-json — Grammar for JSON syntax. Used to parse package.json, tsconfig.json, and other JSON configuration files.
@babel/parser ^7.25.0 The JavaScript/TypeScript parser from the Babel project, producing a standardised AST. Used alongside tree-sitter for cases requiring Babel's more detailed AST representation.
@babel/traverse ^7.25.0 AST traversal utilities from Babel. Used to walk and transform Babel ASTs for code analysis and automated refactoring in Iris.
@babel/types ^7.25.0 Type definitions and utilities for Babel AST node types. Used alongside @babel/traverse for type-safe AST manipulation.
acorn ^8.14.0 A fast, standards-compliant JavaScript parser that produces an ESTree-compatible AST. Used for lightweight JavaScript parsing where the full Babel toolchain is unnecessary.
acorn-walk ^8.3.0 AST walk utilities for acorn-produced syntax trees. Used to traverse and extract information from acorn-parsed JavaScript.

Media & 3D Processing#

Library Version What it is and how Oshun uses it
sharp ^0.33.0 A high-performance Node.js image processing library backed by the libvips C library. Used across Oshun for resizing, format conversion, thumbnail generation, and optimising images before storage in S3 — particularly in the Isis generation pipeline and Yemaya's asset management.
three ^0.169.0 Three.js — the most widely used JavaScript 3D graphics library, providing a high-level interface over WebGL. Used in the Oshun web frontend for rendering 3D visualisations, sacred geometry in Lilith, and 3D asset previews in Maya's web tooling.
@gltf-transform/core ^4.0.0 A library for reading, writing, and transforming glTF 3D model files. Used in the Maya domain's asset pipeline to optimise, compress, and convert 3D assets before they are loaded into the Neith engine or served to web clients.

Domain-Specific Libraries#

Library Version Domain What it is and how Oshun uses it
astronomy-engine ^2.1.0 Nyx A precise astronomical calculation library that computes planetary positions, eclipse times, rise/set times, and other celestial events for any date and location. Powers Nyx's core astronomical data layer.
rss-parser ^3.13.0 Sophia / Veritas An RSS and Atom feed parsing library. Used by the Sophia research domain for ingesting academic and research feeds, and by Veritas (the AI news agency) for consuming news source feeds as part of its content ingestion pipeline.

Real-time Communication#

Library Version What it is and how Oshun uses it
ws ^8.18.3 A bare-metal WebSocket server and client library for Node.js. Used in services that need direct WebSocket control without the abstraction overhead of Socket.io.
socket.io ^4.7.0 A real-time event communication library that extends WebSockets with rooms, namespaces, automatic reconnection, and fallback transports. Used in legacy services requiring rich real-time features for Lilith session sync and Yemaya collaboration.
socket.io-client ^4.7.0 The client counterpart to socket.io. Used in frontend applications that connect to socket.io servers for real-time features.

General-Purpose Utilities#

These packages are in the shared catalog and used widely across services but do not belong to a single domain or category.

Library Version What it is and how Oshun uses it
axios ^1.7.0 A promise-based HTTP client for both Node.js and the browser with interceptor support, automatic JSON serialisation, and request/response transformation. Used across TypeScript services for making HTTP requests to external APIs where the native fetch API or node-fetch is insufficient.
date-fns ^3.6.0 A comprehensive, modular date utility library for JavaScript. Provides pure functions for parsing, formatting, comparing, and manipulating dates. Used throughout Oshun services for date arithmetic, scheduling, and display formatting without the overhead of a full date library.
nanoid ^5.0.0 A tiny, secure, URL-friendly unique ID generator. Used throughout the platform for generating collision-resistant identifiers for entities, sessions, and generation job IDs.
uuid ^10.0.0 RFC-standard UUID v4 generation. Used where UUID-format identifiers are required by external protocols or database schemas (notably in the Rust game engine via the uuid crate and in TypeScript services).
node-fetch ^3.3.2 A lightweight fetch API implementation for Node.js environments that predate native fetch support. Used in services still running Node versions below 18's native fetch or needing specific fetch behaviours.
cheerio ^1.0.0 A fast, jQuery-compatible HTML parsing and manipulation library for Node.js. Used in Sophia and Veritas for scraping and extracting structured content from web pages during research and news ingestion pipelines.
cron-parser ^4.9.0 A library for parsing and evaluating cron expression syntax. Used in scheduling-related features to validate and compute next-run times for recurring tasks.
eventemitter3 ^5.0.0 A high-performance EventEmitter implementation compatible with Node.js's built-in but significantly faster. Used as the event backbone in services that need high-throughput in-process event dispatch.
ignore ^5.3.0 A library that parses .gitignore-style file exclusion rules. Used in Iris's code-indexing pipeline to respect .gitignore and .iriignore patterns when crawling repository file trees.
minimatch ^9.0.0 A glob-pattern matching library. Used wherever file paths need to be matched against include/exclude glob patterns — primarily in Iris's file-tree analysis and in build tooling.

pnpm patches applied:

  • expo-dev-menu@5.0.23.patch — Fixes a compatibility issue in the Expo dev menu used by Lilith and Tara mobile apps
  • test-exclude@6.0.0.patch — Fixes a test coverage exclusion bug in the Vitest coverage pipeline
  • lz4@0.6.5.patch — Patches the Node.js LZ4 binding used for compressed asset streaming
  • rbxm-parser@1.1.4.patch — Fixes a parser issue in the Roblox model format reader used in Maya's asset import pipeline

24. Summary Counts#

Category Count Services
Cloud providers 3 AWS (primary), GCP, Azure (optional)
AWS services 16 EKS, ECS, RDS, ElastiCache, S3, CloudFront, SQS, SNS, Lambda, CloudWatch, Secrets Manager, KMS, SSM Parameter Store, MSK, DynamoDB, EC2, VPC
AI / ML providers 20 OpenAI, Anthropic, Google AI, ElevenLabs, Deepgram, Cartesia, AssemblyAI, Replicate, HuggingFace, Together AI, Groq, Cohere, Mistral AI, Voyage AI, Stability AI, Tavus, Runway, Azure OpenAI, AWS Bedrock, LiteLLM
LLM frameworks 4 LangChain, LiteLLM, ChromaDB, Model Context Protocol SDK
Video conferencing 5 Zoom, Google Meet, Microsoft Teams, Webex, Recall.ai (all Serwaa integrations)
Search APIs 1 Tavily (AI-optimised web search for agents)
Self-hosted TTS 3 Orpheus, F5-TTS, Piper (Serwaa alternatives)
Databases 7 PostgreSQL, Redis, Qdrant, Weaviate, Elasticsearch, Neo4j, DynamoDB
Message systems 5 Kafka, Zookeeper, BullMQ, Redis Streams, NATS
Object storage 2 MinIO (dev), AWS S3 (prod)
Observability tools 11 Prometheus, Grafana, Jaeger, OpenTelemetry, Pino, Sentry, PostHog, Logstash, Kibana, Filebeat, Metricbeat
Auth / identity 6 JWT, Vault, Google OAuth, GitHub OAuth, Discord OAuth, Apple/Microsoft OAuth
Payment services 2 Stripe, RevenueCat
Email / messaging 5 Mailpit, SendGrid, Firebase, Twilio, Slack/Discord Webhooks
Container runtimes 4 Docker, Kubernetes (EKS/ECS), RunPod, Traefik
CI/CD tools 6 GitHub Actions (80+ workflows), Nx, pnpm, Terraform, ArgoCD, Pulumi
Language runtimes 3 Node.js/TypeScript, Rust, Python
Backend frameworks 4 Fastify, Hono, Express, FastAPI
ORM / DB clients 10 Prisma, Drizzle ORM, Knex.js, pg, ioredis, minio client, SQLAlchemy, asyncpg, alembic, qdrant-client
Python task queues 2 Celery (Metis), Ray (Minerva)
Rust workspaces 4 neith/core, maya/engine-core, uzume/protocol-engines, iris/sdk/rust
Frontend tools 8 React, Next.js, Tailwind CSS, Vite, Zustand, TanStack Query, React Native/Expo, Storybook
Testing tools 6 Vitest, Playwright, React Testing Library, testcontainers, pytest, Storybook
CI/CD workflows 80+ 43 root + ~37 in minerva/serwaa/yaa sub-projects (full root list in Section 11)

Last updated: 2026-04-05

Primary sources of truth to audit on update:

  • docker/docker-compose.dev.yml, docker/docker-compose.yml, docker/docker-compose.maat.yml, docker/docker-compose.iris.yml, infra/elk/docker-compose.elk.yml
  • Root package.json and pnpm-workspace.yaml catalog section
  • Per-service pyproject.toml files: minerva/, services/psyche/, libs/psyche/, serwaa/, services/metis/
  • Key Cargo.toml files: libs/neith/core/, libs/maya/engine-core/, libs/uzume/protocol-engines/, libs/iris/sdk/rust/
  • Terraform versions.tf files across deploy/terraform/, infra/terraform-v1/, infra/terraform/iris/
  • .github/workflows/ (root) + minerva/.github/workflows/, serwaa/.github/workflows/, yaa/.github/workflows/
  • .env.example (root) for domain-specific env var names