Architecture

The Orbit platform is MaxQ Labs’ implementation of the Trajectory methodology: it takes a software system from as-is through R2B (Refactor-to-Be) to to-be, producing a machine-readable solution tree (currently Trajectory v1.8) as it goes. Everything in the platform is organised around that tree — some components read it, exactly one component per solution writes it, and one application manages the whole fleet of solutions from above.

This page gives the big picture: the four layers, the component inventory, the single-writer principle, and the three-repo split. The sibling pages in this section carry the details — see Where to go next.

The four layers

The platform decomposes into four layers, from the data outward:

Each layer has exactly one manager:

• Aurora manages the portfolio — every customer, tenant, and solution (MaxQ-internal).
• A tenant’s Orbit app manages that tenant (customer-facing).
• Each solution’s agent authors that solution — the single writer over its repo pair.

Component inventory

All application code lives under implementation/ in the platform repo. Each app follows the codebase/ + dockerfiles/ convention.

Outside implementation/, the platform repo also holds:

• infrastructure/local/ — the one docker-compose dev stack for all apps.
• infrastructure/azure/ — ACA/ACR provisioning: the singleton aurora app plus the per-solution Orbit stacks. Azure is the sole deployment target.
• releases/ — the per-component release registry: one directory per component, one release.yaml per v<semver>.
• designs/ — design documents; solution-definition/ — the repo dogfoods Trajectory on itself (solution id orbit, v1.8).

The big picture

Aurora sits above many per-solution stacks. Each stack is the same trio — reader, agent, Mission Control — arranged over that solution’s repositories, with the agent as the only component that touches the repos.

Key relationships, reading the diagram top to bottom:

• Aurora → stacks. Aurora operates across solutions: it correlates live GitHub data with the portfolio registry, creates new solutions by forking the template repos, and provisions a running Orbit stack per solution on Azure Container Apps.
• Readers → agent. Neither the viewer nor Mission Control mounts the solution repositories. The agent holds the loaded solution tree in memory and serves it over HTTP (/solution/version, /solution/tree, /sources/*), pushing a solution.updated server-sent event when it changes.
• Agent → repos. Only the agent reads and writes the customer and internal repositories.

The single-writer principle

Every solution has exactly one writer: its Orbit agent.

• The agent is the sole owner of the solution repo mounts — the customer repo (mounted at /repo, read-write) and the internal repo (mounted at /repo-internal). Since the 2026-07-02 refactor, the read-only viewer has no repo mount at all; it fetches everything from the agent over HTTP.
• The agent executes worker tasks strictly one at a time across all requests, and owns a disciplined git lifecycle: a branch per request, a commit per task, and a merge to the base branch on success.
• Because the agent is the only process that mutates the tree, it can hold the authoritative in-memory model and version it (a per-boot instance plus a monotonic version), which is what makes cheap HTTP serving and live refresh possible for the readers.

The practical consequence: there are no write conflicts to reconcile, no distributed locking, and the viewer can never corrupt a solution — it is a lens, not a hand.

The three-repo split at a glance

A Trajectory solution is not one repository. It is spread across three, each with a distinct audience and lifecycle:

New solutions are created by forking two template repositories — solution-template (customer) and solution-template-internal (internal) — into the Orbit GitHub organisations, then seeding solution.yaml.

Deployment shape

• Azure Container Apps is the sole deployment target (the earlier Vercel path was retired on 2026-07-02). Aurora runs as a singleton ACA app; each solution gets its own stack of three apps — the reader, the agent (writer), and Mission Control — built from shared ACR images per release.
• Public URLs follow a flat subdomain-per-app convention under maxqlabs-orbit.com: aurora., <solution-id>. (reader), and <solution-id>-mc. (Mission Control) — one level deep so a single wildcard certificate covers the fleet, with origin isolation between apps. The agent is not public: since 2026-07-03 it runs with internal ACA ingress and no subdomain, reachable in-env only (as http://agent-<h>).
• Releases are recorded per component in releases/ (release.yaml per v<semver>), written by the Azure image-build pipeline.

Where to go next

This page is the map; the three sibling pages are the territory:

• System Context — the platform’s place in the world: customers, tenants, solutions, and the repositories they live in. Start here for the portfolio model (Customer → Tenant → Solution) and how Aurora relates to the per-tenant and per-solution scopes.
• Solution Model — the Trajectory solution tree that every Orbit app consumes and the agent authors: stages, artefacts, schemas, and the v1.8 base format.
• Data Flow — how solution data moves between repositories, the agent, and the readers: the agent’s HTTP solution API, live refresh over SSE, and the git lifecycle behind each change.