# novaforgectrl/lums architecture

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

- Interactive diagram: https://gitdiagram.com/novaforgectrl/lums
- Repository: https://github.com/novaforgectrl/lums

## Overview

LUMS centrally manages Linux clients: administrators inspect inventory and updates, authorize package work, monitor jobs, and review outcomes; agents run approved operations through APT/dpkg or pacman and report results. The graph preserves the documented client/update/job workflow alongside authentication and audit, the SOC event-analysis capability, and backup/alerts. Some feature links are README-documented rather than verified in sampled runtime code; SOC worker links follow its excerpted orchestration references.

Main entry points: [`server/app.py`](https://github.com/novaforgectrl/lums/blob/main/server/app.py) (Server API and UI), [`server/soc/pipeline.py`](https://github.com/novaforgectrl/lums/blob/main/server/soc/pipeline.py) (Event analysis pipeline), [`server/soc/worker.py`](https://github.com/novaforgectrl/lums/blob/main/server/soc/worker.py) (SOC worker), [`agent/agent.py`](https://github.com/novaforgectrl/lums/blob/main/agent/agent.py) (Client agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Update management"]
  node_webapp["Server API and UI<br/>[app.py]"]
  node_clients["Client management"]
  node_inventory["Software inventory<br/>[app.py]"]
  node_updates["Update inventory<br/>[app.py]"]
  node_jobs["Update jobs"]
  node_agent["Client agent<br/>[agent.py]"]
  node_package["Package managers<br/>[package_manager.py]"]
  node_watcher["Client watcher<br/>[watcher.py]"]
end

subgraph group_identity["Identity and audit"]
  node_auth["Authentication and security<br/>[security.py]"]
  node_rbac["Roles and permissions<br/>[postgres_rbac.py]"]
  node_audit["Audit logging<br/>[postgres_audit.py]"]
end

subgraph group_soc["Security operations"]
  node_socroutes["SOC API and pages<br/>[routes.py]"]
  node_collector["Event collector<br/>[collector_api.py]"]
  node_inbox[("Event inbox store<br/>[collector_store.py]")]
  node_worker["SOC worker<br/>[worker.py]"]
  node_pipeline["Event analysis pipeline<br/>[pipeline.py]"]
  node_ingestion["Event validation<br/>[ingestion.py]"]
  node_dedup["Deduplication<br/>[deduplication.py]"]
  node_detection["Detection rules<br/>[detection.py]"]
  node_correlation["Event correlation<br/>[correlation.py]"]
  node_incidents[("Incident store<br/>[incident_store.py]")]
end

subgraph group_operations["Operations"]
  node_alerts["Alert management<br/>[alerts.py]"]
  node_alertapi["Alert routes<br/>[alerts_routes.py]"]
  node_backup["Database backup<br/>[database_backup.py]"]
  node_database[("Application database<br/>[db.py]")]
end

node_admin(("Administrator"))
node_browser(("Web interface"))
node_linux["Linux package tools"]

node_admin -->|"uses"| node_browser
node_browser -->|"requests"| node_webapp
node_webapp -.->|"manages clients"| node_clients
node_webapp -.->|"serves inventory"| node_inventory
node_webapp -.->|"serves updates"| node_updates
node_webapp -.->|"creates jobs"| node_jobs
node_jobs -.->|"dispatches jobs"| node_agent
node_agent -->|"executes actions"| node_package
node_agent -->|"uses watcher"| node_watcher
node_package -->|"runs package tools"| node_linux
node_webapp -->|"authenticates requests"| node_auth
node_webapp -.->|"checks permissions"| node_rbac
node_webapp -.->|"records actions"| node_audit
node_webapp -.->|"persists state"| node_database
node_socroutes -->|"reads dashboard data"| node_inbox
node_collector -.->|"stores events"| node_inbox
node_worker -->|"claims events"| node_inbox
node_worker -->|"processes events"| node_pipeline
node_pipeline -->|"validates events"| node_ingestion
node_pipeline -->|"deduplicates events"| node_dedup
node_pipeline -->|"evaluates rules"| node_detection
node_pipeline -->|"correlates events"| node_correlation
node_worker -->|"finalizes incidents"| node_incidents
node_alertapi -->|"manages alerts"| node_alerts
node_webapp -->|"uses backups"| node_backup

click node_webapp "https://github.com/novaforgectrl/lums/blob/main/server/app.py"
click node_clients "https://github.com/novaforgectrl/lums/blob/main/server/postgres_clients.py"
click node_inventory "https://github.com/novaforgectrl/lums/blob/main/server/app.py"
click node_updates "https://github.com/novaforgectrl/lums/blob/main/server/app.py"
click node_jobs "https://github.com/novaforgectrl/lums/blob/main/server/postgres_update_jobs.py"
click node_agent "https://github.com/novaforgectrl/lums/blob/main/agent/agent.py"
click node_package "https://github.com/novaforgectrl/lums/blob/main/agent/package_manager.py"
click node_watcher "https://github.com/novaforgectrl/lums/blob/main/agent/watcher.py"
click node_auth "https://github.com/novaforgectrl/lums/blob/main/server/security.py"
click node_rbac "https://github.com/novaforgectrl/lums/blob/main/server/postgres_rbac.py"
click node_audit "https://github.com/novaforgectrl/lums/blob/main/server/postgres_audit.py"
click node_socroutes "https://github.com/novaforgectrl/lums/blob/main/server/soc/routes.py"
click node_collector "https://github.com/novaforgectrl/lums/blob/main/server/soc/collector_api.py"
click node_inbox "https://github.com/novaforgectrl/lums/blob/main/server/soc/collector_store.py"
click node_worker "https://github.com/novaforgectrl/lums/blob/main/server/soc/worker.py"
click node_pipeline "https://github.com/novaforgectrl/lums/blob/main/server/soc/pipeline.py"
click node_ingestion "https://github.com/novaforgectrl/lums/blob/main/server/soc/ingestion.py"
click node_dedup "https://github.com/novaforgectrl/lums/blob/main/server/soc/deduplication.py"
click node_detection "https://github.com/novaforgectrl/lums/blob/main/server/soc/detection.py"
click node_correlation "https://github.com/novaforgectrl/lums/blob/main/server/soc/correlation.py"
click node_incidents "https://github.com/novaforgectrl/lums/blob/main/server/soc/incident_store.py"
click node_alerts "https://github.com/novaforgectrl/lums/blob/main/server/alerts.py"
click node_alertapi "https://github.com/novaforgectrl/lums/blob/main/server/alerts_routes.py"
click node_backup "https://github.com/novaforgectrl/lums/blob/main/server/database_backup.py"
click node_database "https://github.com/novaforgectrl/lums/blob/main/server/db.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_webapp,node_clients,node_inventory,node_updates,node_jobs,node_agent,node_package,node_watcher toneBlue
class node_auth,node_rbac,node_audit toneAmber
class node_socroutes,node_collector,node_inbox,node_worker,node_pipeline,node_ingestion,node_dedup,node_detection,node_correlation,node_incidents toneMint
class node_alerts,node_alertapi,node_backup,node_database toneRose
class node_admin,node_browser,node_linux toneIndigo
```

## Components

### Update management

- [Server API and UI](https://github.com/novaforgectrl/lums/blob/main/server/app.py): `server/app.py`
- [Client management](https://github.com/novaforgectrl/lums/blob/main/server/postgres_clients.py): `server/postgres_clients.py`
- [Software inventory](https://github.com/novaforgectrl/lums/blob/main/server/app.py): `server/app.py`
- [Update inventory](https://github.com/novaforgectrl/lums/blob/main/server/app.py): `server/app.py`
- [Update jobs](https://github.com/novaforgectrl/lums/blob/main/server/postgres_update_jobs.py): `server/postgres_update_jobs.py`
- [Client agent](https://github.com/novaforgectrl/lums/blob/main/agent/agent.py): `agent/agent.py`
- [Package managers](https://github.com/novaforgectrl/lums/blob/main/agent/package_manager.py): `agent/package_manager.py`
- [Client watcher](https://github.com/novaforgectrl/lums/blob/main/agent/watcher.py): `agent/watcher.py`

### Identity and audit

- [Authentication and security](https://github.com/novaforgectrl/lums/blob/main/server/security.py): `server/security.py`
- [Roles and permissions](https://github.com/novaforgectrl/lums/blob/main/server/postgres_rbac.py): `server/postgres_rbac.py`
- [Audit logging](https://github.com/novaforgectrl/lums/blob/main/server/postgres_audit.py): `server/postgres_audit.py`

### Security operations

- [SOC API and pages](https://github.com/novaforgectrl/lums/blob/main/server/soc/routes.py): `server/soc/routes.py`
- [Event collector](https://github.com/novaforgectrl/lums/blob/main/server/soc/collector_api.py): `server/soc/collector_api.py`
- [Event inbox store](https://github.com/novaforgectrl/lums/blob/main/server/soc/collector_store.py): `server/soc/collector_store.py`
- [SOC worker](https://github.com/novaforgectrl/lums/blob/main/server/soc/worker.py): `server/soc/worker.py`
- [Event analysis pipeline](https://github.com/novaforgectrl/lums/blob/main/server/soc/pipeline.py): `server/soc/pipeline.py`
- [Event validation](https://github.com/novaforgectrl/lums/blob/main/server/soc/ingestion.py): `server/soc/ingestion.py`
- [Deduplication](https://github.com/novaforgectrl/lums/blob/main/server/soc/deduplication.py): `server/soc/deduplication.py`
- [Detection rules](https://github.com/novaforgectrl/lums/blob/main/server/soc/detection.py): `server/soc/detection.py`
- [Event correlation](https://github.com/novaforgectrl/lums/blob/main/server/soc/correlation.py): `server/soc/correlation.py`
- [Incident store](https://github.com/novaforgectrl/lums/blob/main/server/soc/incident_store.py): `server/soc/incident_store.py`

### Operations

- [Alert management](https://github.com/novaforgectrl/lums/blob/main/server/alerts.py): `server/alerts.py`
- [Alert routes](https://github.com/novaforgectrl/lums/blob/main/server/alerts_routes.py): `server/alerts_routes.py`
- [Database backup](https://github.com/novaforgectrl/lums/blob/main/server/database_backup.py): `server/database_backup.py`
- [Application database](https://github.com/novaforgectrl/lums/blob/main/server/db.py): `server/db.py`

### Other components

- **Administrator**
- **Web interface**
- **Linux package tools**

## Connections

- Administrator → Web interface: uses (evidence: `README.md`)
- Web interface → Server API and UI: requests (evidence: `README.md`)
- Server API and UI → Client management: manages clients
- Server API and UI → Software inventory: serves inventory (evidence: `server/app.py`)
- Server API and UI → Update inventory: serves updates (evidence: `server/app.py`)
- Server API and UI → Update jobs: creates jobs
- Update jobs → Client agent: dispatches jobs
- Client agent → Package managers: executes actions (evidence: `agent/agent.py`)
- Client agent → Client watcher: uses watcher (evidence: `agent/watcher.py`)
- Package managers → Linux package tools: runs package tools (evidence: `agent/package_manager.py`)
- Server API and UI → Authentication and security: authenticates requests (evidence: `server/app.py`)
- Server API and UI → Roles and permissions: checks permissions
- Server API and UI → Audit logging: records actions
- Server API and UI → Application database: persists state
- SOC API and pages → Event inbox store: reads dashboard data (evidence: `server/soc/routes.py`)
- Event collector → Event inbox store: stores events
- SOC worker → Event inbox store: claims events (evidence: `server/soc/worker.py`)
- SOC worker → Event analysis pipeline: processes events (evidence: `server/soc/worker.py`)
- Event analysis pipeline → Event validation: validates events (evidence: `server/soc/pipeline.py`)
- Event analysis pipeline → Deduplication: deduplicates events (evidence: `server/soc/pipeline.py`)
- Event analysis pipeline → Detection rules: evaluates rules (evidence: `server/soc/pipeline.py`)
- Event analysis pipeline → Event correlation: correlates events (evidence: `server/soc/pipeline.py`)
- SOC worker → Incident store: finalizes incidents (evidence: `server/soc/worker.py`)
- Alert routes → Alert management: manages alerts (evidence: `server/alerts_routes.py`)
- Server API and UI → Database backup: uses backups (evidence: `server/app.py`)