# cortexflow/cortexbrain architecture

> Architecture diagram of the GitHub repository cortexflow/cortexbrain, 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/cortexflow/cortexbrain
- Repository: https://github.com/cortexflow/cortexbrain

## Overview

CortexBrain is a sidecarless, eBPF-based monitoring and network-policy platform for distributed workloads. Its main workflow is to attach kernel probes, collect network and system events, and expose telemetry for monitoring; the identity service also tracks interfaces and connections and supports packet blocking. The repository additionally includes a Kubernetes-focused CLI, an agent gRPC API, and an MCP server centered on Prometheus. Some service wiring is not shown in the sampled source, so the graph omits uncertain connections.

Main entry points: [`cli/src/main.rs`](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/main.rs) (cfcli), [`core/src/components/metrics/src/main.rs`](https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/metrics/src/main.rs) (Metrics service), [`cli/src/install.rs`](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/install.rs) (Install and lifecycle), [`cli/src/service.rs`](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/service.rs) (Service management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Cluster management"]
  node_cli["cfcli<br/>[main.rs]"]
  node_cli_install["Install and lifecycle<br/>[install.rs]"]
  node_cli_service["Service management<br/>[service.rs]"]
  node_cli_monitor["Monitoring commands<br/>[monitoring.rs]"]
  node_cli_policy["Network policies<br/>[policies.rs]"]
  node_cli_logs["Logs and status<br/>[logs.rs]"]
end

subgraph group_kernel["Kernel observability"]
  node_conntracker["Connection and veth probes<br/>[main.rs]"]
  node_metrics_tracer["Kernel metrics probes<br/>[main.rs]"]
end

subgraph group_runtime["Telemetry runtime"]
  node_identity["Identity service<br/>[main.rs]"]
  node_metrics["Metrics service<br/>[main.rs]"]
  node_common_maps["BPF map handling<br/>[map_handlers.rs]"]
end

subgraph group_api["Agent API"]
  node_agent_api["Agent gRPC server<br/>[main.rs]"]
  node_agent_client["Agent client<br/>[client.rs]"]
end

subgraph group_integrations["Monitoring integrations"]
  node_mcp["Prometheus MCP server<br/>[main.rs]"]
  node_prometheus_tool["Prometheus tool<br/>[tools.rs]"]
end

node_operator(("Operator"))
node_kubernetes["Kubernetes cluster"]
node_otel["OpenTelemetry collector"]
node_prometheus[("Prometheus")]

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches install"| node_cli_install
node_cli -->|"dispatches service"| node_cli_service
node_cli -->|"dispatches monitoring"| node_cli_monitor
node_cli -->|"dispatches policies"| node_cli_policy
node_cli -->|"dispatches logs"| node_cli_logs
node_cli_install -->|"manages deployment"| node_kubernetes
node_cli_service -->|"queries services"| node_kubernetes
node_cli_logs -->|"queries cluster"| node_kubernetes
node_conntracker -->|"emits kernel events"| node_identity
node_metrics_tracer -->|"emits perf events"| node_metrics
node_metrics -->|"exports telemetry"| node_otel
node_identity -->|"initializes maps"| node_common_maps
node_metrics -->|"initializes maps"| node_common_maps
node_agent_client -->|"connects via gRPC"| node_agent_api
node_operator -.->|"starts server"| node_mcp
node_mcp -->|"serves tool"| node_prometheus_tool
node_prometheus_tool -.->|"queries metrics"| node_prometheus

click node_cli "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/main.rs"
click node_cli_install "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/install.rs"
click node_cli_service "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/service.rs"
click node_cli_monitor "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/monitoring.rs"
click node_cli_policy "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/policies.rs"
click node_cli_logs "https://github.com/cortexflow/cortexbrain/blob/main/cli/src/logs.rs"
click node_conntracker "https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/conntracker/src/main.rs"
click node_identity "https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/identity/src/main.rs"
click node_metrics_tracer "https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/metrics_tracer/src/main.rs"
click node_metrics "https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/metrics/src/main.rs"
click node_common_maps "https://github.com/cortexflow/cortexbrain/blob/main/core/common/src/map_handlers.rs"
click node_agent_api "https://github.com/cortexflow/cortexbrain/blob/main/core/api/src/main.rs"
click node_agent_client "https://github.com/cortexflow/cortexbrain/blob/main/core/api/src/client.rs"
click node_mcp "https://github.com/cortexflow/cortexbrain/blob/main/mcp/src/main.rs"
click node_prometheus_tool "https://github.com/cortexflow/cortexbrain/blob/main/mcp/src/tools.rs"

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_cli,node_cli_install,node_cli_service,node_cli_monitor,node_cli_policy,node_cli_logs toneBlue
class node_conntracker,node_metrics_tracer,node_prometheus toneAmber
class node_identity,node_metrics,node_common_maps toneMint
class node_agent_api,node_agent_client toneRose
class node_mcp,node_prometheus_tool,node_operator,node_kubernetes,node_otel toneIndigo
```

## Components

### Cluster management

- [cfcli](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/main.rs): `cli/src/main.rs`
- [Install and lifecycle](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/install.rs): `cli/src/install.rs`
- [Service management](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/service.rs): `cli/src/service.rs`
- [Monitoring commands](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/monitoring.rs): `cli/src/monitoring.rs`
- [Network policies](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/policies.rs): `cli/src/policies.rs`
- [Logs and status](https://github.com/cortexflow/cortexbrain/blob/main/cli/src/logs.rs): `cli/src/logs.rs`

### Kernel observability

- [Connection and veth probes](https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/conntracker/src/main.rs): `core/src/components/conntracker/src/main.rs`
- [Kernel metrics probes](https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/metrics_tracer/src/main.rs): `core/src/components/metrics_tracer/src/main.rs`

### Telemetry runtime

- [Identity service](https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/identity/src/main.rs): `core/src/components/identity/src/main.rs`
- [Metrics service](https://github.com/cortexflow/cortexbrain/blob/main/core/src/components/metrics/src/main.rs): `core/src/components/metrics/src/main.rs`
- [BPF map handling](https://github.com/cortexflow/cortexbrain/blob/main/core/common/src/map_handlers.rs): `core/common/src/map_handlers.rs`

### Agent API

- [Agent gRPC server](https://github.com/cortexflow/cortexbrain/blob/main/core/api/src/main.rs): `core/api/src/main.rs`
- [Agent client](https://github.com/cortexflow/cortexbrain/blob/main/core/api/src/client.rs): `core/api/src/client.rs`

### Monitoring integrations

- [Prometheus MCP server](https://github.com/cortexflow/cortexbrain/blob/main/mcp/src/main.rs): `mcp/src/main.rs`
- [Prometheus tool](https://github.com/cortexflow/cortexbrain/blob/main/mcp/src/tools.rs): `mcp/src/tools.rs`

### Other components

- **Operator**
- **Kubernetes cluster**
- **OpenTelemetry collector**
- **Prometheus**

## Connections

- Operator → cfcli: runs commands
- cfcli → Install and lifecycle: dispatches install
- cfcli → Service management: dispatches service
- cfcli → Monitoring commands: dispatches monitoring
- cfcli → Network policies: dispatches policies
- cfcli → Logs and status: dispatches logs
- Install and lifecycle → Kubernetes cluster: manages deployment
- Service management → Kubernetes cluster: queries services
- Logs and status → Kubernetes cluster: queries cluster
- Connection and veth probes → Identity service: emits kernel events
- Kernel metrics probes → Metrics service: emits perf events
- Metrics service → OpenTelemetry collector: exports telemetry
- Identity service → BPF map handling: initializes maps
- Metrics service → BPF map handling: initializes maps
- Agent client → Agent gRPC server: connects via gRPC
- Operator → Prometheus MCP server: starts server
- Prometheus MCP server → Prometheus tool: serves tool
- Prometheus tool → Prometheus: queries metrics