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

The "Day Zero" Guided Walkthrough

Welcome to Wordloop! Instead of throwing a wall of terminal commands at you, this guide walks you through setting up your environment for an optimal local development experience, including hooking up your IDE debuggers.

Step 1: Environment Checks

Before starting, validate your local toolchain:

# Assumes you have cloned the repo and are at the root
./dev doctor

If doctor flags any missing dependencies (like Docker, Go, or Node) or occupied ports, follow its provided instructions to resolve them.

Step 2: Bootstrapping Config & Secrets

Generate and configure your local environment files:

./dev setup env

This scaffolds .env and .env.local files across the monorepo.

• wordloop-ml: Edit to add ML/AI API keys.
• wordloop-app & core: Add your Clerk frontend & backend keys for authentication.

Step 3: Install Package Dependencies

./dev setup install

Step 4: Infrastructure & IDE Debugging

We use a Hybrid Development Model. Infrastructure (Postgres, PubSub, etc.) runs statically in Docker, allowing you to run your target application natively in your IDE.

If you are working on the App Frontend but want to run Core natively so you can step through Go code:

1. Start the dependencies in the background:

   ./dev start infra ml app

   This starts the DB, Pub/Sub, the ML service, and the Next.js frontend.

2. Launch the Core service in your IDE:

   • VSCode: Open the debug panel and run the "Launch Core API" configuration.
   • GoLand: Run the cmd/server/main.go file with Debug context. Now, any frontend requests will hit your breakpoints in the Core API.

If you just want to run everything locally without IDE debugging (e.g., verifying a PR):

./dev start all

The Hybrid Development Model

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

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 core ml    # Multi-tail Core + ML simultaneously
./dev logs all        # Tail everything (Docker)

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:

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

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.