# Oshun Ecosystem — Infrastructure & Dependency Registry 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](#1-cloud-providers--compute) 2. [Databases](#2-databases) 3. [Message Queues & Event Streaming](#3-message-queues--event-streaming) 4. [Object Storage & CDN](#4-object-storage--cdn) 5. [AI / ML Services](#5-ai--ml-services) 6. [Authentication & Identity](#6-authentication--identity) 7. [Payment & Billing](#7-payment--billing) 8. [Monitoring & Observability](#8-monitoring--observability) 9. [Email & Notifications](#9-email--notifications) 10. [Containerization & Orchestration](#10-containerization--orchestration) 11. [CI/CD & Build Infrastructure](#11-cicd--build-infrastructure) 12. [Language Runtimes](#12-language-runtimes) 13. [Backend Frameworks](#13-backend-frameworks) 14. [ORM & Database Clients](#14-orm--database-clients) 15. [Frontend Stack](#15-frontend-stack) 16. [API Standards & Protocols](#16-api-standards--protocols) 17. [Testing Frameworks](#17-testing-frameworks) 18. [External Content APIs](#18-external-content-apis) 19. [Python Service Dependencies](#19-python-service-dependencies) 20. [Rust / Cargo Ecosystem](#20-rust--cargo-ecosystem) 21. [Domain-Specific Infrastructure](#21-domain-specific-infrastructure) 22. [Security & Secrets Management](#22-security--secrets-management) 23. [Tooling & Build Utilities](#23-tooling--build-utilities) 24. [Summary Counts](#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//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 ` 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