# ongridio/ongrid architecture

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

- Interactive diagram: https://gitdiagram.com/ongridio/ongrid
- Repository: https://github.com/ongridio/ongrid

## Overview

Ongrid is an infrastructure-operations platform combining a cloud manager, an outbound-connected Edge agent, and a React operator workspace. Operators ask questions or alerts trigger investigation; the system gathers telemetry, topology, and knowledge, then presents analysis or routes permitted actions. The README documents specialist agents, workflows, skills, MCP, approvals, browser SSH, Kubernetes, and network-device management, which are included as distinct branches. Wiring details are based on the sampled entry points and documented capabilities; unsampled subsystem links are omitted where ownership is unclear.

Main entry points: [`internal/manager/biz/aiops/graph/react.go`](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/graph/react.go) (Agent graph), [`cmd/ongrid-edge/main.go`](https://github.com/ongridio/ongrid/blob/main/cmd/ongrid-edge/main.go) (Edge agent), [`cmd/ongrid/main.go`](https://github.com/ongridio/ongrid/blob/main/cmd/ongrid/main.go) (Cloud manager), [`internal/manager/biz/aiops/chatruntime/runtime.go`](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/chatruntime/runtime.go) (Chat runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Operator workspace"]
  node_web["Web workspace<br/>[App.tsx]"]
end

subgraph group_agent["Agent and automation"]
  node_chat["Chat runtime<br/>[runtime.go]"]
  node_agentgraph["Agent graph<br/>[react.go]"]
  node_tools["Agent tools<br/>[registry.go]"]
  node_alertinvestigator["Alert investigation<br/>[usecase.go]"]
  node_approvals["Approval gate<br/>[usecase.go]"]
  node_workflow["Workflow engine<br/>[engine.go]"]
end

subgraph group_observability["Observability and context"]
  node_knowledge["Knowledge vault<br/>[usecase.go]"]
  node_topology["Topology service<br/>[usecase.go]"]
  node_telemetry["Metrics logs traces<br/>[query.go]"]
  node_alerts["Alert evaluation<br/>[pipeline.go]"]
end

subgraph group_edge["Edge and infrastructure"]
  node_edge["Edge agent<br/>[main.go]"]
  node_edgecollect["Host collectors<br/>[composite.go]"]
  node_edgeplugins["Telemetry plugins<br/>[plugin.go]"]
  node_k8s["Kubernetes management<br/>[usecase.go]"]
  node_devices["Network devices<br/>[usecase.go]"]
  node_shell["Browser SSH<br/>[router.go]"]
end

subgraph group_platform["Platform services"]
  node_manager["Cloud manager<br/>[main.go]"]
  node_iam["Identity and access<br/>[http.go]"]
  node_im["IM channels<br/>[usecase.go]"]
  node_mcp["MCP integrations<br/>[usecase.go]"]
end

node_operator(("Operator"))
node_observabilitystack[("Telemetry backends")]
node_infra["Managed infrastructure"]
node_chatservices(("Slack and Telegram"))

node_operator -->|"uses"| node_web
node_web -->|"API requests"| node_manager
node_manager -->|"composes"| node_iam
node_chatservices -->|"messages"| node_im
node_im -->|"dispatches"| node_chat
node_manager -->|"builds runtime"| node_chat
node_chat -->|"runs agent"| node_agentgraph
node_agentgraph -->|"invokes tools"| node_tools
node_alerts -->|"triggers investigation"| node_alertinvestigator
node_alertinvestigator -->|"starts RCA"| node_agentgraph
node_agentgraph -->|"searches context"| node_knowledge
node_agentgraph -->|"queries topology"| node_topology
node_agentgraph -->|"queries telemetry"| node_telemetry
node_agentgraph -->|"requests approval"| node_approvals
node_workflow -->|"executes nodes"| node_tools
node_edge -->|"runs collectors"| node_edgecollect
node_edge -->|"runs plugins"| node_edgeplugins
node_edgecollect -->|"exports telemetry"| node_observabilitystack
node_edgeplugins -->|"exports telemetry"| node_observabilitystack
node_edge -->|"dials tunnel"| node_manager
node_infra -->|"observed by"| node_edge
node_k8s -->|"enrolls clusters"| node_edge
node_devices -->|"discovers through"| node_edge
node_shell -->|"tunnels shell"| node_edge
node_mcp -.->|"exposes tools"| node_tools

click node_web "https://github.com/ongridio/ongrid/blob/main/web/src/App.tsx"
click node_manager "https://github.com/ongridio/ongrid/blob/main/cmd/ongrid/main.go"
click node_iam "https://github.com/ongridio/ongrid/blob/main/internal/iam/server/http.go"
click node_chat "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/chatruntime/runtime.go"
click node_agentgraph "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/graph/react.go"
click node_tools "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/tools/registry.go"
click node_alertinvestigator "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/alert/investigator/usecase.go"
click node_approvals "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/approval/usecase.go"
click node_workflow "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/flow/engine.go"
click node_knowledge "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/knowledge/usecase.go"
click node_topology "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/topology/usecase.go"
click node_telemetry "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/metric/query.go"
click node_alerts "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/alert/pipeline.go"
click node_edge "https://github.com/ongridio/ongrid/blob/main/cmd/ongrid-edge/main.go"
click node_edgecollect "https://github.com/ongridio/ongrid/blob/main/internal/edgeagent/collector/composite.go"
click node_edgeplugins "https://github.com/ongridio/ongrid/blob/main/internal/edgeagent/plugins/plugin.go"
click node_k8s "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/k8s/usecase.go"
click node_devices "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/device/usecase.go"
click node_shell "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/webshell/router.go"
click node_im "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/imbridge/usecase.go"
click node_mcp "https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/mcp/usecase.go"

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_web toneBlue
class node_chat,node_agentgraph,node_tools,node_alertinvestigator,node_approvals,node_workflow,node_observabilitystack toneAmber
class node_knowledge,node_topology,node_telemetry,node_alerts toneMint
class node_edge,node_edgecollect,node_edgeplugins,node_k8s,node_devices,node_shell toneRose
class node_manager,node_iam,node_im,node_mcp,node_operator,node_infra,node_chatservices toneIndigo
```

## Components

### Operator workspace

- [Web workspace](https://github.com/ongridio/ongrid/blob/main/web/src/App.tsx): `web/src/App.tsx`

### Agent and automation

- [Chat runtime](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/chatruntime/runtime.go): `internal/manager/biz/aiops/chatruntime/runtime.go`
- [Agent graph](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/graph/react.go): `internal/manager/biz/aiops/graph/react.go`
- [Agent tools](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/aiops/tools/registry.go): `internal/manager/biz/aiops/tools/registry.go`
- [Alert investigation](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/alert/investigator/usecase.go): `internal/manager/biz/alert/investigator/usecase.go`
- [Approval gate](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/approval/usecase.go): `internal/manager/biz/approval/usecase.go`
- [Workflow engine](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/flow/engine.go): `internal/manager/biz/flow/engine.go`

### Observability and context

- [Knowledge vault](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/knowledge/usecase.go): `internal/manager/biz/knowledge/usecase.go`
- [Topology service](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/topology/usecase.go): `internal/manager/biz/topology/usecase.go`
- [Metrics logs traces](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/metric/query.go): `internal/manager/biz/metric/query.go`
- [Alert evaluation](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/alert/pipeline.go): `internal/manager/biz/alert/pipeline.go`

### Edge and infrastructure

- [Edge agent](https://github.com/ongridio/ongrid/blob/main/cmd/ongrid-edge/main.go): `cmd/ongrid-edge/main.go`
- [Host collectors](https://github.com/ongridio/ongrid/blob/main/internal/edgeagent/collector/composite.go): `internal/edgeagent/collector/composite.go`
- [Telemetry plugins](https://github.com/ongridio/ongrid/blob/main/internal/edgeagent/plugins/plugin.go): `internal/edgeagent/plugins/plugin.go`
- [Kubernetes management](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/k8s/usecase.go): `internal/manager/biz/k8s/usecase.go`
- [Network devices](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/device/usecase.go): `internal/manager/biz/device/usecase.go`
- [Browser SSH](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/webshell/router.go): `internal/manager/biz/webshell/router.go`

### Platform services

- [Cloud manager](https://github.com/ongridio/ongrid/blob/main/cmd/ongrid/main.go): `cmd/ongrid/main.go`
- [Identity and access](https://github.com/ongridio/ongrid/blob/main/internal/iam/server/http.go): `internal/iam/server/http.go`
- [IM channels](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/imbridge/usecase.go): `internal/manager/biz/imbridge/usecase.go`
- [MCP integrations](https://github.com/ongridio/ongrid/blob/main/internal/manager/biz/mcp/usecase.go): `internal/manager/biz/mcp/usecase.go`

### Other components

- **Operator**
- **Telemetry backends**
- **Managed infrastructure**
- **Slack and Telegram**

## Connections

- Operator → Web workspace: uses
- Web workspace → Cloud manager: API requests
- Cloud manager → Identity and access: composes
- Slack and Telegram → IM channels: messages
- IM channels → Chat runtime: dispatches
- Cloud manager → Chat runtime: builds runtime
- Chat runtime → Agent graph: runs agent
- Agent graph → Agent tools: invokes tools
- Alert evaluation → Alert investigation: triggers investigation
- Alert investigation → Agent graph: starts RCA
- Agent graph → Knowledge vault: searches context
- Agent graph → Topology service: queries topology
- Agent graph → Metrics logs traces: queries telemetry
- Agent graph → Approval gate: requests approval
- Workflow engine → Agent tools: executes nodes
- Edge agent → Host collectors: runs collectors
- Edge agent → Telemetry plugins: runs plugins
- Host collectors → Telemetry backends: exports telemetry
- Telemetry plugins → Telemetry backends: exports telemetry
- Edge agent → Cloud manager: dials tunnel
- Managed infrastructure → Edge agent: observed by
- Kubernetes management → Edge agent: enrolls clusters
- Network devices → Edge agent: discovers through
- Browser SSH → Edge agent: tunnels shell
- MCP integrations → Agent tools: exposes tools