Go API Architecture

Project Layout

api/
  cmd/api/              # Entry point (main.go)
  internal/
    config/             # App configuration (env vars)
    db/
      migrations/       # SQL migrations (goose)
      queries/          # sqlc query definitions
      sqlc/             # Generated Go code
    handler/            # HTTP handlers (chi router)
    middleware/         # Auth, logging, CORS middleware
    orchestrator/       # Nomad job management
    runtime/            # RuntimeProvider interface + implementations
    service/            # Business logic layer
    caddy/              # Caddy Admin API client

Request Flow

HTTP → chi router → middleware (auth, logging) → handler → service → db/orchestrator

Key Patterns

chi router — lightweight, stdlib-compatible HTTP router
sqlc — type-safe SQL queries, no ORM
pgx/v5 — PostgreSQL driver with connection pooling
hashicorp/nomad/api — Nomad API client for job management
Error wrapping — fmt.Errorf("context: %w", err) everywhere

RuntimeProvider Interface

internal/runtime/provider.go defines the abstraction for different AI runtimes:

GetStatus() — health check
GetConfig() — read runtime config
PatchConfig() — update runtime config
Channel management methods

Implementations:

openclaw.go — WebSocket-based
zeroclaw.go — HTTP REST-based

Project Layout

Request Flow

Key Patterns

RuntimeProvider Interface

On this page