Architecture decision records
ADRs record the significant architectural decisions behind GPUlayer: what was decided, why, which alternatives were rejected, and what the decision costs us.
Status values:
- Accepted (milestone 1): implemented in the current code and covered by tests.
- Proposed: a direction under evaluation. It is not policy and must not be described as available.
- Superseded by ADR-XXXX: replaced; kept for history.
Several ADRs are split: the implemented part is accepted and named follow-ups stay proposed. Each ADR says which part is which.
Index
| # | Title | Status | Summary |
|---|---|---|---|
| 0001 | Control plane and deployment model | Accepted (milestone 1); hosted mode Proposed | One modular-monolith ControlPlane, used embedded (SQLite file) or served over authenticated HTTP. |
| 0002 | Job contracts and packaging | Accepted (milestone 1); container images Proposed | Versioned pydantic contracts; code ships as content-addressed source bundles; functions take JSON args, never pickle. |
| 0003 | Worker protocol and authentication | Accepted (milestone 1); mTLS/OIDC Proposed | HTTP+JSON polling; separate client, join, per-worker session and single-use instance tokens; TLS required off loopback. |
| 0004 | Scheduling and placement policy | Accepted (milestone 1) | A pure, deterministic, explainable scheduler with gang scheduling, explicit fallback and reservations. |
| 0005 | GPU capabilities and runtime profiles | Accepted (milestone 1); runtime profiles Proposed | Capability model, isolated torch probe, explicit support matrix. |
| 0006 | Apple Metal / MPS boundaries | Accepted (milestone 1) | MPS supports independent jobs only; unified memory is explicit; distributed MPS is unsupported. |
| 0007 | Distributed launch and rendezvous | Accepted (milestone 1, single host); multi-machine Proposed | torchrun with static rendezvous published by the rank-0 worker; fail-fast; no distributed retry. |
| 0008 | Storage and artifact management | Accepted (milestone 1); shared DB/object store Proposed | SQLite (WAL) metadata plus a local content-addressed artifact store behind interfaces. |
| 0009 | Security and workload isolation | Accepted (milestone 1) for trusted single-team use | Process groups, an env allowlist and secret references with log redaction. This is not a sandbox. |
| 0010 | Provider adapters and provisioning | Accepted (interface + FakeProvider); first real provider Proposed | Offers are expressed as capability templates; provisioning flow is tested only against a simulated provider. |
| 0011 | Cost accounting and retry semantics | Accepted (milestone 1) | Estimates and charges are distinct record kinds; delivery is at-least-once; retries are opt-in. |
| 0012 | Licensing and project governance | Proposed | Compares Apache-2.0, MIT, MPL-2.0 and AGPL-3.0. Undecided. |
| 0013 | Website and documentation stack | Proposed | Compares MkDocs-Material, Docusaurus and Astro Starlight. Undecided. |
| 0014 | PyTorch integration and a training API | Accepted (milestone 2, first slice) | The first framework integration: launcher, runtime helpers for devices/DDP/precision, and a small Module + Trainer API; code ships as source. |
| 0015 | A workload-agnostic GPU layer, with framework integrations on top | Accepted (milestone 2) | Any command or Python library is a workload; GPUs are usable when their driver is; frameworks are reported and required explicitly. |
| 0017 | Distribution: install script, Docker images, then packages | Accepted (milestone 2) | `curl ... install.sh |
| 0016 | Speed, parallelism and job distribution as primary goals | Accepted (milestone 2) | No fixed sleeps on hot paths (long-poll dispatch and job waits), no per-step device syncs, measured changes, and a roadmap for concurrent tasks per worker and topology-aware placement. |
Template
markdown
# ADR-NNNN: Title- **Status:** Proposed | Accepted (milestone N) | Superseded by ADR-XXXX- **Date:** YYYY-MM-DD## ContextThe problem, the constraints and the forces involved.## DecisionWhat we do. Name the modules that implement it.## Alternatives consideredEach option and why it was not chosen.## Consequences and trade-offsWhat gets easier, what gets harder, and known gaps.## Security and operational implications## Follow-upConcrete next steps, each with the condition that would change this decision.