Skip to main content

Getting Started

Prerequisites​

  • Python 3.11+
  • Node.js 18+
  • Docker (for ClickHouse)
  • AWS CLI configured with profile "polo" (aws configure --profile polo)

Setup​

1. Start ClickHouse​

polo up
# Verify it's running:
curl http://localhost:8123/ping  # Should return "Ok."

2. Apply schema migrations​

polo migrate

This runs components/schema/migrate.py, applying all SQL migrations in components/schema/migrations/ (001-010).

3. Seed test data (optional)​

polo seed

Runs scripts/seed_test_data.py to populate ClickHouse with sample data for local development.

4. Install UI dependencies​

cd components/ui && npm install
cd ../api && npm install

5. Run the UI in dev mode​

cd components/ui && npm run dev

6. Run the API Worker in dev mode​

cd components/api && npx wrangler dev

Running Tests​

polo test schema       # Schema validation (requires CH)
polo test unit         # Unit tests (mocked AWS, no CH needed)
polo test integration  # Integration tests (requires CH)
polo test perf         # Performance benchmarks (requires CH)
polo test e2e          # E2E tests (requires AWS credentials + CH)
polo test all          # All of the above in order

See testing.md for the full testing strategy and phase checkpoints.

Code Quality​

pants lint ::          # Lint all Python code (ruff)
pants fmt ::           # Auto-format all Python code
polo health            # Run repo health checks

Project Layout​

See project-structure.md for the full directory tree and conventions.

Quick reference:

  • components/schema/ — ClickHouse migrations
  • components/collectors/ — Python Lambda collectors
  • components/api/ — Cloudflare Worker API (TypeScript)
  • components/ui/ — React SPA (TypeScript)
  • infra/legacy/ — AWS CDK infrastructure (Python)
  • tests/ — Integration, performance, and e2e tests