# Veritas Domain - Developer Guide

Veritas is the AI-powered news agency domain for Ghana and West Africa. It
includes 13 applications and 57+ libraries spanning news ingestion, AI editorial
agents, NLP analysis, multimedia production (video, audio, podcasts), social
media automation, and client applications (web PWA, mobile, USSD, B2B SDK).

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Local Development Setup](#local-development-setup)
3. [Project Structure](#project-structure)
4. [Running Services](#running-services)
5. [Building and Testing](#building-and-testing)
6. [Common Development Tasks](#common-development-tasks)
7. [Environment Variables Reference](#environment-variables-reference)
8. [Debugging Tips](#debugging-tips)

---

## Prerequisites

### Required Software

| Software   | Minimum Version | Purpose                                  |
| ---------- | --------------- | ---------------------------------------- |
| Node.js    | >= 20.0.0       | Runtime for all backend services         |
| pnpm       | >= 10.0.0       | Package manager (monorepo workspace)     |
| Docker     | >= 24.0         | Infrastructure (PostgreSQL, Redis, etc.) |
| TypeScript | ^6.0.3          | Type checking and compilation            |

### For Mobile Development

| Software       | Purpose                                     |
| -------------- | ------------------------------------------- |
| Expo CLI       | Mobile development tooling                  |
| EAS CLI        | Expo Application Services (builds, submits) |
| Xcode          | iOS development (macOS only)                |
| Android Studio | Android development                         |

### For Python SDK Development

| Software | Version | Purpose                    |
| -------- | ------- | -------------------------- |
| Python   | 3.12+   | B2B SDK Python development |
| uv       | Latest  | Python package manager     |

---

## Local Development Setup

### 1. Start Infrastructure

Veritas requires PostgreSQL (with pgvector), Redis, MinIO (S3-compatible
storage), and optionally Elasticsearch for full-text search.

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

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

# Verify services are healthy
docker compose -f docker/docker-compose.dev.yml ps
```

This starts:

| Service       | Port(s)    | Purpose                                     |
| ------------- | ---------- | ------------------------------------------- |
| PostgreSQL    | 5432       | Primary database (with pgvector, citext)    |
| Redis         | 6379       | Caching, job queues (BullMQ), rate limiting |
| MinIO         | 9000, 9001 | S3-compatible media storage                 |
| Mailpit       | 1025, 8025 | Local email testing                         |
| Elasticsearch | 9200       | Full-text article search (optional profile) |

### 2. Set Environment Variables

The following environment variables should be set in the root `.env` file. Most
have sensible defaults for local development.

#### Database and Infrastructure

| Variable               | Default                                               | Used By                |
| ---------------------- | ----------------------------------------------------- | ---------------------- |
| `VERITAS_DATABASE_URL` | `postgresql://oshun:oshun_dev@localhost:5432/veritas` | database, ingestion    |
| `DATABASE_URL`         | Same as above                                         | api, cms, video, audio |
| `REDIS_URL`            | `redis://localhost:6379`                              | all backend services   |
| `ELASTICSEARCH_URL`    | `http://localhost:9200`                               | api, search            |
| `S3_ENDPOINT`          | `http://localhost:9000`                               | audio, video           |
| `S3_ACCESS_KEY`        | `minioadmin`                                          | audio, video           |
| `S3_SECRET_KEY`        | `minioadmin`                                          | audio, video           |

#### AI Services (optional for basic development)

| Variable             | Default    | Used By                        |
| -------------------- | ---------- | ------------------------------ |
| `ANTHROPIC_API_KEY`  | (required) | agents, ai-workers, cms, video |
| `OPENAI_API_KEY`     | (optional) | agents (alternative)           |
| `HEYGEN_API_KEY`     | (optional) | video service                  |
| `ELEVENLABS_API_KEY` | (optional) | audio service                  |
| `GHANA_NLP_API_KEY`  | (optional) | nlp, audio                     |

#### Social Platform Tokens (optional)

| Variable                | Used By        |
| ----------------------- | -------------- |
| `META_ACCESS_TOKEN`     | social service |
| `INSTAGRAM_ACCOUNT_ID`  | social service |
| `FACEBOOK_PAGE_ID`      | social service |
| `TWITTER_BEARER_TOKEN`  | social service |
| `TELEGRAM_BOT_TOKEN`    | social service |
| `YOUTUBE_API_KEY`       | social, video  |
| `TIKTOK_CLIENT_KEY`     | social         |
| `LINKEDIN_ACCESS_TOKEN` | social         |

#### Payment Providers (optional)

| Variable              | Used By        |
| --------------------- | -------------- |
| `STRIPE_SECRET_KEY`   | api (payments) |
| `PAYSTACK_SECRET_KEY` | api (payments) |

### 3. Database Setup (Prisma)

The Veritas database schema is managed by Prisma and lives at
`libs/veritas/database/prisma/schema.prisma`.

```bash
cd libs/veritas/database

# Generate the Prisma client
npx prisma generate

# Apply schema to local database (create tables)
npx prisma db push

# Or run migrations if available
npx prisma migrate dev
```

### 4. Seed the Database

The ingestion service includes a seed command that populates the database with
300+ Ghanaian news sources.

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

# Preview sources without database changes
pnpm nx run veritas-ingestion seed -- --dry-run

# Print source summary only
pnpm nx run veritas-ingestion seed -- --summary
```

### 5. Install Dependencies

```bash
pnpm install
```

---

## Project Structure

### Applications (`apps/veritas/`)

```
apps/veritas/
  api/                 # REST API Gateway (Hono, Port 3001)
  nlp/                 # NLP Microservice (Hono, Port 3002)
  ingestion/           # News ingestion (scheduler, producer, worker)
  agents/              # Multi-agent orchestration (Port 3006)
  ai-workers/          # BullMQ AI content processing workers
  cms/                 # Editorial CMS (Port 3004)
  analytics/           # Analytics service (Port 3004)
  video/               # Video production with HeyGen (Port 3004)
  audio/               # Audio/TTS/podcast production
  social/              # Social media automation (Port 3005)
  notifications/       # Email and FCM push notifications
  web/                 # Next.js PWA (Port 3000)
  mobile/              # Expo/React Native mobile app
```

### Libraries (`libs/veritas/`)

```
libs/veritas/
  # Foundation
  core/                # Core types, branded primitives (Uuid, Slug, etc.)
  models/              # Zod-validated data model schemas
  database/            # Prisma client, repositories, health, metrics
  auth/                # Authentication, API keys, OAuth, middleware
  cache/               # Redis caching strategies (articles, search, sessions)
  search/              # Elasticsearch client, query builder, index manager

  # AI and NLP
  llm/                 # LLM client router, cost optimizer, prompts
  agents-core/         # Base agent framework
  agents-orchestrator/ # Multi-agent workflow orchestration
  agents-editorial/    # Editorial content agents
  agents-journalism/   # Journalist and reporter agents
  agents-fact-checking/ # Fact-checker agent
  agents-social-media/ # Social media management agents
  agents-devops/       # DevOps agents
  agents-product/      # Product management agents
  agents-qa/           # Quality assurance agents
  nlp-core/            # NLP primitives
  ghana-nlp/           # Ghana NLP Khaya API client
  bias-detection/      # Political bias and GPL scoring
  fact-checking/       # Claim verification and evidence
  claims/              # Claim extraction and linking

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

  # Media Production
  audio-production/    # Audio rendering pipeline
  video-production/    # Video composition pipeline
  live-stream/         # 24/7 YouTube Live, RTMP, graphics, Q&A
  social-automation/   # Cross-platform social posting

  # Business
  analytics/           # Content, user, revenue analytics
  payments/            # Stripe, Paystack, mobile money
  billing/             # Subscriptions, invoicing, pricing
  notifications/       # Push, email, SMS delivery
  b2b-sdk/             # TypeScript SDK for B2B API
  b2b-sdk-python/      # Python SDK for B2B API
  business/            # Business logic and domain rules
  seo/                 # SEO optimization
  newsletter/          # Email newsletter campaigns

  # Regional and Access
  regional/            # Region-specific content
  ussd/                # USSD channel (MTN, Vodafone, AirtelTigo, Glo)
  signup/              # User registration flows
  developer-support/   # Developer documentation tools

  # Infrastructure
  ab-testing/          # A/B testing framework
  archive/             # Content archival
  community/           # Community engagement
  comments/            # Article commenting
  events/              # Event bus and domain events
  emergency/           # Emergency broadcast distribution
  expansion/           # Platform expansion (regions, languages)
  operations/          # Operations management
  platforms/           # Platform abstraction
  realtime-data/       # Real-time data feeds
  risk/                # Risk assessment
  storage/             # File storage abstraction (S3/MinIO/GCS)
  automated-content/   # Automated content pipeline
  ai-next-gen/         # Next-gen AI R&D
  research-assistant/  # Research tools for journalists
```

### API Structure

The API application follows a layered architecture:

```
apps/veritas/api/src/
  main.ts                              # Entry point, server startup
  interfaces/http/
    server.ts                          # Hono app creation, middleware setup
    routes/v1/
      articles.ts                      # Article CRUD, search, feed
      sources.ts                       # News source management
      authors.ts                       # Author profiles
      claims.ts                        # Fact-check claims
      bias.ts                          # Bias analysis
      stories.ts                       # Story clusters
      search.ts                        # Full-text search
      users.ts                         # User management
      subscriptions.ts                 # Subscription management
      payments.ts                      # Payment processing
      b2b-api.ts                       # B2B partner endpoints
      writingAssistant.ts              # AI writing assistance
      compliance.ts                    # Content compliance
      ads.ts                           # Advertising
      tips.ts                          # Confidential tips
      ...                              # Additional route files
  infrastructure/
    postgres/createPool.ts             # pg connection pool factory
    redis/createRedis.ts               # ioredis client factory
    elasticsearch/createClient.ts      # ES client factory
```

---

## Running Services

### Core Services (Start These First)

#### API Server (Port 3001)

The primary backend service that all clients connect to.

```bash
# Development (via Nx)
pnpm nx serve veritas-api

# Build and run
pnpm nx build veritas-api
node dist/apps/veritas/api/main.mjs
```

Once running, visit http://localhost:3001/docs for the Swagger UI (OpenAPI
documentation).

#### NLP Service (Port 3002)

Dedicated NLP analysis microservice.

```bash
# Development
pnpm nx serve veritas-nlp

# Build and run
pnpm nx build veritas-nlp
node dist/apps/veritas/nlp/main.mjs
```

Verify: `curl http://localhost:3002/health`

#### Web Application (Port 3000)

Next.js progressive web application.

```bash
# Development (hot reload)
pnpm nx serve veritas-web

# Or directly
cd apps/veritas/web
npx next dev -p 3000
```

### Ingestion Pipeline

The ingestion service runs as three separate processes:

```bash
# Terminal 1: Scheduler - fetches feeds on a timer
pnpm nx run veritas-ingestion scheduler

# Terminal 2: Producer - enqueues unprocessed items
pnpm nx run veritas-ingestion producer

# Terminal 3: Worker - processes items from queue
pnpm nx run veritas-ingestion worker
```

Or use environment variables to run once:

```bash
VERITAS_ONCE=true pnpm nx run veritas-ingestion scheduler
```

#### Seed Database

```bash
pnpm nx run veritas-ingestion seed
pnpm nx run veritas-ingestion seed -- --dry-run
pnpm nx run veritas-ingestion seed -- --summary
```

### AI Services

#### Multi-Agent Service (Port 3006)

Requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.

```bash
# Development (with tsx watch)
pnpm nx dev veritas-agents

# Or via serve
pnpm nx serve veritas-agents
```

#### AI Workers

```bash
# List available workers
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js list

# Run a specific worker once
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js run \
    --worker weather-report --once

# Run continuously
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js run \
    --worker article-summarization --poll-ms 60000

# Show queue status
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js status

# Set up scheduled jobs
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js schedule
```

Available workers:

| Worker                  | Category           | Description                     |
| ----------------------- | ------------------ | ------------------------------- |
| `weather-report`        | Content Generation | Ghana weather forecasts         |
| `market-summary`        | Content Generation | GSE and forex market summaries  |
| `fuel-price`            | Content Generation | NPA fuel price updates          |
| `trend-analysis`        | Content Generation | Trending topic analysis         |
| `article-summarization` | Processing         | Article summary variants        |
| `headline-variants`     | Processing         | Alternative headline generation |
| `article-tagging`       | Processing         | Topic/entity tagging            |
| `article-priority`      | Processing         | Priority score calculation      |
| `story-clustering`      | Analysis           | Related article clustering      |
| `source-accuracy`       | Analysis           | Source accuracy scoring         |
| `blindspot-detection`   | Analysis           | Coverage gap detection          |
| `fact-check`            | Editorial          | Claim verification              |

### Media Services

#### CMS (Port 3004)

```bash
pnpm nx serve veritas-cms
```

#### Video Service (Port 3004)

Requires `HEYGEN_API_KEY` for video rendering and `ANTHROPIC_API_KEY` for script
generation.

```bash
# HTTP server
pnpm nx run veritas-video serve

# Queue worker (direct rendering)
pnpm nx run veritas-video worker -- --concurrency 3

# Queue worker (HTTP mode - calls video service)
pnpm nx run veritas-video worker -- --http-mode

# Queue producer
pnpm nx run veritas-video producer -- --limit 50

# Sync avatar profiles from HeyGen
pnpm nx run veritas-video serve   # (then in another terminal)
node --import tsx apps/veritas/video/src/main.ts sync-avatars
```

#### Audio Service

Requires `ELEVENLABS_API_KEY` for English TTS or `GHANA_NLP_API_KEY` for local
language TTS.

```bash
pnpm nx serve veritas-audio
```

#### Social Service (Port 3005)

Configure platform tokens via environment variables (see
[Environment Variables Reference](#environment-variables-reference)).

```bash
# HTTP server
pnpm nx run veritas-social serve

# Queue worker
pnpm nx run veritas-social worker -- --concurrency 3

# Scheduler tick (development)
pnpm nx run veritas-social scheduler
```

### Analytics Service (Port 3004)

```bash
pnpm nx serve veritas-analytics
```

### Notification Service

```bash
pnpm nx serve veritas-notifications
```

### Mobile Application

```bash
# Start Expo development server
pnpm nx start veritas-mobile

# iOS
pnpm nx start:ios veritas-mobile

# Android
pnpm nx start:android veritas-mobile

# Build for iOS (requires EAS CLI)
pnpm nx build:ios veritas-mobile

# Build for Android
pnpm nx build:android veritas-mobile

# Submit to App Store
pnpm nx submit:ios veritas-mobile

# Submit to Google Play
pnpm nx submit:android veritas-mobile
```

---

## Building and Testing

### Build All Veritas Projects

```bash
pnpm nx run-many --target=build --projects=tag:domain:veritas
```

### Build Individual Projects

```bash
# Backend services (esbuild, outputs ESM)
pnpm nx build veritas-api
pnpm nx build veritas-nlp
pnpm nx build veritas-ingestion
pnpm nx build veritas-agents
pnpm nx build veritas-ai-workers
pnpm nx build veritas-video
pnpm nx build veritas-audio
pnpm nx build veritas-social
pnpm nx build veritas-cms
pnpm nx build veritas-analytics
pnpm nx build veritas-notifications

# Web (Next.js build)
pnpm nx build veritas-web

# Mobile (Expo/EAS)
pnpm nx build veritas-mobile
```

### Running Tests

All Veritas projects use Vitest via the `@nx/vite:test` executor (except the
mobile app which uses Jest).

```bash
# All Veritas projects
pnpm nx run-many --target=test --projects=tag:domain:veritas

# Individual project
pnpm nx test veritas-api
pnpm nx test veritas-nlp
pnpm nx test veritas-agents

# Library tests
pnpm nx test @veritas/core
pnpm nx test @veritas/database
pnpm nx test @veritas/analytics

# With watch mode
cd apps/veritas/api
npx vitest

# With coverage
cd apps/veritas/api
npx vitest run --coverage
```

Test configuration for backend services is in `vitest.config.ts`:

```typescript
// Typical vitest.config.ts pattern
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
    },
    testTimeout: 10000,
  },
});
```

### Linting

```bash
# All Veritas projects
pnpm nx run-many --target=lint --projects=tag:domain:veritas

# Individual project
pnpm nx lint veritas-api
pnpm nx lint veritas-web
pnpm nx lint veritas-mobile
```

### Type Checking

```bash
# Web
cd apps/veritas/web
pnpm type-check   # tsc --noEmit

# Mobile
pnpm nx typecheck veritas-mobile

# Social
pnpm nx typecheck veritas-social
```

### Load Testing

The API has k6 load test configurations:

```bash
# Standard load test
pnpm nx load-test veritas-api

# Stress test
pnpm nx load-test veritas-api --configuration=stress

# Combined load test
pnpm nx load-test veritas-api --configuration=combined
```

### E2E Testing

```bash
# Web (Playwright)
pnpm nx e2e veritas-web

# Mobile (Detox)
pnpm nx e2e veritas-mobile                       # iOS debug
pnpm nx e2e veritas-mobile --configuration=android.debug  # Android debug
```

### Python SDK Testing

```bash
cd libs/veritas/b2b-sdk-python

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=veritas_sdk
```

---

## Common Development Tasks

### Adding a New API Endpoint

1. Create the route file in `apps/veritas/api/src/interfaces/http/routes/v1/`:

   ```typescript
   import { Hono } from 'hono';
   import { zValidator } from '@hono/zod-validator';
   import { z } from 'zod';

   const myRoute = new Hono();

   const querySchema = z.object({
     limit: z.coerce.number().int().min(1).max(100).default(20),
     offset: z.coerce.number().int().min(0).default(0),
   });

   myRoute.get('/', zValidator('query', querySchema), async (c) => {
     const { limit, offset } = c.req.valid('query');
     // Implementation using pool from context
     return c.json({ items: [], total: 0 });
   });

   export { myRoute };
   ```

2. Register the route in the server setup (`server.ts`).

3. The API auto-generates OpenAPI documentation from Zod schemas when using
   `@hono/zod-openapi`.

### Adding a New AI Worker

1. Create the worker tick function in `apps/veritas/ai-workers/src/workers/`:

   ```typescript
   import type { Pool } from 'pg';

   interface MyWorkerOptions {
     dryRun: boolean;
     limit: number;
   }

   export async function tick(pool: Pool, opts: MyWorkerOptions) {
     // Query for items to process
     // Call LLM or NLP service
     // Write results to database
     return { processed: 0, skipped: 0 };
   }

   export function getDefaultOptions(): MyWorkerOptions {
     return { dryRun: false, limit: 50 };
   }
   ```

2. Register the worker in `apps/veritas/ai-workers/src/workers/index.ts`.

3. Add queue configuration in `apps/veritas/ai-workers/src/config.ts` with an
   optional cron schedule.

### Adding a New Social Platform

1. Create a platform adapter in `apps/veritas/social/src/platforms/`:

   ```typescript
   import type { PlatformAdapter, PostResult } from '../types.js';

   export class MyPlatformAdapter implements PlatformAdapter {
     async publish(post: ScheduledPost): Promise<PostResult> {
       // Platform-specific publishing logic
     }

     async getMetrics(postId: string): Promise<PostMetrics> {
       // Platform-specific metrics retrieval
     }
   }
   ```

2. Register the adapter in `apps/veritas/social/src/main.ts` within
   `createPlatformAdapters()`.

3. Add environment variable configuration for the platform credentials.

### Adding a New Podcast Series

1. Define the series in `apps/veritas/audio/src/services/podcast-series.ts`:

   ```typescript
   export function buildMyNewSeries(): PodcastSeriesDefinition {
     return {
       id: 'my-series',
       name: 'My New Series',
       description: 'Description of the series',
       schedule: { frequency: 'daily', timeSlot: { hour: 8, minute: 0 } },
       contentFilter: { categories: ['politics', 'business'] },
       segmentTemplates: [
         { type: 'intro', durationSeconds: 30 },
         { type: 'main', durationSeconds: 300 },
         { type: 'outro', durationSeconds: 30 },
       ],
     };
   }
   ```

2. Create a script generator function that takes articles and produces a
   `PodcastScript`.

3. Register the series in `buildAllDefaultSeries()`.

### Working with the Database

```bash
# Generate Prisma client after schema changes
cd libs/veritas/database
npx prisma generate

# Create a new migration
npx prisma migrate dev --name add_my_new_table

# Apply migrations in production
npx prisma migrate deploy

# View database in browser
npx prisma studio

# Reset database (destructive)
npx prisma migrate reset
```

### Adding a New NLP Endpoint

1. Create the service function in `apps/veritas/nlp/src/services/`.

2. Add the route handler in `apps/veritas/nlp/src/server.ts`.

3. Add both single and batch variants of the endpoint.

4. Update the startup banner in `apps/veritas/nlp/src/main.ts` to list the new
   endpoint.

---

## Environment Variables Reference

### Complete Variable List

#### Core Infrastructure

| Variable               | Default                                               | Description                  |
| ---------------------- | ----------------------------------------------------- | ---------------------------- |
| `VERITAS_DATABASE_URL` | `postgresql://oshun:oshun_dev@localhost:5432/veritas` | PostgreSQL connection string |
| `DATABASE_URL`         | Same as above                                         | Fallback for some services   |
| `REDIS_URL`            | `redis://localhost:6379`                              | Redis connection string      |
| `ELASTICSEARCH_URL`    | `http://localhost:9200`                               | Elasticsearch URL            |
| `S3_ENDPOINT`          | `http://localhost:9000`                               | MinIO/S3 endpoint            |
| `S3_ACCESS_KEY`        | `minioadmin`                                          | S3 access key                |
| `S3_SECRET_KEY`        | `minioadmin`                                          | S3 secret key                |

#### API Service

| Variable                       | Default            | Description                          |
| ------------------------------ | ------------------ | ------------------------------------ |
| `PORT`                         | `3001`             | API server port                      |
| `HOST`                         | `0.0.0.0`          | API server host                      |
| `CORS_ENABLED`                 | `true`             | Enable CORS                          |
| `CORS_ORIGINS`                 | `*`                | Comma-separated allowed origins      |
| `RATE_LIMIT_ENABLED`           | `true`             | Enable rate limiting                 |
| `RATE_LIMIT_MAX`               | `120`              | Max requests per window              |
| `RATE_LIMIT_WINDOW_SECONDS`    | `60`               | Rate limit window size               |
| `API_KEY_AUTH_ENABLED`         | `false`            | Enable API key authentication        |
| `API_KEYS`                     | --                 | Comma-separated valid API keys       |
| `OPENAPI_ENABLED`              | `true`             | Enable OpenAPI/Swagger docs          |
| `VERITAS_ACCESS_TOKEN_SECRET`  | --                 | JWT signing secret                   |
| `ELASTICSEARCH_ARTICLES_INDEX` | `veritas-articles` | ES articles index name               |
| `TIPS_ENCRYPTION_KEY`          | --                 | Encryption key for confidential tips |

#### NLP Service

| Variable    | Default   | Description     |
| ----------- | --------- | --------------- |
| `NLP_PORT`  | `3002`    | NLP server port |
| `NLP_HOST`  | `0.0.0.0` | NLP server host |
| `LOG_LEVEL` | `info`    | Logging level   |

#### Ingestion Service

| Variable                     | Default          | Description                      |
| ---------------------------- | ---------------- | -------------------------------- |
| `VERITAS_ONCE`               | `false`          | Run one tick and exit            |
| `VERITAS_POLL_INTERVAL_MS`   | `60000`          | Interval between scheduler ticks |
| `VERITAS_DISABLE_RSS`        | `false`          | Disable RSS collection           |
| `VERITAS_ENABLE_SITEMAPS`    | `false`          | Enable sitemap collection        |
| `VERITAS_ENABLE_SOCIAL`      | `false`          | Enable social media monitoring   |
| `VERITAS_RSS_LIMIT`          | `100`            | Max feeds per tick               |
| `VERITAS_RSS_CONCURRENCY`    | `10`             | Concurrent feed fetches          |
| `VERITAS_RSS_TIMEOUT_MS`     | `30000`          | Feed fetch timeout               |
| `VERITAS_PRODUCER_LIMIT`     | `100`            | Items per producer tick          |
| `VERITAS_WORKER_CONCURRENCY` | `4`              | Concurrent processing jobs       |
| `VERITAS_SCRAPE_MISSING`     | `true`           | Scrape missing article content   |
| `VERITAS_USER_AGENT`         | `VeritasBot/1.0` | HTTP user agent                  |

#### Agent Service

| Variable                         | Default   | Description                 |
| -------------------------------- | --------- | --------------------------- |
| `AGENTS_PORT`                    | `3006`    | Agent service port          |
| `AGENTS_HOST`                    | `0.0.0.0` | Agent service host          |
| `HEALTH_CHECK_INTERVAL_MS`       | `30000`   | Agent health check interval |
| `METRICS_COLLECTION_INTERVAL_MS` | `60000`   | Metrics collection interval |

#### CMS Service

| Variable                | Default        | Description          |
| ----------------------- | -------------- | -------------------- |
| `CMS_PORT`              | `3004`         | CMS server port      |
| `CMS_HOST`              | `0.0.0.0`      | CMS server host      |
| `CMS_TIMEZONE`          | `Africa/Accra` | Publication timezone |
| `CMS_QUIET_HOURS_START` | `22:00`        | Quiet hours start    |
| `CMS_QUIET_HOURS_END`   | `06:00`        | Quiet hours end      |

#### Video Service

| Variable                            | Default | Description                  |
| ----------------------------------- | ------- | ---------------------------- |
| `PORT`                              | `3004`  | Video server port            |
| `HEYGEN_API_KEY`                    | --      | HeyGen API key               |
| `ANTHROPIC_API_KEY`                 | --      | Claude API key (scripts)     |
| `VIDEO_QUEUE_CONCURRENCY`           | `3`     | Worker concurrency           |
| `VIDEO_QUEUE_POLL_MS`               | `10000` | Producer poll interval       |
| `VIDEO_DEFAULT_AVATAR_PROFILE_SLUG` | --      | Default avatar for rendering |

#### Social Service

| Variable                        | Default | Description               |
| ------------------------------- | ------- | ------------------------- |
| `PORT`                          | `3005`  | Social server port        |
| `SOCIAL_TIMEZONE`               | --      | Timezone for scheduling   |
| `SOCIAL_QUEUE_CONCURRENCY`      | `3`     | Worker concurrency        |
| `SOCIAL_CROSS_POST_DELAY_MS`    | --      | Delay between cross-posts |
| `SOCIAL_BREAKING_NEWS_DELAY_MS` | --      | Breaking news post delay  |
| `SOCIAL_MAX_RETRIES`            | --      | Max post retries          |

#### Analytics Service

| Variable                 | Default   | Description           |
| ------------------------ | --------- | --------------------- |
| `ANALYTICS_PORT`         | `3004`    | Analytics server port |
| `ANALYTICS_HOST`         | `0.0.0.0` | Analytics server host |
| `ANALYTICS_CORS_ORIGINS` | `*`       | Allowed CORS origins  |

---

## Debugging Tips

### Database Issues

**Connection failures**: Verify PostgreSQL is running and the connection string
is correct.

```bash
# Check if PostgreSQL is running
docker compose -f docker/docker-compose.dev.yml ps

# Test connection directly
psql postgresql://oshun:oshun_dev@localhost:5432/veritas -c "SELECT 1"

# View container logs
docker logs oshun-dev-postgres

# Reset database volumes if corrupted
docker compose -f docker/docker-compose.dev.yml down -v
docker compose -f docker/docker-compose.dev.yml up -d
```

**Prisma schema drift**: If the database schema is out of sync with the Prisma
schema:

```bash
cd libs/veritas/database
npx prisma db push --force-reset  # WARNING: drops all data
npx prisma generate
```

### Redis Issues

**BullMQ workers not processing**: Verify Redis is accessible and that the
connection URL is correct.

```bash
# Test Redis connection
redis-cli ping

# View BullMQ queue status
pnpm nx build veritas-ai-workers && \
  node dist/apps/veritas/ai-workers/main.js status

# Monitor Redis commands in real-time
redis-cli monitor
```

### Elasticsearch Issues

**Search returning empty results**: Verify Elasticsearch is running and the
index exists.

```bash
# Check cluster health
curl http://localhost:9200/_cluster/health?pretty

# List indices
curl http://localhost:9200/_cat/indices?v

# Check Veritas articles index
curl http://localhost:9200/veritas-articles/_count
```

### Ingestion Pipeline

**No articles being ingested**: Start all three ingestion processes (scheduler,
producer, worker) and check that feeds are seeded.

```bash
# 1. Seed sources
pnpm nx run veritas-ingestion seed

# 2. Run scheduler once to fetch feeds
VERITAS_ONCE=true pnpm nx run veritas-ingestion scheduler

# 3. Run producer once to enqueue items
VERITAS_ONCE=true pnpm nx run veritas-ingestion producer

# 4. Run worker to process queue
pnpm nx run veritas-ingestion worker
```

### Agent Service

**Agents not processing tasks**: Verify `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
is set. Check the health monitor for agent status.

```bash
# Check agent health
curl http://localhost:3006/health

# Check agent metrics
curl http://localhost:3006/metrics
```

### Mobile Development

**Expo build issues**: Clear caches and reinstall.

```bash
cd apps/veritas/mobile

# Clean Expo cache
expo start --clear

# Clean prebuild
expo prebuild --clean

# Reset Metro bundler cache
npx react-native start --reset-cache
```

### Port Conflicts

If a port is already in use, find the conflicting process:

```bash
# Find process on a specific port
lsof -i :3001
lsof -i :3002
lsof -i :3006

# Or use ss
ss -tlnp | grep 3001
```

### Viewing Logs

All services log to stdout/stderr. Use structured JSON logging in production:

```bash
# Set log level
LOG_LEVEL=debug pnpm nx serve veritas-api

# Quiet mode (errors only)
LOG_LEVEL=error pnpm nx serve veritas-api
```

### Running a Minimal Stack

For frontend development, you only need the API and optionally the NLP service:

```bash
# Terminal 1: Infrastructure
docker compose -f docker/docker-compose.dev.yml up -d

# Terminal 2: API
pnpm nx serve veritas-api

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

The web app will be available at http://localhost:3000 and the API at
http://localhost:3001/docs.
