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) |

