Applications

The Orbit platform is not one application but a small fleet of them, split along a deliberate responsibility boundary. Everything lives in the single platform repository under implementation/, and everything runs together in one local docker-compose stack (infrastructure/local/docker-compose.yml) or as Azure Container Apps in production.

The responsibility split

The platform separates reading, writing, observing, and managing into distinct applications:

• The lens — Orbit Webapp. A strictly read-only viewer over a single Trajectory solution tree. It renders stages (as-is / R2B / to-be), domains, components, entities, workflows, assessments, concerns, questions, sources and iterations — and it never mutates anything. Since the 2026-07-02 refactor it has no repository mount at all: it fetches the solution tree from the agent over HTTP and live-refreshes via server-sent events.

• The hand — Orbit Agent. The sole writer. A headless Hono service that owns the solution repository mounts, holds the loaded solution tree in memory and serves it to the webapp, and authors the solution by running a team of Claude-powered agents (Claude Agent SDK) under a Team Lead orchestrator. It owns the git lifecycle: a branch per request, a commit per task, merge to base on success. One container manages one solution repo pair.

• The console — Mission Control. The maxq-orbit-agent-webapp UI for driving and observing the agent: submit requests, follow task execution and agent messages, inspect the queue. It talks purely to the agent’s HTTP + SSE surface.

• The control plane — Aurora. The management application above the per-solution stacks. Where the three Orbit apps are scoped to one solution at a time, Aurora operates across the whole portfolio: it reads every solution’s solution.yaml live from GitHub (two GitHub Apps over the customer and internal orgs), creates new solutions by forking the template repos, auto-deploys per-solution Orbit stacks to Azure Container Apps, and embeds an in-product agent chat.

• The registry — Customer / Tenant / Solution services. Three small Hono microservices implementing the Customer → Tenant → Solution portfolio registry on Postgres (a Cosmos-shaped document store: one records table per service schema, jsonb documents with optimistic-concurrency versions and an audit trail). Aurora’s BFF joins registry records with the live GitHub data.

• The feed — Activity Service. A fourth platform microservice: the append-only activity feed recording what happened, to what, by whom, when, across the whole platform (“Patrick deployed smals-sas-poc to Azure”). Producers log fire-and-forget through the shared @maxq/activity-kit emitter; the feed is queryable at any level of the portfolio. Built 2026-07-05 — producer integration and the Aurora “Flight Log” UI are still pending.

One sentence version: three managers for three layers — Aurora manages the portfolio, a tenant’s Orbit app manages that tenant’s solutions, and each solution’s agent authors that one solution as its single writer.

Application inventory

In production each public app gets its own subdomain under maxqlabs-orbit.com: aurora. for the control plane, and per solution ⟨solution-id⟩. (webapp) and ⟨solution-id⟩-mc. (Mission Control). The agent has no subdomain — since 2026-07-03 it runs with internal ACA ingress and is reached in-env only (as http://agent-<h>).

Shared packages

The workspace packages under implementation/shared/ consumed as file: dependencies include:

Because both are file: dependencies, the docker build context for their consumers is implementation/ (not the individual codebase folder) so the shared package is inside the context.

Runtime communication

Key flows, spelled out:

• Orbit Webapp → Orbit Agent (HTTP + SSE). The webapp’s server side calls the agent at ORBIT_AGENT_URL (docker-network name locally) for the in-memory solution model — /solution/version, /solution/tree, /sources/* — and relays the agent’s solution.updated SSE stream to the browser through its own /api/orbit-events proxy. The browser never talks to the agent directly for solution data.

• Mission Control → Orbit Agent (HTTP + SSE). Locally, browser code uses NEXT_PUBLIC_AGENT_URL (host-reachable) and server-side code uses AGENT_URL_INTERNAL (docker-network name); on Azure the internal-only agent is unreachable from the browser, so browser traffic goes through Mission Control’s same-origin /agent streaming proxy to the in-env AGENT_URL. Work is submitted via POST /requests/tasks and POST /requests/chats (non-blocking, 202 + request id) and observed via the GET /events/subscribe SSE stream.

• Orbit Agent → solution repos + Claude. The agent is the only process that mounts the customer repo (/repo), the internal repo (/repo-internal) and the read-only methodology repo (/methodology). It runs its worker agents through the Claude Agent SDK and commits/merges their output.

• Aurora → registry services. Aurora’s BFF calls the three services at CUSTOMER_SERVICE_URL / TENANT_SERVICE_URL / SOLUTION_SERVICE_URL, joining registry records with live GitHub data; the services call each other peer-to-peer for referential checks, authenticated by a shared secret.

• Aurora → GitHub. Two GitHub Apps (octokit auth-app), one per org: the customer org holds the solution-* repos whose workspace/solution-definition/solution.yaml is the source of truth, the internal org holds the matching *-internal repos. Solution creation forks the two template repos cross-org.

• Aurora → Azure. Via the ARM SDKs (@azure/arm-appcontainers, @azure/arm-storage, @azure/identity), Aurora provisions a per-solution stack of the three Orbit apps on Azure Container Apps from shared ACR images.

Where to go next

Each application has its own detail page in this section: Orbit Webapp covers the viewer’s pages, data layer and rendering pipeline; Orbit Agent covers the orchestrator, task processor, git lifecycle and HTTP surface; Mission Control covers the console; Aurora covers the control plane’s GitHub data layer, solution creation, Azure auto-deploy and agent chat; and Registry Services covers the three registry microservices and registry-kit; and Activity Service covers the platform activity feed and activity-kit.