Eve library

Veritas Domain - Developer Guide

Guide

Revision 1

On this page

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
  2. Local Development Setup
  3. Project Structure
  4. Running Services
  5. Building and Testing
  6. Common Development Tasks
  7. Environment Variables Reference
  8. 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/)#

text
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/)#

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

text
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).

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.