# juan52878911/kindling architecture

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

- Interactive diagram: https://gitdiagram.com/juan52878911/kindling
- Repository: https://github.com/juan52878911/kindling

## Overview

kindling runs isolated microVMs, using Firecracker on Linux or Virtualization.framework on macOS. The main workflow is a user invoking `kling`, which sends machine operations through the API to the daemon’s machine manager and then to a VMM. The repository also includes separately installable MCP, sandbox, database, and Android-phone extensions, plus an AI gateway. Some extension links and backend details are documented rather than visible in sampled source, so those relationships cite the README; unsampled implementation links are omitted.

Main entry points: [`internal/machine/manager.go`](https://github.com/juan52878911/kindling/blob/main/internal/machine/manager.go) (Machine Manager), [`internal/daemon/server.go`](https://github.com/juan52878911/kindling/blob/main/internal/daemon/server.go) (Daemon API), [`ext/mcp/cmd/kling-mcp/main.go`](https://github.com/juan52878911/kindling/blob/main/ext/mcp/cmd/kling-mcp/main.go) (MCP Extension), [`pkg/api/client.go`](https://github.com/juan52878911/kindling/blob/main/pkg/api/client.go) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_api["CLI and API"]
  node_kling_cli["kling CLI<br/>[main.go]"]
  node_api_client["API Client<br/>[client.go]"]
end

subgraph group_vm_core["Machine Runtime"]
  node_daemon_api["Daemon API<br/>[server.go]"]
  node_authz["Authorization<br/>[authz.go]"]
  node_machine_manager["Machine Manager<br/>[manager.go]"]
  node_machine_state[("Machine State")]
  node_share_server["Shared Folders<br/>[server.go]"]
end

subgraph group_vm_backends["VM Backends"]
  node_firecracker["Firecracker Backend<br/>[client.go]"]
  node_vz_service["macOS VMM<br/>[server.go]"]
end

subgraph group_extensions["Product Extensions"]
  node_mcp_ext["MCP Extension<br/>[main.go]"]
  node_mcp_gateway["MCP Gateway<br/>[router.go]"]
  node_mcp_bridge["MCP Bridge<br/>[main.go]"]
  node_sandbox_ext["Sandbox Extension<br/>[main.go]"]
  node_sandbox_operator["Sandbox Operator<br/>[controller.go]"]
  node_db_ext["Database Extension<br/>[app.go]"]
  node_db_engines["Database Engines<br/>[engines.go]"]
  node_phone_ext["Android Phone Extension<br/>[main.go]"]
end

subgraph group_ai["AI Gateway"]
  node_ai_gateway["AI Gateway<br/>[server.go]"]
  node_ai_learning["Learning Review<br/>[learn_review.go]"]
  node_chispa["Chispa Models"]
end

node_user(("CLI User"))
node_guest(("MicroVM Guest"))

node_user -->|"invokes"| node_kling_cli
node_kling_cli -->|"uses API"| node_api_client
node_api_client -->|"HTTP over socket"| node_daemon_api
node_daemon_api -->|"authorizes"| node_authz
node_daemon_api -->|"dispatches"| node_machine_manager
node_machine_manager -->|"persists"| node_machine_state
node_machine_manager -->|"uses backend"| node_firecracker
node_machine_manager -->|"uses on macOS"| node_vz_service
node_guest -->|"accesses shares"| node_share_server
node_user -->|"uses extension"| node_mcp_ext
node_mcp_ext -->|"provides gateway"| node_mcp_gateway
node_mcp_gateway -->|"uses API"| node_api_client
node_mcp_ext -.->|"bridges guest server"| node_mcp_bridge
node_user -->|"uses extension"| node_sandbox_ext
node_sandbox_ext -->|"runs operator"| node_sandbox_operator
node_user -->|"uses extension"| node_db_ext
node_db_ext -->|"selects engine"| node_db_engines
node_user -->|"uses extension"| node_phone_ext
node_user -.->|"sends AI requests"| node_ai_gateway
node_ai_gateway -.->|"serves review"| node_ai_learning
node_ai_learning -->|"uses models"| node_chispa

click node_kling_cli "https://github.com/juan52878911/kindling/blob/main/cmd/kling/main.go"
click node_api_client "https://github.com/juan52878911/kindling/blob/main/pkg/api/client.go"
click node_daemon_api "https://github.com/juan52878911/kindling/blob/main/internal/daemon/server.go"
click node_authz "https://github.com/juan52878911/kindling/blob/main/internal/daemon/authz.go"
click node_machine_manager "https://github.com/juan52878911/kindling/blob/main/internal/machine/manager.go"
click node_machine_state "https://github.com/juan52878911/kindling/tree/main/internal/machine"
click node_share_server "https://github.com/juan52878911/kindling/blob/main/internal/share/server.go"
click node_firecracker "https://github.com/juan52878911/kindling/blob/main/internal/fc/client.go"
click node_vz_service "https://github.com/juan52878911/kindling/blob/main/vz/internal/server/server.go"
click node_mcp_ext "https://github.com/juan52878911/kindling/blob/main/ext/mcp/cmd/kling-mcp/main.go"
click node_mcp_gateway "https://github.com/juan52878911/kindling/blob/main/ext/mcp/internal/gateway/router.go"
click node_mcp_bridge "https://github.com/juan52878911/kindling/blob/main/ext/mcp/cmd/kling-bridge/main.go"
click node_sandbox_ext "https://github.com/juan52878911/kindling/blob/main/ext/sandbox/cmd/kling-sandbox/main.go"
click node_sandbox_operator "https://github.com/juan52878911/kindling/blob/main/ext/sandbox/internal/operator/controller.go"
click node_db_ext "https://github.com/juan52878911/kindling/blob/main/ext/db/cmd/kling-db/app.go"
click node_db_engines "https://github.com/juan52878911/kindling/blob/main/ext/db/cmd/kling-db/engines.go"
click node_phone_ext "https://github.com/juan52878911/kindling/blob/main/ext/phone/cmd/kling-phone/main.go"
click node_ai_gateway "https://github.com/juan52878911/kindling/blob/main/pkg/aigw/server.go"
click node_ai_learning "https://github.com/juan52878911/kindling/blob/main/pkg/aigw/learn_review.go"
click node_chispa "https://github.com/juan52878911/kindling/tree/main/pkg/chispa"

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_kling_cli,node_api_client,node_user toneBlue
class node_daemon_api,node_authz,node_machine_manager,node_machine_state,node_share_server toneAmber
class node_firecracker,node_vz_service toneMint
class node_mcp_ext,node_mcp_gateway,node_mcp_bridge,node_sandbox_ext,node_sandbox_operator,node_db_ext,node_db_engines,node_phone_ext toneRose
class node_ai_gateway,node_ai_learning,node_chispa,node_guest toneIndigo
```

## Components

### CLI and API

- [kling CLI](https://github.com/juan52878911/kindling/blob/main/cmd/kling/main.go): `cmd/kling/main.go`
- [API Client](https://github.com/juan52878911/kindling/blob/main/pkg/api/client.go): `pkg/api/client.go`

### Machine Runtime

- [Daemon API](https://github.com/juan52878911/kindling/blob/main/internal/daemon/server.go): `internal/daemon/server.go`
- [Authorization](https://github.com/juan52878911/kindling/blob/main/internal/daemon/authz.go): `internal/daemon/authz.go`
- [Machine Manager](https://github.com/juan52878911/kindling/blob/main/internal/machine/manager.go): `internal/machine/manager.go`
- [Machine State](https://github.com/juan52878911/kindling/tree/main/internal/machine): `internal/machine`
- [Shared Folders](https://github.com/juan52878911/kindling/blob/main/internal/share/server.go): `internal/share/server.go`

### VM Backends

- [Firecracker Backend](https://github.com/juan52878911/kindling/blob/main/internal/fc/client.go): `internal/fc/client.go`
- [macOS VMM](https://github.com/juan52878911/kindling/blob/main/vz/internal/server/server.go): `vz/internal/server/server.go`

### Product Extensions

- [MCP Extension](https://github.com/juan52878911/kindling/blob/main/ext/mcp/cmd/kling-mcp/main.go): `ext/mcp/cmd/kling-mcp/main.go`
- [MCP Gateway](https://github.com/juan52878911/kindling/blob/main/ext/mcp/internal/gateway/router.go): `ext/mcp/internal/gateway/router.go`
- [MCP Bridge](https://github.com/juan52878911/kindling/blob/main/ext/mcp/cmd/kling-bridge/main.go): `ext/mcp/cmd/kling-bridge/main.go`
- [Sandbox Extension](https://github.com/juan52878911/kindling/blob/main/ext/sandbox/cmd/kling-sandbox/main.go): `ext/sandbox/cmd/kling-sandbox/main.go`
- [Sandbox Operator](https://github.com/juan52878911/kindling/blob/main/ext/sandbox/internal/operator/controller.go): `ext/sandbox/internal/operator/controller.go`
- [Database Extension](https://github.com/juan52878911/kindling/blob/main/ext/db/cmd/kling-db/app.go): `ext/db/cmd/kling-db/app.go`
- [Database Engines](https://github.com/juan52878911/kindling/blob/main/ext/db/cmd/kling-db/engines.go): `ext/db/cmd/kling-db/engines.go`
- [Android Phone Extension](https://github.com/juan52878911/kindling/blob/main/ext/phone/cmd/kling-phone/main.go): `ext/phone/cmd/kling-phone/main.go`

### AI Gateway

- [AI Gateway](https://github.com/juan52878911/kindling/blob/main/pkg/aigw/server.go): `pkg/aigw/server.go`
- [Learning Review](https://github.com/juan52878911/kindling/blob/main/pkg/aigw/learn_review.go): `pkg/aigw/learn_review.go`
- [Chispa Models](https://github.com/juan52878911/kindling/tree/main/pkg/chispa): `pkg/chispa`

### Other components

- **CLI User**
- **MicroVM Guest**

## Connections

- CLI User → kling CLI: invokes (evidence: `README.md`)
- kling CLI → API Client: uses API (evidence: `cmd/kling/main.go`)
- API Client → Daemon API: HTTP over socket (evidence: `README.md`)
- Daemon API → Authorization: authorizes (evidence: `internal/daemon/server.go`)
- Daemon API → Machine Manager: dispatches (evidence: `internal/daemon/server.go`)
- Machine Manager → Machine State: persists (evidence: `internal/machine/manager.go`)
- Machine Manager → Firecracker Backend: uses backend (evidence: `internal/machine/manager.go`)
- Machine Manager → macOS VMM: uses on macOS (evidence: `README.md`)
- MicroVM Guest → Shared Folders: accesses shares (evidence: `internal/share/server.go`)
- CLI User → MCP Extension: uses extension (evidence: `README.md`)
- MCP Extension → MCP Gateway: provides gateway (evidence: `ext/mcp/cmd/kling-mcp/main.go`)
- MCP Gateway → API Client: uses API (evidence: `ext/mcp/internal/gateway/router.go`)
- MCP Extension → MCP Bridge: bridges guest server
- CLI User → Sandbox Extension: uses extension (evidence: `README.md`)
- Sandbox Extension → Sandbox Operator: runs operator
- CLI User → Database Extension: uses extension (evidence: `README.md`)
- Database Extension → Database Engines: selects engine (evidence: `ext/db/cmd/kling-db/engines.go`)
- CLI User → Android Phone Extension: uses extension (evidence: `README.md`)
- CLI User → AI Gateway: sends AI requests
- AI Gateway → Learning Review: serves review
- Learning Review → Chispa Models: uses models (evidence: `pkg/aigw/learn_review.go`)
