Local Infrastructure & Emulation

Wordloop utilizes a hybrid local-first development model orchestrated via our custom ./dev CLI.

Instead of running the entire stack in heavy, monolithic Docker containers, we segment the environment:

• Infrastructure & Observability (Docker): Stateful services (Postgres, Pub/Sub emulator, Storage emulator) and telemetry tools (Aspire Dashboard) run in Docker.
• Application Services (Native): Code bases (wordloop-core, wordloop-ml, wordloop-app, wordloop-docs) run natively on your host machine. We use file monitoring tools (air for Go, uvicorn for Python, and Next.js dev server) to enable instant hot-reloading, bypassing the need to rebuild Docker images after every code change.

Local Port Architecture

To prevent port collisions, all services follow a well-structured port layout:

Application Services (Native)

Infrastructure Spaces (Docker)

• Statefulness: Postgres data is persisted in a local Docker volume (db_data). Emulators spin up ephemerally. The Core service programmatically provisions required Pub/Sub topics and buckets on boot.
• Bootstrapping: Use ./dev start all to bring up the Docker infra and native host services concurrently. Run ./dev help for more granularity.

Environment Configuration

Configuration relies exclusively on environment variables injected at runtime. There are NO configuration files deployed with the containers. See individual service handbooks for specifics.