# Veritas Domain — Architecture Named after the Roman goddess of truth, Veritas is the autonomous AI-powered news agency for Ghana and West Africa. Where a traditional newsroom employs dozens of people to discover, verify, write, and distribute news, Veritas replaces that workflow with an integrated pipeline: software agents continuously monitor Ghanaian news sources, extract and fact-check claims, generate multimedia content, and distribute stories across every platform where Ghanaian audiences consume news — the web, mobile apps, YouTube, WhatsApp, USSD feature phones, and beyond. The platform is designed with Ghana's specific media landscape at its core. This means built-in support for six Ghanaian languages (English, Twi, Ewe, Ga, Hausa, Dagbani), Ghana-specific political bias tracking aligned to the NDC/NPP spectrum, three mobile money payment providers, and a USSD channel so that readers without smartphones can access headlines via basic phone menus. Veritas is a product of the Oshun monorepo and operates as a self-contained domain. It does not depend on other Oshun domains for its core function, though it publishes and subscribes to the platform-wide event bus and delegates copyright enforcement to Themis, content moderation to Kuanyin, and academic research grounding to Sophia. --- ## Architecture Overview **Architecture Type**: Modular monolith with service-oriented decomposition Veritas uses 13 applications coordinated through 64 shared libraries and three core infrastructure services (PostgreSQL, Redis, Elasticsearch). Each application is a standalone Node.js process (or mobile/web client) that can be deployed and scaled independently, while sharing a common library layer that enforces consistent business logic, type safety, and validation. The system is organized into five conceptual layers. Reading bottom-to-top, the Data Layer stores all persistent state; the Ingestion Layer continuously discovers and normalizes new content from the outside world; the Processing Layer applies AI analysis and editorial logic; the API Layer exposes everything to clients; and the Client Layer is the reader-facing surface. ``` +──────────────────────────────────────────────────────────────────────────+ │ CLIENT LAYER │ │ Web PWA (Next.js) | Mobile (Expo/RN) | USSD | B2B SDK │ +──────────────────────────────────────────────────────────────────────────+ │ API LAYER │ │ REST API (Hono) | NLP Service (Hono) | Analytics │ +──────────────────────────────────────────────────────────────────────────+ │ PROCESSING LAYER │ │ Agents | AI Workers | CMS | Video | Audio | Social │ +──────────────────────────────────────────────────────────────────────────+ │ INGESTION LAYER │ │ Scheduler | Producer | Worker | Notifications │ +──────────────────────────────────────────────────────────────────────────+ │ DATA LAYER │ │ PostgreSQL (pgvector) | Redis | Elasticsearch | MinIO (S3) │ +──────────────────────────────────────────────────────────────────────────+ ``` --- ## System Context ### External System Integrations Veritas integrates with a large ecosystem of external APIs. The diagram below shows which external systems feed into the platform and which downstream channels it pushes content to. ``` AI/LLM Providers Media Production Search/Fact-Check ───────────────── ──────────────── ───────────────── Anthropic Claude HeyGen (video avatars) Serper OpenAI ElevenLabs (English TTS) Brave Search Cohere (embeddings) Ghana NLP/Khaya (local) ClaimBuster HuggingFace Tavus CVI (live Q&A) Google FCT Shotstack / D-ID │ ▼ ┌─────────────────────────┐ │ VERITAS PLATFORM │ │ veritas-api (Hono) │ │ veritas-nlp (Hono) │ │ 64 shared libraries │ └─────────────────────────┘ │ ▼ Payment Gateways Social Platforms Client Apps ──────────────── ──────────────── ─────────── Stripe YouTube Web PWA Paystack TikTok Mobile App MTN MoMo Instagram B2B Partners Vodafone Cash Facebook USSD/Feature Phones AirtelTigo WhatsApp / Telegram LinkedIn / X/Twitter ``` --- ## Application Architecture Veritas ships 13 Nx applications. Each application is a standalone deployable that imports from the shared library layer for its domain logic. The sections below describe each application's purpose, configuration, and internal structure. ### veritas-api The primary REST API gateway for all client applications. Every request from the web app, mobile app, and B2B partners passes through this service. - **Framework**: Hono with `@hono/node-server` - **API spec**: OpenAPI document via `generateOpenApiSpec`, Swagger UI at `/docs`, JSON at `/openapi.json` (server base URL `/api/v1`) - **Authentication**: API key via `X-API-Key` header; a separate JWT access token mechanism backs the `/auth/*` routes - **Rate limiting**: Redis-backed sliding window applied to `/api/*` - **Sandbox mode**: test API keys (`sk_test_*`) route through sandbox middleware with `X-Sandbox-*` request headers - **29 v1 route groups** mounted under `/api/v1`: auth, articles, sources, claims, bias, stories, taxonomy, audio/video, voice/avatar profiles, writing assistant, tips, preferences, reading mode, compliance (NMC), data protection, election coverage, payments (MoMo/Vodafone/AirtelTigo/Stripe), subscriptions, paywall, subscription analytics, ads, ad networks, B2B API, and API keys The internal directory structure keeps infrastructure concerns — database pooling, Redis, Elasticsearch — cleanly separated from the HTTP route handlers: ``` apps/veritas/api/src/ main.ts # Entry point, config, startup interfaces/http/ server.ts # Hono app and middleware routes/v1/ # Route handlers infrastructure/ postgres/createPool.ts # PostgreSQL connection pool redis/createRedis.ts # Redis client elasticsearch/createClient.ts # Elasticsearch client ``` ### veritas-nlp Dedicated NLP microservice. Separate process from the API to allow independent scaling during high-analysis load. Running NLP in its own process means a surge in sentiment analysis requests (e.g., during an election) does not starve the API of resources. - 23 HTTP endpoints (plus health/readiness) covering sentiment, topics, keywords, summarization, claims, language detection, code-switching, Ghanaian English normalization, embeddings, similarity, evidence search, and Ghana NLP TTS/NER/translation — most with a `/batch` variant ### veritas-ingestion Four operational modes in a single deployable. This design means one Docker image covers the full ingestion lifecycle — scheduling, queuing, processing, and seeding — without requiring four separate builds. | Mode | Command | Description | | --------- | ------------------------ | ---------------------------------------------------- | | Scheduler | `node main.js scheduler` | Timed RSS/sitemap/social polling | | Producer | `node main.js producer` | Dequeue unprocessed items → BullMQ | | Worker | `node main.js worker` | Process queue: scrape, normalize, deduplicate, store | | Seed | `node main.js seed` | Seed Ghana news sources (33 Tier-1 + government) | The `seed` command upserts `TIER1_GHANA_SOURCES` (21 Tier-1 Ghana media sources) and `GOVERNMENT_SOURCES` (12 government/institutional sources), together contributing roughly 102 feeds. The ingestion pipeline runs as a multi-stage assembly line, with each stage handing off to the next via the BullMQ queue: ``` RSS/Sitemap/Social Sources ↓ Scheduler (collect raw items → PostgreSQL) ↓ Producer (unprocessed items → BullMQ queue veritas:content-processing) ↓ Worker (scrape → normalize → language detect → SimHash near-dup detection → store) ↓ PostgreSQL + Elasticsearch ``` ### veritas-agents Multi-agent orchestration service with event-driven architecture. The seven agents are modelled on a real newsroom hierarchy — the Editor-in-Chief sets editorial standards, the Managing Editor coordinates quality, the Fact-Checker verifies claims, and so on down to the Social Media Manager. - **7 default agents** (Editor-in-Chief priority 10, Managing Editor 9, Fact-Checker 8, two Journalists 7, Content Strategist 6, Social Media Manager 5) - **Orchestrator**: Load-balanced task distribution with auto-scaling and agent registry - **Message Bus**: Redis pub/sub with in-memory fallback - **State Manager**: Redis KV with TTL and compression - **Health Monitor**: Automatic self-healing with configurable failure thresholds ### veritas-ai-workers BullMQ workers for AI content processing. Workers are independent processes that pull from Redis queues. 24 workers across four registries (`ALL_WORKERS`): ``` Content Generation (8): weather-report | traffic-update | market-summary | fuel-price gpl-score | ecg-load-shedding | event-calendar | trend-analysis Content Processing (9): article-summarization | headline-variants | article-tagging article-priority | claim-linking | press-release | breaking-news entity-extraction | seo-metadata Analysis (5): story-clustering | source-accuracy | blindspot-detection political-bias | sentiment-analysis Editorial (2): fact-check | original-content ``` ### veritas-cms Editorial CMS with Anthropic Claude-powered quality reviews. The CMS sits between the AI processing pipeline and final publication, giving the editorial agents a structured workflow to manage drafts before they reach readers. - **Scheduling**: Ghana timezone (Africa/Accra), quiet hours 22:00–06:00, max 6 articles per 30-minute window - **AI Reviews**: Claude-powered approve/reject/request-changes decisions at Managing Editor and Editor-in-Chief stages ### veritas-video HeyGen video production service. Articles are converted into professional news video segments with AI avatar anchors, then published to social video platforms automatically. ``` Article → Script Generation (Claude) → Avatar Selection (HeyGen) → Video Rendering → Captioning → Platform Optimization → Publishing ``` Targets: YouTube, YouTube Shorts, TikTok, Instagram Reels ### veritas-audio TTS and podcast pipeline. English articles use ElevenLabs for natural-sounding voice; local-language articles use the Ghana NLP Khaya API, making Veritas the first news audio service in Twi, Ewe, Ga, Hausa, and Dagbani at scale. ``` Article → Text Chunking → Voice Assignment → TTS (ElevenLabs/Ghana NLP) → Audio Storage (S3/MinIO) → Podcast RSS Generation → Distribution ``` Six podcast series: Veritas Daily News Digest, Weekly Deep Dive, Sports Recap, Money Matters, Veritas Culture, and Twi Dawubɔ. ### veritas-social Multi-platform social automation for Instagram, Facebook, WhatsApp, Twitter/X, YouTube, TikTok, Telegram, LinkedIn. Three modes: HTTP server, BullMQ worker, scheduler. --- ## Library Architecture ### Dependency Graph The 64 libraries form four tiers. Foundation libraries are imported by everything above them; Domain libraries implement the core editorial logic; Service libraries handle cross-cutting concerns like auth and payments; Application libraries are feature bundles consumed directly by the apps. ``` +────────────────────────────────────────────────────────────────────────+ │ APPLICATION LIBRARIES │ │ live-stream | social-automation | audio-production | video-production │ │ automated-content | emergency | newsletter | seo │ +────────────────────────────────────────────────────────────────────────+ ↑ ↑ +────────────────────────────────────────────────────────────────────────+ │ DOMAIN LIBRARIES │ │ agents-* | cms | rag | knowledge-graph | recommendations │ │ headline-service | article-generation | content-classification │ │ fact-checking | bias-detection | claims | story-clustering │ +────────────────────────────────────────────────────────────────────────+ ↑ ↑ +────────────────────────────────────────────────────────────────────────+ │ SERVICE LIBRARIES │ │ analytics | payments | billing | notifications | b2b-sdk │ │ auth | search | cache | storage | events | community | ussd │ +────────────────────────────────────────────────────────────────────────+ ↑ ↑ +────────────────────────────────────────────────────────────────────────+ │ FOUNDATION LIBRARIES │ │ core | models | database | llm | nlp-core | ghana-nlp │ │ ingestion-core | agents-core | content-auth │ +────────────────────────────────────────────────────────────────────────+ ``` ### Key Library Relationships The three dependency chains below show which foundation library anchors each major subsystem. `@veritas/core` anchors the data model; `@veritas/llm` anchors the agent system; `@veritas/nlp-core` anchors all analysis and fact-checking. ``` @veritas/core └─ @veritas/models (Zod validation of core types) └─ @veritas/database (Prisma, repositories) ├─ @veritas/auth ├─ @veritas/cache └─ @veritas/search @veritas/llm └─ @veritas/agents-core (base agent + LLM client) ├─ @veritas/agents-orchestrator ├─ @veritas/agents-editorial ├─ @veritas/agents-journalism ├─ @veritas/agents-fact-checking └─ @veritas/agents-social-media @veritas/nlp-core ├─ @veritas/ghana-nlp (Khaya API) ├─ @veritas/bias-detection ├─ @veritas/fact-checking ├─ @veritas/claims ├─ @veritas/content-classification └─ @veritas/story-clustering ``` --- ## Data Flow Diagrams The following diagrams trace the three main journeys content takes through the system: discovery and normalization, AI editorial enrichment, and multimedia production. ### News Ingestion Pipeline ``` RSS Feeds → Sitemap URLs → Social Media (X/Twitter) ↓ SCHEDULER (veritas-ingestion) Raw collection → PostgreSQL feed_items ↓ PRODUCER (veritas-ingestion) Unprocessed items → BullMQ (Redis) ↓ WORKER (veritas-ingestion) Scrape → Normalize → Language detect → SimHash near-dup detection → Attribute → Store ↓ PostgreSQL articles + Elasticsearch index ``` ### AI Editorial Pipeline Once an article is ingested it enters a parallel AI enrichment and editorial review process. AI workers apply fast, queue-based enrichment first; the slower, more considered agent workflow then handles editorial decisions. ``` New Articles (post-ingestion) ↓ AI WORKERS (BullMQ) article-summarization → headline-variants → tagging → fact-check ↓ AI AGENTS (veritas-agents) Fact-Checker → Verify claims, add evidence Managing Editor → Review balance and quality Editor-in-Chief → Approve/reject for publication Content Strategist → Plan topic coverage Social Media Manager → Queue social posts ↓ CMS (veritas-cms) Draft → AI Review → Schedule → Publish ``` ### Multimedia Production Pipeline Published articles are simultaneously converted to video, audio, and social posts, enabling a single piece of journalism to reach audiences on every major platform. ``` Published Articles ├── veritas-video → HeyGen → YouTube/TikTok/Shorts/Reels ├── veritas-audio → ElevenLabs/Ghana NLP → Podcast RSS / S3 └── veritas-social → Meta/YouTube/Telegram/LinkedIn/X ``` --- ## Key Design Decisions ### 1. Modular Monolith over Microservices Veritas uses a modular monolith where all services share a common library layer, rather than fully independent microservices. For a news platform where data consistency and latency matter, shared libraries avoid inter-service serialization overhead while still allowing independent deployment. ### 2. Hono as HTTP Framework Hono provides excellent TypeScript support, built-in OpenAPI integration via `@hono/zod-openapi`, minimal overhead, and consistent patterns across the API and NLP services. ### 3. BullMQ for All Background Processing BullMQ (Redis-backed) provides reliable job processing with retries, priorities, delayed execution, repeatable schedules, and concurrency control. It is used for ingestion, AI workers, video/audio production, and social media scheduling. ### 4. PostgreSQL with pgvector for Semantic Storage PostgreSQL serves as both relational database and vector store (via pgvector). This avoids the operational complexity of a separate vector database while providing sufficient embedding search performance for hundreds of thousands of articles. Elasticsearch handles full-text search only. ### 5. Prisma for Schema Management Prisma provides type-safe database access and schema-first migrations. Raw `pg` is used in the API for performance-critical queries requiring fine-grained SQL control. ### 6. Seven-Agent Newsroom Architecture Seven specialized agents mirror a real newsroom structure. Each agent has focused capabilities and priority levels (10 for Editor-in-Chief down to 5 for Social Media Manager), enabling nuanced editorial decisions that a single monolithic pipeline cannot produce. ### 7. Ghana-Centric Language Architecture Ghana's multilingual reality (6+ major languages with pervasive code-switching) is built into the core architecture, not added as an afterthought. The NLP service includes dedicated endpoints for code-switching detection, Ghanaian English normalization, and Ghana NLP Khaya API integration. ### 8. USSD Channel for Feature Phone Access A significant portion of Ghanaians access information through feature phones. The `@veritas/ussd` library provides text-based news delivery with voice callback support through MTN, Vodafone, AirtelTigo, and Glo gateway adapters. ### 9. Dual B2B SDKs B2B API consumers receive both TypeScript (`@veritas/b2b-sdk`) and Python (`@veritas/b2b-sdk-python`) SDKs. The Python SDK supports async and sync usage patterns. Both provide type hints, rate limiting, and retry logic. --- ## Infrastructure Requirements ### Application Ports The HTTP services read their port from an environment variable. The verified in-code default is the API at port `3002` (env `PORT`) and the NLP service at port `3002` (env `NLP_PORT`); other services bind whatever port their deployment environment supplies. | Service | Variable | In-code default | | -------------- | ---------- | --------------- | | veritas-api | `PORT` | `3002` | | veritas-nlp | `NLP_PORT` | `3002` | | veritas-agents | (config) | — | | veritas-cms | (config) | — | | veritas-video | `PORT` | — | | veritas-social | `PORT` | — | ### Production Deployment Veritas is designed for Kubernetes or AWS ECS with horizontal scaling. Worker pools are autoscaled independently of the API tier; the data tier uses managed cloud services rather than self-hosted databases in production. ``` Load Balancer (ALB/Nginx) ├── API (3+ pods) ├── NLP (2+ pods) ├── Web (2+ pods, CDN-cached) └── Worker Pool (autoscaled) ├── Ingestion Workers ├── AI Workers ├── Video Workers ├── Audio Workers └── Social Workers ↓ Data Tier (Managed Services) RDS PostgreSQL | ElastiCache Redis | OpenSearch | S3 ``` --- ## Domain Boundaries Veritas owns the entire news production pipeline from source ingestion to multi-platform distribution. The boundaries below explain not just what each domain owns, but why the boundary is placed there. **Veritas provides:** - Complete news production pipeline from ingestion to publication - AI-powered editorial agents and quality control - Ghana-specific NLP, language support, and payment integration - Multimedia production (video, audio, podcasts, live streaming) - Multi-platform social media distribution - B2B API with TypeScript and Python SDKs - USSD channel for feature phone access **Veritas does not provide (and why):** - Generic content management unrelated to news — that is not Veritas's domain - Live performance or media production — owned by the Uzume domain, which is purpose-built for live events - Music production — owned by the Euterpe domain - Governance or policy analysis — owned by the Themis domain, which has dedicated IP and copyright enforcement capabilities that Veritas relies on via `@themis/text-shield` for originality scanning **Cross-domain data flows:** - Veritas publishes and subscribes to the `@oshun/event-bus` for platform-wide events such as breaking news alerts and user subscription changes - Veritas delegates copyright and originality enforcement to Themis; generated articles will be submitted to `@themis/text-shield` (planned) - Veritas delegates comment moderation to Kuanyin, which provides the platform-wide safety and moderation layer - Veritas uses Sophia for academic research grounding in investigative journalism features **Shared infrastructure:** - `@oshun/database`, `@oshun/errors`, `@oshun/logging` shared libraries - Docker Compose dev infrastructure at `docker/docker-compose.dev.yml` - Nx build system for all project targets