README
¶
IAM — Authentication & Identity
Headless authentication & identity server. The HTTP contract is the single
source of truth: openapi/openapi.yaml (OpenAPI 3.1.0).
Layout
| Path | Purpose |
|---|---|
Makefile |
Developer entry point — make help lists targets. |
openapi/ |
The OpenAPI 3.1 spec (source of truth) + notes. |
.ogen.yaml |
ogen config — Go codegen from the spec. |
pkg/ |
Public, importable Go: the API implementation (pkg/api) and the Go SDK (pkg/sdk). |
internal/oas/ |
Module-private generated ogen code (wire types, client, server scaffolding). |
internal/infrastructure/postgres/ |
SQL store: pgx + pgtx + bob + the sqld codegen toolchain. |
internal/ |
Other module-private packages; not importable from outside. |
cmd/iam/ |
The Go server — serves the API and the embedded admin SPA. |
ts/ |
Yarn workspace; the TypeScript SDK, published to the GitHub npm registry. |
web/ |
Admin panel SPA, served by the server. |
deployments/ |
Production deployment artifacts. |
docker-compose.yml |
Local dev environment (full infra). |
docs/rfc/ |
Reference set of the standards IAM implements. |
Quickstart
make help # list targets
make generate # regenerate Go + TS from the spec
make dev # bring up dev infra
make run # run the server
Stacks (HTTP runtime, storage, frontend, TS toolchain) are decided separately; scaffolding here is intentionally stack-agnostic.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
iam
command
Command iam runs the IAM server: it loads configuration, connects to Postgres, applies migrations, assembles the ogen-generated HTTP API (pkg/api) over the Postgres adapters, exposes liveness/readiness probes, runs the transactional outbox relay, and shuts down gracefully on SIGINT/SIGTERM.
|
Command iam runs the IAM server: it loads configuration, connects to Postgres, applies migrations, assembles the ogen-generated HTTP API (pkg/api) over the Postgres adapters, exposes liveness/readiness probes, runs the transactional outbox relay, and shuts down gracefully on SIGINT/SIGTERM. |
|
internal
|
|
|
config
Package config holds the IAM service configuration, loaded from a config file (config.yaml, path via CONFIG_PATH) overlaid with environment variables and validated.
|
Package config holds the IAM service configuration, loaded from a config file (config.yaml, path via CONFIG_PATH) overlaid with environment variables and validated. |
|
domain
Package domain holds the IAM domain model: aggregate roots and the command value-objects services pass to the aggregate ports.
|
Package domain holds the IAM domain model: aggregate roots and the command value-objects services pass to the aggregate ports. |
|
infrastructure/postgres
Package postgres is the Postgres-backed persistence for IAM: a hand-written pgx + pgtx + bob layer following the komeet pattern — a single *pgxpool.Pool, a pgtx transaction manager (tx.Trm) services use to run repo calls inside an ambient transaction, a ctx-aware TxDB executor, and a bob pool for typed query building.
|
Package postgres is the Postgres-backed persistence for IAM: a hand-written pgx + pgtx + bob layer following the komeet pattern — a single *pgxpool.Pool, a pgtx transaction manager (tx.Trm) services use to run repo calls inside an ambient transaction, a ctx-aware TxDB executor, and a bob pool for typed query building. |
|
oas
Code generated by ogen, DO NOT EDIT.
|
Code generated by ogen, DO NOT EDIT. |
|
pkg
|
|
|
api
Package api is the IAM API implementation: the hand-written code that consumers import.
|
Package api is the IAM API implementation: the hand-written code that consumers import. |
|
sdk
Package sdk is the ergonomic Go SDK for IAM resource servers.
|
Package sdk is the ergonomic Go SDK for IAM resource servers. |
|
sdk/grpc
Package grpc contains IAM authentication interceptors for gRPC servers.
|
Package grpc contains IAM authentication interceptors for gRPC servers. |
|
Package web serves the admin SPA.
|
Package web serves the admin SPA. |
Click to show internal directories.
Click to hide internal directories.