Local Dev Setup

:::info Source Sourced from services/analytics-service/LOCAL_DEV_SETUP.md in the documentation repo. :::

1. Prerequisites

Node 20, pnpm 9, Docker 24.

2. Quick Start

cd services/analytics-service
cp .env.example .env.local
pnpm install
docker compose -f docker-compose.dev.yml up -d   # postgres, nats, kafka, clickhouse, minio, ai-gateway-mock
pnpm db:migrate
pnpm ch:init
pnpm seed
pnpm dev                 # :3150
pnpm dev:firehose
pnpm dev:export
pnpm dev:scheduler

3. Dependencies

Service	Port
postgres	5432
nats	4222
kafka	9092
clickhouse	8123 (HTTP), 9000 (native)
minio	9000 (S3)
ai-gateway-mock	3020

4. Environment

PORT=3150
DATABASE_URL=postgres://analytics:analytics@localhost:5432/analytics
NATS_URL=nats://localhost:4222
KAFKA_BROKERS=localhost:9092
CH_URL=http://localhost:8123
CH_DATABASE=analytics

S3_EXPORT_BUCKET=analytics-exports-dev

AI_GATEWAY_URL=http://localhost:3020
AI_INSIGHTS_ENABLED=true

QUERY_TIMEOUT_MS=30000
EXPORT_MAX_ROWS=100000000
DASHBOARD_CACHE_TTL_S=60

5. Seed

• 3 sample dashboards (learner progress, compliance, revenue).
• 10 metric definitions.
• 50k fixture events in ClickHouse.
• 2 cohorts.

6. Commands

pnpm dev
pnpm test
pnpm test:integration
pnpm test:pipeline           # NATS → Kafka → ClickHouse
pnpm metric:query <id>
pnpm export:run <queryId>
pnpm ai:nl --question "how many learners completed course X?"
pnpm ch:explain <query>

7. Debugging

• ClickHouse UI: http://localhost:8123/play.
• Kafka UI: localhost:8080.
• pnpm ingest:trace tracks event from NATS → CH.