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#
- Prerequisites
- Local Development Setup
- Project Structure
- Running Services
- Building and Testing
- Common Development Tasks
- Environment Variables Reference
- 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.
# 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.
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.
# 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#
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.
# 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.
# 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.
# 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:
# 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:
VERITAS_ONCE=true pnpm nx run veritas-ingestion scheduler
Seed Database#
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.
# Development (with tsx watch)
pnpm nx dev veritas-agents
# Or via serve
pnpm nx serve veritas-agents
AI Workers#
# 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)#
pnpm nx serve veritas-cms
Video Service (Port 3004)#
Requires HEYGEN_API_KEY for video rendering and ANTHROPIC_API_KEY for script
generation.
# 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.
pnpm nx serve veritas-audio
Social Service (Port 3005)#
Configure platform tokens via environment variables (see Environment Variables Reference).
# 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)#
pnpm nx serve veritas-analytics
Notification Service#
pnpm nx serve veritas-notifications
Mobile Application#
# 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#
pnpm nx run-many --target=build --projects=tag:domain:veritas
Build Individual Projects#
# 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).
# 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:
// 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#
# 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#
# 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:
# 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#
# 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#
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#
-
Create the route file in
apps/veritas/api/src/interfaces/http/routes/v1/:typescriptimport { 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 }; -
Register the route in the server setup (
server.ts). -
The API auto-generates OpenAPI documentation from Zod schemas when using
@hono/zod-openapi.
Adding a New AI Worker#
-
Create the worker tick function in
apps/veritas/ai-workers/src/workers/:typescriptimport 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 }; } -
Register the worker in
apps/veritas/ai-workers/src/workers/index.ts. -
Add queue configuration in
apps/veritas/ai-workers/src/config.tswith an optional cron schedule.
Adding a New Social Platform#
-
Create a platform adapter in
apps/veritas/social/src/platforms/:typescriptimport 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 } } -
Register the adapter in
apps/veritas/social/src/main.tswithincreatePlatformAdapters(). -
Add environment variable configuration for the platform credentials.
Adding a New Podcast Series#
-
Define the series in
apps/veritas/audio/src/services/podcast-series.ts:typescriptexport 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 }, ], }; } -
Create a script generator function that takes articles and produces a
PodcastScript. -
Register the series in
buildAllDefaultSeries().
Working with the Database#
# 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#
-
Create the service function in
apps/veritas/nlp/src/services/. -
Add the route handler in
apps/veritas/nlp/src/server.ts. -
Add both single and batch variants of the endpoint.
-
Update the startup banner in
apps/veritas/nlp/src/main.tsto 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.
# 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:
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.
# 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.
# 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.
# 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.
# 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.
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:
# 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:
# 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:
# 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.