Skip to main content

Architecture Decision Records (ADRs)

This index lists GPUWorks architecture decisions, their status, and which decisions supersede them. Moved-out decisions retain their original numbers.

NumberDecisionDateStatus
0001Verify images by pulling a tag and comparing afterward, instead of using immutable digest references2026-08-22All 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
0002RunSpec overrides use field-level editing with whole-instance snapshot storage2026-08-22Moved Out (RunSpec was removed; see 0020 and 0022 for the principles)
0003Embed the benchmark engine in the binary without external tools or containers2026-08-23In Effect
0004An empty revision follows the platform's default branch, without filling in main2026-08-23In Effect
0005Blueprints are first-class entities with two levels (blueprint × spec) and structurally equivalent manifest distribution2026-08-24Moved Out (superseded by 0007 and 0009)
0006Store encrypted SSH credentials for out-of-band recovery2026-08-24In Effect; authentication material provisions revised by 0035
0007Inference template schema v2: renaming, images moved to the chip level, dictionary-based parameter reverse parsing, and evidence tiers2026-08-28Moved Out (superseded by 0009 and 0020)
0008Convention-based quantization gating by chip class and catalog, with matching by class instead of explicit names2026-08-30Moved Out (superseded by 0009)
0009A flat spec catalog replaces the five-layer evidence model2026-09-01In Effect; see 0020 for the internal split of the args column
0010Use an executable, multi-file inference catalog package alongside the model2026-09-01Image immutability provision superseded by 0017; ImageDefaults layer removed by 0031
0011Isolate spec identities for the same original model by source2026-09-01In Effect
0012PublicURL resolution order2026-08-23Superseded by 0025
0013Assemble container commands using three command modes based on image source2026-08-24All three modes remain in effect; manual is the sole exception path under 0020; source-based defaults superseded by 0022 and 0031
0014Partition capability is ready when the container-level probe passes2026-08-25In Effect
0015Four-layer Playground request composition (protocol definition × catalog declaration × engine discovery × user overrides) and expert mode2026-09-05Accepted
0016Model kinds are projections of operation and input modalities2026-09-06Moved Out (the kinds mechanism was removed)
0017Embedded catalog images use tag-only references without requiring immutable digest references2026-09-07Accepted
0018Make deployment sources explicit; the server validates without replacing user selections2026-09-07Accepted; explicit deployment acquisition superseded by 0048
0019The image catalog maintains only runtime facts; compatibility uses ranking and warnings2026-09-14Accepted
0020A single source of truth for launch configuration: one dictionary-based parameter set, with command mode as the sole special path2026-09-15Accepted; amended 2026-11-02: template values the dictionary cannot read pass through with a warning instead of blocking the import
0021Separate platform parameters from engine parameters; displayed commands must work when copied2026-09-16Accepted
0022Templates and explicit selections own deployment launch configuration; images no longer provide an editable defaults layer2026-09-19Accepted; existing-deployment compatibility and the launch_contract marker superseded by 0031
0023The multi-replica inference gateway load balances by default and retries connection-level failures2026-09-23Accepted
0024A disconnected data-plane lane never falls back to the control plane; wait for reconnection or return a retryable 5032026-09-24Accepted; supersedes artifacts/archive/2026-09-08-tunnel-bandwidth/plan.md §3.2
0025The server does not manage its own external address; the party obtaining it supplies the address2026-09-27Accepted; supersedes 0012
0026Centralize network decisions in a pure leaf package and one service, injecting the network catalog through an interface2026-09-27Accepted
0027Infer RDMA networks with node pinning instead of selectors; test tools prefer host tools, then embedded tools2026-09-28Accepted; revises decision 1 of 0030
0028A PD-disaggregated deployment is one deployment with instance roles; the existing gateway orchestrates both phases2026-09-29Accepted
0029Reconcile every deployment as units: role → unit → rank, with shared retry, whole-group failure, and draining behavior2026-09-29Accepted
0030Node networks are attachable objects; resolve each node and role on demand2026-09-25Accepted; originally 0024, renumbered to 0030 on 2026-09-30 due to a collision with data-plane lane ADR 0024
0031The image catalog carries no launch configuration; all deployments use the same launch semantics2026-10-01Accepted; supersedes the existing-deployment compatibility provisions of 0022
0032Persist facts in typed columns by default; JSON columns are opaque snapshots read and written as a whole2026-10-01Accepted
0033Lifecycle operations act on replicas: draining state, rolling restarts by default, multiple multi-node replicas, and sleep intent on instances2026-09-30Accepted
0034Model files belong to storages; model files on shared storage have only one record2026-10-02Accepted; changes the acquisition candidates in 0018
0035The server holds a platform SSH key pair and prefers it for out-of-band recovery; node passwords are no longer stored2026-10-03Accepted; changes authentication material in 0006
0036The template owns the callable command line; platform facts are provided as template variables2026-10-08Accepted
0037Playground HTML previews run in an opaque-origin sandbox; networking is blocked by default and enabled through an administrator switch2026-10-08Accepted
0038Inference templates declare image sources; system rewrite rules apply only to system images2026-10-08Accepted; adds image candidate sources to 0018; decision 5 superseded by 0048
0039Inference metric sources have layers; only the server resolves observation configuration, which updates in place at runtime2026-10-10Accepted
0040Server upgrades and the official catalog use a multi-source release channel with a signed index; the most recently imported official catalog takes effect2026-10-11Accepted
0041Platform API tokens and the MCP service share one credential type2026-10-11Accepted
0042The gateway requests usage from vLLM / SGLang for streaming requests and strips the extra chunk; per-request records go to a separate ux.db2026-10-12Accepted; revises D4 of the inference metrics plan
0043Probe requests determine service health; monitoring no longer draws conclusions from rules and thresholds2026-10-13Accepted
0044Engines on Mac nodes run as host processes; images are darwin environment packages2026-10-14Accepted
0045The public endpoint connector runs in a separate connector service, independently of server startup and shutdown2026-10-14Accepted
0046The gateway creates a W3C trace context for each request, writes its trace id to the request record, and exports per-request records through OTLP2026-10-15Accepted; decision 3 revised by 0047
0047The gateway directly measures and separately reports the prefill phase of PD requests; KV transfer provides aggregate statistics only2026-10-15Accepted; revises decision 3 of 0046
0048Node pull settings determine where images are pulled from; deployments no longer select sources2026-10-16Accepted; supersedes explicit deployment acquisition in 0018 and decision 5 of 0038
0049While the public endpoint is enabled, the server trusts forwarding headers from the same host2026-10-17Accepted; supplements 0045
0050Source rules also cover model sites; proxies are configured by label, and credentials are unified by host2026-10-17Accepted; supersedes the item deferring model download rules in the “Consequences” of 0048
0051Store agent launch configuration in <state>/gpuworks-agent.conf; every launch method uses only run --state2026-10-19Accepted
0052Kubernetes is both a node source and a runtime; cards are borrowed from the kubelet on demand2026-10-19Accepted
0053Browse the entire storage, but write only to files/ and .gpuworks/apps/; stage uploads and report success only after completion; package downloads while streaming2026-10-21Accepted
0054The user experience improvement program is enabled by default and sends daily reports to a hosted log service; publisher notices use the signed release channel2026-10-22Accepted; revises the switch tradeoff added to 0040
0055Store 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.db2026-10-22Accepted
0056Connections for runveil image pulls adapt through a per-registry-host budget, and slow connections are judged relative to their siblings2026-10-27Accepted
0057The platform places multi-node and PD units automatically by writing the pick back into the units2026-10-28Accepted; extends the placement of 0028 and 0029
0058The 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 would2026-10-25Accepted; supplements 0033; the “no preemption, no held requests” part of decision 1 is changed by 0059
0059Share GPUs by service level: the gateway holds requests while a wake happens, and the residency arbiter preempts by one yield rule2026-10-28Accepted; 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
0060A card's health is judged only from hardware facts; event-type errors need evidence of recovery, and operator decisions come first2026-11-01Accepted; supplements 0043
0061Inference spec display names are written by hand in the catalog, no longer assembled by the frontend2026-11-02Accepted; changes 0009
0062Template components follow the primary model into its shared storage2026-11-11Accepted; supplements 0034
0063For 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 credentials2026-10-22Accepted
0064Metric 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 reconnect2026-11-13Accepted; supplements 0024
0065Official 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 strict2026-11-15Accepted; supplements 0040 and 0010
0066Agent state is grouped by owner and lifetime, and the composition root only wires2026-11-15Accepted

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?