Architecture Decision Records
Architecture Decision Records (ADRs)
This index lists GPUWorks architecture decisions, their status, and which decisions supersede them. Moved-out decisions retain their original numbers.
| Number | Decision | Date | Status |
|---|---|---|---|
| 0001 | Verify images by pulling a tag and comparing afterward, instead of using immutable digest references | 2026-08-22 | All verification provisions retired (the three-state image ID mechanism was removed on 2026-08-23; offline package blob comparison was removed with offline import on 2026-10-08); mandatory tags in refs remain in effect |
| 0002 | RunSpec overrides use field-level editing with whole-instance snapshot storage | 2026-08-22 | Moved Out (RunSpec was removed; see 0020 and 0022 for the principles) |
| 0003 | Embed the benchmark engine in the binary without external tools or containers | 2026-08-23 | In Effect |
| 0004 | An empty revision follows the platform's default branch, without filling in main | 2026-08-23 | In Effect |
| 0005 | Blueprints are first-class entities with two levels (blueprint × spec) and structurally equivalent manifest distribution | 2026-08-24 | Moved Out (superseded by 0007 and 0009) |
| 0006 | Store encrypted SSH credentials for out-of-band recovery | 2026-08-24 | In Effect; authentication material provisions revised by 0035 |
| 0007 | Inference template schema v2: renaming, images moved to the chip level, dictionary-based parameter reverse parsing, and evidence tiers | 2026-08-28 | Moved Out (superseded by 0009 and 0020) |
| 0008 | Convention-based quantization gating by chip class and catalog, with matching by class instead of explicit names | 2026-08-30 | Moved Out (superseded by 0009) |
| 0009 | A flat spec catalog replaces the five-layer evidence model | 2026-09-01 | In Effect; see 0020 for the internal split of the args column |
| 0010 | Use an executable, multi-file inference catalog package alongside the model | 2026-09-01 | Image immutability provision superseded by 0017; ImageDefaults layer removed by 0031 |
| 0011 | Isolate spec identities for the same original model by source | 2026-09-01 | In Effect |
| 0012 | PublicURL resolution order | 2026-08-23 | Superseded by 0025 |
| 0013 | Assemble container commands using three command modes based on image source | 2026-08-24 | All three modes remain in effect; manual is the sole exception path under 0020; source-based defaults superseded by 0022 and 0031 |
| 0014 | Partition capability is ready when the container-level probe passes | 2026-08-25 | In Effect |
| 0015 | Four-layer Playground request composition (protocol definition × catalog declaration × engine discovery × user overrides) and expert mode | 2026-09-05 | Accepted |
| 0016 | Model kinds are projections of operation and input modalities | 2026-09-06 | Moved Out (the kinds mechanism was removed) |
| 0017 | Embedded catalog images use tag-only references without requiring immutable digest references | 2026-09-07 | Accepted |
| 0018 | Make deployment sources explicit; the server validates without replacing user selections | 2026-09-07 | Accepted; explicit deployment acquisition superseded by 0048 |
| 0019 | The image catalog maintains only runtime facts; compatibility uses ranking and warnings | 2026-09-14 | Accepted |
| 0020 | A single source of truth for launch configuration: one dictionary-based parameter set, with command mode as the sole special path | 2026-09-15 | Accepted; amended 2026-11-02: template values the dictionary cannot read pass through with a warning instead of blocking the import |
| 0021 | Separate platform parameters from engine parameters; displayed commands must work when copied | 2026-09-16 | Accepted |
| 0022 | Templates and explicit selections own deployment launch configuration; images no longer provide an editable defaults layer | 2026-09-19 | Accepted; existing-deployment compatibility and the launch_contract marker superseded by 0031 |
| 0023 | The multi-replica inference gateway load balances by default and retries connection-level failures | 2026-09-23 | Accepted |
| 0024 | A disconnected data-plane lane never falls back to the control plane; wait for reconnection or return a retryable 503 | 2026-09-24 | Accepted; supersedes artifacts/archive/2026-09-08-tunnel-bandwidth/plan.md §3.2 |
| 0025 | The server does not manage its own external address; the party obtaining it supplies the address | 2026-09-27 | Accepted; supersedes 0012 |
| 0026 | Centralize network decisions in a pure leaf package and one service, injecting the network catalog through an interface | 2026-09-27 | Accepted |
| 0027 | Infer RDMA networks with node pinning instead of selectors; test tools prefer host tools, then embedded tools | 2026-09-28 | Accepted; revises decision 1 of 0030 |
| 0028 | A PD-disaggregated deployment is one deployment with instance roles; the existing gateway orchestrates both phases | 2026-09-29 | Accepted |
| 0029 | Reconcile every deployment as units: role → unit → rank, with shared retry, whole-group failure, and draining behavior | 2026-09-29 | Accepted |
| 0030 | Node networks are attachable objects; resolve each node and role on demand | 2026-09-25 | Accepted; originally 0024, renumbered to 0030 on 2026-09-30 due to a collision with data-plane lane ADR 0024 |
| 0031 | The image catalog carries no launch configuration; all deployments use the same launch semantics | 2026-10-01 | Accepted; supersedes the existing-deployment compatibility provisions of 0022 |
| 0032 | Persist facts in typed columns by default; JSON columns are opaque snapshots read and written as a whole | 2026-10-01 | Accepted |
| 0033 | Lifecycle operations act on replicas: draining state, rolling restarts by default, multiple multi-node replicas, and sleep intent on instances | 2026-09-30 | Accepted |
| 0034 | Model files belong to storages; model files on shared storage have only one record | 2026-10-02 | Accepted; changes the acquisition candidates in 0018 |
| 0035 | The server holds a platform SSH key pair and prefers it for out-of-band recovery; node passwords are no longer stored | 2026-10-03 | Accepted; changes authentication material in 0006 |
| 0036 | The template owns the callable command line; platform facts are provided as template variables | 2026-10-08 | Accepted |
| 0037 | Playground HTML previews run in an opaque-origin sandbox; networking is blocked by default and enabled through an administrator switch | 2026-10-08 | Accepted |
| 0038 | Inference templates declare image sources; system rewrite rules apply only to system images | 2026-10-08 | Accepted; adds image candidate sources to 0018; decision 5 superseded by 0048 |
| 0039 | Inference metric sources have layers; only the server resolves observation configuration, which updates in place at runtime | 2026-10-10 | Accepted |
| 0040 | Server upgrades and the official catalog use a multi-source release channel with a signed index; the most recently imported official catalog takes effect | 2026-10-11 | Accepted |
| 0041 | Platform API tokens and the MCP service share one credential type | 2026-10-11 | Accepted |
| 0042 | The gateway requests usage from vLLM / SGLang for streaming requests and strips the extra chunk; per-request records go to a separate ux.db | 2026-10-12 | Accepted; revises D4 of the inference metrics plan |
| 0043 | Probe requests determine service health; monitoring no longer draws conclusions from rules and thresholds | 2026-10-13 | Accepted |
| 0044 | Engines on Mac nodes run as host processes; images are darwin environment packages | 2026-10-14 | Accepted |
| 0045 | The public endpoint connector runs in a separate connector service, independently of server startup and shutdown | 2026-10-14 | Accepted |
| 0046 | The gateway creates a W3C trace context for each request, writes its trace id to the request record, and exports per-request records through OTLP | 2026-10-15 | Accepted; decision 3 revised by 0047 |
| 0047 | The gateway directly measures and separately reports the prefill phase of PD requests; KV transfer provides aggregate statistics only | 2026-10-15 | Accepted; revises decision 3 of 0046 |
| 0048 | Node pull settings determine where images are pulled from; deployments no longer select sources | 2026-10-16 | Accepted; supersedes explicit deployment acquisition in 0018 and decision 5 of 0038 |
| 0049 | While the public endpoint is enabled, the server trusts forwarding headers from the same host | 2026-10-17 | Accepted; supplements 0045 |
| 0050 | Source rules also cover model sites; proxies are configured by label, and credentials are unified by host | 2026-10-17 | Accepted; supersedes the item deferring model download rules in the “Consequences” of 0048 |
| 0051 | Store agent launch configuration in <state>/gpuworks-agent.conf; every launch method uses only run --state | 2026-10-19 | Accepted |
| 0052 | Kubernetes is both a node source and a runtime; cards are borrowed from the kubelet on demand | 2026-10-19 | Accepted |
| 0053 | Browse the entire storage, but write only to files/ and .gpuworks/apps/; stage uploads and report success only after completion; package downloads while streaming | 2026-10-21 | Accepted |
| 0054 | The user experience improvement program is enabled by default and sends daily reports to a hosted log service; publisher notices use the signed release channel | 2026-10-22 | Accepted; revises the switch tradeoff added to 0040 |
| 0055 | Store long-term statistics separately from raw observations: one row per object, accumulation during ingestion, and incremental writes; token usage in the main database and other statistics in stats.db | 2026-10-22 | Accepted |
| 0056 | Connections for runveil image pulls adapt through a per-registry-host budget, and slow connections are judged relative to their siblings | 2026-10-27 | Accepted |
| 0057 | The platform places multi-node and PD units automatically by writing the pick back into the units | 2026-10-28 | Accepted; extends the placement of 0028 and 0029 |
| 0058 | The scheduling center only carries out orders operators gave in advance, sleep releases capacity down to a per-instance residue, and node-loss rescheduling rewrites the placement the way an operator's edit would | 2026-10-25 | Accepted; supplements 0033; the “no preemption, no held requests” part of decision 1 is changed by 0059 |
| 0059 | Share GPUs by service level: the gateway holds requests while a wake happens, and the residency arbiter preempts by one yield rule | 2026-10-28 | Accepted; changes 0058; amended 2026-10-29: the yield policy replaces service level and idle sleep; amended again: the yield policy is the only choice, presets and auto sleep are gone; amended 2026-10-29: a new deployment waits for cards as well |
| 0060 | A card's health is judged only from hardware facts; event-type errors need evidence of recovery, and operator decisions come first | 2026-11-01 | Accepted; supplements 0043 |
| 0061 | Inference spec display names are written by hand in the catalog, no longer assembled by the frontend | 2026-11-02 | Accepted; changes 0009 |
| 0062 | Template components follow the primary model into its shared storage | 2026-11-11 | Accepted; supplements 0034 |
| 0063 | For managed clusters connected from a cloud account, the server applies the connect manifest after user confirmation using a freshly issued short-lived kubeconfig, and stores no credentials | 2026-10-22 | Accepted |
| 0064 | Metric and log batches ride a telemetry stream on the data lane (enabled when the server advertises the capability); logs are buffered on the agent within a bound and sent after a reconnect | 2026-11-13 | Accepted; supplements 0024 |
| 0065 | Official inference catalog packages are read tolerantly per model and spec: what cannot be read is skipped and reported, existing records stay as they are; a user's own import stays strict | 2026-11-15 | Accepted; supplements 0040 and 0010 |
| 0066 | Agent state is grouped by owner and lifetime, and the composition root only wires | 2026-11-15 | Accepted |
Note: 0012–0014 originally collided with 0004, 0004, and 0006, respectively, and were renumbered by creation order during cleanup on 2026-09-03. Old numbers in historical commit messages and MR descriptions are no longer accurate. Similarly, the original 0024 (node network objects) was renumbered to 0030 on 2026-09-30 because it collided with the data-plane lane's 0024. Earlier references to “ADR 0024” meaning network objects were updated accordingly; “ADR 0024” in CLAUDE.md and todo.md refers to the data-plane lane.
Was this page helpful?