# Veritas Domain

> **Veritas** - AI-Powered News Agency for Ghana and West Africa

Veritas is an autonomous AI-powered news agency that combines multi-source news
aggregation, AI-driven editorial workflows, fact-checking, multilingual support
for Ghanaian languages, and multimedia production (video, audio, podcasts,
social media). Named after the Roman goddess of truth, Veritas delivers
verified, balanced news across digital, mobile, social, USSD, and broadcast
channels.

Originally developed as the standalone **Yaa** project, Veritas was integrated
into the Oshun monorepo as a dedicated domain with the library prefix
`@veritas/*` and app prefix `veritas-*`.

---

## Table of Contents

1. [Overview](#overview)
2. [Key Features](#key-features)
3. [Applications](#applications)
4. [Library Ecosystem](#library-ecosystem)
5. [Technology Stack](#technology-stack)
6. [Quick Start](#quick-start)
7. [Language Support](#language-support)
8. [Cross-Domain Integration](#cross-domain-integration)
9. [Related Documentation](#related-documentation)

---

## Overview

Veritas provides a complete news production and distribution pipeline:

- **Ingestion**: Automated collection from 300+ RSS feeds, sitemaps, and social
  media sources across Ghanaian news outlets
- **NLP Analysis**: Sentiment analysis, topic classification, entity extraction,
  language detection, embeddings, summarization, and claim extraction
- **AI Agents**: Seven specialized newsroom agents (editor-in-chief, managing
  editor, journalists, fact-checker, content strategist, social media manager)
  that orchestrate the editorial pipeline
- **Fact-Checking**: Claim extraction, evidence retrieval, bias detection, and
  Ghana Political Lean (GPL) scoring
- **Content Generation**: AI-generated articles, weather reports, market
  summaries, fuel price updates, and trend analysis
- **Multimedia Production**: AI video anchors (HeyGen), text-to-speech
  (ElevenLabs, Ghana NLP), podcast series, and 24/7 live streaming
- **Multi-Platform Distribution**: Web PWA, mobile app (React Native/Expo),
  YouTube, TikTok, Instagram, Facebook, WhatsApp, Telegram, LinkedIn, and USSD
- **B2B API**: RESTful API with SDKs (TypeScript and Python) for third-party
  news consumers and partners

### Key Statistics

| Metric                | Value                                           |
| --------------------- | ----------------------------------------------- |
| Applications          | 13 (web, mobile, api, nlp, agents, video, etc.) |
| Libraries             | 57+ domain modules                              |
| API Endpoints         | 80+ REST endpoints                              |
| Database Tables       | 50+ tables                                      |
| External Integrations | 30+ third-party APIs                            |
| Supported Languages   | 6 (English, Twi, Ewe, Ga, Hausa, Dagbani)       |
| AI Agent Types        | 7 specialized newsroom agents                   |
| NLP Services          | 13 analysis modules                             |
| Content Sources       | 300+ Ghanaian news outlet RSS feeds             |
| Payment Providers     | 4 (Stripe, MTN MoMo, Vodafone Cash, AirtelTigo) |

---

## Key Features

### Automated News Ingestion

- RSS, sitemap, and social media collectors with configurable schedules
- Semantic deduplication using pgvector embeddings
- Language detection for all 6 supported Ghanaian languages
- Content normalization, timestamp standardization, and media extraction
- Source attribution tracking and reliability scoring

### AI Newsroom Agents

Seven specialized AI agents powered by Anthropic Claude that simulate a
professional newsroom:

| Agent              | Priority | Role                                   |
| ------------------ | -------- | -------------------------------------- |
| Editor-in-Chief    | 10       | Editorial decisions, content approval  |
| Managing Editor    | 9        | Content editing, editorial standards   |
| Fact-Checker       | 8        | Claim verification, evidence retrieval |
| Journalists (x2)   | 7        | Investigative and political reporting  |
| Content Strategist | 6        | Trending topics, content planning      |
| Social Media Mgr   | 5        | Social posting, audience engagement    |

### Fact-Checking and Bias Detection

- Automated claim extraction from articles
- Evidence retrieval and cross-referencing
- Ghana Political Lean (GPL) scoring with political spectrum analysis
- Coverage blindspot detection (inspired by Ground News)
- Source credibility tracking and accuracy scoring

### Multimedia Production

- **Video**: AI avatar anchors via HeyGen, captioning, YouTube Shorts, TikTok,
  Instagram Reels production
- **Audio**: Text-to-speech via ElevenLabs and Ghana NLP (local languages),
  podcast series with automated scheduling and distribution
- **Live Streaming**: 24/7 YouTube Live infrastructure with RTMP server,
  lower-thirds graphics, breaking news overlays, and viewer Q&A

### Content Management

- Editorial CMS with draft, review, schedule, publish, and archive workflows
- AI-powered quality control reviews (Managing Editor QC, Editor-in-Chief
  standards)
- Revision history with content diffing
- Priority-based scheduling with peak traffic window optimization
- Ghana timezone-aware quiet hours (Africa/Accra)

---

## Applications

All applications live under `apps/veritas/` in the Oshun monorepo.

### Backend Services

| Application       | Nx Project              | Port | Description                                                       |
| ----------------- | ----------------------- | ---- | ----------------------------------------------------------------- |
| **API**           | `veritas-api`           | 3001 | REST API with Hono, OpenAPI docs, JWT auth, rate limiting         |
| **NLP**           | `veritas-nlp`           | 3002 | NLP microservice (sentiment, topics, embeddings, Ghana NLP)       |
| **Ingestion**     | `veritas-ingestion`     | --   | Scheduler, producer, and worker for RSS/sitemap/social collection |
| **AI Workers**    | `veritas-ai-workers`    | --   | BullMQ workers for AI content processing tasks                    |
| **Agents**        | `veritas-agents`        | 3006 | Multi-agent orchestration service with message bus and state      |
| **CMS**           | `veritas-cms`           | 3004 | Editorial content management with scheduling and AI reviews       |
| **Notifications** | `veritas-notifications` | --   | Email (SMTP/SendGrid/SES) and FCM push notification delivery      |
| **Analytics**     | `veritas-analytics`     | 3004 | Content, user, revenue, social, and real-time analytics           |

### Media Services

| Application | Nx Project       | Port | Description                                                   |
| ----------- | ---------------- | ---- | ------------------------------------------------------------- |
| **Video**   | `veritas-video`  | 3004 | HeyGen video rendering, captioning, YouTube/TikTok production |
| **Audio**   | `veritas-audio`  | --   | ElevenLabs/Ghana NLP TTS, podcast pipeline, voice profiles    |
| **Social**  | `veritas-social` | 3005 | Multi-platform social media automation and scheduling         |

### Client Applications

| Application | Nx Project       | Port | Description                                                |
| ----------- | ---------------- | ---- | ---------------------------------------------------------- |
| **Web**     | `veritas-web`    | 3000 | Next.js PWA with i18n (next-intl), Tailwind CSS, React 19  |
| **Mobile**  | `veritas-mobile` | --   | Expo/React Native app with Zustand state, i18next, offline |

---

## Library Ecosystem

All libraries live under `libs/veritas/` in the Oshun monorepo and use the
`@veritas/*` package prefix.

### Core Foundation

| Library    | Package             | Description                                          |
| ---------- | ------------------- | ---------------------------------------------------- |
| `core`     | `@veritas/core`     | Core types, branded primitives (Uuid, Slug, etc.)    |
| `models`   | `@veritas/models`   | Shared data model schemas with Zod validation        |
| `database` | `@veritas/database` | Prisma client, repositories, health monitoring       |
| `auth`     | `@veritas/auth`     | Authentication adapter, API keys, OAuth, middleware  |
| `cache`    | `@veritas/cache`    | Redis caching (articles, sessions, search, realtime) |
| `search`   | `@veritas/search`   | Elasticsearch client, query builder, index manager   |

### AI and NLP

| Library                | Package                         | Description                                |
| ---------------------- | ------------------------------- | ------------------------------------------ |
| `llm`                  | `@veritas/llm`                  | LLM client router, cost optimizer, prompts |
| `agents-core`          | `@veritas/agents-core`          | Base agent framework and LLM integration   |
| `agents-orchestrator`  | `@veritas/agents-orchestrator`  | Multi-agent workflow orchestration         |
| `agents-editorial`     | `@veritas/agents-editorial`     | Editorial content agents                   |
| `agents-journalism`    | `@veritas/agents-journalism`    | Journalist and reporter agents             |
| `agents-fact-checking` | `@veritas/agents-fact-checking` | Fact-checker agent with evidence retrieval |
| `agents-social-media`  | `@veritas/agents-social-media`  | Social media management agents             |
| `agents-devops`        | `@veritas/agents-devops`        | DevOps and infrastructure agents           |
| `agents-product`       | `@veritas/agents-product`       | Product management agents                  |
| `agents-qa`            | `@veritas/agents-qa`            | Quality assurance agents                   |
| `nlp-core`             | `@veritas/nlp-core`             | NLP primitives and shared utilities        |
| `ghana-nlp`            | `@veritas/ghana-nlp`            | Ghana NLP API client (Twi, Ewe, Ga, etc.)  |
| `bias-detection`       | `@veritas/bias-detection`       | Political bias analysis and GPL scoring    |
| `fact-checking`        | `@veritas/fact-checking`        | Claim verification and evidence scoring    |
| `claims`               | `@veritas/claims`               | Claim extraction and linking               |

### Content and Knowledge

| Library                  | Package                           | Description                              |
| ------------------------ | --------------------------------- | ---------------------------------------- |
| `rag`                    | `@veritas/rag`                    | RAG pipeline (indexing, search, archive) |
| `knowledge-graph`        | `@veritas/knowledge-graph`        | Entity graph, profiles, relationships    |
| `story-clustering`       | `@veritas/story-clustering`       | Semantic story grouping and timeline     |
| `recommendations`        | `@veritas/recommendations`        | Collaborative/content-based filtering    |
| `headline-service`       | `@veritas/headline-service`       | Headline generation and A/B testing      |
| `article-generation`     | `@veritas/article-generation`     | AI article drafting pipeline             |
| `content-classification` | `@veritas/content-classification` | Topic and category classification        |
| `content-auth`           | `@veritas/content-auth`           | Content authenticity and provenance      |
| `cms`                    | `@veritas/cms`                    | CMS workflow engine                      |
| `ingestion-core`         | `@veritas/ingestion-core`         | Core ingestion pipeline primitives       |

### Media Production

| Library             | Package                      | Description                                   |
| ------------------- | ---------------------------- | --------------------------------------------- |
| `audio-production`  | `@veritas/audio-production`  | Audio rendering and mastering pipeline        |
| `video-production`  | `@veritas/video-production`  | Video composition and rendering pipeline      |
| `live-stream`       | `@veritas/live-stream`       | 24/7 YouTube Live, RTMP, graphics, viewer Q&A |
| `social-automation` | `@veritas/social-automation` | Cross-platform social media posting           |

### Business and Monetization

| Library          | Package                   | Description                                     |
| ---------------- | ------------------------- | ----------------------------------------------- |
| `analytics`      | `@veritas/analytics`      | Content, user, revenue, social analytics        |
| `payments`       | `@veritas/payments`       | Stripe, Paystack, mobile money integration      |
| `billing`        | `@veritas/billing`        | Subscriptions, invoicing, pricing, usage        |
| `notifications`  | `@veritas/notifications`  | Push (FCM), email, SMS notification delivery    |
| `b2b-sdk`        | `@veritas/b2b-sdk`        | TypeScript SDK for B2B API consumers            |
| `b2b-sdk-python` | `@veritas/b2b-sdk-python` | Python SDK for B2B API consumers (async + sync) |
| `business`       | `@veritas/business`       | Business logic and domain rules                 |
| `seo`            | `@veritas/seo`            | SEO optimization and sitemap generation         |
| `newsletter`     | `@veritas/newsletter`     | Email newsletter campaigns                      |

### Regional and Access

| Library             | Package                      | Description                                     |
| ------------------- | ---------------------------- | ----------------------------------------------- |
| `regional`          | `@veritas/regional`          | Region-specific content and configuration       |
| `ussd`              | `@veritas/ussd`              | USSD channel for telco news delivery (MTN etc.) |
| `signup`            | `@veritas/signup`            | User registration flows                         |
| `developer-support` | `@veritas/developer-support` | Developer documentation and tools               |

### Infrastructure

| Library              | Package                       | Description                                  |
| -------------------- | ----------------------------- | -------------------------------------------- |
| `ab-testing`         | `@veritas/ab-testing`         | A/B testing framework for headlines, content |
| `archive`            | `@veritas/archive`            | Content archival and retrieval               |
| `community`          | `@veritas/community`          | Community engagement features                |
| `comments`           | `@veritas/comments`           | Article commenting system                    |
| `events`             | `@veritas/events`             | Event bus and domain event handling          |
| `emergency`          | `@veritas/emergency`          | Emergency broadcast and alert distribution   |
| `expansion`          | `@veritas/expansion`          | Platform expansion (new regions, languages)  |
| `operations`         | `@veritas/operations`         | Operations management and monitoring         |
| `platforms`          | `@veritas/platforms`          | Platform abstraction layer                   |
| `realtime-data`      | `@veritas/realtime-data`      | Real-time data feeds and streaming           |
| `risk`               | `@veritas/risk`               | Risk assessment and content safety           |
| `storage`            | `@veritas/storage`            | File storage abstraction (S3/MinIO/GCS)      |
| `automated-content`  | `@veritas/automated-content`  | Automated content generation pipeline        |
| `ai-next-gen`        | `@veritas/ai-next-gen`        | Next-generation AI capabilities R&D          |
| `research-assistant` | `@veritas/research-assistant` | Research tools for journalists               |

---

## Technology Stack

### Languages and Runtimes

| Technology | Version | Purpose                                  |
| ---------- | ------- | ---------------------------------------- |
| TypeScript | ^6.0.3  | All packages (strict mode)               |
| Node.js    | >= 22   | Server runtime for all backend services  |
| Python     | 3.12+   | B2B SDK, NLP NER service (spaCy/FastAPI) |

### Frameworks

| Framework      | Purpose                                    |
| -------------- | ------------------------------------------ |
| Hono           | REST API server (veritas-api, veritas-nlp) |
| Next.js (16.x) | Web application (React 19, App Router)     |
| Expo (51.x)    | Mobile application (React Native)          |
| BullMQ         | Job queue orchestration (Redis-backed)     |
| Prisma         | Database ORM and migrations                |

### Databases and Storage

| Technology     | Purpose                                      |
| -------------- | -------------------------------------------- |
| PostgreSQL     | Primary relational database                  |
| pgvector       | Vector embeddings for semantic search        |
| citext         | Case-insensitive text columns                |
| Elasticsearch  | Full-text article search and indexing        |
| Redis          | Caching, job queues, rate limiting, sessions |
| MinIO / AWS S3 | Object storage for media assets              |

### AI and ML Services

| Service           | Purpose                                      |
| ----------------- | -------------------------------------------- |
| Anthropic Claude  | LLM orchestration, content generation        |
| OpenAI            | Alternative LLM provider                     |
| HeyGen            | AI video avatars and rendering               |
| ElevenLabs        | Text-to-speech (English, accented voices)    |
| Ghana NLP (Khaya) | Local language TTS, NER, translation         |
| Tavus CVI         | Conversational video intelligence (live Q&A) |
| Cohere            | Embeddings and reranking                     |

### Social and Distribution

| Platform  | Integration Type                      |
| --------- | ------------------------------------- |
| YouTube   | Video uploads, Shorts, Live streaming |
| TikTok    | Short-form video, analytics           |
| Instagram | Reels, Stories, feed posts            |
| Facebook  | Page management, posts                |
| WhatsApp  | Business API, channel posting         |
| Telegram  | Bot API, channel management           |
| LinkedIn  | Company page, professional updates    |
| X/Twitter | News monitoring, posting              |

### Payment Providers

| Provider      | Region | Type                         |
| ------------- | ------ | ---------------------------- |
| Stripe        | Global | Card payments, subscriptions |
| Paystack      | Ghana  | Local payment processing     |
| MTN MoMo      | Ghana  | Mobile money                 |
| Vodafone Cash | Ghana  | Mobile money                 |
| AirtelTigo    | Ghana  | Mobile money                 |

---

## Quick Start

### Prerequisites

| Software | Minimum Version | Purpose                                  |
| -------- | --------------- | ---------------------------------------- |
| Node.js  | >= 20.0.0       | Runtime for all services                 |
| pnpm     | >= 10.0.0       | Package manager                          |
| Docker   | >= 24.0         | Infrastructure (PostgreSQL, Redis, etc.) |

### 1. Start Infrastructure

```bash
# Start core infrastructure (PostgreSQL, Redis, MinIO, Mailpit)
docker compose -f docker/docker-compose.dev.yml up -d

# Start Elasticsearch (required for search)
docker compose -f docker/docker-compose.dev.yml --profile search up -d
```

### 2. Install Dependencies

```bash
pnpm install
```

### 3. Set Up Database

```bash
cd libs/veritas/database

# Generate Prisma client
npx prisma generate

# Apply schema to local database
npx prisma db push

# Seed with Ghana news sources
pnpm nx run veritas-ingestion seed
```

### 4. Start Core Services

```bash
# Terminal 1: API server
pnpm nx serve veritas-api

# Terminal 2: NLP service
pnpm nx serve veritas-nlp

# Terminal 3: Web application
pnpm nx serve veritas-web

# Terminal 4: Ingestion scheduler
pnpm nx run veritas-ingestion scheduler
```

### 5. Verify

- API: http://localhost:3001/docs (OpenAPI/Swagger UI)
- NLP: http://localhost:3002/health
- Web: http://localhost:3000

---

## Language Support

Veritas supports six languages used in Ghana, with English as the primary
language:

| Language | ISO Code | Region                | TTS Provider      |
| -------- | -------- | --------------------- | ----------------- |
| English  | `en`     | National              | ElevenLabs        |
| Twi      | `tw`     | Ashanti, most regions | Ghana NLP (Khaya) |
| Ewe      | `ee`     | Volta Region          | Ghana NLP (Khaya) |
| Ga       | `gaa`    | Greater Accra         | Ghana NLP (Khaya) |
| Hausa    | `ha`     | Northern Ghana        | Ghana NLP (Khaya) |
| Dagbani  | `dag`    | Northern Ghana        | Ghana NLP (Khaya) |

The NLP service handles code-switching detection (common in Ghanaian English),
language normalization for Ghanaian English idioms, and translation between all
supported languages via the Ghana NLP Khaya API.

---

## Cross-Domain Integration

Veritas operates primarily as a standalone domain within the Oshun monorepo. It
uses shared foundation libraries from `@oshun/*` for database patterns and
common utilities, while maintaining its own comprehensive library ecosystem of
57+ modules.

### Shared Infrastructure

- **@oshun/database**: Unified database access patterns that Veritas integrates
  with through `@veritas/database`
- **Docker Compose**: Shared development infrastructure (PostgreSQL, Redis,
  MinIO) via `docker/docker-compose.dev.yml`
- **Nx Build System**: All Veritas projects use Nx executors for build, test,
  lint, and serve targets

### Database Isolation

Veritas uses its own dedicated PostgreSQL database (`veritas`) with the
connection string `VERITAS_DATABASE_URL`. The Prisma schema is located at
`libs/veritas/database/prisma/schema.prisma` and includes 50+ tables with
pgvector and citext extensions.

---

## Related Documentation

| Document               | Path                                                                         |
| ---------------------- | ---------------------------------------------------------------------------- |
| Architecture           | [architecture.md](./architecture.md)                                         |
| Developer Guide        | [developer-guide.md](./developer-guide.md)                                   |
| System Architecture    | [architecture/system-architecture.md](./architecture/system-architecture.md) |
| API Documentation      | [architecture/api-documentation.md](./architecture/api-documentation.md)     |
| Package Inventory      | [package-inventory.md](./package-inventory.md)                               |
| Database Schemas       | [database-schemas.md](./database-schemas.md)                                 |
| Security Audit         | [security-audit.md](./security-audit.md)                                     |
| Editorial Guidelines   | [editorial/editorial-guidelines.md](./editorial/editorial-guidelines.md)     |
| Agent Documentation    | [editorial/agent-documentation.md](./editorial/agent-documentation.md)       |
| Dependency Analysis    | [dependency-analysis.md](./dependency-analysis.md)                           |
| Communication Patterns | [communication-patterns.md](./communication-patterns.md)                     |
| Test Coverage          | [test-coverage-analysis.md](./test-coverage-analysis.md)                     |
