Code Generation

The platform uses code generation pipelines to keep API contracts in sync across all services.

Event types (AsyncAPI)

The AsyncAPI specification in services/wordloop-core/asyncapi.yaml is the single source of truth for all event-driven types (WebSocket events and Pub/Sub messages).

# Compile AsyncAPI spec to typed internal Events for all services
./dev gen events

This produces:

Consumer scripts (App, ML) try to fetch the spec from a running Core instance at http://localhost:4002/asyncapi.yaml first, and fall back to the local monorepo path for offline generation.

:::info Core owns the spec and generates its own types locally. App and ML are consumers that pull the spec from Core — following the same pattern as OpenAPI client generation. :::

Core → ML client (oapi-codegen)

wordloop-core generates a Go HTTP client for calling wordloop-ml's API.

# Core must be running at localhost:4002 and ML at localhost:4003
./dev gen clients

Under the hood:

cd services/wordloop-core
WORDLOOP_ML_BASE_URL=http://127.0.0.1:4003 ./scripts/generate-clients.sh

Adding a new external API client in Core:

1. Create internal/provider/<name>/
2. Add an oapi-codegen.yaml config in that directory
3. Set <NAME>_BASE_URL when running the script

ML → Core client (openapi-python-client)

wordloop-ml generates a Python client for calling wordloop-core's API.

# Generated simultaneously alongside Core's
./dev gen clients

Under the hood:

cd services/wordloop-ml
./scripts/generate_wordloop_core_client.sh

The generated client is written to src/wordloop/providers/wordloop_core/client/ and must not be edited manually.

App TypeScript client (Orval)

wordloop-app generates TypeScript types, SWR hooks, and API functions from Core's OpenAPI spec.

# Generated simultaneously via Orval
./dev gen clients

Under the hood:

curl http://localhost:4002/openapi.json -o services/wordloop-app/openapi.json
cd services/wordloop-app && pnpm orval

The generated file is lib/api/generated.ts — never edit it manually. Use the wrapper hooks in hooks/use-data.ts.

Regenerate everything

# All services must be running for clients to pull live specs
./dev gen all

This runs: events → clients → docs.