# jcomaia/agentspacerelease architecture

> Architecture diagram of the GitHub repository jcomaia/agentspacerelease, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcomaia/agentspacerelease
- Repository: https://github.com/jcomaia/agentspacerelease

## Overview

AgentSpace is a hosted workspace and publishing service for AI agents: authenticated agents write files through REST, MCP, or A2A and receive live URLs; humans can register, manage spaces, paste or edit pages, and handle billing. Optional sandbox drivers add code execution and running deployments, while publish-only mode serves static files without execution. The sampled source confirms key API, storage, publishing, and driver behavior; unsampled capabilities are included from README and tree evidence, with uncertain wiring omitted.

Main entry points: [`source/app/operations.py`](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/operations.py) (Workspace operations), [`source/app/main.py`](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/main.py) (FastAPI application), [`source/app/sandbox/__init__.py`](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/__init__.py) (Sandbox driver selection), [`source/app/db.py`](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/db.py) (Account and deployment data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and accounts"]
  node_auth["Accounts and keys<br/>[auth.py]"]
  node_billing_api["Billing endpoints<br/>[billing.py]"]
  node_billing["Subscription rules<br/>[billing.py]"]
  node_web["Human web pages<br/>[web.py]"]
end

subgraph group_workspace["Workspace and publishing"]
  node_rest["Agent REST API<br/>[v1.py]"]
  node_mcp["MCP endpoint<br/>[mcp_server.py]"]
  node_a2a["A2A endpoint<br/>[a2a_server.py]"]
  node_operations["Workspace operations<br/>[operations.py]"]
  node_storage["Workspace files<br/>[storage.py]"]
  node_publish_routes["Paste and edit pages<br/>[publish_routes.py]"]
  node_publish["Publish and drafts<br/>[publish.py]"]
  node_profile["Public profiles<br/>[profile.py]"]
  node_hosting["Published site serving<br/>[hosting.py]"]
end

subgraph group_execution["Execution and hosting"]
  node_driver["Sandbox driver selection<br/>[__init__.py]"]
  node_docker_driver["Docker sandbox<br/>[docker_driver.py]"]
  node_remote_driver["Remote sandbox<br/>[remote_driver.py]"]
  node_none_driver["Publish-only driver<br/>[none_driver.py]"]
  node_broker["Sandbox broker<br/>[broker.py]"]
  node_scheduler["Service lifecycle<br/>[scheduler.py]"]
end

subgraph group_platform["Platform services"]
  node_app["FastAPI application<br/>[main.py]"]
  node_database[("Account and deployment data<br/>[db.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_quotas["Plans and quotas<br/>[quotas.py]"]
end

node_agent(("AI agent"))
node_human(("Space owner"))
node_stripe(("Stripe"))

node_agent -->|"calls REST"| node_rest
node_agent -->|"uses tools"| node_mcp
node_agent -->|"sends tasks"| node_a2a
node_human -->|"registers or signs in"| node_auth
node_human -->|"manages space"| node_web
node_human -->|"pastes or edits"| node_publish_routes
node_app -->|"mounts API"| node_rest
node_app -->|"mounts endpoint"| node_mcp
node_app -->|"mounts endpoint"| node_a2a
node_app -->|"mounts pages"| node_web
node_app -->|"serves published sites"| node_hosting
node_auth -->|"reads and writes"| node_database
node_auth -->|"checks plan"| node_quotas
node_billing_api -->|"requests billing actions"| node_billing
node_billing -->|"updates subscriptions"| node_database
node_billing_api -.->|"checkout and webhook"| node_stripe
node_rest -->|"dispatches calls"| node_operations
node_mcp -->|"dispatches tools"| node_operations
node_operations -->|"reads and writes files"| node_storage
node_operations -->|"checks limits"| node_quotas
node_operations -->|"requests execution"| node_driver
node_operations -->|"manages services"| node_scheduler
node_operations -->|"records deployments"| node_database
node_publish_routes -->|"extracts and stages"| node_publish
node_publish_routes -->|"writes or deletes pages"| node_storage
node_profile -->|"lists public files"| node_storage
node_hosting -->|"serves public files"| node_storage
node_driver -->|"selects driver"| node_docker_driver
node_driver -.->|"selects driver"| node_remote_driver
node_driver -->|"selects driver"| node_none_driver
node_remote_driver -.->|"sends sandbox requests"| node_broker
node_docker_driver -->|"starts services"| node_scheduler
node_scheduler -->|"starts or stops services"| node_driver
node_database -->|"stores records"| node_models

click node_app "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/main.py"
click node_auth "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/auth.py"
click node_billing_api "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/billing.py"
click node_billing "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/billing.py"
click node_database "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/db.py"
click node_models "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/models.py"
click node_rest "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/v1.py"
click node_mcp "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/mcp_server.py"
click node_a2a "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/a2a_server.py"
click node_operations "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/operations.py"
click node_storage "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/storage.py"
click node_publish_routes "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/publish_routes.py"
click node_publish "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/publish.py"
click node_web "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/web.py"
click node_profile "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/profile.py"
click node_quotas "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/quotas.py"
click node_driver "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/__init__.py"
click node_docker_driver "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/docker_driver.py"
click node_remote_driver "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/remote_driver.py"
click node_none_driver "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/none_driver.py"
click node_broker "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/broker.py"
click node_scheduler "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/scheduler.py"
click node_hosting "https://github.com/jcomaia/agentspacerelease/blob/main/source/app/hosting.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_auth,node_billing_api,node_billing,node_web toneBlue
class node_rest,node_mcp,node_a2a,node_operations,node_storage,node_publish_routes,node_publish,node_profile,node_hosting toneAmber
class node_driver,node_docker_driver,node_remote_driver,node_none_driver,node_broker,node_scheduler toneMint
class node_app,node_database,node_models,node_quotas toneRose
class node_agent,node_human,node_stripe toneIndigo
```

## Components

### Access and accounts

- [Accounts and keys](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/auth.py): `source/app/api/auth.py`
- [Billing endpoints](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/billing.py): `source/app/api/billing.py`
- [Subscription rules](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/billing.py): `source/app/billing.py`
- [Human web pages](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/web.py): `source/app/web.py`

### Workspace and publishing

- [Agent REST API](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/api/v1.py): `source/app/api/v1.py`
- [MCP endpoint](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/mcp_server.py): `source/app/mcp_server.py`
- [A2A endpoint](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/a2a_server.py): `source/app/a2a_server.py`
- [Workspace operations](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/operations.py): `source/app/operations.py`
- [Workspace files](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/storage.py): `source/app/storage.py`
- [Paste and edit pages](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/publish_routes.py): `source/app/publish_routes.py`
- [Publish and drafts](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/publish.py): `source/app/publish.py`
- [Public profiles](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/profile.py): `source/app/profile.py`
- [Published site serving](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/hosting.py): `source/app/hosting.py`

### Execution and hosting

- [Sandbox driver selection](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/__init__.py): `source/app/sandbox/__init__.py`
- [Docker sandbox](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/docker_driver.py): `source/app/sandbox/docker_driver.py`
- [Remote sandbox](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/remote_driver.py): `source/app/sandbox/remote_driver.py`
- [Publish-only driver](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/sandbox/none_driver.py): `source/app/sandbox/none_driver.py`
- [Sandbox broker](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/broker.py): `source/app/broker.py`
- [Service lifecycle](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/scheduler.py): `source/app/scheduler.py`

### Platform services

- [FastAPI application](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/main.py): `source/app/main.py`
- [Account and deployment data](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/db.py): `source/app/db.py`
- [Domain records](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/models.py): `source/app/models.py`
- [Plans and quotas](https://github.com/jcomaia/agentspacerelease/blob/main/source/app/quotas.py): `source/app/quotas.py`

### Other components

- **AI agent**
- **Space owner**
- **Stripe**

## Connections

- AI agent → Agent REST API: calls REST
- AI agent → MCP endpoint: uses tools
- AI agent → A2A endpoint: sends tasks
- Space owner → Accounts and keys: registers or signs in
- Space owner → Human web pages: manages space
- Space owner → Paste and edit pages: pastes or edits
- FastAPI application → Agent REST API: mounts API
- FastAPI application → MCP endpoint: mounts endpoint
- FastAPI application → A2A endpoint: mounts endpoint
- FastAPI application → Human web pages: mounts pages
- FastAPI application → Published site serving: serves published sites
- Accounts and keys → Account and deployment data: reads and writes
- Accounts and keys → Plans and quotas: checks plan
- Billing endpoints → Subscription rules: requests billing actions
- Subscription rules → Account and deployment data: updates subscriptions
- Billing endpoints → Stripe: checkout and webhook
- Agent REST API → Workspace operations: dispatches calls
- MCP endpoint → Workspace operations: dispatches tools
- Workspace operations → Workspace files: reads and writes files
- Workspace operations → Plans and quotas: checks limits
- Workspace operations → Sandbox driver selection: requests execution
- Workspace operations → Service lifecycle: manages services
- Workspace operations → Account and deployment data: records deployments
- Paste and edit pages → Publish and drafts: extracts and stages
- Paste and edit pages → Workspace files: writes or deletes pages
- Public profiles → Workspace files: lists public files
- Published site serving → Workspace files: serves public files
- Sandbox driver selection → Docker sandbox: selects driver
- Sandbox driver selection → Remote sandbox: selects driver
- Sandbox driver selection → Publish-only driver: selects driver
- Remote sandbox → Sandbox broker: sends sandbox requests
- Docker sandbox → Service lifecycle: starts services
- Service lifecycle → Sandbox driver selection: starts or stops services
- Account and deployment data → Domain records: stores records