Architecture

The service turns a validated build specification into a source workspace, compiler execution, and published artifacts.

flowchart LR
  UI[Browser or legacy CLI] --> API[Go API]
  API --> DB[(PostgreSQL)]
  API --> Queue[Job queue]
  Queue --> Source[Source preparation]
  Source --> Runner[Docker runner / SCons]
  Runner --> Artifacts[(Artifact storage)]
  UI --> Gateway[Private download gateway]
  Gateway --> Artifacts
  API --> Redis[(Public verification / enforcement Redis)]
  Gateway --> Redis

Components

Component	Responsibility
cmd/gbb	Remote CLI and local in-process compilation
cmd/gbb-server	API, frontend, migrations, queue, maintenance
cmd/gbb-gateway	Private artifact delivery, without build or migration duties
internal/spec	Build specification, options, validation, normalization
internal/registry, internal/catalog	Module resolution and catalog snapshots
internal/source	Repository mirrors and assembled engine workspace
internal/runner	Docker container lifecycle and SCons arguments
internal/job	Queue, leases, statuses, logs, cancellation
internal/store	PostgreSQL persistence and embedded migrations
internal/artifact	Filesystem and S3 artifact storage
internal/human, internal/enforcement	Browser verification and shared abuse controls
internal/execution	Durable execution contracts and Kubernetes adapter work

Build lifecycle

Admission validates a request and reserves queue capacity. Public admission records browser ownership, quota accounting, and an immutable catalog snapshot transactionally. Preparation resolves the selected repositories, records exact source commits, and grafts module directories into an engine workspace.

The Docker runner mounts that workspace and starts the platform toolchain image. The image entrypoint owns compiler-specific arguments; the service owns validated build-spec arguments. The compiler container runs without network access, so cloning and repository authentication happen during preparation.

Packaging records artifacts and checksums in storage and publishes metadata with the job outcome. Only listed artifacts from successful jobs are eligible for public delivery. Logs have separate private diagnostic and public progress paths.

Persistence and retries

PostgreSQL holds catalog, jobs, leases, public events, ownership, quotas, audit data, and durable execution records. Worker heartbeats renew ownership. Expired leases permit bounded recovery attempts; a worker that has lost ownership must not publish a later outcome.

Catalog snapshots prevent subsequent administrative edits from changing admitted public selections. Persisted source pins allow retries to reuse commits. These protections do not alone establish fully reproducible binaries: production toolchain digest pinning and the remaining execution integration still matter.

Redis holds expiring verification state, request buckets, stream/transfer leases, and the shared ban index. It is not the durable source of ban history; PostgreSQL supports reconstruction. Protected actions fail closed when required enforcement state is unavailable.

Kubernetes execution boundary

The Kubernetes adapter models preparation, compilation, and publication as separate Jobs sharing a PVC. It checks plan identity, resource UIDs, phase ordering, cancellation, and cleanup. It is not yet connected to the running queue. Do not assume compiler NetworkPolicies from that adapter protect the current Docker deployment.

See Kubernetes execution, durable execution storage, and immutable configuration.