Design Decisions
This section is the platform’s decision log: the significant, deliberate choices that shaped how Orbit is built, deployed, and operated. Each page follows a light ADR format — Context (the forces at play), Decision (what was decided, precisely), Consequences (what it bought and what it costs), and Evidence (where in the repository the decision is visible).
The log is mined from the platform’s memory records (memory/*.md) and design
documents (designs/*.md), which capture decisions as they were made — dates
below are as recorded there. Where a record gives only a month, or no date at
all, the status line on the decision page says so rather than inventing one.
A recurring theme runs through the log: single writer, many readers. The per-solution agent is the only process that mutates a solution’s repositories (one replica, serial tasks, per-request branches); everything else — the reader webapp, Mission Control, Aurora — observes over HTTP. Several decisions below are downstream of that stance.
The decisions
| Id | Title | Date | Area | Decision in one line |
|---|---|---|---|---|
| ADR-001 | Azure Container Apps as the sole deployment target | 2026-07-02 | Deployment | Aurora and all per-solution stacks run on ACA via managed identity; the Vercel path was retired and deleted. |
| ADR-002 | Shared images per release, built from immutable git tags | 2026-06 (month as recorded) | Deployment | Container images are shared across solutions and built server-side from per-component git tags; per-solution state is only apps, shares, and env. |
| ADR-003 | Two external apps per solution; the agent is internal-only | 2026-06-30 (revised 2026-07-01, 2026-07-03) | Deployment | Reader and Mission Control are external ACA apps with per-solution subdomains; since 2026-07-03 the agent has internal ingress only, reached in-env at http://agent-<h>, with Mission Control’s browser traffic going through a same-origin /agent proxy. |
| ADR-004 | Single-replica writer with keep-alive-guarded scale-to-zero | 2026-07-03 | Deployment | The agent is capped at one replica and scales to zero, kept alive mid-task by a self-directed long-poll rather than a queue + KEDA. |
| ADR-005 | Consolidate the aurora repo into the orbit platform repo | 2026-07-02 | Repositories | One repo holds the whole platform — apps, Aurora, services, infrastructure, and releases. |
| ADR-006 | The three-repo split for solutions | 2026-05 (in progress as of 2026-05-31) | Repositories | A solution spans a global methodology repo, a customer repo, and a MaxQLabs-only internal repo that tracks .orbit/ as first-class history. |
| ADR-007 | Agent-served solution data | 2026-07-02 | Data | The agent is the sole owner of the solution mounts and serves the tree over HTTP; the reader webapp is mount-free and caches per (instance, version). |
| ADR-008 | Portfolio registry as three microservices on Cosmos-shaped Postgres | 2026-07-02 (live 2026-07-03) | Data | Customer/Tenant/Solution are three Hono services over JSONB records with If-Match concurrency and Entra-only Postgres auth, fronted by the aurora-webapp BFF. |
| ADR-009 | Release records reference artifacts, never bytes | not dated in the record | Releases | releases/ stores per-component release.yaml records pinning a git tag and an ACR image reference; components version independently. |
| ADR-010 | Strictly serial task processing with per-request git branches | 2026-05-30 | Agents | One process-wide TaskProcessor runs tasks one at a time across all requests and owns the branch-per-request, commit-per-task, merge-on-success lifecycle. |
| ADR-011 | Vendored per-stage methodology digest in cached system prompts | 2026-06-22/23 (PoC) | Agents | A generated ~8.2K-token per-stage digest is injected into cached system prompts instead of every agent re-reading ~74K tokens of methodology. |
| ADR-012 | Native octokit solution tools, gated by conversational confirmation | not dated in the record | Agents | The in-product agent chat creates solutions through a native GitHub-API service (no gh/git subprocess), behind a typed-confirm gate plus a canUseTool hard guard. |
| ADR-013 | Fork-with-upstream solution provisioning; the LLM is the glue | 2026-06 (month as recorded) | Solutions | New solutions are true GitHub forks (upstream link kept for template sync); deterministic work lives in scripts, skills only orchestrate. |
| ADR-014 | The editorial broadsheet design language | 2026-06-09/10 | UI | The webapp is light-first warm paper with a graphite dark companion, one accent color, token-only theming, and banned glass/glow/gradient idioms. |
| ADR-015 | TypeScript is canonical for the solution plane | 2026-07-05 | Deployment | Per-solution deployment lives once in the @maxq/orbit-deploy engine (steps with plan/apply/verify under scenarios, driven by agent tools, CLI, and the creation hook); bash keeps only the human-run platform singletons, and provision-solution.sh is legacy until the engine is live-proven. |
Reading the log
- Status is
Acceptedunless noted; one entry (ADR-011) is an accepted proof of concept with rollout still in progress. - Areas group thematically: Deployment, Repositories, Data, Releases, Agents, Solutions, UI. The sidebar follows this grouping.
- Several decisions explicitly supersede earlier ones — e.g. the internal
repo tracking
.orbit/(ADR-006) supersedes the gitignore approach noted in ADR-010, the busy keep-alive (ADR-004) supersedes an earlier queue + KEDA plan, and ADR-003’s 2026-07-03 revision (agent internal-only) supersedes its own earlier “the agent is public by design” stance. The pages note this so future work does not re-litigate settled questions or “finish” retired mechanisms. - Evidence paths are relative to the platform repo root
(
maxq-labs-orbit-platform/orbit) unless stated otherwise.