# maarckz/inventory architecture

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

- Interactive diagram: https://gitdiagram.com/maarckz/inventory
- Repository: https://github.com/maarckz/inventory

## Overview

INVENTORY is a Flask-based corporate asset inventory and security-operations application. Its primary workflow gathers Wazuh agent telemetry and independently discovers agentless network devices, persists both inventory domains, then serves dashboards, machine records, topology documentation, alerts, reports, and AI assistance to authenticated users. The map preserves those distinct stages and the NetScope discovery/documentation branches. Some subsystems are documented or named in the source index but were not sampled; their links are included only where README or indexed references support them.

Main entry points: [`routes/netscope.py`](https://github.com/maarckz/inventory/blob/main/routes/netscope.py) (Topology API), [`core/app.py`](https://github.com/maarckz/inventory/blob/main/core/app.py) (Flask app), [`services/netscope_core.py`](https://github.com/maarckz/inventory/blob/main/services/netscope_core.py) (Device documentation), [`models.py`](https://github.com/maarckz/inventory/blob/main/models.py) (Data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Flask app<br/>[app.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_machine_ui["Machine records<br/>[machines.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

subgraph group_inventory["Wazuh inventory"]
  node_collector["Wazuh collector<br/>[collector.py]"]
end

subgraph group_netscope["NetScope topology"]
  node_netscope_routes["Topology API<br/>[netscope.py]"]
  node_discovery["Network discovery"]
  node_scan_engine["Scan engine<br/>[netscope_engine.py]"]
  node_device_store["Device documentation<br/>[netscope_core.py]"]
  node_wazuh_bridge["Agent bridge"]
  node_snapshots["Topology snapshots"]
  node_switches["Switch mapping"]
  node_portscan["Port scanning"]
  node_export["Topology export<br/>[netscope_export.py]"]
end

subgraph group_insights["Analysis and alerts"]
  node_stats["Inventory statistics<br/>[stats.py]"]
  node_notifications["Notification center<br/>[notifications.py]"]
  node_assistant_route["Assistant API<br/>[assistant.py]"]
  node_assistant["AI assistant<br/>[assistant.py]"]
  node_pdf["PDF reports<br/>[pdf_export.py]"]
end

subgraph group_platform["Persistence and services"]
  node_models["Data models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_cache["Cache<br/>[cache.py]"]
end

node_operator(("IT operator"))
node_wazuh["Wazuh Manager"]
node_network(("Local network"))
node_redis[("Redis")]

node_operator -->|"uses"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_dashboard
node_app -->|"registers routes"| node_machine_ui
node_app -->|"registers routes"| node_settings
node_app -->|"registers blueprint"| node_netscope_routes
node_app -->|"registers blueprint"| node_assistant_route
node_wazuh -->|"supplies telemetry"| node_collector
node_collector -->|"persists inventory"| node_postgres
node_netscope_routes -->|"invokes scans"| node_scan_engine
node_netscope_routes -->|"uses device store"| node_device_store
node_netscope_routes -->|"uses discovery"| node_discovery
node_netscope_routes -->|"uses agent bridge"| node_wazuh_bridge
node_netscope_routes -->|"uses snapshots"| node_snapshots
node_netscope_routes -->|"uses switch mapping"| node_switches
node_netscope_routes -->|"uses port scans"| node_portscan
node_netscope_routes -->|"uses export"| node_export
node_network -->|"provides hosts"| node_discovery
node_scan_engine -->|"records scan results"| node_device_store
node_scan_engine -->|"syncs agents"| node_wazuh_bridge
node_discovery -->|"updates devices"| node_device_store
node_wazuh_bridge -->|"merges agent data"| node_device_store
node_device_store -->|"queries device records"| node_models
node_dashboard -->|"loads statistics"| node_stats
node_dashboard -->|"loads topology data"| node_device_store
node_machine_ui -->|"uses inventory helpers"| node_stats
node_assistant_route -->|"delegates requests"| node_assistant
node_assistant -->|"reads host and chat data"| node_models
node_assistant -->|"uses network context"| node_device_store
node_operator -->|"receives alerts"| node_notifications
node_notifications -->|"checks network conflicts"| node_device_store
node_notifications -->|"stores alert settings"| node_models
node_operator -->|"requests reports"| node_pdf
node_settings -->|"exports reports"| node_pdf
node_stats -->|"queries inventory"| node_models
node_models -->|"maps relational records"| node_postgres
node_dashboard -->|"caches dashboard data"| node_cache
node_cache -.->|"uses when configured"| node_redis

click node_app "https://github.com/maarckz/inventory/blob/main/core/app.py"
click node_auth "https://github.com/maarckz/inventory/blob/main/routes/auth.py"
click node_machine_ui "https://github.com/maarckz/inventory/blob/main/routes/machines.py"
click node_dashboard "https://github.com/maarckz/inventory/blob/main/routes/dashboard.py"
click node_settings "https://github.com/maarckz/inventory/blob/main/routes/settings.py"
click node_collector "https://github.com/maarckz/inventory/blob/main/utils/collector.py"
click node_netscope_routes "https://github.com/maarckz/inventory/blob/main/routes/netscope.py"
click node_discovery "https://github.com/maarckz/inventory/blob/main/services/netscope_discovery.py"
click node_scan_engine "https://github.com/maarckz/inventory/blob/main/services/netscope_engine.py"
click node_device_store "https://github.com/maarckz/inventory/blob/main/services/netscope_core.py"
click node_wazuh_bridge "https://github.com/maarckz/inventory/blob/main/services/netscope_wazuh_bridge.py"
click node_snapshots "https://github.com/maarckz/inventory/blob/main/services/netscope_snapshots.py"
click node_switches "https://github.com/maarckz/inventory/blob/main/services/netscope_switches.py"
click node_portscan "https://github.com/maarckz/inventory/blob/main/services/netscope_portscan.py"
click node_export "https://github.com/maarckz/inventory/blob/main/services/netscope_export.py"
click node_stats "https://github.com/maarckz/inventory/blob/main/services/stats.py"
click node_notifications "https://github.com/maarckz/inventory/blob/main/services/notifications.py"
click node_assistant_route "https://github.com/maarckz/inventory/blob/main/routes/assistant.py"
click node_assistant "https://github.com/maarckz/inventory/blob/main/services/assistant.py"
click node_pdf "https://github.com/maarckz/inventory/blob/main/utils/pdf_export.py"
click node_models "https://github.com/maarckz/inventory/blob/main/models.py"
click node_cache "https://github.com/maarckz/inventory/blob/main/utils/cache.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_app,node_auth,node_machine_ui,node_dashboard,node_settings toneBlue
class node_collector,node_redis toneAmber
class node_netscope_routes,node_discovery,node_scan_engine,node_device_store,node_wazuh_bridge,node_snapshots,node_switches,node_portscan,node_export toneMint
class node_stats,node_notifications,node_assistant_route,node_assistant,node_pdf toneRose
class node_models,node_postgres,node_cache,node_operator,node_wazuh,node_network toneIndigo
```

## Components

### Web application

- [Flask app](https://github.com/maarckz/inventory/blob/main/core/app.py): `core/app.py`
- [Authentication](https://github.com/maarckz/inventory/blob/main/routes/auth.py): `routes/auth.py`
- [Machine records](https://github.com/maarckz/inventory/blob/main/routes/machines.py): `routes/machines.py`
- [Dashboard](https://github.com/maarckz/inventory/blob/main/routes/dashboard.py): `routes/dashboard.py`
- [Settings](https://github.com/maarckz/inventory/blob/main/routes/settings.py): `routes/settings.py`

### Wazuh inventory

- [Wazuh collector](https://github.com/maarckz/inventory/blob/main/utils/collector.py): `utils/collector.py`

### NetScope topology

- [Topology API](https://github.com/maarckz/inventory/blob/main/routes/netscope.py): `routes/netscope.py`
- [Network discovery](https://github.com/maarckz/inventory/blob/main/services/netscope_discovery.py): `services/netscope_discovery.py`
- [Scan engine](https://github.com/maarckz/inventory/blob/main/services/netscope_engine.py): `services/netscope_engine.py`
- [Device documentation](https://github.com/maarckz/inventory/blob/main/services/netscope_core.py): `services/netscope_core.py`
- [Agent bridge](https://github.com/maarckz/inventory/blob/main/services/netscope_wazuh_bridge.py): `services/netscope_wazuh_bridge.py`
- [Topology snapshots](https://github.com/maarckz/inventory/blob/main/services/netscope_snapshots.py): `services/netscope_snapshots.py`
- [Switch mapping](https://github.com/maarckz/inventory/blob/main/services/netscope_switches.py): `services/netscope_switches.py`
- [Port scanning](https://github.com/maarckz/inventory/blob/main/services/netscope_portscan.py): `services/netscope_portscan.py`
- [Topology export](https://github.com/maarckz/inventory/blob/main/services/netscope_export.py): `services/netscope_export.py`

### Analysis and alerts

- [Inventory statistics](https://github.com/maarckz/inventory/blob/main/services/stats.py): `services/stats.py`
- [Notification center](https://github.com/maarckz/inventory/blob/main/services/notifications.py): `services/notifications.py`
- [Assistant API](https://github.com/maarckz/inventory/blob/main/routes/assistant.py): `routes/assistant.py`
- [AI assistant](https://github.com/maarckz/inventory/blob/main/services/assistant.py): `services/assistant.py`
- [PDF reports](https://github.com/maarckz/inventory/blob/main/utils/pdf_export.py): `utils/pdf_export.py`

### Persistence and services

- [Data models](https://github.com/maarckz/inventory/blob/main/models.py): `models.py`
- **PostgreSQL**
- [Cache](https://github.com/maarckz/inventory/blob/main/utils/cache.py): `utils/cache.py`

### Other components

- **IT operator**
- **Wazuh Manager**
- **Local network**
- **Redis**

## Connections

- IT operator → Flask app: uses (evidence: `README.md`)
- Flask app → Authentication: registers routes (evidence: `core/app.py`)
- Flask app → Dashboard: registers routes (evidence: `core/app.py`)
- Flask app → Machine records: registers routes (evidence: `core/app.py`)
- Flask app → Settings: registers routes (evidence: `core/app.py`)
- Flask app → Topology API: registers blueprint (evidence: `core/app.py`)
- Flask app → Assistant API: registers blueprint (evidence: `core/app.py`)
- Wazuh Manager → Wazuh collector: supplies telemetry (evidence: `README.md`)
- Wazuh collector → PostgreSQL: persists inventory (evidence: `README.md`)
- Topology API → Scan engine: invokes scans (evidence: `routes/netscope.py`)
- Topology API → Device documentation: uses device store (evidence: `routes/netscope.py`)
- Topology API → Network discovery: uses discovery (evidence: `routes/netscope.py`)
- Topology API → Agent bridge: uses agent bridge (evidence: `routes/netscope.py`)
- Topology API → Topology snapshots: uses snapshots (evidence: `routes/netscope.py`)
- Topology API → Switch mapping: uses switch mapping (evidence: `routes/netscope.py`)
- Topology API → Port scanning: uses port scans (evidence: `routes/netscope.py`)
- Topology API → Topology export: uses export (evidence: `routes/netscope.py`)
- Local network → Network discovery: provides hosts (evidence: `README.md`)
- Scan engine → Device documentation: records scan results (evidence: `services/netscope_engine.py`)
- Scan engine → Agent bridge: syncs agents (evidence: `services/netscope_engine.py`)
- Network discovery → Device documentation: updates devices (evidence: `services/netscope_discovery.py`)
- Agent bridge → Device documentation: merges agent data (evidence: `services/netscope_wazuh_bridge.py`)
- Device documentation → Data models: queries device records (evidence: `services/netscope_core.py`)
- Dashboard → Inventory statistics: loads statistics (evidence: `routes/dashboard.py`)
- Dashboard → Device documentation: loads topology data (evidence: `routes/dashboard.py`)
- Machine records → Inventory statistics: uses inventory helpers (evidence: `routes/machines.py`)
- Assistant API → AI assistant: delegates requests (evidence: `routes/assistant.py`)
- AI assistant → Data models: reads host and chat data (evidence: `services/assistant.py`)
- AI assistant → Device documentation: uses network context (evidence: `services/assistant.py`)
- IT operator → Notification center: receives alerts (evidence: `README.md`)
- Notification center → Device documentation: checks network conflicts (evidence: `services/notifications.py`)
- Notification center → Data models: stores alert settings (evidence: `services/notifications.py`)
- IT operator → PDF reports: requests reports (evidence: `README.md`)
- Settings → PDF reports: exports reports (evidence: `routes/settings.py`)
- Inventory statistics → Data models: queries inventory (evidence: `services/stats.py`)
- Data models → PostgreSQL: maps relational records (evidence: `README.md`)
- Dashboard → Cache: caches dashboard data (evidence: `routes/dashboard.py`)
- Cache → Redis: uses when configured (evidence: `utils/cache.py`)
