Skip to content

Project tour

  • Directoryapi/
    • openapi.yaml the HTTP contract — canonical, served at /docs
  • cmd/app/main.go the single entry point (ims)
  • Directorydocs/ these pages, as plain Markdown
    • …
  • Directoryinternal/
    • Directoryapp/ composition root
      • platform.go shared dependencies (DB, cache, queue, services)
      • schedule.go recurring tasks
      • wiring.go HTTP handlers
      • routes.go middleware chain and route groups
      • dev_commands.go commands runnable from the dashboard
    • Directoryapperr/ error codes → RFC 9457 problems
      • …
    • Directoryauthn/ tokens, OTP, throttle, password recovery
      • …
    • Directoryauthz/ permission catalog and checker
      • …
    • Directorycli/ Cobra commands (ims migrate, ims gen module, …)
      • …
    • Directoryconfig/ typed config, one file per section
      • …
    • Directorydbgen/ generated by sqlc — never edit
      • …
    • Directorycontract/ generated from openapi.yaml — never edit
      • …
    • Directorymodules/ one folder per business module
      • Directorybranches/ the small reference module
        • …
      • Directoryidentity/ users (the rich reference)
        • …
      • Directorybilling/ big module, split into domain/ and service/
        • …
      • …
    • Directoryplatform/ infrastructure: httpx, database, cache, queue, scheduler, storage, mail, telemetry
      • …
    • Directoryscaffold/ the module and OpenAPI generators
      • …
    • Directorytenancy/ tenant scope and resolve middleware
      • …
    • Directorytestkit/ integration-test helpers
      • …
  • Directorymigrations/ goose SQL — the only schema source
    • …
  • Directorysql/queries/ SQL that sqlc turns into Go
    • …
  • Directoryweb/dev/ developer dashboard (React, embedded in the binary)
    • …
  • Directorywebsite/ this documentation site (Astro Starlight)
    • …
  • Directory.agents/skills/ task recipes for AI agents
    • …
  • AGENTS.md working guide for humans and agents
  • Makefile
  • VERSION the release version (semver)

Anatomy of a module

Small and medium modules are flat: one package, a handful of files, each with one job.

File Holds Must not
routes.go paths → handlers, each with its permission contain logic
handler.go bind, call the service, respond contain SQL or business rules
request.go request and response DTOs, NewXResponse mappers contain logic
service.go business rules, tenancy, transactions, activity import httpx or authn
repository.go Repository interface + sqlc implementation import httpx or authn
model.go domain structs and row mappers let dbgen types leak out

Big modules (billing) keep routes/handler/request at the root, shared types in domain/ and business services in service/, which keeps the packages free of import cycles.

Reference modules to copy from: branches (small), identity (rich), billing (big).

Generated code

Three folders are generated and committed. CI regenerates them and fails on any diff.

Folder Generated from Regenerate with
internal/dbgen migrations/ + sql/queries/ make sqlc
internal/contract api/openapi.yaml make openapi
docs/reference/* the CLI, .env.example, the permission catalog, the Makefile make docs-gen

make gen-check runs all of them and fails if anything is stale.

Where does X go?

I want to… Put it in
add a resource with CRUD ims gen module, then internal/modules/<name> — see the tutorial
add an endpoint to a module request.go → service.go → handler.go → routes.go (recipe)
add a permission internal/authz/catalog.go, then ims permission:sync
add a config setting internal/config/<section>.go and .env.example
add a recurring task internal/app/schedule.go
add a queue job the module’s RegisterJobs, registered in platform.go
add a CLI command internal/cli
add a dashboard command internal/app/dev_commands.go
change the schema a new file in migrations/ (database guide)