# benediktschackenberg/octofleet architecture

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

- Interactive diagram: https://gitdiagram.com/benediktschackenberg/octofleet
- Repository: https://github.com/benediktschackenberg/octofleet

## Overview

Octofleet is a self-hosted endpoint-management platform. Administrators use its web dashboard to enroll and monitor a fleet, inspect inventory and security posture, then deploy jobs, packages, patches, or provisioning workflows; agents collect endpoint data and receive remote work. The backend exposes the API and persists fleet state. The README documents additional capabilities—including content lifecycle, query, metering, reports, and SQL Server management—that are included as product branches. Some subsystem connections are documented rather than verified in sampled implementation, so those edges are dashed.

Main entry points: [`backend/main.py`](https://github.com/benediktschackenberg/octofleet/blob/main/backend/main.py) (REST API), [`src/OctofleetAgent.Service/NodeWorker.cs`](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/NodeWorker.cs) (Octofleet agent), [`frontend/src/app/page.tsx`](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/page.tsx) (Fleet dashboard), [`frontend/src/lib/api-client.ts`](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/lib/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_console["Fleet dashboard<br/>[page.tsx]"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_inventory_ui["Inventory and monitoring<br/>[page.tsx]"]
  node_deploy_ui["Deployments and jobs<br/>[page.tsx]"]
  node_patch_ui["Patch explorer<br/>[page.tsx]"]
  node_provision_ui["Provisioning console<br/>[page.tsx]"]
  node_query_ui["Query workspace<br/>[page.tsx]"]
  node_query_hooks["Query state hooks<br/>[useQueryEngine.ts]"]
end

subgraph group_api["API and fleet services"]
  node_api["REST API<br/>[main.py]"]
  node_auth["Authentication and RBAC<br/>[auth.py]"]
  node_inventory_api["Inventory and metrics<br/>[inventory.py]"]
  node_jobs_api["Jobs and deployments<br/>[jobs.py]"]
  node_patch_api["Patch management<br/>[patches.py]"]
  node_provision_api["Provisioning services<br/>[provisioning.py]"]
  node_content_api["Content lifecycle"]
  node_query_api["Query engine<br/>[query_engine.py]"]
  node_metering_api["Software metering"]
  node_reports_api["Reports and exports<br/>[reports.py]"]
  node_db[("Fleet database<br/>[main.py]")]
  node_sql_api["SQL Server management<br/>[mssql.py]"]
end

subgraph group_security["Security and compliance"]
  node_security_ui["Security center<br/>[page.tsx]"]
  node_security_api["Monitoring and findings<br/>[monitoring_mgmt.py]"]
  node_vuln_api["Vulnerability management<br/>[vulnerabilities.py]"]
  node_baseline_api["Configuration baselines<br/>[baselines.py]"]
end

subgraph group_agent["Endpoint agents"]
  node_agent["Octofleet agent<br/>[NodeWorker.cs]"]
  node_agent_inventory["Inventory collectors"]
  node_agent_jobs["Job execution<br/>[JobPoller.cs]"]
  node_agent_patches["Patch scanner<br/>[PatchScanner.cs]"]
  node_remote_access["Remote access"]
end

node_admin(("Administrator"))

node_admin -->|"manages fleet"| node_console
node_console -.->|"uses"| node_api_client
node_api_client -.->|"calls API"| node_api
node_console -.->|"opens"| node_inventory_ui
node_inventory_ui -.->|"requests inventory"| node_api
node_deploy_ui -.->|"requests deployment"| node_api
node_patch_ui -.->|"requests patches"| node_api
node_provision_ui -.->|"requests provisioning"| node_api
node_query_ui -.->|"uses hooks"| node_query_hooks
node_query_hooks -->|"executes queries"| node_query_api
node_api -->|"authenticates requests"| node_auth
node_api -->|"reads and writes"| node_db
node_api -->|"routes inventory"| node_inventory_api
node_api -->|"routes jobs"| node_jobs_api
node_api -->|"routes patches"| node_patch_api
node_api -->|"routes provisioning"| node_provision_api
node_api -->|"routes content"| node_content_api
node_api -->|"routes queries"| node_query_api
node_api -->|"routes metering"| node_metering_api
node_api -->|"routes reports"| node_reports_api
node_security_ui -.->|"views security posture"| node_security_api
node_security_api -.->|"serves security data"| node_api
node_api -->|"routes vulnerability data"| node_vuln_api
node_api -->|"routes baselines"| node_baseline_api
node_agent -->|"collects inventory"| node_agent_inventory
node_agent -.->|"polls jobs"| node_agent_jobs
node_agent -.->|"scans updates"| node_agent_patches
node_agent -.->|"sends fleet data"| node_api
node_api -.->|"dispatches work"| node_agent
node_agent -.->|"provides remote access"| node_remote_access
node_api -->|"routes SQL management"| node_sql_api

click node_console "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/page.tsx"
click node_api_client "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/lib/api-client.ts"
click node_inventory_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/nodes/page.tsx"
click node_deploy_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/deployments/page.tsx"
click node_patch_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/patches/explorer/page.tsx"
click node_provision_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/provisioning/page.tsx"
click node_query_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/query/page.tsx"
click node_query_hooks "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/hooks/useQueryEngine.ts"
click node_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/main.py"
click node_auth "https://github.com/benediktschackenberg/octofleet/blob/main/backend/auth.py"
click node_inventory_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/inventory.py"
click node_jobs_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/jobs.py"
click node_patch_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/patches.py"
click node_provision_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/provisioning.py"
click node_content_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/content_lifecycle.py"
click node_query_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/query_engine.py"
click node_metering_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/software_metering.py"
click node_reports_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/reports.py"
click node_db "https://github.com/benediktschackenberg/octofleet/blob/main/backend/main.py"
click node_security_ui "https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/security/page.tsx"
click node_security_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/monitoring_mgmt.py"
click node_vuln_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/vulnerabilities.py"
click node_baseline_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/baselines.py"
click node_agent "https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/NodeWorker.cs"
click node_agent_inventory "https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/Inventory/InventoryCollector.cs"
click node_agent_jobs "https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/JobPoller.cs"
click node_agent_patches "https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/PatchScanner.cs"
click node_remote_access "https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/Screen/ScreenStreamService.cs"
click node_sql_api "https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/mssql.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_console,node_api_client,node_inventory_ui,node_deploy_ui,node_patch_ui,node_provision_ui,node_query_ui,node_query_hooks toneBlue
class node_api,node_auth,node_inventory_api,node_jobs_api,node_patch_api,node_provision_api,node_content_api,node_query_api,node_metering_api,node_reports_api,node_db,node_sql_api toneAmber
class node_security_ui,node_security_api,node_vuln_api,node_baseline_api toneMint
class node_agent,node_agent_inventory,node_agent_jobs,node_agent_patches,node_remote_access toneRose
class node_admin toneIndigo
```

## Components

### Web console

- [Fleet dashboard](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [API client](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/lib/api-client.ts): `frontend/src/lib/api-client.ts`
- [Inventory and monitoring](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/nodes/page.tsx): `frontend/src/app/nodes/page.tsx`
- [Deployments and jobs](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/deployments/page.tsx): `frontend/src/app/deployments/page.tsx`
- [Patch explorer](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/patches/explorer/page.tsx): `frontend/src/app/patches/explorer/page.tsx`
- [Provisioning console](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/provisioning/page.tsx): `frontend/src/app/provisioning/page.tsx`
- [Query workspace](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/query/page.tsx): `frontend/src/app/query/page.tsx`
- [Query state hooks](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/hooks/useQueryEngine.ts): `frontend/src/hooks/useQueryEngine.ts`

### API and fleet services

- [REST API](https://github.com/benediktschackenberg/octofleet/blob/main/backend/main.py): `backend/main.py`
- [Authentication and RBAC](https://github.com/benediktschackenberg/octofleet/blob/main/backend/auth.py): `backend/auth.py`
- [Inventory and metrics](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/inventory.py): `backend/routers/inventory.py`
- [Jobs and deployments](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/jobs.py): `backend/routers/jobs.py`
- [Patch management](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/patches.py): `backend/routers/patches.py`
- [Provisioning services](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/provisioning.py): `backend/routers/provisioning.py`
- [Content lifecycle](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/content_lifecycle.py): `backend/routers/content_lifecycle.py`
- [Query engine](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/query_engine.py): `backend/routers/query_engine.py`
- [Software metering](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/software_metering.py): `backend/routers/software_metering.py`
- [Reports and exports](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/reports.py): `backend/routers/reports.py`
- [Fleet database](https://github.com/benediktschackenberg/octofleet/blob/main/backend/main.py): `backend/main.py`
- [SQL Server management](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/mssql.py): `backend/routers/mssql.py`

### Security and compliance

- [Security center](https://github.com/benediktschackenberg/octofleet/blob/main/frontend/src/app/security/page.tsx): `frontend/src/app/security/page.tsx`
- [Monitoring and findings](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/monitoring_mgmt.py): `backend/routers/monitoring_mgmt.py`
- [Vulnerability management](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/vulnerabilities.py): `backend/routers/vulnerabilities.py`
- [Configuration baselines](https://github.com/benediktschackenberg/octofleet/blob/main/backend/routers/baselines.py): `backend/routers/baselines.py`

### Endpoint agents

- [Octofleet agent](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/NodeWorker.cs): `src/OctofleetAgent.Service/NodeWorker.cs`
- [Inventory collectors](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/Inventory/InventoryCollector.cs): `src/OctofleetAgent.Service/Inventory/InventoryCollector.cs`
- [Job execution](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/JobPoller.cs): `src/OctofleetAgent.Service/JobPoller.cs`
- [Patch scanner](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/PatchScanner.cs): `src/OctofleetAgent.Service/PatchScanner.cs`
- [Remote access](https://github.com/benediktschackenberg/octofleet/blob/main/src/OctofleetAgent.Service/Screen/ScreenStreamService.cs): `src/OctofleetAgent.Service/Screen/ScreenStreamService.cs`

### Other components

- **Administrator**

## Connections

- Administrator → Fleet dashboard: manages fleet (evidence: `README.md`)
- Fleet dashboard → API client: uses
- API client → REST API: calls API
- Fleet dashboard → Inventory and monitoring: opens
- Inventory and monitoring → REST API: requests inventory
- Deployments and jobs → REST API: requests deployment
- Patch explorer → REST API: requests patches
- Provisioning console → REST API: requests provisioning
- Query workspace → Query state hooks: uses hooks
- Query state hooks → Query engine: executes queries
- REST API → Authentication and RBAC: authenticates requests (evidence: `backend/main.py`)
- REST API → Fleet database: reads and writes (evidence: `backend/main.py`)
- REST API → Inventory and metrics: routes inventory (evidence: `backend/main.py`)
- REST API → Jobs and deployments: routes jobs (evidence: `backend/main.py`)
- REST API → Patch management: routes patches (evidence: `backend/main.py`)
- REST API → Provisioning services: routes provisioning (evidence: `backend/main.py`)
- REST API → Content lifecycle: routes content (evidence: `backend/main.py`)
- REST API → Query engine: routes queries (evidence: `backend/main.py`)
- REST API → Software metering: routes metering (evidence: `backend/main.py`)
- REST API → Reports and exports: routes reports (evidence: `backend/main.py`)
- Security center → Monitoring and findings: views security posture
- Monitoring and findings → REST API: serves security data (evidence: `backend/main.py`)
- REST API → Vulnerability management: routes vulnerability data (evidence: `backend/main.py`)
- REST API → Configuration baselines: routes baselines (evidence: `backend/main.py`)
- Octofleet agent → Inventory collectors: collects inventory (evidence: `src/OctofleetAgent.Service/NodeWorker.cs`)
- Octofleet agent → Job execution: polls jobs
- Octofleet agent → Patch scanner: scans updates
- Octofleet agent → REST API: sends fleet data
- REST API → Octofleet agent: dispatches work
- Octofleet agent → Remote access: provides remote access
- REST API → SQL Server management: routes SQL management (evidence: `backend/main.py`)