Polyanalytics

Local Development

The local stack uses Docker Compose for PostgreSQL, NATS JetStream, MinIO, Caddy, and the behavior-free service skeletons.

Architecture starts at docs/architecture.md, with the detailed service boundary contract in docs/architecture/service-boundaries.md. Development commands and module-boundary rules are in docs/development.md.

Commands

• Start: bun run infra:up
• Stop without deleting volumes: bun run infra:down
• Follow logs: bun run infra:logs
• Show container health: bun run infra:health
• Reset volumes: CONFIRM_INFRA_RESET=yes bun run infra:reset

infra:reset refuses to run unless CONFIRM_INFRA_RESET=yes is set.

Expected URLs

• Web placeholder through Caddy: http://localhost
• API health through Caddy: http://api.localhost/health/live
• MCP health through Caddy: http://mcp.localhost/health/live
• PostgreSQL: 127.0.0.1:5432
• NATS client: 127.0.0.1:4222
• NATS monitoring: http://127.0.0.1:8222
• MinIO API: http://127.0.0.1:9000
• MinIO admin UI: http://127.0.0.1:9001

PostgreSQL, NATS, NATS monitoring, MinIO API, and MinIO admin UI are bound to loopback only.

Verification

Run:

docker compose -f deploy/compose/compose.yaml config
bun run infra:up
docker compose -f deploy/compose/compose.yaml exec postgres pg_isready -U polyanalytics -d polyanalytics
curl -fsS http://127.0.0.1:8222/jsz
docker compose -f deploy/compose/compose.yaml run --rm minio-client ls local/polyanalytics-parquet
curl -fsS http://api.localhost/health/live
curl -fsS http://mcp.localhost/health/live
bun run infra:down

Expected health responses include the service name, version, and status. Readiness may report degraded until real external dependencies are implemented.

Database Migrations

Migration SQL files live in migrations/ and are append-only. The runner contract is documented in docs/architecture/migration-runner.md.

The TypeScript database package uses Bun's PostgreSQL client and explicit SQL. CLI commands:

• Apply pending migrations: DATABASE_URL=postgresql://polyanalytics:polyanalytics_dev_password@127.0.0.1:5432/polyanalytics bun run db:migrate
• Show migration state and health: DATABASE_URL=postgresql://polyanalytics:polyanalytics_dev_password@127.0.0.1:5432/polyanalytics bun run db:status
• Verify role grants: DATABASE_URL=postgresql://polyanalytics:polyanalytics_dev_password@127.0.0.1:5432/polyanalytics bun run db:verify-permissions

To run migration integration checks against a disposable PostgreSQL database:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/polyanalytics_test bun run db:test:migrations

The command applies pending migrations once, applies them a second time expecting no work, checks role permissions and constraints, verifies API-key plaintext is not represented in the schema, and proves a failed migration rolls back.

To run the database package integration tests, point DATABASE_TEST_URL or DATABASE_URL at a disposable PostgreSQL database and opt in to schema reset:

DATABASE_TEST_URL=postgres://postgres:postgres@127.0.0.1:5432/polyanalytics_test DATABASE_TEST_RESET=yes bun run test:integration

Demo Historical Data

Use the guarded local seeder to create deterministic catalog, ingestion, and analytics data for demos:

POLYANALYTICS_DEMO_SEED=yes DATABASE_URL=postgresql://polyanalytics:polyanalytics_dev_password@127.0.0.1:5432/polyanalytics bun run seed:demo

See docs/operations/demo-seeding.md for options, reset behavior, and safety guarantees.