# snowwiy/sentra architecture

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

- Interactive diagram: https://gitdiagram.com/snowwiy/sentra
- Repository: https://github.com/snowwiy/sentra

## Overview

Sentra monitors hosts through an agent-to-API-to-database workflow and presents their state in a polling web dashboard. The backend’s domain stages include enrollment and liveness, telemetry and inventory ingestion, change detection, event/metric alerting, and queryable asset views; retention and offline sweeps are supporting internal services. The README documents the broad architecture and API capabilities. Source excerpts are selective, so unsampled route-to-service and frontend-to-endpoint details are not asserted beyond documented relationships.

Main entry points: [`backend/app/api/v1/routes`](https://github.com/snowwiy/sentra/tree/main/backend/app/api/v1/routes) (Versioned API routes), [`agent/sentra_agent/runner.py`](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/runner.py) (Agent runner), [`backend/app/repositories`](https://github.com/snowwiy/sentra/tree/main/backend/app/repositories) (Data access), [`frontend/src/api/sentra.ts`](https://github.com/snowwiy/sentra/blob/main/frontend/src/api/sentra.ts) (Web API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host agent"]
  node_agent_runner["Agent runner<br/>[runner.py]"]
  node_agent_collect["Host collection<br/>[collectors.py]"]
  node_agent_inventory["Inventory scan<br/>[inventory.py]"]
  node_agent_events["Event collection<br/>[events.py]"]
  node_agent_client["API client<br/>[client.py]"]
end

subgraph group_backend["Sentra backend"]
  node_app["API application<br/>[main.py]"]
  node_api_routes["Versioned API routes"]
  node_enrollment["Agent enrollment<br/>[agent_service.py]"]
  node_telemetry["Telemetry ingestion"]
  node_inventory["Inventory changes"]
  node_events["Host events<br/>[event_service.py]"]
  node_alerts["Alert rules<br/>[alert_service.py]"]
  node_asset_queries["Asset views<br/>[asset_service.py]"]
  node_background["Background jobs<br/>[background.py]"]
  node_repositories["Data access"]
  node_models["Domain records"]
  node_retention["Data retention"]
end

subgraph group_frontend["Web dashboard"]
  node_dashboard["Dashboard pages"]
  node_asset_detail["Asset detail tabs"]
  node_alert_view["Alert view<br/>[AlertsView.tsx]"]
  node_api_client["Web API client<br/>[sentra.ts]"]
  node_polling["Refresh polling<br/>[usePolling.ts]"]
end

node_host(("Monitored host"))
node_browser(("Operator browser"))
node_database[("PostgreSQL")]

node_host -->|"runs on"| node_agent_runner
node_agent_runner -->|"collects metrics"| node_agent_collect
node_agent_runner -->|"collects inventory"| node_agent_inventory
node_agent_runner -->|"collects events"| node_agent_events
node_agent_runner -->|"sends reports"| node_agent_client
node_agent_client -->|"HTTP JSON"| node_api_routes
node_browser -->|"views"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_asset_detail -->|"requests asset data"| node_api_client
node_alert_view -->|"requests alerts"| node_api_client
node_dashboard -->|"refreshes periodically"| node_polling
node_api_client -->|"calls API"| node_api_routes
node_app -->|"mounts routes"| node_api_routes
node_api_routes -.->|"handles registration"| node_enrollment
node_api_routes -.->|"ingests samples"| node_telemetry
node_api_routes -.->|"ingests snapshots"| node_inventory
node_api_routes -.->|"ingests events"| node_events
node_api_routes -.->|"serves alerts"| node_alerts
node_api_routes -.->|"serves assets"| node_asset_queries
node_enrollment -->|"uses data access"| node_repositories
node_alerts -->|"queries and stores"| node_repositories
node_inventory -->|"uses data access"| node_repositories
node_repositories -->|"queries ORM records"| node_models
node_repositories -->|"persists records"| node_database
node_app -->|"starts jobs"| node_background
node_background -->|"runs purge"| node_retention
node_background -.->|"sweeps offline assets"| node_alerts
node_retention -->|"purges old data"| node_database

click node_agent_runner "https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/runner.py"
click node_agent_collect "https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/collectors.py"
click node_agent_inventory "https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/inventory.py"
click node_agent_events "https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/events.py"
click node_agent_client "https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/client.py"
click node_app "https://github.com/snowwiy/sentra/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/snowwiy/sentra/tree/main/backend/app/api/v1/routes"
click node_enrollment "https://github.com/snowwiy/sentra/blob/main/backend/app/services/agent_service.py"
click node_telemetry "https://github.com/snowwiy/sentra/blob/main/backend/app/services/telemetry_service.py"
click node_inventory "https://github.com/snowwiy/sentra/blob/main/backend/app/services/inventory_service.py"
click node_events "https://github.com/snowwiy/sentra/blob/main/backend/app/services/event_service.py"
click node_alerts "https://github.com/snowwiy/sentra/blob/main/backend/app/services/alert_service.py"
click node_asset_queries "https://github.com/snowwiy/sentra/blob/main/backend/app/services/asset_service.py"
click node_background "https://github.com/snowwiy/sentra/blob/main/backend/app/services/background.py"
click node_repositories "https://github.com/snowwiy/sentra/tree/main/backend/app/repositories"
click node_models "https://github.com/snowwiy/sentra/tree/main/backend/app/models"
click node_dashboard "https://github.com/snowwiy/sentra/tree/main/frontend/src/pages"
click node_asset_detail "https://github.com/snowwiy/sentra/tree/main/frontend/src/components/asset"
click node_alert_view "https://github.com/snowwiy/sentra/blob/main/frontend/src/components/AlertsView.tsx"
click node_api_client "https://github.com/snowwiy/sentra/blob/main/frontend/src/api/sentra.ts"
click node_polling "https://github.com/snowwiy/sentra/blob/main/frontend/src/lib/usePolling.ts"
click node_retention "https://github.com/snowwiy/sentra/blob/main/backend/app/services/retention_service.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_agent_runner,node_agent_collect,node_agent_inventory,node_agent_events,node_agent_client,node_browser toneBlue
class node_app,node_api_routes,node_enrollment,node_telemetry,node_inventory,node_events,node_alerts,node_asset_queries,node_background,node_repositories,node_models,node_retention,node_database toneAmber
class node_dashboard,node_asset_detail,node_alert_view,node_api_client,node_polling toneMint
class node_host toneIndigo
```

## Components

### Host agent

- [Agent runner](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/runner.py): `agent/sentra_agent/runner.py`
- [Host collection](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/collectors.py): `agent/sentra_agent/collectors.py`
- [Inventory scan](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/inventory.py): `agent/sentra_agent/inventory.py`
- [Event collection](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/events.py): `agent/sentra_agent/events.py`
- [API client](https://github.com/snowwiy/sentra/blob/main/agent/sentra_agent/client.py): `agent/sentra_agent/client.py`

### Sentra backend

- [API application](https://github.com/snowwiy/sentra/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned API routes](https://github.com/snowwiy/sentra/tree/main/backend/app/api/v1/routes): `backend/app/api/v1/routes`
- [Agent enrollment](https://github.com/snowwiy/sentra/blob/main/backend/app/services/agent_service.py): `backend/app/services/agent_service.py`
- [Telemetry ingestion](https://github.com/snowwiy/sentra/blob/main/backend/app/services/telemetry_service.py): `backend/app/services/telemetry_service.py`
- [Inventory changes](https://github.com/snowwiy/sentra/blob/main/backend/app/services/inventory_service.py): `backend/app/services/inventory_service.py`
- [Host events](https://github.com/snowwiy/sentra/blob/main/backend/app/services/event_service.py): `backend/app/services/event_service.py`
- [Alert rules](https://github.com/snowwiy/sentra/blob/main/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Asset views](https://github.com/snowwiy/sentra/blob/main/backend/app/services/asset_service.py): `backend/app/services/asset_service.py`
- [Background jobs](https://github.com/snowwiy/sentra/blob/main/backend/app/services/background.py): `backend/app/services/background.py`
- [Data access](https://github.com/snowwiy/sentra/tree/main/backend/app/repositories): `backend/app/repositories`
- [Domain records](https://github.com/snowwiy/sentra/tree/main/backend/app/models): `backend/app/models`
- [Data retention](https://github.com/snowwiy/sentra/blob/main/backend/app/services/retention_service.py): `backend/app/services/retention_service.py`

### Web dashboard

- [Dashboard pages](https://github.com/snowwiy/sentra/tree/main/frontend/src/pages): `frontend/src/pages`
- [Asset detail tabs](https://github.com/snowwiy/sentra/tree/main/frontend/src/components/asset): `frontend/src/components/asset`
- [Alert view](https://github.com/snowwiy/sentra/blob/main/frontend/src/components/AlertsView.tsx): `frontend/src/components/AlertsView.tsx`
- [Web API client](https://github.com/snowwiy/sentra/blob/main/frontend/src/api/sentra.ts): `frontend/src/api/sentra.ts`
- [Refresh polling](https://github.com/snowwiy/sentra/blob/main/frontend/src/lib/usePolling.ts): `frontend/src/lib/usePolling.ts`

### Other components

- **Monitored host**
- **Operator browser**
- **PostgreSQL**

## Connections

- Monitored host → Agent runner: runs on (evidence: `README.md`)
- Agent runner → Host collection: collects metrics (evidence: `agent/sentra_agent/runner.py`)
- Agent runner → Inventory scan: collects inventory (evidence: `agent/sentra_agent/runner.py`)
- Agent runner → Event collection: collects events (evidence: `agent/sentra_agent/runner.py`)
- Agent runner → API client: sends reports (evidence: `agent/sentra_agent/runner.py`)
- API client → Versioned API routes: HTTP JSON (evidence: `README.md`)
- Operator browser → Dashboard pages: views (evidence: `README.md`)
- Dashboard pages → Web API client: requests data (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Asset detail tabs → Web API client: requests asset data (evidence: `README.md`)
- Alert view → Web API client: requests alerts (evidence: `frontend/src/components/AlertsView.tsx`)
- Dashboard pages → Refresh polling: refreshes periodically (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Web API client → Versioned API routes: calls API (evidence: `README.md`)
- API application → Versioned API routes: mounts routes (evidence: `backend/app/main.py`)
- Versioned API routes → Agent enrollment: handles registration
- Versioned API routes → Telemetry ingestion: ingests samples
- Versioned API routes → Inventory changes: ingests snapshots
- Versioned API routes → Host events: ingests events
- Versioned API routes → Alert rules: serves alerts
- Versioned API routes → Asset views: serves assets
- Agent enrollment → Data access: uses data access (evidence: `backend/app/services/agent_service.py`)
- Alert rules → Data access: queries and stores (evidence: `backend/app/services/alert_service.py`)
- Inventory changes → Data access: uses data access (evidence: `backend/app/services/inventory_service.py`)
- Data access → Domain records: queries ORM records (evidence: `backend/app/repositories/alert_repository.py`)
- Data access → PostgreSQL: persists records (evidence: `README.md`)
- API application → Background jobs: starts jobs (evidence: `backend/app/main.py`)
- Background jobs → Data retention: runs purge (evidence: `backend/app/main.py`)
- Background jobs → Alert rules: sweeps offline assets
- Data retention → PostgreSQL: purges old data (evidence: `backend/app/services/retention_service.py`)
