Core Service (Go)

wordloop-core is the platform's system of record. It handles all database interactions, operational transactional logic, and asynchronous job orchestration.

[!IMPORTANT] The Core service exposes a strictly typed REST API via Huma, ensuring absolute contract adherence.

Architecture & Layout

The project strictly abides by Clean Architecture principles, enforcing strong boundaries between domain logic and side-effects.

services/wordloop-core/
├── cmd/api/main.go          # Entrypoint (DI wiring & server boot)
├── internal/
│   ├── core/domain/         # Entities, Value Objects, Pure Logic
│   ├── core/service/        # Orchestration & Use-Cases
│   ├── entrypoints/         # HTTP Handlers (Huma), Clerk JWT Middleware
│   └── provider/            # Postgres, Pub/Sub, Storage Adapters
└── scripts/migrations/      # SQL up/down migrations

Local Development Workflow

Run the Go server locally with standard tools and the consolidated CLI driver.

1. Start Infrastructure Services

   ./dev start infra

   (Boots Postgres, Pub/Sub, Storage Emulators, and the OTel Aspire Dashboard)

2. Execute Database Migrations

   ./dev db migrate

3. Start the API Server

   cd services/wordloop-core
   go run cmd/api/main.go

Development Guidelines

[!WARNING]
Always adhere to the Core Architecture Rules.

If your changes expose new HTTP endpoints, you must regenerate the OpenAPI client before committing. Run:

./dev gen api