Getting Started

The `./dev` CLI Driver

All local orchestration, testing, database migrations, and telemetry dashboards are driven exclusively by the custom ./dev CLI tool located in the repository root. See the CLI Reference to get started!

Prerequisites

Tool	Version	Purpose
Docker	Compose v2.20+	Infrastructure services
Go	1.25+	wordloop-core
Air	latest	Go auto-reload (`go install github.com/air-verse/air@latest`)
uv	latest	wordloop-ml Python env
pnpm	latest	wordloop-app dependencies
ffmpeg	latest	ML audio processing

Quick start

# 1. Clone the monorepo
git clone <repository-url>
cd wordloop-platform
 
# 2. Copy environment files
./dev setup
 
# 3. Fill in secrets
#    Edit services/wordloop-ml/.env (API keys)
#    Edit services/wordloop-app/.env.local (Clerk keys)
#    Edit services/wordloop-core/.env (Clerk secret key)
 
# 4. Install dependencies
./dev setup install
 
# 5. Start everything
./dev start all

This boots infrastructure in Docker and runs Core, ML, and App natively. Code changes auto-restart — no manual intervention needed.

The Hybrid Development Model

Infrastructure runs in Docker (stable, rarely changes). Application services run natively for instant feedback:

What runs	Where	Auto-reload?
Postgres, PubSub, Storage, OTel	Docker containers	n/a
Core API (Go)	Native via Air	✅ Rebuilds on `.go` file change
ML API (Python)	Native via uv	✅ Restarts on `.py` file change
App (Next.js)	Native via pnpm	✅ HMR in browser

Typical workflows

# Full stack (recommended for daily work)
./dev start all
 
# Infrastructure only (run services from your IDE)
./dev start infra
 
# Infrastructure + specific services
./dev start infra core        # Debug ML from IDE
./dev start infra core ml     # Debug App from IDE
 
# Force Docker containers (for integration testing)
./dev start core ml --docker

Tailing logs

Native service logs are written to .dev/logs/ and can be tailed with the same CLI:

./dev logs core    # Tail Core output
./dev logs ml      # Tail ML output
./dev logs all     # Tail everything

Full stack in Docker

For CI-like environments or full-stack integration testing:

./dev start all --docker   # Everything in containers
./dev logs all             # Tail all logs
./dev stop all             # Stop everything

Authentication

Authentication is handled automatically through JIT provisioning:

Sign in via Clerk (Google, email, or test accounts) in the browser
The Core API verifies the Clerk JWT
If the user doesn't exist locally yet, they're auto-created from the Clerk API
No webhook tunnels, no manual tokens, no database seeding

[!NOTE] System tests use a separate APP_ENV=test mode with raw UUID tokens. See Testing Strategy for details.

Linting

./dev lint        # Lints core (go vet), ml (ruff), and app (eslint)
./dev lint core   # Go linter only
./dev lint ml     # Python Ruff only
./dev lint app    # TypeScript ESLint only

Checking status

./dev status      # Show nicely formatted dashboard of running services

See CLI Reference for the complete target list.

Getting Started

On this page