Skip to content

Repository layout

Implemented

Source: AGENTS.md · top-level tree

Top-level tree

GPUasService/
├── AGENTS.md           — project rules (this is the entry doc)
├── CLAUDE.md           — symlinks to AGENTS.md
├── README.md           — quick start
├── Makefile            — every target you'll use
├── go.mod / go.sum
├── cmd/                — service entrypoints (13 binaries)
├── packages/
│   ├── shared/         — cross-cutting libraries
│   ├── services/       — 12 domain service packages
│   └── web/            — Next.js frontend
├── pkg/                — public Go utilities
├── sdk/python/         — generated Python SDK
├── infra/              — terraform / k8s manifests (where applicable)
├── scripts/
│   ├── seed.sql        — bootstrap reference data
│   ├── codegen.sh      — OpenAPI → Go + TS types
│   └── ci/             — reusable CI gate scripts
├── build/              — build artifacts
├── doc/                — canonical product/arch/api/governance/ops docs
└── tmp-ux/             — temporary review portal (this site lives here)

cmd/ — 13 binaries

flowchart LR
    subgraph entry[Entrypoints]
        API[cmd/api]
        CLI[cmd/gpuaas-cli]
        TG[cmd/terminal-gateway]
        NLG[cmd/node-log-gateway]
    end
    subgraph workers[Workers]
        PW[cmd/provisioning-worker]
        BW[cmd/billing-worker]
        WW[cmd/webhook-worker]
        ARW[cmd/app-runtime-worker]
        NR[cmd/notification-relay]
        OR[cmd/outbox-relay]
    end
    subgraph host[Fleet]
        NA[cmd/node-agent]
    end
    subgraph appctl[App controllers]
        SLURM[cmd/slurm-reference-controller]
        RKE2[cmd/rke2-self-managed-controller]
    end

Full table with line counts → Runtime binaries.

packages/services/ — 12 domain packages

Package Owns
auth OIDC, JWT, sessions
inventory SKUs, nodes, slots, OS images
provisioning Allocations, claims, Temporal activities
billing Usage, ledger, balance, force-release
payments Stripe checkout, webhook, refunds
terminal WS sessions, token validation
appruntime App-instance lifecycle
storage Object-storage CRUD
admin Audit, refunds, privileged ops
notification WS + email fan-out
releases SSH key release
maas Bare-metal MAAS facade

Full responsibility map → Service packages.

packages/shared/ — cross-cutting

Package Purpose
errors ErrorResponse envelope + ErrCode catalog
events NATS client + envelope types
middleware Auth, rate-limit, sanitize, OTel
outbox Outbox claim/publish/retry
policy PolicyClient (no hardcoded constants)
pki CAClient interface (step-ca today, Vault later)
db pgx wrappers, retry, tx helpers
rdb Redis helpers
vault Vault KV reader
readcache Read-model cache
storagepath Path-safety enforcement
authz Scope-aware role/policy decisions
buildinfo Build version stamp
gen/openapigen Generated OpenAPI types — only at HTTP boundary

doc/ — canonical documentation

doc/
├── README.md                — start here
├── Implementation_Roadmap.md
├── Governance_Overview.md
├── Execution_Progress.md
├── Phase_Readiness_Tracker.md
├── Release_Go_NoGo_Checklist.md
├── api/
│   ├── openapi.draft.yaml   — 33,132 lines (authoritative REST)
│   ├── asyncapi.draft.yaml  — 2,296 lines (authoritative events)
│   ├── openapi/             — domain authoring manifests
│   ├── asyncapi/            — domain authoring manifests
│   └── API_Surface.md       — human catalog
├── architecture/            — 135 architecture docs
├── product/                 — 56 product docs (PRD, UX, mocks)
├── governance/              — 50+ governance docs
├── operations/              — runbooks, baselines, local-dev
├── security/                — node↔control mTLS audit
└── rca/                     — 3 documented incidents

scripts/ci/ — gate scripts

Host-agnostic CI scripts. Both GitLab and GitHub Actions YAML are thin wrappers over these:

Script Enforces
bootstrap_ci_toolchain.sh Toolchain install
backend_build_and_tests.sh go build + unit + integration
frontend_build_and_tests.sh Web build + tests
frontend_e2e*.sh Playwright E2E
contracts_validate.sh OpenAPI/AsyncAPI lint + structure
contracts_breaking_change.sh Diff against previous spec
audit_mandatory_guard.sh Privileged mutations write audit_logs
audit_presence_guard.sh Audit rows present in integration tests
canonical_error_guard.sh Errors use catalog codes only
observability_trace_gate.sh Tracing middleware wired everywhere

→ CI gates for the full list.

Where to look next