# ukhan262/claude-managed-agents-aca architecture

> Architecture diagram of the GitHub repository ukhan262/claude-managed-agents-aca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ukhan262/claude-managed-agents-aca
- Repository: https://github.com/ukhan262/claude-managed-agents-aca

## Overview

1. **What this repo implements**
   - This is a three-part reference architecture for running Claude “managed agents” with **Anthropic handling the agent loop** and **Azure Container Apps dynamic sessions handling tool execution**. The repository is organized around one user-facing app, one session allocator, and one ephemeral sandbox worker.

2. **Main subsystems**
   - `frontend/`: the chat/UI entrypoint that talks to Anthropic with an org API key.
   - `dispatcher/`: the always-on or webhook-triggered allocator that decides when a session needs a sandbox.
   - `sandbox/`: the per-run container image that executes tools locally inside a dynamic session.
   - `environment-queue-cleanup/`: a supporting utility for clearing stale queue/session state.

3. **Frontend boundary**
   - The frontend is the only component meant to interact with end users. It creates Anthropic sessions, sends `user.message` events, and streams back agent/tool events for rendering.
   - Architecturally, it sits outside the dynamic-session pool and never runs tools itself. Its main dependency is the Anthropic API, with the secret boundary being the **org API key** stored server-side.

4. **Dispatcher boundary**
   - The dispatcher is the control plane bridge between Anthropic and Azure session allocation.
   - In **poll mode**, it uses the Anthropic API to check for queued work and needs the API key.
   - In **webhook mode**, it reacts to Anthropic session events instead, so it can avoid holding the Anthropic API key and only needs a webhook secret plus access to the session pool management endpoint.

5. **Sandbox boundary**
   - The sandbox is the execution plane. It is an ephemeral container started per run in a **dynamic session**.
   - It holds only the **environment key** and **environment ID**, not the Anthropic API key. That is the key security boundary: the sandbox can execute tools locally, reach private VNet resources, and report results back through the Anthropic-managed agent loop without owning the user-facing secret.

6. **End-to-end request flow**
   - User input starts in the frontend, which creates a session and sends a message to Anthropic.
   - Anthropic enqueues work for the managed agent.
   - The dispatcher notices pending work or receives a webhook, then calls `/start` on the session pool with an identifier.
   - Azure allocates one fresh sandbox container, forwards the start request, and the sandbox claims the pending item, runs bash/file tools, posts results, and exits.
   - Exiting the container ends the dynamic session, which is why the pool lifecycle must be aligned to container exit.

7. **Queueing and idempotency model**
   - The README makes an important architectural point: `handle_item()` claims **one pending session item** and each run maps to one sandbox instance.
   - In webhook mode, the Azure Container Apps `identifier` is the session id, which makes allocation effectively 1:1 and retry-safe. This is the key diagram element for avoiding duplicated work.

8. **Infrastructure dependencies that matter**
   - The sandbox runs inside an **Azure Container Apps dynamic sessions pool** with `OnContainerExit` lifecycle, target port `8080`, and secrets injected via environment variables.
   - The pool is expected to be VNet-integrated so the sandbox can directly reach internal APIs/databases.
   - The dispatcher needs permission to invoke the session pool, and the pool may need `AcrPull` if it pulls sandbox images from Azure Container Registry.

9. **Data and secret flow**
   - Secrets are intentionally split by responsibility: frontend gets `ANTHROPIC_API_KEY`; dispatcher gets either the API key or webhook secret depending on mode; sandbox gets only `ANTHROPIC_ENVIRONMENT_KEY` and `ANTHROPIC_ENVIRONMENT_ID`.
   - This separation is central to the design: the browser never sees secrets, the dispatcher never runs tools, and the sandbox never gets the org API key.

10. **Operational/supporting component**
   - `environment-queue-cleanup/` appears to be a maintenance worker for queue/session hygiene, likely used to clean stale environments or pending items. It is not part of the main request path, but it supports reliable operation of the managed-agent queue.

11. **What a diagram should emphasize**
   - Draw three trust zones: user-facing frontend, control-plane dispatcher, and ephemeral sandbox pool.
   - Show Anthropic as the system that owns the agent loop and event stream.
   - Show Azure Container Apps dynamic sessions as the execution substrate that spawns one isolated container per run.
   - Highlight the one-way secret boundary: API key stays outside the sandbox; environment key stays inside it.

12. **Repo shape and runtime**
   - Each major component is a separate Python container image (`Dockerfile` + `requirements.txt`), which suggests independently deployable services rather than a single monolith.
   - The presence of `frontend/static/index.html` indicates a small server-rendered or API-backed UI, while the other two services are backend workers/operators.

Main entry points: [`dispatcher/main.py`](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/dispatcher/main.py) (Dispatcher), [`sandbox/server.py`](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/sandbox/server.py) (Sandbox), [`frontend/app.py`](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/app.py) (Frontend), [`frontend/static/index.html`](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/static/index.html) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user["User-facing"]
  node_browser(("User<br/>person"))
  node_frontend_app["Frontend<br/>chat app<br/>[app.py]"]
  node_frontend_ui["Web UI<br/>static ui<br/>[index.html]"]
end

subgraph group_control["Control plane"]
  node_anthropic[("Anthropic<br/>agent loop")]
  node_dispatcher_main["Dispatcher<br/>allocator<br/>[main.py]"]
  node_poll_mode(("Poll mode<br/>work queue poller"))
  node_webhook_mode(("Webhook mode<br/>event handler"))
  node_session_pool[("Session pool<br/>aca dynamic sessions")]
  node_aca_control["ACA control<br/>platform control"]
  node_org_key{{"Org API key<br/>secret"}}
  node_acr[("ACR<br/>image registry")]
end

subgraph group_exec["Execution plane"]
  node_sandbox_server["Sandbox<br/>executor<br/>[server.py]"]
  node_tools(("Local tools<br/>tool runtime"))
  node_vnet_resources[("Private resources<br/>vnet targets")]
  node_env_secret{{"Env secrets"}}
end

subgraph group_support["Support"]
  node_cleanup_main["Cleanup<br/>maintenance worker<br/>[main.py]"]
end

node_browser -->|"uses"| node_frontend_ui
node_frontend_ui -->|"serves"| node_frontend_app
node_frontend_app -->|"creates session"| node_anthropic
node_frontend_app -.->|"reads secret"| node_org_key
node_anthropic -->|"event / queue"| node_dispatcher_main
node_dispatcher_main -->|"supports"| node_poll_mode
node_dispatcher_main -->|"supports"| node_webhook_mode
node_poll_mode -.->|"uses key"| node_org_key
node_webhook_mode -->|"triggers"| node_dispatcher_main
node_dispatcher_main -->|"starts sessions"| node_aca_control
node_aca_control -->|"allocates"| node_session_pool
node_session_pool -->|"launches"| node_sandbox_server
node_sandbox_server -->|"executes"| node_tools
node_sandbox_server -->|"reaches"| node_vnet_resources
node_sandbox_server -.->|"reads secret"| node_env_secret
node_session_pool -.->|"pulls image"| node_acr
node_cleanup_main -.->|"cleans state"| node_session_pool

click node_frontend_app "https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/app.py"
click node_frontend_ui "https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/static/index.html"
click node_dispatcher_main "https://github.com/ukhan262/claude-managed-agents-aca/blob/main/dispatcher/main.py"
click node_sandbox_server "https://github.com/ukhan262/claude-managed-agents-aca/blob/main/sandbox/server.py"
click node_cleanup_main "https://github.com/ukhan262/claude-managed-agents-aca/blob/main/environment-queue-cleanup/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_frontend_app,node_frontend_ui toneBlue
class node_anthropic,node_dispatcher_main,node_poll_mode,node_webhook_mode,node_session_pool,node_aca_control,node_org_key,node_acr toneAmber
class node_sandbox_server,node_tools,node_vnet_resources,node_env_secret toneMint
class node_cleanup_main toneRose
```

## Components

### User-facing

Interactive entrypoint for the managed-agent workflow.

- **User**: person · End user interacting with the chat UI.
- [Frontend](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/app.py): chat app · UI and server entrypoint that creates Anthropic sessions and streams agent events. · `frontend/app.py`
- [Web UI](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/frontend/static/index.html): static ui · Browser-facing HTML front end for the chat experience. · `frontend/static/index.html`

### Control plane

Allocates and coordinates sandbox sessions.

- **Anthropic**: agent loop · Owns the managed-agent loop, session events, and queued work.
- [Dispatcher](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/dispatcher/main.py): allocator · Always-on or webhook-triggered session allocator that bridges Anthropic work to Azure sessions. · `dispatcher/main.py`
- **Poll mode**: work queue poller · Checks Anthropic for queued work using the API key.
- **Webhook mode**: event handler · Receives Anthropic session events and avoids storing the Anthropic API key.
- **Session pool**: aca dynamic sessions · Azure Container Apps dynamic sessions pool that starts one sandbox container per run.
- **ACA control**: platform control · Azure Container Apps control surface used to start sessions and manage lifecycle.
- **Org API key**: secret · Anthropic API credential kept outside the sandbox.
- **ACR**: image registry · Container registry used to pull sandbox images when needed.

### Execution plane

Ephemeral per-run sandbox containers.

- [Sandbox](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/sandbox/server.py): executor · Ephemeral container that runs bash and file tools inside the dynamic session. · `sandbox/server.py`
- **Local tools**: tool runtime · Tool execution layer inside the sandbox.
- **Private resources**: vnet targets · Internal APIs and databases reachable from the VNet-integrated sandbox.
- **Env secrets**: secret · Sandbox-only environment key and environment ID injected as runtime secrets.

### Support

Operational maintenance for queue and session hygiene.

- [Cleanup](https://github.com/ukhan262/claude-managed-agents-aca/blob/main/environment-queue-cleanup/main.py): maintenance worker · Background maintenance for clearing stale queue or session state. · `environment-queue-cleanup/main.py`

## Connections

- User → Web UI: uses · User interacts with the chat interface.
- Web UI → Frontend: serves · Static UI is served by the frontend application.
- Frontend → Anthropic: creates session · Frontend sends user messages and streams events through Anthropic.
- Frontend → Org API key: reads secret · Frontend uses the organization API key server-side.
- Anthropic → Dispatcher: event / queue · Anthropic exposes queued work or webhook events to the dispatcher.
- Dispatcher → Poll mode: supports · Dispatcher can operate by polling Anthropic for pending work.
- Dispatcher → Webhook mode: supports · Dispatcher can also operate as a webhook receiver.
- Poll mode → Org API key: uses key · Polling mode needs the Anthropic API key.
- Webhook mode → Dispatcher: triggers · Webhook events wake the dispatcher without requiring the API key.
- Dispatcher → ACA control: starts sessions · Dispatcher calls the session pool start endpoint with an identifier.
- ACA control → Session pool: allocates · Azure Container Apps creates a fresh sandbox container per run.
- Session pool → Sandbox: launches · Dynamic session starts the sandbox container.
- Sandbox → Local tools: executes · Sandbox runs local tool actions such as bash and file operations.
- Sandbox → Private resources: reaches · Sandbox can access private network resources.
- Sandbox → Env secrets: reads secret · Sandbox receives only environment-specific secrets.
- Session pool → ACR: pulls image · Pool may pull the sandbox image from Azure Container Registry.
- Cleanup → Session pool: cleans state · Maintenance worker clears stale queue or session state.
