# namtrungdn310/sentinelx architecture

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

- Interactive diagram: https://gitdiagram.com/namtrungdn310/sentinelx
- Repository: https://github.com/namtrungdn310/sentinelx

## Overview

SentinelX is a planned Linux infrastructure monitoring and automated-defense platform. The documented workflow is dashboard/API management, node telemetry collection and push, controller-side detection and policy decisions, then agent-side local validation and defense execution. The checked-in runtime is only a controller foundation: its implemented API exposes system health, with configuration and request-correlation support. The agent, load balancer, dashboard, storage, and business-domain modules are documented capabilities, not demonstrated implementations in the sampled source; their links reflect documented architecture only.

Main entry points: [`src/sentinelx_controller/main.py`](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/main.py) (Controller entry), [`src/sentinelx_controller/app.py`](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/app.py) (FastAPI application), [`src/sentinelx_agent/__init__.py`](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py) (Linux node agent), [`src/sentinelx_controller/modules`](https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules) (Management and telemetry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controller["Controller"]
  node_entry["Controller entry<br/>[main.py]"]
  node_app["FastAPI application<br/>[app.py]"]
  node_middleware["Correlation middleware<br/>[correlation.py]"]
  node_api["Versioned API router<br/>[router.py]"]
  node_system["System health API<br/>[router.py]"]
  node_healthschema["Health response schema<br/>[schemas.py]"]
  node_domain["Management and telemetry"]
  node_detection["Anomaly detection"]
  node_incidents["Incidents and policy"]
  node_defense["Defense and recovery"]
end

subgraph group_node["Node runtime"]
  node_agent["Linux node agent<br/>[__init__.py]"]
  node_collection["Resource and network collection<br/>[__init__.py]"]
  node_executor["Local defense executor<br/>[__init__.py]"]
end

subgraph group_shared["Shared services"]
  node_config["Controller settings<br/>[config.py]"]
  node_yaml["YAML configuration<br/>[yaml_loader.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
end

subgraph group_external["External systems"]
  node_lb["HTTP load balancer<br/>[__init__.py]"]
  node_postgres[("PostgreSQL")]
end

node_operator(("Operator"))
node_dashboard["Management dashboard"]

node_operator -.->|"manages"| node_dashboard
node_dashboard -.->|"REST requests"| node_entry
node_dashboard -.->|"WebSocket updates"| node_entry
node_lb -.->|"proxies HTTP"| node_entry
node_entry -->|"loads settings"| node_config
node_entry -->|"creates app"| node_app
node_app -->|"configures logging"| node_logging
node_app -->|"installs"| node_middleware
node_app -->|"mounts"| node_api
node_middleware -->|"dispatches requests"| node_api
node_api -->|"routes health"| node_system
node_system -->|"returns response"| node_healthschema
node_config -.->|"reads YAML"| node_yaml
node_agent -.->|"pushes telemetry"| node_entry
node_collection -.->|"feeds telemetry"| node_agent
node_entry -.->|"manages nodes"| node_domain
node_domain -.->|"stores records"| node_postgres
node_domain -.->|"provides telemetry"| node_detection
node_detection -.->|"raises incidents"| node_incidents
node_incidents -.->|"selects actions"| node_defense
node_defense -.->|"pushes commands"| node_agent
node_agent -.->|"validates and executes"| node_executor

click node_entry "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/main.py"
click node_app "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/app.py"
click node_middleware "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/api/middleware/correlation.py"
click node_api "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/api/v1/router.py"
click node_system "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/modules/system/router.py"
click node_healthschema "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/modules/system/schemas.py"
click node_domain "https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules"
click node_detection "https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules"
click node_incidents "https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules"
click node_defense "https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules"
click node_agent "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py"
click node_collection "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py"
click node_executor "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py"
click node_lb "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_lb/__init__.py"
click node_config "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/config.py"
click node_yaml "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_common/config/yaml_loader.py"
click node_logging "https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_common/observability/logging.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_entry,node_app,node_middleware,node_api,node_system,node_healthschema,node_domain,node_detection,node_incidents,node_defense toneBlue
class node_agent,node_collection,node_executor toneAmber
class node_config,node_yaml,node_logging toneMint
class node_lb,node_postgres toneRose
class node_operator,node_dashboard toneIndigo
```

## Components

### Controller

- [Controller entry](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/main.py): `src/sentinelx_controller/main.py`
- [FastAPI application](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/app.py): `src/sentinelx_controller/app.py`
- [Correlation middleware](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/api/middleware/correlation.py): `src/sentinelx_controller/api/middleware/correlation.py`
- [Versioned API router](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/api/v1/router.py): `src/sentinelx_controller/api/v1/router.py`
- [System health API](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/modules/system/router.py): `src/sentinelx_controller/modules/system/router.py`
- [Health response schema](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/modules/system/schemas.py): `src/sentinelx_controller/modules/system/schemas.py`
- [Management and telemetry](https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules): `src/sentinelx_controller/modules`
- [Anomaly detection](https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules): `src/sentinelx_controller/modules`
- [Incidents and policy](https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules): `src/sentinelx_controller/modules`
- [Defense and recovery](https://github.com/namtrungdn310/sentinelx/tree/main/src/sentinelx_controller/modules): `src/sentinelx_controller/modules`

### Node runtime

- [Linux node agent](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py): `src/sentinelx_agent/__init__.py`
- [Resource and network collection](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py): `src/sentinelx_agent/__init__.py`
- [Local defense executor](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_agent/__init__.py): `src/sentinelx_agent/__init__.py`

### Shared services

- [Controller settings](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_controller/config.py): `src/sentinelx_controller/config.py`
- [YAML configuration](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_common/config/yaml_loader.py): `src/sentinelx_common/config/yaml_loader.py`
- [Structured logging](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_common/observability/logging.py): `src/sentinelx_common/observability/logging.py`

### External systems

- [HTTP load balancer](https://github.com/namtrungdn310/sentinelx/blob/main/src/sentinelx_lb/__init__.py): `src/sentinelx_lb/__init__.py`
- **PostgreSQL**

### Other components

- **Operator**
- **Management dashboard**

## Connections

- Operator → Management dashboard: manages
- Management dashboard → Controller entry: REST requests
- Management dashboard → Controller entry: WebSocket updates
- HTTP load balancer → Controller entry: proxies HTTP
- Controller entry → Controller settings: loads settings
- Controller entry → FastAPI application: creates app
- FastAPI application → Structured logging: configures logging
- FastAPI application → Correlation middleware: installs
- FastAPI application → Versioned API router: mounts
- Correlation middleware → Versioned API router: dispatches requests
- Versioned API router → System health API: routes health
- System health API → Health response schema: returns response
- Controller settings → YAML configuration: reads YAML
- Linux node agent → Controller entry: pushes telemetry
- Resource and network collection → Linux node agent: feeds telemetry
- Controller entry → Management and telemetry: manages nodes
- Management and telemetry → PostgreSQL: stores records
- Management and telemetry → Anomaly detection: provides telemetry
- Anomaly detection → Incidents and policy: raises incidents
- Incidents and policy → Defense and recovery: selects actions
- Defense and recovery → Linux node agent: pushes commands
- Linux node agent → Local defense executor: validates and executes