# Veritas Domain — Features and Capabilities Named after the Roman goddess of truth, Veritas is the autonomous AI-powered news agency for Ghana and West Africa. It is a full-stack domain covering every stage of the news lifecycle — from automated ingestion of Ghanaian RSS, sitemap, and social sources through AI editorial processing, fact-checking, multimedia production, and multi-platform distribution — while maintaining editorial integrity through AI-powered verification, bias detection, content authentication, and compliance monitoring. --- ## At a Glance | Stage | What Veritas Does | | ---------- | ------------------------------------------------------------------------- | | Discover | Ingests from RSS feeds, sitemaps, and social media sources | | Analyze | NLP pipeline: sentiment, topics, entities, language detection, embeddings | | Verify | Automated claim extraction, evidence retrieval, fact-checking | | Score | Political bias analysis with a Ghana political-lean band system | | Produce | AI-generated articles, video, audio, podcasts, and social content | | Edit | Seven AI agents simulate a professional newsroom editorial process | | Distribute | Pushes to web, mobile, YouTube, TikTok, Instagram, WhatsApp, USSD | | Monetize | Subscriptions, ads, mobile money, B2B API licensing | **Key Numbers** | Metric | Value | | ------------------ | ----------------------------------------------------- | | Seeded Sources | 33 Ghana sources (21 Tier-1 media + 12 government) | | Language Tags | 8 (`en`, `tw`, `ee`, `gaa`, `ha`, `dag`, `fr`, `und`) | | AI Newsroom Agents | 7 default agents | | Social Platforms | 9 platforms in the `PLATFORMS` enum | | AI Workers | 24 across four registries | | Domain Events | 41 `veritas.*` event types | | Payment Providers | 5 (including 3 mobile money providers) | --- ## 1. Core Data Foundation The foundation libraries define the type system, infrastructure clients, and event bus that every other Veritas library imports. All domain entities live in `@veritas/core` as TypeScript types; `@veritas/models` mirrors them as Zod schemas for runtime validation at API boundaries. ### 1.1 Domain Types and Models (`@veritas/core`, `@veritas/models`) - **Article type system** — Comprehensive `Article`, `Source`, `Author`, `Claim`, `BiasScore`, and associated types covering the full data lifecycle from raw ingestion through publication and archival. All types are strictly typed with Zod validation schemas. - **Source registry** — Structured representation of every monitored news outlet, including source metadata, reliability scores, political lean profiles, contact information, and ingestion configuration. - **Claim types** — The `CLAIM_TYPES` enum distinguishes claims extracted from articles: `factual`, `opinion`, `prediction`, `quote`, `statistical`, `historical`, and `scientific`. Each `Claim` also carries a `checkworthiness` and `extractionConfidence` score. ### 1.2 Infrastructure Libraries - **Database access layer (`@veritas/database`)** — PostgreSQL connection pooling, Prisma-based ORM, schema migrations, and transaction management. Includes pgvector extension support for embedding storage and similarity queries. - **Caching layer (`@veritas/cache`)** — Redis-backed caching for hot data (trending articles, source scores, user preferences) with configurable TTL and automatic invalidation. - **Object storage (`@veritas/storage`)** — MinIO/S3 asset storage client for media files, audio output, video output, and document archives. Handles upload, retrieval, and lifecycle policies. - **Search client (`@veritas/search`)** — Elasticsearch client with index management for full-text and semantic article search. Manages index mappings, query construction, and faceted filtering. - **LLM abstraction (`@veritas/llm`)** — Provider-agnostic LLM client with Anthropic Claude as the primary provider and fallbacks configured. Handles prompt management, streaming, rate limiting, and cost tracking. - **Event bus (`@veritas/events`)** — `VERITAS_EVENT_TYPES` defines 41 typed `veritas.*` events across ten groups: article lifecycle, content processing, fact-checking, story clustering, source/feed, media generation, alerts, analytics, user, and NLP processing. Built on `@oshun/event-bus` with a publisher and subscriber. - **Real-time data (`@veritas/realtime-data`)** — WebSocket server for live reader counts, breaking news push notifications, and live editorial status updates. --- ## 2. Authentication and Access Control (`@veritas/auth`) `@veritas/auth` provides the authentication layer for three distinct audiences: reader subscribers (OAuth + phone OTP), internal editorial users (JWT with role-based scopes), and B2B API partners (API key management). It integrates with the Oshun-wide auth system so users with accounts across multiple Oshun products can log in once. - **Veritas role system** — News platform-specific roles (journalist, editor, fact-checker, social media manager, B2B API partner) with fine-grained permission scopes covering article creation, editorial review, source management, and API access. - **JWT middleware** — Hono-compatible authentication and authorization middleware enforcing role and permission requirements on protected endpoints. Ready-to-use across all Veritas service applications. - **API key management** — Generates, validates, and rate-limits B2B API keys for partner integrations. Each key is scoped to specific permission categories and tracked for usage billing. - **OAuth 2.0 providers** — Google, Apple, and Facebook OAuth support for reader subscriber accounts, reducing registration friction. - **Phone OTP** — Phone number verification with Ghana-specific carrier support and configurable rate limiting. Used for mobile money payment verification and subscriber account recovery. - **`@oshun/auth` integration** — Full compatibility with the platform-wide Oshun authentication layer, enabling single sign-on across Oshun domains for users with accounts on multiple products. --- ## 3. News Ingestion and Aggregation Ingestion is the entry point for all external content. It runs continuously as a background pipeline that discovers new articles, normalizes them into a canonical format, deduplicates near-identical stories from different outlets, and queues them for AI analysis. Without this layer, every other capability in the system would have no content to work with. ### 3.1 Automated Source Collection (`@veritas/ingestion-core`) - **RSS feed monitoring** — Scheduled polling of Ghanaian news outlet RSS feeds with configurable refresh intervals per source. New articles are queued for processing within minutes of publication. The `FEED_TYPES` enum covers `rss`, `atom`, `sitemap`, `api`, and `scrape` feed kinds. The seed set ships 21 Tier-1 Ghana media sources and 12 government sources (~102 feeds). - **Sitemap crawling** — Deep sitemap discovery and recursive parsing for outlets that publish `sitemap.xml` files. Ensures comprehensive coverage even when RSS feeds are incomplete or delayed. - **Social media monitoring** — Tracks breaking news and trending topics from X/Twitter and Facebook pages of major Ghanaian outlets. Social signals trigger priority ingestion of related stories from RSS sources. - **Source reliability scoring** — Each source maintains a dynamic reliability score derived from historical accuracy, editorial standards adherence, and how often the source issues corrections. Scores influence content weighting and editorial decisions throughout the pipeline. ### 3.2 Content Processing Pipeline - **Near-duplicate detection** — The ingestion worker computes a 64-bit SimHash fingerprint of each normalized article and compares it (via Hamming distance over bucketed candidates) to detect near-duplicate stories from different sources, mapping them to a canonical record. (Embedding-based semantic clustering is a separate stage — see §3.3 Story Clustering.) - **Language detection** — Automatically identifies whether content is in English, Twi, Ewe, Ga, Hausa, or Dagbani. Detection uses statistical models trained on Ghanaian text corpora, including code-switching patterns common in Ghanaian English. - **Content normalization** — Standardizes headlines, timestamps, author attribution, and media assets across different source formats. Converts all timestamps to Africa/Accra timezone. - **Media extraction** — Pulls featured images, embedded videos, and other media assets from source pages with full attribution preservation. Assets are cached in MinIO/S3 with configurable lifecycle policies. - **Source attribution tracking** — Every article maintains a complete provenance record linking it to its original source, ingestion timestamp, and full processing history. - **Content classification (`@veritas/content-classification`)** — Automatically assigns topic categories, entity tags, and audience classifications to ingested content. Classification feeds the recommendation engine and analytics systems. ### 3.3 Story Clustering (`@veritas/story-clustering`) - **Semantic story grouping** — Clusters articles covering the same event using embedding cosine similarity. Multiple outlets covering the same press conference, accident, or political announcement are grouped into a single story cluster with a canonical record. - **Timeline construction** — Builds chronological timelines showing how a story develops across sources over hours and days. Readers can trace a story from the initial breaking news fragment through full investigative coverage. - **Multi-source perspective display** — Presents the same story from multiple outlets side by side, surfacing differences in framing, emphasis, and tone. This is the foundation for Veritas's bias-awareness features. --- ## 4. NLP Analysis Pipeline Once an article is ingested, the NLP pipeline enriches it with structured signals: sentiment, topic categories, named entities, keyword tags, and dense vector embeddings. These signals feed the recommendation engine, the bias detector, the fact-checker, and the search index. The Ghana-specific sub-library extends the pipeline with local-language capabilities that standard English-only models cannot provide. ### 4.1 Core NLP Engine (`@veritas/nlp-core`) - **Sentiment analysis** — Sentence and document-level sentiment scoring calibrated to Ghanaian political and cultural discourse. Distinguishes emotional tone in news reporting from the events being reported. - **Topic modeling** — Unsupervised topic detection identifying the main subjects of each article beyond predefined categories. Topic models are updated periodically as the Ghanaian news cycle evolves. - **Named entity recognition** — Identification and classification of people, organizations, locations, events, and institutions mentioned in articles. Ghana-specific NER trained to recognize Ghanaian names, places, political parties, and institutions that standard models miss. - **Embedding generation** — Dense vector embeddings for every article and passage using models fine-tuned on Ghanaian news text. Embeddings stored in pgvector for similarity search and deduplication. - **Keyword and keyphrase extraction** — Statistical and neural keyphrase extraction for SEO tagging, search indexing, and recommendation signals. ### 4.2 Ghana-Specific NLP (`@veritas/ghana-nlp`) - **Code-switching detection** — Identifies when content mixes languages, a common pattern in Ghanaian English where speakers blend English with Twi, Ga, or other local languages mid-sentence. Code-switched content is handled appropriately rather than misclassified. - **Ghanaian English normalization** — Handles local idioms, expressions, and spelling conventions distinct to Ghanaian English (e.g., "chale", "wo nim", "herh"). Normalizes variant spellings for search and deduplication. - **Cross-language translation** — Translates between all six supported language pairs via the Ghana NLP Khaya API. Enables readers in one language region to access content originally published in another. - **Pronunciation dictionaries** — Ghana-specific pronunciation dictionaries covering local proper nouns, place names, political figures, and Ghanaian English expressions. Used by text-to-speech systems for natural-sounding audio output. **Language Tags** The `LANGUAGE_TAGS` constant (BCP 47) defines eight tags. The six Ghanaian- context languages drive content; `fr` and `und` round out the set. | Language | Tag | Region | TTS Provider | | ------------ | ----- | ------------------------ | ----------------- | | English | `en` | National | ElevenLabs | | Twi (Akan) | `tw` | Ashanti and 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) | | French | `fr` | Upper West / Upper East | — | | Undetermined | `und` | — | — | --- ## 5. AI Editorial Pipeline ### 5.1 Seven Specialized AI Agents (`@veritas/agents-core`) Veritas simulates a professional newsroom using seven Anthropic Claude-powered agents arranged in a priority hierarchy. Each agent has domain knowledge, tool access, and a defined role in the editorial process. | Agent | Priority | Responsibilities | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | Editor-in-Chief | 10 | Final editorial decisions, content approval, editorial standards enforcement, platform-wide content strategy | | Managing Editor | 9 | Content editing, quality control, balance review, journalist coordination | | Fact-Checker | 8 | Claim verification, evidence retrieval, accuracy scoring, source credibility assessment | | Investigative Journalist | 7 | Deep investigative reporting, document analysis, source relationship development | | Political Journalist | 7 | Political coverage, election reporting, parliamentary monitoring, government news | | Content Strategist | 6 | Trending topic analysis, content planning, SEO strategy, audience insights | | Social Media Manager | 5 | Social posting, platform-specific content adaptation, engagement optimization | ### 5.2 Agent Orchestration and Coordination (`@veritas/agents-orchestrator`) - **Workflow routing** — The orchestrator assigns tasks to the correct agent based on content type, editorial stage, and agent availability. Ensures no article is published without completing the required review stages. - **Priority queue management** — Breaking news bypasses the standard queue and receives immediate high-priority processing across all relevant agents. - **Inter-agent handoffs** — Structured protocol for handing off content between agents with full context preservation. An article handed from the journalist to the fact-checker carries all research, sources, and draft history. - **Agent performance tracking** — Task completion rates, latency, cost, and accuracy tracked per agent. Used for agent configuration optimization. ### 5.3 Specialized Agent Libraries - **`@veritas/agents-journalism`** — Investigative and political journalist agents with domain knowledge of Ghanaian politics, institutions, public figures, and investigative reporting techniques. - **`@veritas/agents-fact-checking`** — Claim extraction, evidence retrieval, and verdict assignment agents with access to the fact-check database and external verification sources. - **`@veritas/agents-editorial`** — Managing editor and editor-in-chief quality control agents enforcing editorial standards, balance, and publication readiness. - **`@veritas/agents-social-media`** — Social media manager agent for platform-specific content adaptation, hashtag optimization, and cross-platform scheduling. - **`@veritas/agents-product`** — Product and audience analytics agents generating content strategy recommendations from engagement data. - **`@veritas/agents-devops`** — Infrastructure monitoring and operational agents alerting on system health, pipeline failures, and performance degradation. - **`@veritas/agents-qa`** — Quality assurance and regression testing agents verifying editorial pipeline correctness. ### 5.4 Content Management System (`@veritas/cms`) - **Full lifecycle workflow** — Draft → Review → Schedule → Publish → Archive workflow with role-based access control at each stage. Every state transition is logged for audit trails. - **Revision history** — Full version history with content diffing between revisions. Any revision can be compared against any other or restored to become the current version. - **Priority scheduling** — Peak traffic window optimization with Africa/Accra timezone awareness. Quiet hours (22:00–06:00) are respected for non-breaking content. - **Publication rate limiting** — Maximum 6 articles per 30-minute window prevents feed flooding and maintains reader trust. - **AI quality reviews** — Claude-powered quality control produces structured approve/reject/request-changes decisions with written rationale for each article. --- ## 6. Fact-Checking and Verification Automated fact-checking is one of Veritas's core differentiators. The pipeline extracts verifiable claims from articles, retrieves evidence from internal and external sources, scores that evidence for quality and relevance, and assigns a verdict that is displayed alongside the article. Every step of the process is structured so human fact-checkers can audit and override the AI decision. ### 6.1 Claim Extraction (`@veritas/claims`, `@veritas/fact-checking`) - **Claim detection** — NLP identification of factual claims within article text. Distinguishes verifiable claims from editorial opinion, analysis, and background context. The NLP service ships both a heuristic extractor and an LLM extractor. - **Claim classification** — The `CLAIM_TYPES` enum categorizes claims as `factual`, `opinion`, `prediction`, `quote`, `statistical`, `historical`, or `scientific`. - **Claim linking** — The `claim-linking` AI worker connects extracted claims to related prior fact-check records, helping avoid re-checking previously verified claims. ### 6.2 Evidence Retrieval and Scoring - **Cross-reference search** — Searches the internal knowledge base, prior Veritas articles, and configured external databases for evidence relevant to each claim. Uses the RAG pipeline over the full archived content. - **External verification sources** — Integrated with ClaimBuster, Google Fact Check API, and Brave Search/Serper for external evidence. Source reliability weights applied to all retrieved evidence. - **Evidence quality scoring** — Each piece of retrieved evidence is scored for quality based on source reliability, publication recency, and direct relevance to the specific claim. - **Verdict assignment** — A `ClaimVerification` carries a status from the `FACT_CHECK_OVERALL_STATUSES` enum (`verified`, `likely_true`, `disputed`, `misleading`, `mostly_false`, `false`, `unverifiable`, `unverified`), a confidence score, and the evidence IDs that support it. - **Schema.org structured data** — Article SEO metadata supports the `NewsArticle`, `Article`, and `ReportageNewsArticle` Schema.org types. ### 6.3 Source Credibility Tracking - Dynamic credibility scores maintained for every source in the system, derived from historical accuracy rates, correction frequency, editorial standards, and corroboration rates. Credibility scores feed back into claim verification — a claim from a low-credibility source requires stronger corroborating evidence before receiving a True or Mostly True verdict. ### 6.4 Fact-Check Reports - **Comprehensive reports** — The `FactCheckReport` entity collects the checked claims, their verifications, the gathered evidence, an overall verdict, a methodology description, and a publication `status` (`draft`, `review`, `published`). --- ## 7. Bias Detection and Balance (`@veritas/bias-detection`) Bias detection gives readers visibility into how different sources frame the same story and alerts the editorial team when Veritas's own output is drifting in a political direction. The system models Ghana's two-party political spectrum explicitly — NPP and NDC — rather than using a generic left/right axis that does not map cleanly onto Ghanaian politics. ### 7.1 Ghana Political Bias Bands - **Political spectrum analysis** — `@veritas/core` defines a discrete band system: `GHANA_POLITICAL_BIAS_BANDS` are the integers −3 to +3 (−3 = Strong NDC lean … 0 = Neutral … +3 = Strong NPP lean). `ghanaPoliticalAlignment` maps a band to `npp`, `ndc`, or `independent`; the axis version constant is `gh_political_axis_v1`. - **Continuous bias score** — `BiasScore` carries a continuous `political` value (−1…1) alongside regional bias, a confidence score, and a methodology label. `toGhanaPoliticalBiasBand` clamps and rounds a continuous score onto the discrete −3…+3 band. The `gpl-score` AI worker computes these scores. - **Coverage blindspot detection** — The `blindspot-detection` AI worker identifies which political perspectives or significant stories are being systematically under-covered in Veritas's own output; `CoverageBlindspot` models the result. - **Balance tracking over time** — Tracks political balance in Veritas's coverage over rolling time windows. The managing editor agent receives automated balance reports and can commission balancing coverage when imbalance is detected. - **Source bias profiling** — Maintains historical bias profiles for all ingested sources. Profiles show trend data — a source drifting in political lean over time is flagged for editorial review. --- ## 8. Content Generation In addition to aggregating and enriching human-authored articles, Veritas generates entirely AI-authored content for structured domains where data is available but no human correspondent has filed a story — routine market summaries, weather reports, electricity load-shedding schedules, and similar high-frequency but lower-complexity pieces. ### 8.1 AI Article Generation (`@veritas/article-generation`) AI-generated articles produced from ingested source material for: - Breaking news summaries synthesizing multiple source perspectives into a single authoritative account - Weather reports derived from meteorological data feeds (Ghana Meteorological Agency) - Ghana Stock Exchange and commodity market summaries generated from financial data feeds - Fuel price tracker updates from GOIL, TotalEnergies, and BOST station data - Trending topic analysis synthesizing social and news signals into explanatory articles - Parliamentary and legislative summaries from Hansard data and government announcements ### 8.2 AI Workers (`veritas-ai-workers`) The `veritas-ai-workers` app runs 24 BullMQ workers across four registries. The `@veritas/automated-content` library backs the generator 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`. Each worker exposes a `tick` function and a default-options factory; the combined `ALL_WORKERS` registry is queried via `listWorkers` / `getWorker`. ### 8.3 Headline Service (`@veritas/headline-service`) - **Headline generation** — AI-powered headline generation from article content with SEO scoring. Produces multiple candidate headlines ranked by predicted click-through performance. - **Headline scoring** — Multi-factor scoring including clarity, engagement prediction, SEO value, and alignment with Veritas editorial standards. - **A/B headline testing** — Infrastructure for testing headline variants against live audiences and recording performance data to improve future generation. --- ## 9. Multimedia Production ### 9.1 Video Production (`@veritas/video-production`) - **AI avatar anchors** — HeyGen AI video anchors read news scripts generated by Claude. Multiple avatar personalities and voice profiles represent a diverse editorial team. - **Script generation** — Automatic news script generation from published articles optimized for spoken delivery with natural language patterns and appropriate pacing. - **Avatar management** — Multiple avatar personalities differentiated by presentation style, gender, language, and regional accent. Specific avatars can be assigned to specific content categories or time slots. - **Video captioning** — Automatic caption generation and embedding compliant with accessibility standards and platform requirements. - **YouTube optimization** — YouTube-formatted video production with AI-generated thumbnail prompts, description optimization, tags, and playlist assignment. - **Short-form video** — Automatic production of YouTube Shorts, TikTok, and Instagram Reels from long-form video content using automated highlight extraction and re-framing. - **Production pipeline** — Article → Script (Claude) → Avatar selection (HeyGen) → Rendering → Captioning → Publishing → Analytics ### 9.2 Audio Production (`@veritas/audio-production`) - **English TTS** — ElevenLabs text-to-speech for English articles with multiple anchor voice profiles and emotion modeling for natural delivery. - **Local language TTS** — Ghana NLP (Khaya) text-to-speech for Twi, Ewe, Ga, Hausa, and Dagbani articles — the first news audio service in these languages at scale. - **Pronunciation dictionaries** — Ghana-specific pronunciation dictionaries covering local proper nouns, place names, political figures, and Ghanaian English expressions for accurate TTS output. - **Podcast series** — Six ongoing podcast series: Daily Digest, Weekly Deep Dive, Sports Recap, Money Matters, Culture, and Twi Daily. Each series has its own feed, branding, and publication schedule. - **Podcast distribution** — RSS feeds, OPML, and Podcast 2.0 JSON for all major podcast directories (Spotify, Apple Podcasts, Google Podcasts, Pocket Casts). - **Production pipeline** — Article → Text chunking → Voice assignment → TTS synthesis → S3/MinIO storage → Distribution --- ## 10. Live Streaming (`@veritas/live-stream`) Live streaming gives Veritas a broadcast presence on YouTube. The infrastructure supports both continuous automated programming (filling airtime between live events) and live contributions from journalists in the field via standard RTMP broadcast software. Interactive Q&A segments are powered by Tavus CVI. - **24/7 YouTube Live** — Continuous live stream infrastructure with automated programming that fills airtime with produced content between live events, ensuring the channel never goes dark. - **RTMP server** — Self-hosted RTMP ingest for accepting live stream contributions from journalists in the field using standard broadcast software (OBS, vMix, mobile streaming apps). - **Lower-thirds graphics** — Real-time lower-third graphic overlays displaying anchor name, story title, and live ticker data. - **Breaking news overlays** — Breaking news banner injection into the live stream without interrupting the current segment. - **Viewer Q&A** — Live viewer question management and display via Tavus CVI integration for interactive broadcast segments. - **Stream health monitoring** — Real-time monitoring of bitrate, frame rate, encoder health, and viewer count with automated alerts for degraded stream quality. --- ## 11. Social Media Distribution ### 11.1 Multi-Platform Automation (`@veritas/social-automation`, `@veritas/platforms`) | Platform | API | Capabilities | | --------- | -------------------------- | ----------------------------------------------------------------- | | YouTube | YouTube Data API v3 | Video uploads, Shorts, Live streaming, analytics, community posts | | TikTok | TikTok Content Posting API | Short-form video uploads, hashtag optimization, analytics | | Instagram | Meta Graph API | Reels, Stories, feed posts, caption and hashtag optimization | | Facebook | Meta Graph API | Page management, link posts, video posts, event creation | | WhatsApp | WhatsApp Business API | Channel posting, breaking news subscriber updates | | Telegram | Telegram Bot API | Channel management, scheduled posts, media groups | | LinkedIn | LinkedIn API | Company page updates, professional news articles | | X/Twitter | X API v2 | Breaking news posting, news monitoring, thread creation | | Threads | Meta API | Short-form text and media posts | The `social-automation` `SocialPlatform` type and the `veritas-social` `PLATFORMS` enum together enumerate these channels. ### 11.2 Content Calendar - **Cross-post scheduling** — Schedule posts across all platforms from a single calendar interface. Each post is platform-adapted from a single source article by the social media manager agent. - **Breaking news priority** — Breaking news events can override the scheduled calendar, immediately triggering posts across all platforms. - **Platform adaptation** — Automatically adapts content format, length, hashtags, and media crop for each platform's specifications and audience expectations. - **Best time optimization** — Historical audience engagement analysis per platform recommends and automatically applies optimal posting times by day of week and content category. --- ## 12. A/B Testing and Optimization (`@veritas/ab-testing`) - **Headline experiments** — A/B test alternative headlines against live audiences, measuring click-through rates to feed back into headline generation scoring. - **Recommendation experiments** — Test alternative recommendation algorithms or blending strategies and measure downstream engagement differences. - **UI/UX experiments** — Experiment framework for testing reader interface changes (paywall placement, notification prompts, feed ordering) with statistically rigorous significance testing. - **Experiment lifecycle** — Full lifecycle management: define experiment, set traffic allocation, run, collect results, determine winner, and roll out. Experiments are scoped to prevent interference between concurrent tests. --- ## 13. Reader Experience ### 13.1 Web Platform - **Progressive web app** — Installable PWA with offline article caching and background sync for reading without an internet connection. - **Multilingual interface** — Full i18n with locale-based routing for all 6 supported languages. Language preference persists across sessions and devices. - **Reading list** — Save articles for later reading with cross-device syncing. - **Audio articles** — In-page audio player for articles with ElevenLabs/Ghana NLP TTS. Supports background playback. - **Semantic search** — Full-text and semantic search powered by Elasticsearch with Ghana-specific entity recognition and spelling normalization. - **Story timeline view** — Chronological story development view showing how a story evolved across sources and days. ### 13.2 Mobile Application - **Native audio playback** — Background audio using react-native-track-player for listening to news while the app is backgrounded or the phone screen is off. - **Video streaming** — In-app video with react-native-video supporting offline caching for videos saved for later. - **Offline storage** — Article caching for offline reading using encrypted local storage. - **Push notifications** — Firebase Cloud Messaging (FCM) for breaking news alerts with topic-based subscription (sports, politics, business, regional news by region). - **Biometric authentication** — Fingerprint/Face ID for subscriber authentication, reducing friction for repeat login. - **Secure credential storage** — Encrypted local credential storage using the platform keychain. ### 13.3 Personalization (`@veritas/recommendations`) - **Hybrid recommendations** — Collaborative filtering combined with content-based recommendations using reading history, topic preferences, and engagement signals. Avoids filter bubble effects by injecting diverse perspectives. - **Topic following** — Follow specific topics, journalists, and sources to curate a personalized feed. Followed entities receive priority ranking. - **Breaking news alerts** — Configurable real-time breaking news push notifications. Users select categories, regions, and alert sensitivity threshold. --- ## 14. Subscription and Monetization (`@veritas/payments`, `@veritas/billing`) Veritas monetizes through three channels: reader subscriptions (Stripe and Paystack for cards, plus three mobile money providers for the majority of Ghanaian readers who use mobile wallets), advertising, and B2B API licensing. The billing layer handles subscription lifecycle, invoicing, and VAT for all three channels. ### 14.1 Subscription Tiers - **Tiered subscriptions** — Free, Standard, and Premium tier management with feature gating. Free includes basic news access; Premium adds live streams, audio articles, investigation archives, and ad-free reading. - **Stripe integration** — International card payment and subscription management with automatic billing, invoice generation, and dunning management for failed payments. - **Paystack** — Ghana-native card payment processing with support for Ghanaian-issued Visa and Mastercard cards. ### 14.2 Mobile Money - **MTN Mobile Money** — MTN MoMo integration covering the largest mobile money user base in Ghana. - **Vodafone Cash** — Vodafone Cash integration for Vodafone subscribers. - **AirtelTigo Money** — AirtelTigo mobile money integration covering both legacy Airtel and Tigo networks. ### 14.3 B2B Revenue - **Usage-based billing** — API usage metering for B2B customers with configurable rate limits, overage billing, and tier-based pricing. - **Automated invoicing** — Invoice generation for digital subscribers and B2B customers with VAT handling for Ghana. - **Self-service signup (`@veritas/signup`)** — Self-service B2B API signup flow with account provisioning, API key generation, and plan selection. Automated enterprise sales workflow for high-value prospects. - **Business analytics (`@veritas/business`)** — Profitability modeling, unit economics, and business optimization intelligence for internal operations management. --- ## 15. B2B API Platform (`@veritas/b2b-sdk`, `@veritas/b2b-sdk-python`) - **B2B API surface** — The `/api/v1/b2b/*` route group exposes programmatic access to the content feed, search, fact-check claims, entity profiles and relationships, media, and monitoring alerts. - **TypeScript SDK** — `@veritas/b2b-sdk` is a typed, auto-retrying, rate-limited client (`client.ts` + per-resource modules under `src/resources/`). - **Python SDK** — `@veritas/b2b-sdk-python` is an async client built on `httpx`, with resource modules for feed, search, claims, entities, media, alerts, and sandbox. - **API key authentication** — Per-partner API keys with usage tracking, configurable rate limits, and permission scoping. The `/api/v1/api-keys/*` routes cover creation, rotation, usage, billing, and validation. - **Webhook delivery** — Webhook configuration is handled by the API's `domain/webhooks.ts` module. - **Developer support chatbot (`@veritas/developer-support`)** — AI-powered developer support chatbot for the Veritas B2B API, answering integration questions and explaining endpoints. - **OpenAPI documentation** — The API serves an OpenAPI document at `/openapi.json` with Swagger UI at `/docs`. --- ## 16. USSD and Feature Phone Access (`@veritas/ussd`) A significant share of Ghanaians access digital services through basic feature phones rather than smartphones. USSD is the mechanism that makes this possible: it is a mobile protocol built into the GSM network itself, requiring neither internet connectivity nor a data plan. USSD (Unstructured Supplementary Service Data) is a mobile protocol that works on every phone — including basic feature phones — over the GSM network, requiring no internet connection or smartphone. - **USSD channel** — Text-based news delivery via telco USSD shortcodes. Readers with basic phones access top headlines, sports, business, and regional news without a smartphone or data plan. - **Voice callback** — News audio delivery via automated voice callback for users who prefer audio or have low literacy. The USSD menu triggers an automated phone call that reads the selected story. - **Multi-telco adapters** — Gateway adapters for MTN, Vodafone, AirtelTigo, and Glo networks covering near-total Ghanaian subscriber coverage. - **Hierarchical menu navigation** — Category → subcategory → article navigation flow for browsing by news category, region, or date. - **Language selection** — Language selector in the USSD flow allows users to receive content in English, Twi, or other supported languages. --- ## 17. Emergency and Crisis Features (`@veritas/emergency`) During emergencies — natural disasters, public health crises, election violence — the normal content pipeline is set aside in favour of urgent alert distribution. Veritas integrates directly with NADMO (Ghana's National Disaster Management Organisation) so official alerts flow to all channels within seconds of being issued. - **Emergency alert distribution** — Emergency alerts from NADMO (National Disaster Management Organisation) and government emergency communications distributed across all Veritas channels simultaneously: web, mobile push, WhatsApp, Telegram, and SMS. - **Crisis coverage mode** — Editorial pipeline switches to crisis mode during declared emergencies, prioritizing alert distribution over standard content scheduling. - **Election emergency protocols** — Heightened monitoring and accelerated fact-checking during election periods. All election-related content triggers mandatory balance review. - **Emergency broadcast integration** — Integration with national emergency broadcasting systems for cross-channel alert amplification. --- ## 18. Election Coverage and Compliance Elections are the highest-stakes editorial event for a news agency. Veritas has a dedicated election coverage mode that tightens fact-checking, mandates balance review for all political content, and integrates with the Electoral Commission of Ghana for official result data. The compliance layer tracks adherence to National Media Commission (NMC) guidelines and flags violations for editorial review. - **Election calendar** — Structured tracking of Ghana's presidential, parliamentary, and local government election schedules including registration deadlines, campaign periods, and result timelines. - **Candidate tracking** — Profiles for all registered candidates with stated policy positions, campaign records, past fact-check results, and biographical information. - **Result tabulation integration** — Integration with Electoral Commission of Ghana data feeds for official result tracking. - **Legislative monitoring** — Bill tracking, parliamentary vote analysis, and government action monitoring using data from the Ghana Parliament website and Hansard records. - **Political balance enforcement** — Mandatory balance review for all content published during election periods. The managing editor agent automatically flags imbalanced coverage for human review. - **NMC/NCA compliance monitoring** — Media regulatory compliance tracking aligned with National Media Commission and National Communications Authority requirements. --- ## 19. Investigative and Research Tools (`@veritas/research-assistant`, `@veritas/knowledge-graph`) Veritas owns the journalism-facing research layer: tools for journalists to discover connections, query the archive, and analyse documents. Academic research grounding (peer-reviewed citations, structured knowledge bases) is the responsibility of the Sophia domain, which Veritas may query as an external source. - **Research assistant** — AI-powered research tools for journalist use. Accepts natural language research questions and returns structured findings with source citations and confidence levels. - **Knowledge graph** — Entity graph with profiles, timeline events, and relationships for Ghanaian public figures, organizations, political parties, and companies. Journalists can explore entity connections to uncover hidden relationships. - **Document analysis** — AI-powered analysis of uploaded documents — government filings, contracts, financial statements, court documents — extracting key facts, timelines, and entities automatically. - **Source tracking** — Source relationship and reliability tracking for investigative journalism. Records which sources contributed to which stories and their reliability history. - **RAG pipeline (`@veritas/rag`)** — Retrieval-augmented generation (RAG) over the full archive of published articles, documents, and fact-check records. Journalists query the full editorial archive in natural language for background research without manual search. --- ## 20. Historical Archive (`@veritas/archive`) - **Full-text archive search** — Search across the complete history of published Veritas articles with faceted filtering by date, source, topic, entity, and language. - **Entity timelines** — Chronological timelines of all articles mentioning a specific person, organization, location, or topic. Journalists and researchers can trace the full history of any tracked entity. - **Story evolution tracking** — Tracks how a specific story developed over time: from the first fragmentary report through comprehensive coverage, corrections, and follow-ups. Shows how the understanding of events changed as more information emerged. - **"On This Day" feature** — Surfaces historically significant Ghanaian events that occurred on the current date in prior years, enabling evergreen content production and historical context. - **Special collections** — Curated collections of archived articles grouped by significance: major elections, constitutional crises, economic milestones, and cultural events. - **Article significance scoring** — Algorithmic scoring of historical articles by significance, enabling the archive to surface important journalism rather than just recency-ranked results. - **Corrections and updates** — Full record of issued corrections, retractions, and material updates to published articles. Corrections are permanently linked to the original article for transparency. --- ## 21. Content Authentication (`@veritas/content-auth`) In an era of AI-generated media and deepfakes, cryptographic provenance matters. `@veritas/content-auth` gives every piece of Veritas-produced content a tamper-evident certificate that can be independently verified. The C2PA (Coalition for Content Provenance and Authenticity) support makes these certificates interoperable with other news organizations and platforms that implement the standard. Copyright enforcement (originality scanning, trademark checks) is the responsibility of the Themis domain via `@themis/text-shield`. - **Cryptographic content authentication** — `@veritas/content-auth` implements content hashing, blockchain timestamp proofs, authenticity certificates, digital signatures, custody records, and device signing (`BlockchainTimestampManager`, `DeviceSigningManager`). - **C2PA content provenance** — The library defines a full C2PA type set (`C2PAManifest`, `C2PAAssertion`, `C2PACredential`, `C2PASignature`, `C2PAValidationStatus`) for Coalition for Content Provenance and Authenticity manifests, plus media-origin tracking and edit history. - **Manipulation detection** — Deepfake detection and image-manipulation detection support tamper-evidence on published media. - **Copyright protection via Themis** `(planned)` — All Veritas-generated articles, newsletters, and social posts will be automatically scanned by `@themis/text-shield` for verbatim reproduction of copyrighted text and paraphrased reproduction above semantic similarity thresholds. See Themis Universal Originality Shield. --- ## 22. Regional Coverage (`@veritas/regional`) Ghana has 16 administrative regions with distinct languages, demographics, and local concerns. National-level news coverage often fails communities in the Northern, Volta, and Upper regions. Veritas addresses this with dedicated regional segments, region-specific video anchors, and content in local dialects. - **16-region coverage** — Dedicated coverage for all 16 administrative regions of Ghana, with region-specific reporters, story categories, and audience segments. - **Regional AI anchors** — Region-specific video anchor personas for each major region, presenting news in regional dialects where applicable. - **Localized content** — Region-specific articles, weather, local government news, and event coverage tailored to each region's audience. --- ## 23. Pan-African Expansion (`@veritas/expansion`) The Veritas platform is architected from the start for multi-country operation. The `@veritas/expansion` library provides the scaffolding for adding new African markets without rebuilding the core system: country-specific source registries, payment systems, regulatory environments, and localization frameworks are all parameterized. - **Market entry framework** — Structured market analysis and entry planning tools for expanding Veritas to additional West African and pan-African markets beyond Ghana. - **Multi-country source management** — Infrastructure for managing news source registries across multiple African countries with country-specific reliability scoring and editorial standards. - **Localization framework** — Language and cultural localization framework for adapting the Veritas platform to each target country's languages, payment systems, and regulatory environment. --- ## 24. Analytics and Intelligence (`@veritas/analytics`) Analytics serves two audiences: editorial teams (which stories are landing, which topics to prioritize) and business teams (subscription conversion, revenue health). The anomaly detection capability is specifically designed to catch viral content emergence early enough to assign editorial resources before a story explodes. - **Content analytics** — Article-level performance metrics: pageviews, unique visitors, reading time, completion rate, scroll depth, and social shares. - **User engagement analytics** — Cohort analysis, user segmentation by acquisition channel, retention curves, and user journey mapping. - **Revenue analytics** — Subscription conversion funnel analysis, churn prediction, MRR tracking, and revenue projections. - **Social performance** — Cross-platform engagement aggregation: likes, shares, comments, reach, and viral coefficient by article and time period. - **Real-time sessions** — Live concurrent user tracking with geographic distribution and traffic source breakdown. - **Anomaly detection** — Automated detection of unusual traffic spikes, viral content emergence, and bot traffic patterns. - **Best posting time analysis** — AI-powered analysis of historical engagement data to recommend optimal publication times by category and platform. --- ## 25. Notifications and Alerts (`@veritas/notifications`) - **Multi-channel delivery** — Push notifications (FCM), email, SMS, WhatsApp, and Telegram notifications delivered through a unified notification service with per-channel delivery confirmation. - **Breaking news alerts** — Configurable breaking news detection threshold triggers immediate cross-channel notification blasts within seconds of the editorial decision. - **Topic subscriptions** — Users subscribe to specific topics, journalists, regions, or source reliability updates and receive targeted notifications. - **Notification preferences** — Granular user notification preferences stored per device with quiet hours configuration and notification frequency limits. --- ## 26. Community and Content Discovery (`@veritas/community`, `@veritas/comments`) Reader engagement features extend the editorial product beyond one-way news delivery. Comment moderation is delegated to the Kuanyin domain (the Oshun-wide safety and moderation layer) rather than being built from scratch inside Veritas — the boundary exists because moderation patterns are shared across all Oshun products and should be governed centrally. - **Article comments** — Threaded commenting system with Kuanyin-powered moderation, reply notifications, and upvoting. Comments are filtered for harm before posting using the Kuanyin platform-wide moderation layer. - **Community forums** — Topic-based community discussion spaces for ongoing conversation beyond individual articles. - **Newsletter campaigns (`@veritas/newsletter`)** — Scheduled email newsletter delivery with click tracking, open rate analytics, and segmented content by user preferences and language. - **SEO optimization (`@veritas/seo`)** — Automated sitemap generation, structured data (Article, NewsArticle, BreadcrumbList schema.org types), and meta tag optimization for search engine visibility. - **Events** — Virtual and in-person reader event creation and management. --- ## 27. Risk and Compliance Management (`@veritas/risk`, `@veritas/operations`) A news agency faces risks that a generic software product does not: defamation liability, regulatory sanctions from the NMC, and reputational damage from publishing false claims. The risk and operations libraries provide automated monitoring so these issues are surfaced before they become crises. - **Technical risk monitoring** — Automated monitoring of infrastructure risks: pipeline failures, API outages, data quality degradation, and latency spikes. - **Legal risk management** — Defamation risk scoring for published articles; legal review flagging for sensitive claims about named individuals or organizations. - **Reputational risk tracking** — Monitor social and reader response for emerging reputational issues with the Veritas brand. - **Operational security** — Security monitoring, compliance scanning, and QA automation for ongoing operational integrity. - **Business risk modeling** — Business continuity risk assessment and mitigation planning for the Veritas platform. --- ## 28. Platform Architecture This section provides a summary view of all 13 application services and the `@veritas/ai-next-gen` advanced capability library for engineers who need a quick reference to which deployable handles what. ### 28.1 Application Services | Service | Purpose | | ----------------------- | --------------------------------------------------------------------- | | `veritas-api` | Main REST API gateway serving web, mobile, and B2B clients | | `veritas-ingestion` | Continuous news source monitoring and content processing | | `veritas-nlp` | NLP analysis pipeline: language detection, NER, embeddings, sentiment | | `veritas-ai-workers` | AI content generation, processing, analysis, and editorial workers | | `veritas-audio` | Audio production service: TTS generation and podcast assembly | | `veritas-video` | Video production service: script generation and HeyGen orchestration | | `veritas-social` | Social media scheduling and cross-platform posting automation | | `veritas-cms` | Content management system and editorial workflow engine | | `veritas-agents` | AI newsroom agent orchestration | | `veritas-analytics` | Analytics event processing and reporting | | `veritas-notifications` | Multi-channel notification delivery | | `veritas-web` | Next.js progressive web application | | `veritas-mobile` | Expo / React Native mobile application | ### 28.2 Next-Generation AI (`@veritas/ai-next-gen`) `@veritas/ai-next-gen` ships three modules: - **Investigations** — investigation tooling with entity-driven analysis. - **OSINT** — open-source intelligence with bot detection and entity extraction. - **Real-time anchors** — real-time anchor support with conversational memory. --- ## 29. V2 Esports Fact-Checking Bridge Veritas's fact-checking engine is reused outside the newsroom by the V2 game project. The **V2 Esports Fact-Checking Bridge** lives in the V2 esports tooling package `@v2/esports-tools` and consumes `@veritas/fact-checking` to verify esports outcomes and reporting after a match has already concluded. - **Bracket result verification** — Reconciles the reported winner against the replay-derived winner and the tournament bracket, scoring each source with Veritas's `getDomainCredibility` and `calculateVerificationScore` rather than trusting a single feed. - **Post-match reporting** — Runs caster recaps and editorial post-match reports through the same `calculateConsensus` / `FactCheckReport` flow used for any Veritas claim. - **Esports news publication holds** — When the bracket, replay, and reported results disagree, the bridge does not publish a guess; it holds the esports news story until an editor resolves the conflict, so contested results never ship as verified fact. This bridge is **off rollback** by design (`mayInfluenceRollback: false`): it can flag, score, and hold a story, but it can never rewrite a completed match or influence the deterministic game simulation. It is verified by `V2/ue/Tools/check-v2-veritas-esports-fact-checking.py`. --- ## 30. Planned Features The following capabilities are planned as part of ongoing Veritas development and platform-wide Phase 74/75 work: - **Text originality scanning** `(planned — Phase 75)` — All Veritas-generated articles, newsletters, and social posts will be automatically scanned by `@themis/text-shield` for verbatim reproduction of copyrighted text, paraphrased reproduction above semantic similarity thresholds, and unattributed factual claims. The scanner uses verbatim n-gram matching, semantic embedding comparison, and LLM-based narrative analysis. - **C2PA labeling pipeline integration** `(planned — Phase 75)` — Wiring the existing `@veritas/content-auth` C2PA manifest types into the article and multimedia generation pipelines so every AI-generated asset carries a provenance manifest, as relevant to EU AI Act Article 50 synthetic-media disclosure. - **Brand and trademark scanning** `(planned — Phase 75)` — Generated articles will be scanned against a database of trademarked phrases and slogans to prevent inadvertent trademark misuse. - **Production deployment automation** `(planned)` — Kubernetes namespace configuration, multi-region deployment, CDN setup, and auto-scaling policies for full production operation across multiple African markets. - **Gaia severe-weather desk** `(planned, Phase 175)` — Automated weather and tropical-cyclone bulletin generation from Gaia forecast products, preserving forecast provenance, alert IDs, uncertainty, CAP metadata, and editorial review state. - **Concordia evidence disputes** `(planned, Phase 179)` — Support for editorial corrections, evidence quality disagreements, collaborative research authorship disputes, and publication conflict workflows through the Concordia substrate. ## Training-Data Flywheel (Phases 85–86) `libs/veritas/training-data` implements this domain's side of the ML-sovereignty data flywheel: a training-data pipeline that captures news-production interactions (editorial decisions, fact-check outcomes, story performance) as passive training signals. Signals are consent-gated, anonymized where required, and emitted in the shared flywheel envelope that Nous dataset management (Phase 87) ingests for training and evaluation. Nous owns the training infrastructure; this domain owns what constitutes a high-quality domain signal. ## Autonomous Research Contribution (Phase 178) Veritas is a co-owner of the autonomous research / agentic-scientist substrate (Phase 178, centered in Nous). Veritas's side is novelty checking and fact-verification: the agentic scientist routes generated claims and proposed contributions through Veritas's fact-checking and source-verification pipeline before they enter the shared literature/novelty graph. Nous owns the research loop; Veritas owns claim verification.