Repository map
| Location | Purpose |
|---|---|
package.json, package-lock.json | Pinned documentation build dependencies and npm commands |
go.work | Explicit inventory of local Go modules |
services/ | Business modules, API entry point, and legacy viewer |
pkg/ | Shared Go libraries and infrastructure boundaries |
tools/cli/ | Operational pcli command and embedded-migration orchestration |
api/openapi.yaml | Checked-in generated Huma specification |
api-docs/ | Caddy pages, docs build dependencies, configuration, and image |
docs/ | Authored Markdown, ADRs, and ignored generated Go reference |
bruno-api/ | Identity authentication request collection and environments |
deploy/ | Development Docker Compose configuration |
proto/ | Health protobuf schema scaffold |
scripts/ | Setup/protobuf helpers, Go docs generation, and container verification |
Database assets
Migrations live inside their owning services, not a global root migration directory. Identity, Admin, and Organization export embedded migration files through their migrations packages. The CLI selects and orders these sets. Identity also keeps SQL query definitions and a sqlc.yaml configuration; generated query accessors are service-private. Planned clinical and billing tables in ADRs are not equivalent to migrations already present in the repository.
HTTP development tools
Use Scalar or Swagger to inspect Huma operations. Use the Bruno testing guide for the stateful authentication request sequence and manual email-token checkpoints. Contract examples and downloaded fixtures are distinct from running a functional API test.
Protobuf and setup helpers
go run ./tools/cli generate protobuf invokes scripts/proto-gen.sh, which runs buf lint and buf generate inside proto/. The current repository contains a health schema but no Buf configuration; complete the protobuf generation configuration before treating this scaffold as a ready build pipeline. The health Go module has no source and is not the API's health handler.
scripts/setup.sh is a legacy dependency-install helper using mise and a global Goose install. The operational workflow now uses pcli rather than requiring the standalone Goose binary. Prefer the explicit prerequisites and commands in getting started; the setup script is not a production provisioning/deployment system.
Keeping documentation aligned
Generated pages follow go.work package discovery. New modules also need authored service/package or operations guides; npm run docs:build && npm run docs:check verifies guide coverage. Follow documentation authoring for navigation, Go comments/examples, downloadable fixtures, and build commands.