# pandastack-io/pandastack-ai architecture

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

- Interactive diagram: https://gitdiagram.com/pandastack-io/pandastack-ai
- Repository: https://github.com/pandastack-io/pandastack-ai

## Overview

PandaStack is a self-hosted control plane for disposable Firecracker sandboxes and managed PostgreSQL running in dedicated microVMs. The principal workflow is a client request entering the API, capacity selection by the scheduler, and VM creation or restoration by a host agent. The agent exposes sandbox operations and manages lifecycle, snapshots, and streaming restores. Separate branches cover managed database provisioning and recovery, template builds, dashboard operations, and database connection routing. Some internals are represented at subsystem level because their source was not excerpted; documented architecture supplies the control-plane flow.

Main entry points: [`agent/internal/sandbox/manager.go`](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/sandbox/manager.go) (Sandbox lifecycle), [`api/cmd/api/main.go`](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/main.go) (REST API), [`api/internal/scheduler/scheduler.go`](https://github.com/pandastack-io/pandastack-ai/blob/main/api/internal/scheduler/scheduler.go) (Capacity scheduler), [`dashboard/src/app/(app)/databases/[id]/client.tsx`](https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/client.tsx) (Database dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_api["REST API<br/>[main.go]"]
  node_scheduler["Capacity scheduler<br/>[scheduler.go]"]
  node_template_build["Template builds"]
  node_template_seed["Template snapshots<br/>[seed.go]"]
  node_audit_observability[("Audit and telemetry<br/>[main.go]")]
end

subgraph group_host["Host runtime"]
  node_agent_service["Host agent<br/>[main.go]"]
  node_agent_api["Agent HTTP API<br/>[router.go]"]
  node_sandbox_manager["Sandbox lifecycle<br/>[manager.go]"]
  node_firecracker["Firecracker driver<br/>[driver.go]"]
  node_snapshot_store[("Snapshot store<br/>[snapstore.go]")]
  node_memory_stream["Memory streaming<br/>[handler_linux.go]"]
  node_disk_stream["Rootfs streaming<br/>[server_linux.go]"]
  node_agent_store[("Agent metadata<br/>[store.go]")]
  node_guest_daemon["Guest daemon<br/>[main.go]"]
end

subgraph group_databases["Managed databases"]
  node_database_api["Database operations<br/>[databases.go]"]
  node_database_failover["Database failover"]
  node_wal_archive["WAL archiving<br/>[wal_relay.go]"]
  node_connection_proxy["Database proxy<br/>[main.go]"]
end

subgraph group_experience["User surfaces"]
  node_dashboard["Dashboard<br/>[client.tsx]"]
  node_database_dashboard["Database dashboard<br/>[client.tsx]"]
  node_database_charts["Database metrics"]
  node_database_logs["Database logs<br/>[client.tsx]"]
end

node_client(("API client"))

node_client -->|"requests"| node_api
node_api -->|"selects capacity"| node_scheduler
node_scheduler -->|"dispatches work"| node_agent_service
node_agent_service -->|"serves routes"| node_agent_api
node_agent_api -->|"handles lifecycle"| node_sandbox_manager
node_sandbox_manager -->|"manages VMs"| node_firecracker
node_sandbox_manager -->|"persists snapshots"| node_snapshot_store
node_sandbox_manager -->|"persists state"| node_agent_store
node_sandbox_manager -.->|"restores memory"| node_memory_stream
node_sandbox_manager -.->|"streams rootfs"| node_disk_stream
node_firecracker -.->|"runs guest"| node_guest_daemon
node_api -->|"routes database requests"| node_database_api
node_database_api -.->|"selects host"| node_scheduler
node_database_failover -->|"chooses target"| node_scheduler
node_database_failover -.->|"restores database"| node_database_api
node_database_api -.->|"coordinates archiving"| node_wal_archive
node_client -.->|"connects by hostname"| node_connection_proxy
node_template_build -->|"finds agents"| node_scheduler
node_template_seed -.->|"supplies snapshots"| node_sandbox_manager
node_api -.->|"records telemetry"| node_audit_observability
node_client -.->|"uses"| node_dashboard
node_dashboard -.->|"calls API"| node_api
node_client -.->|"manages databases"| node_database_dashboard
node_database_dashboard -->|"renders metrics"| node_database_charts
node_database_dashboard -.->|"opens logs"| node_database_logs
node_database_dashboard -.->|"calls database API"| node_api
node_database_logs -.->|"fetches logs"| node_api

click node_api "https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/main.go"
click node_scheduler "https://github.com/pandastack-io/pandastack-ai/blob/main/api/internal/scheduler/scheduler.go"
click node_template_build "https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/templates_build_handler.go"
click node_agent_service "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/cmd/agent/main.go"
click node_agent_api "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/api/router.go"
click node_sandbox_manager "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/sandbox/manager.go"
click node_firecracker "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/firecracker/driver.go"
click node_snapshot_store "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/snapstore/snapstore.go"
click node_memory_stream "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/uffd/handler_linux.go"
click node_disk_stream "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/nbdstream/server_linux.go"
click node_agent_store "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/store/store.go"
click node_guest_daemon "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/cmd/pandastack-daemon/main.go"
click node_database_api "https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/databases.go"
click node_database_failover "https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/databases_failover.go"
click node_wal_archive "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/sandbox/wal_relay.go"
click node_connection_proxy "https://github.com/pandastack-io/pandastack-ai/blob/main/db-proxy/main.go"
click node_template_seed "https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/seed/seed.go"
click node_audit_observability "https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/main.go"
click node_dashboard "https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/sandboxes/%5Bid%5D/client.tsx"
click node_database_dashboard "https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/client.tsx"
click node_database_charts "https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/db-metrics-charts.tsx"
click node_database_logs "https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/logs/client.tsx"

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_api,node_scheduler,node_template_build,node_template_seed,node_audit_observability,node_client toneBlue
class node_agent_service,node_agent_api,node_sandbox_manager,node_firecracker,node_snapshot_store,node_memory_stream,node_disk_stream,node_agent_store,node_guest_daemon toneAmber
class node_database_api,node_database_failover,node_wal_archive,node_connection_proxy toneMint
class node_dashboard,node_database_dashboard,node_database_charts,node_database_logs toneRose
```

## Components

### Control plane

- [REST API](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/main.go): `api/cmd/api/main.go`
- [Capacity scheduler](https://github.com/pandastack-io/pandastack-ai/blob/main/api/internal/scheduler/scheduler.go): `api/internal/scheduler/scheduler.go`
- [Template builds](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/templates_build_handler.go): `api/cmd/api/templates_build_handler.go`
- [Template snapshots](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/seed/seed.go): `agent/internal/seed/seed.go`
- [Audit and telemetry](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/main.go): `api/cmd/api/main.go`

### Host runtime

- [Host agent](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/cmd/agent/main.go): `agent/cmd/agent/main.go`
- [Agent HTTP API](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/api/router.go): `agent/internal/api/router.go`
- [Sandbox lifecycle](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/sandbox/manager.go): `agent/internal/sandbox/manager.go`
- [Firecracker driver](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/firecracker/driver.go): `agent/internal/firecracker/driver.go`
- [Snapshot store](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/snapstore/snapstore.go): `agent/internal/snapstore/snapstore.go`
- [Memory streaming](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/uffd/handler_linux.go): `agent/internal/uffd/handler_linux.go`
- [Rootfs streaming](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/nbdstream/server_linux.go): `agent/internal/nbdstream/server_linux.go`
- [Agent metadata](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/store/store.go): `agent/internal/store/store.go`
- [Guest daemon](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/cmd/pandastack-daemon/main.go): `agent/cmd/pandastack-daemon/main.go`

### Managed databases

- [Database operations](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/databases.go): `api/cmd/api/databases.go`
- [Database failover](https://github.com/pandastack-io/pandastack-ai/blob/main/api/cmd/api/databases_failover.go): `api/cmd/api/databases_failover.go`
- [WAL archiving](https://github.com/pandastack-io/pandastack-ai/blob/main/agent/internal/sandbox/wal_relay.go): `agent/internal/sandbox/wal_relay.go`
- [Database proxy](https://github.com/pandastack-io/pandastack-ai/blob/main/db-proxy/main.go): `db-proxy/main.go`

### User surfaces

- [Dashboard](https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/sandboxes/%5Bid%5D/client.tsx): `dashboard/src/app/(app)/sandboxes/[id]/client.tsx`
- [Database dashboard](https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/client.tsx): `dashboard/src/app/(app)/databases/[id]/client.tsx`
- [Database metrics](https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/db-metrics-charts.tsx): `dashboard/src/app/(app)/databases/[id]/db-metrics-charts.tsx`
- [Database logs](https://github.com/pandastack-io/pandastack-ai/blob/main/dashboard/src/app/(app)/databases/%5Bid%5D/logs/client.tsx): `dashboard/src/app/(app)/databases/[id]/logs/client.tsx`

### Other components

- **API client**

## Connections

- API client → REST API: requests (evidence: `README.md`)
- REST API → Capacity scheduler: selects capacity (evidence: `README.md`)
- Capacity scheduler → Host agent: dispatches work (evidence: `README.md`)
- Host agent → Agent HTTP API: serves routes (evidence: `agent/cmd/agent/main.go`)
- Agent HTTP API → Sandbox lifecycle: handles lifecycle (evidence: `agent/internal/api/router.go`)
- Sandbox lifecycle → Firecracker driver: manages VMs (evidence: `README.md`)
- Sandbox lifecycle → Snapshot store: persists snapshots (evidence: `README.md`)
- Sandbox lifecycle → Agent metadata: persists state (evidence: `agent/internal/sandbox/manager.go`)
- Sandbox lifecycle → Memory streaming: restores memory
- Sandbox lifecycle → Rootfs streaming: streams rootfs
- Firecracker driver → Guest daemon: runs guest
- REST API → Database operations: routes database requests (evidence: `api/cmd/api/main.go`)
- Database operations → Capacity scheduler: selects host
- Database failover → Capacity scheduler: chooses target (evidence: `api/cmd/api/databases_failover.go`)
- Database failover → Database operations: restores database
- Database operations → WAL archiving: coordinates archiving
- API client → Database proxy: connects by hostname
- Template builds → Capacity scheduler: finds agents (evidence: `api/cmd/api/templates_build_handler.go`)
- Template snapshots → Sandbox lifecycle: supplies snapshots
- REST API → Audit and telemetry: records telemetry (evidence: `api/cmd/api/main.go`)
- API client → Dashboard: uses
- Dashboard → REST API: calls API
- API client → Database dashboard: manages databases
- Database dashboard → Database metrics: renders metrics (evidence: `dashboard/src/app/(app)/databases/[id]/client.tsx`)
- Database dashboard → Database logs: opens logs
- Database dashboard → REST API: calls database API
- Database logs → REST API: fetches logs
