# sugarfarmeriod/tunnelminion architecture

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

- Interactive diagram: https://gitdiagram.com/sugarfarmeriod/tunnelminion
- Repository: https://github.com/sugarfarmeriod/tunnelminion

## Overview

TunnelMinion is a local-first, cross-platform AI agent for inspecting services on a node and diagnosing authorized peers over an existing private network. The main workflow is browser chat or resource browsing → local agent and read-only tools → service evidence and diagnostics; separate flows cover confirmed long-term memory, human-approved peer operations, incident investigation, and managed-network coordination. The README documents these capabilities, while sampled code confirms selected assembly, persistence, and request paths; links for unsampled wiring are intentionally omitted.

Main entry points: [`frontend/src/app/router.tsx`](https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/app/router.tsx) (Page routing), [`src/tunnelminion/agent/runtime.py`](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/runtime.py) (Agent runtime), [`src/tunnelminion/web/conversation.py`](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/web/conversation.py) (Conversation API), [`src/tunnelminion/gateway/client.py`](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/gateway/client.py) (Gateway client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web experience"]
  node_browser["Browser app<br/>[main.tsx]"]
  node_routes["Page routing<br/>[router.tsx]"]
  node_chatui["Chat page<br/>[ChatPage.tsx]"]
  node_resources["Resource views<br/>[resources.py]"]
  node_webchat["Conversation API<br/>[conversation.py]"]
end

subgraph group_agent["Agent and diagnostics"]
  node_app["Application assembly<br/>[app.py]"]
  node_agentruntime["Agent runtime<br/>[runtime.py]"]
  node_tools["Tool runtime<br/>[runtime.py]"]
  node_platform["Windows adapters<br/>[definitions.py]"]
  node_services["Service summaries<br/>[services.py]"]
  node_diagnostics["Cross-node diagnostics<br/>[diagnostics.py]"]
  node_model["Model service<br/>[api.py]"]
end

subgraph group_network["Peer networking"]
  node_gatewayapi["Peer Gateway API<br/>[api.py]"]
  node_gatewayclient["Gateway client<br/>[client.py]"]
  node_coordinator["Coordinator<br/>[app.py]"]
  node_pathcontrol["Managed path control<br/>[path_controller.py]"]
end

subgraph group_governance["Operations and incidents"]
  node_operation["Requester operations"]
  node_incident["Incident investigation<br/>[investigation.py]"]
end

subgraph group_state["Memory and state"]
  node_incidentdb[("Incident store<br/>[storage.py]")]
  node_memory["Memory service<br/>[service.py]"]
  node_memorydb[("Memory store<br/>[sqlite.py]")]
end

node_user(("Operator"))
node_modelservice{{"External model"}}
node_peer(("Authorized peer"))

node_user -->|"uses"| node_browser
node_browser -->|"renders"| node_routes
node_routes -->|"routes to"| node_chatui
node_chatui -->|"requests"| node_webchat
node_routes -->|"loads"| node_resources
node_app -->|"mounts"| node_webchat
node_app -->|"mounts"| node_resources
node_webchat -->|"dispatches"| node_agentruntime
node_agentruntime -->|"queries"| node_model
node_model -.->|"calls"| node_modelservice
node_agentruntime -->|"invokes"| node_tools
node_tools -->|"dispatches"| node_platform
node_diagnostics -->|"summarizes evidence"| node_services
node_diagnostics -->|"requests peer tools"| node_gatewayclient
node_gatewayclient -->|"calls"| node_peer
node_peer -->|"serves"| node_gatewayapi
node_operation -->|"submits plans"| node_gatewayclient
node_coordinator -.->|"coordinates paths"| node_pathcontrol
node_incident -->|"persists state"| node_incidentdb
node_memory -->|"reads and writes"| node_memorydb

click node_browser "https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/main.tsx"
click node_routes "https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/app/router.tsx"
click node_chatui "https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/features/chat/ChatPage.tsx"
click node_resources "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/web/resources.py"
click node_webchat "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/web/conversation.py"
click node_app "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/app.py"
click node_agentruntime "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/runtime.py"
click node_tools "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/tools/runtime.py"
click node_platform "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/platforms/windows/definitions.py"
click node_services "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/services.py"
click node_diagnostics "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/diagnostics.py"
click node_model "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/model/api.py"
click node_gatewayapi "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/gateway/api.py"
click node_gatewayclient "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/gateway/client.py"
click node_coordinator "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/coordinator/app.py"
click node_pathcontrol "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/network/path_controller.py"
click node_operation "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/operation/requester_service.py"
click node_incident "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/incident/investigation.py"
click node_incidentdb "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/incident/storage.py"
click node_memory "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/memory/service.py"
click node_memorydb "https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/memory/sqlite.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_routes,node_chatui,node_resources,node_webchat toneBlue
class node_app,node_agentruntime,node_tools,node_platform,node_services,node_diagnostics,node_model toneAmber
class node_gatewayapi,node_gatewayclient,node_coordinator,node_pathcontrol toneMint
class node_operation,node_incident toneRose
class node_incidentdb,node_memory,node_memorydb,node_user,node_modelservice,node_peer toneIndigo
```

## Components

### Web experience

- [Browser app](https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Page routing](https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/app/router.tsx): `frontend/src/app/router.tsx`
- [Chat page](https://github.com/sugarfarmeriod/tunnelminion/blob/main/frontend/src/features/chat/ChatPage.tsx): `frontend/src/features/chat/ChatPage.tsx`
- [Resource views](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/web/resources.py): `src/tunnelminion/web/resources.py`
- [Conversation API](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/web/conversation.py): `src/tunnelminion/web/conversation.py`

### Agent and diagnostics

- [Application assembly](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/app.py): `src/tunnelminion/app.py`
- [Agent runtime](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/runtime.py): `src/tunnelminion/agent/runtime.py`
- [Tool runtime](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/tools/runtime.py): `src/tunnelminion/tools/runtime.py`
- [Windows adapters](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/platforms/windows/definitions.py): `src/tunnelminion/platforms/windows/definitions.py`
- [Service summaries](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/services.py): `src/tunnelminion/agent/services.py`
- [Cross-node diagnostics](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/agent/diagnostics.py): `src/tunnelminion/agent/diagnostics.py`
- [Model service](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/model/api.py): `src/tunnelminion/model/api.py`

### Peer networking

- [Peer Gateway API](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/gateway/api.py): `src/tunnelminion/gateway/api.py`
- [Gateway client](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/gateway/client.py): `src/tunnelminion/gateway/client.py`
- [Coordinator](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/coordinator/app.py): `src/tunnelminion/coordinator/app.py`
- [Managed path control](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/network/path_controller.py): `src/tunnelminion/network/path_controller.py`

### Operations and incidents

- [Requester operations](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/operation/requester_service.py): `src/tunnelminion/operation/requester_service.py`
- [Incident investigation](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/incident/investigation.py): `src/tunnelminion/incident/investigation.py`

### Memory and state

- [Incident store](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/incident/storage.py): `src/tunnelminion/incident/storage.py`
- [Memory service](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/memory/service.py): `src/tunnelminion/memory/service.py`
- [Memory store](https://github.com/sugarfarmeriod/tunnelminion/blob/main/src/tunnelminion/memory/sqlite.py): `src/tunnelminion/memory/sqlite.py`

### Other components

- **Operator**
- **External model**
- **Authorized peer**

## Connections

- Operator → Browser app: uses
- Browser app → Page routing: renders
- Page routing → Chat page: routes to
- Chat page → Conversation API: requests
- Page routing → Resource views: loads
- Application assembly → Conversation API: mounts
- Application assembly → Resource views: mounts
- Conversation API → Agent runtime: dispatches
- Agent runtime → Model service: queries
- Model service → External model: calls
- Agent runtime → Tool runtime: invokes
- Tool runtime → Windows adapters: dispatches
- Cross-node diagnostics → Service summaries: summarizes evidence
- Cross-node diagnostics → Gateway client: requests peer tools
- Gateway client → Authorized peer: calls
- Authorized peer → Peer Gateway API: serves
- Requester operations → Gateway client: submits plans
- Coordinator → Managed path control: coordinates paths
- Incident investigation → Incident store: persists state
- Memory service → Memory store: reads and writes