# ADR-0001: Implementation Language and Repo Skeleton

Date: 2026-05-15
Status: Accepted
Deciders: Bernd, with assessment from Claude (Opus 4.7)
Supersedes: —

## Context

flex-auth is a policy-as-code authorization registry and control plane. It
must run as a CLI and, later, a service. Its peers in the NetKingdom
ecosystem are written in a mix of languages: `key-cape` is Go, `ops-bridge`
and `ops-warden` are Python, the State Hub itself is Python. There is a
recorded State Hub decision noting that Go was the right call for key-cape
because of orchestration-heavy HTTP adapter code, fast iteration, and
clean domain boundaries.

flex-auth shares the relevant traits with key-cape: HTTP/gRPC adapters to
multiple PDPs and directory backends, latency-sensitive check paths, and
a need to ship a single static binary for local-development ergonomics.

## Decision

- **Language: Go.**
- **Module path: `github.com/netkingdom/flex-auth`** (placeholder; adjust
  if the repo moves under a different GitHub org during publication).
- **Minimum Go version: matching key-cape at time of skeleton landing.**
- **Repo layout:**

  ```text
  cmd/flex-auth/        CLI entrypoint
  cmd/flex-authd/       service entrypoint (added when the service layer lands)
  internal/registry/    resource / subject / relationship store
  internal/policy/      policy package model, Rego evaluation, fixtures
  internal/decision/    check, batch_check, list_allowed, explain, decision log
  internal/audit/       compact decision-envelope persistence
  internal/adapters/    pluggable PDP and directory adapters (later WPs)
  pkg/api/              public types and OpenAPI schemas
  schemas/              JSON Schema for manifests and envelopes
  examples/             runnable example manifests, policies, fixtures
  docs/adr/             this ADR series
  ```

- **Build, lint, test:** `Makefile` targets `build`, `test`, `lint`,
  `tidy`, `sbom`. Linting via `golangci-lint`. Tests via the standard
  `go test ./...` plus contract fixtures.
- **SBOM:** generate on each release tag and on `make sbom`; register via
  the State Hub `ingest_sbom_tool` so `last_sbom_at` stops being `null`.

## Rationale

- Aligns with the only language decision in the NetKingdom ecosystem that
  has already been validated in production (KeyCape v0.1).
- Single static binary makes the standalone-first mode trivial to ship
  for local development across NetKingdom repos.
- Strong concurrency primitives suit batch-check and list-allowed paths.
- Excellent OPA tooling for Go (`open-policy-agent/opa/rego`) means the
  Rego evaluator chosen in ADR-0002 has first-class library support.
- Topaz (the target alignment from ADR-0003) is Go-native — adapter work
  in FLEX-WP-0004 stays in the same language.

## Consequences

- New flex-auth contributors need Go in their toolchain. Python is still
  used elsewhere in the ecosystem; cross-repo work that hits the State
  Hub or ops-bridge must accept the language switch.
- The Go decision is reversible while the repo is empty. Once `cmd/` and
  `internal/` have been populated by FLEX-WP-0005 T01, reversal becomes
  expensive — flag any reservations during the skeleton task, not later.

## Out of Scope

- Database choice (SQLite vs Postgres vs file-backed) is settled in
  FLEX-WP-0002 T02 and recorded in a later ADR.
- Service framework (net/http vs Connect vs gRPC) is deferred to the
  service-skeleton task in FLEX-WP-0002 T07.

## Related

- ADR-0002: Rego-in-Markdown policy format.
- ADR-0003: Topaz-aligned MVP.
- State Hub recorded decision: "Implementation language for KeyCape: Go"
  (resolved 2026-03-25).