# astracreates/astra architecture

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

- Interactive diagram: https://gitdiagram.com/astracreates/astra
- Repository: https://github.com/astracreates/astra

## Overview

Astra is an AI company-building platform: a founder submits an objective, the backend creates a durable run, plans and dispatches specialist work, streams progress, and records outcomes and artifacts. Separate product branches provide persistent company operations, knowledge retrieval, deployable agent stacks, and visual automations. The README documents both legacy and Temporal run paths; excerpts show selected storage, event, and task behavior, so unshown implementation links are omitted or cited only where documented.

Main entry points: [`backend/control_plane/start_run.py`](https://github.com/astracreates/astra/blob/main/backend/control_plane/start_run.py) (Run initialization), [`backend/specialists`](https://github.com/astracreates/astra/tree/main/backend/specialists) (Specialist agents), [`backend/core/events.py`](https://github.com/astracreates/astra/blob/main/backend/core/events.py) (Progress events), [`frontend/components/SessionView.tsx`](https://github.com/astracreates/astra/blob/main/frontend/components/SessionView.tsx) (Astra workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Founder experience"]
  node_frontend["Astra workspace<br/>[SessionView.tsx]"]
  node_api["Product API<br/>[routes.py]"]
end

subgraph group_execution["Run execution"]
  node_run_start["Run initialization<br/>[start_run.py]"]
  node_planner["Run planner<br/>[orchestrator.py]"]
  node_temporal["Durable workflows<br/>[workflows.py]"]
  node_specialists["Specialist agents"]
  node_tools["Agent tools"]
end

subgraph group_company["Company operations"]
  node_company_os[("Company operating layer<br/>[company_os.py]")]
  node_company_dispatch["Company work dispatch"]
  node_company_copilot["Routing copilot"]
  node_missions["Research missions<br/>[goal_engine.py]"]
end

subgraph group_capabilities["Product capabilities"]
  node_brain["Company Brain<br/>[company_brain.py]"]
  node_stacks["Agent Stack<br/>[compiler.py]"]
  node_automations["Visual automations"]
  node_custom_agents["Custom agents<br/>[runner.py]"]
  node_library[("Library and artifacts<br/>[store.py]")]
  node_deployment[("Deployments<br/>[store.py]")]
  node_mcp["MCP interface<br/>[astra_mcp.py]"]
end

subgraph group_platform["Durability and controls"]
  node_events["Progress events<br/>[events.py]"]
  node_sessions[("Session store<br/>[session_store.py]")]
  node_run_records[("Run records")]
  node_approvals["Approval controls"]
  node_billing[("Credits and billing<br/>[store.py]")]
end

node_founder(("Founder"))

node_founder -->|"submits goal"| node_frontend
node_frontend -.->|"requests work"| node_api
node_api -->|"creates run"| node_run_start
node_run_start -->|"starts planning"| node_planner
node_run_start -->|"selects workflow"| node_temporal
node_planner -->|"dispatches tasks"| node_specialists
node_specialists -->|"use tools"| node_tools
node_planner -->|"publishes progress"| node_events
node_temporal -.->|"streams progress"| node_events
node_events -->|"streams updates"| node_frontend
node_events -->|"persists events"| node_sessions
node_run_start -->|"records run"| node_run_records
node_founder -->|"sends message"| node_company_copilot
node_company_copilot -->|"routes work"| node_company_dispatch
node_company_dispatch -->|"updates company state"| node_company_os
node_company_os -.->|"shows company state"| node_frontend
node_missions -->|"gathers evidence"| node_brain
node_specialists -->|"queries context"| node_brain
node_founder -->|"defines outcome"| node_stacks
node_founder -->|"builds flows"| node_automations
node_founder -->|"defines agents"| node_custom_agents
node_specialists -->|"creates deliverables"| node_library
node_tools -->|"deploys work"| node_deployment
node_specialists -->|"requests approval"| node_approvals
node_run_start -->|"accounts credits"| node_billing
node_founder -->|"submits goals"| node_mcp

click node_frontend "https://github.com/astracreates/astra/blob/main/frontend/components/SessionView.tsx"
click node_api "https://github.com/astracreates/astra/blob/main/backend/api/routes.py"
click node_run_start "https://github.com/astracreates/astra/blob/main/backend/control_plane/start_run.py"
click node_planner "https://github.com/astracreates/astra/blob/main/backend/core/orchestrator.py"
click node_temporal "https://github.com/astracreates/astra/blob/main/backend/control_plane/temporal/workflows.py"
click node_specialists "https://github.com/astracreates/astra/tree/main/backend/specialists"
click node_tools "https://github.com/astracreates/astra/tree/main/backend/tools"
click node_events "https://github.com/astracreates/astra/blob/main/backend/core/events.py"
click node_sessions "https://github.com/astracreates/astra/blob/main/backend/core/session_store.py"
click node_run_records "https://github.com/astracreates/astra/blob/main/backend/control_plane/supabase_repositories.py"
click node_company_os "https://github.com/astracreates/astra/blob/main/backend/company_os.py"
click node_company_dispatch "https://github.com/astracreates/astra/blob/main/backend/company_os_dispatch.py"
click node_company_copilot "https://github.com/astracreates/astra/blob/main/backend/company_os_copilot.py"
click node_missions "https://github.com/astracreates/astra/blob/main/backend/missions/goal_engine.py"
click node_brain "https://github.com/astracreates/astra/blob/main/backend/tools/company_brain.py"
click node_stacks "https://github.com/astracreates/astra/blob/main/backend/stacks/compiler.py"
click node_automations "https://github.com/astracreates/astra/blob/main/backend/tools/automation_runtime.py"
click node_custom_agents "https://github.com/astracreates/astra/blob/main/backend/custom_agents/runner.py"
click node_library "https://github.com/astracreates/astra/blob/main/backend/library/store.py"
click node_deployment "https://github.com/astracreates/astra/blob/main/backend/deployments/store.py"
click node_approvals "https://github.com/astracreates/astra/blob/main/backend/approval_workflows.py"
click node_billing "https://github.com/astracreates/astra/blob/main/backend/credits/store.py"
click node_mcp "https://github.com/astracreates/astra/blob/main/backend/astra_mcp.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_frontend,node_api toneBlue
class node_run_start,node_planner,node_temporal,node_specialists,node_tools toneAmber
class node_company_os,node_company_dispatch,node_company_copilot,node_missions toneMint
class node_brain,node_stacks,node_automations,node_custom_agents,node_library,node_deployment,node_mcp toneRose
class node_events,node_sessions,node_run_records,node_approvals,node_billing,node_founder toneIndigo
```

## Components

### Founder experience

- [Astra workspace](https://github.com/astracreates/astra/blob/main/frontend/components/SessionView.tsx): `frontend/components/SessionView.tsx`
- [Product API](https://github.com/astracreates/astra/blob/main/backend/api/routes.py): `backend/api/routes.py`

### Run execution

- [Run initialization](https://github.com/astracreates/astra/blob/main/backend/control_plane/start_run.py): `backend/control_plane/start_run.py`
- [Run planner](https://github.com/astracreates/astra/blob/main/backend/core/orchestrator.py): `backend/core/orchestrator.py`
- [Durable workflows](https://github.com/astracreates/astra/blob/main/backend/control_plane/temporal/workflows.py): `backend/control_plane/temporal/workflows.py`
- [Specialist agents](https://github.com/astracreates/astra/tree/main/backend/specialists): `backend/specialists`
- [Agent tools](https://github.com/astracreates/astra/tree/main/backend/tools): `backend/tools`

### Company operations

- [Company operating layer](https://github.com/astracreates/astra/blob/main/backend/company_os.py): `backend/company_os.py`
- [Company work dispatch](https://github.com/astracreates/astra/blob/main/backend/company_os_dispatch.py): `backend/company_os_dispatch.py`
- [Routing copilot](https://github.com/astracreates/astra/blob/main/backend/company_os_copilot.py): `backend/company_os_copilot.py`
- [Research missions](https://github.com/astracreates/astra/blob/main/backend/missions/goal_engine.py): `backend/missions/goal_engine.py`

### Product capabilities

- [Company Brain](https://github.com/astracreates/astra/blob/main/backend/tools/company_brain.py): `backend/tools/company_brain.py`
- [Agent Stack](https://github.com/astracreates/astra/blob/main/backend/stacks/compiler.py): `backend/stacks/compiler.py`
- [Visual automations](https://github.com/astracreates/astra/blob/main/backend/tools/automation_runtime.py): `backend/tools/automation_runtime.py`
- [Custom agents](https://github.com/astracreates/astra/blob/main/backend/custom_agents/runner.py): `backend/custom_agents/runner.py`
- [Library and artifacts](https://github.com/astracreates/astra/blob/main/backend/library/store.py): `backend/library/store.py`
- [Deployments](https://github.com/astracreates/astra/blob/main/backend/deployments/store.py): `backend/deployments/store.py`
- [MCP interface](https://github.com/astracreates/astra/blob/main/backend/astra_mcp.py): `backend/astra_mcp.py`

### Durability and controls

- [Progress events](https://github.com/astracreates/astra/blob/main/backend/core/events.py): `backend/core/events.py`
- [Session store](https://github.com/astracreates/astra/blob/main/backend/core/session_store.py): `backend/core/session_store.py`
- [Run records](https://github.com/astracreates/astra/blob/main/backend/control_plane/supabase_repositories.py): `backend/control_plane/supabase_repositories.py`
- [Approval controls](https://github.com/astracreates/astra/blob/main/backend/approval_workflows.py): `backend/approval_workflows.py`
- [Credits and billing](https://github.com/astracreates/astra/blob/main/backend/credits/store.py): `backend/credits/store.py`

### Other components

- **Founder**

## Connections

- Founder → Astra workspace: submits goal
- Astra workspace → Product API: requests work
- Product API → Run initialization: creates run (evidence: `backend/api/routes.py`)
- Run initialization → Run planner: starts planning
- Run initialization → Durable workflows: selects workflow
- Run planner → Specialist agents: dispatches tasks
- Specialist agents → Agent tools: use tools (evidence: `backend/specialists/sales_pipeline.py`)
- Run planner → Progress events: publishes progress
- Durable workflows → Progress events: streams progress
- Progress events → Astra workspace: streams updates
- Progress events → Session store: persists events (evidence: `backend/core/events.py`)
- Run initialization → Run records: records run (evidence: `backend/control_plane/start_run.py`)
- Founder → Routing copilot: sends message
- Routing copilot → Company work dispatch: routes work
- Company work dispatch → Company operating layer: updates company state
- Company operating layer → Astra workspace: shows company state
- Research missions → Company Brain: gathers evidence (evidence: `backend/missions/goal_engine.py`)
- Specialist agents → Company Brain: queries context
- Founder → Agent Stack: defines outcome
- Founder → Visual automations: builds flows
- Founder → Custom agents: defines agents
- Specialist agents → Library and artifacts: creates deliverables
- Agent tools → Deployments: deploys work
- Specialist agents → Approval controls: requests approval
- Run initialization → Credits and billing: accounts credits (evidence: `backend/control_plane/start_run.py`)
- Founder → MCP interface: submits goals
