Veritas Domain — Architecture — Veritas domain

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.

text

+──────────────────────────────────────────────────────────────────────────+
│                           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.

text

 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:

text

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:

text

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):

text

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.

text

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.

text

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ɔ.

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.

text

+────────────────────────────────────────────────────────────────────────+
│                       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.

text

@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#

text

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.

text

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.

text

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.

text

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

Architecture Overview#

System Context#

External System Integrations#

Application Architecture#

veritas-api#

veritas-nlp#

veritas-ingestion#

veritas-agents#

veritas-ai-workers#

veritas-cms#

veritas-video#

veritas-audio#

veritas-social#

Library Architecture#

Dependency Graph#

Key Library Relationships#

Data Flow Diagrams#

News Ingestion Pipeline#

AI Editorial Pipeline#

Multimedia Production Pipeline#

Key Design Decisions#

1. Modular Monolith over Microservices#

2. Hono as HTTP Framework#

3. BullMQ for All Background Processing#

4. PostgreSQL with pgvector for Semantic Storage#

5. Prisma for Schema Management#

6. Seven-Agent Newsroom Architecture#

7. Ghana-Centric Language Architecture#

8. USSD Channel for Feature Phone Access#

9. Dual B2B SDKs#

Infrastructure Requirements#

Application Ports#

Production Deployment#

Domain Boundaries#