# kaiden-bell/rootmap architecture

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

- Interactive diagram: https://gitdiagram.com/kaiden-bell/rootmap
- Repository: https://github.com/kaiden-bell/rootmap

## Overview

RootMap is a Linux host-inventory and dependency-mapping application, organized around a head-node API, a host agent, and a web dashboard. The demonstrated collection flow gathers host identity and OS/network details, posts a report to the backend, and stores host records; the dashboard can also list and add hosts and supports login/password change. Service-version and configuration collection is present as a separate agent capability, but the shown agent entry point sends only system information. Scheduling, script synchronization, and dependency-visualization processing are README goals not substantiated by the sampled runtime. Edges reflect shown calls, HTTP requests, or documented interactions.

Main entry points: [`backend/main.py`](https://github.com/kaiden-bell/rootmap/blob/main/backend/main.py) (API and account handling), [`frontend/src/App.tsx`](https://github.com/kaiden-bell/rootmap/blob/main/frontend/src/App.tsx) (Login and host dashboard), [`backend/src/db/connection.py`](https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/connection.py) (PostgreSQL connector), [`client/src/rootmap_client/main.py`](https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/main.py) (Collection entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host Agent"]
  node_client_main["Collection entry point<br/>[main.py]"]
  node_system_collector["System information<br/>[host.py]"]
  node_service_collector["Service/config inventory<br/>[service.py]"]
end

subgraph group_api["Head Node API"]
  node_backend_api["API and account handling<br/>[main.py]"]
end

subgraph group_storage["Persistence"]
  node_db_init["Schema initialization<br/>[init_db.py]"]
  node_db_connection["PostgreSQL connector<br/>[connection.py]"]
  node_schema["Database schema<br/>[schema.sql]"]
end

subgraph group_dashboard["Web Dashboard"]
  node_web_app["Login and host dashboard<br/>[App.tsx]"]
  node_host_table["Host table<br/>[App.tsx]"]
end

node_operator(("Dashboard user"))
node_linux(("Linux host"))
node_postgres[("PostgreSQL")]
node_browser(("Dashboard operator"))

node_linux -->|"provides host data"| node_system_collector
node_client_main -->|"collects system info"| node_system_collector
node_client_main -->|"posts report"| node_backend_api
node_backend_api -->|"opens connections"| node_db_connection
node_backend_api -->|"reads/writes hosts and users"| node_postgres
node_db_init -->|"connects through"| node_db_connection
node_db_init -->|"executes schema"| node_schema
node_db_connection -->|"connects to"| node_postgres
node_web_app -->|"requests API data"| node_backend_api
node_web_app -->|"renders hosts"| node_host_table
node_browser -.->|"uses dashboard"| node_web_app
node_operator -.->|"manages hosts"| node_web_app

click node_client_main "https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/main.py"
click node_system_collector "https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/scripts/host.py"
click node_service_collector "https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/scripts/service.py"
click node_backend_api "https://github.com/kaiden-bell/rootmap/blob/main/backend/main.py"
click node_db_init "https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/init_db.py"
click node_db_connection "https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/connection.py"
click node_schema "https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/schema.sql"
click node_web_app "https://github.com/kaiden-bell/rootmap/blob/main/frontend/src/App.tsx"
click node_host_table "https://github.com/kaiden-bell/rootmap/blob/main/frontend/src/App.tsx"

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_client_main,node_system_collector,node_service_collector,node_operator toneBlue
class node_backend_api,node_postgres toneAmber
class node_db_init,node_db_connection,node_schema toneMint
class node_web_app,node_host_table toneRose
class node_linux,node_browser toneIndigo
```

## Components

### Host Agent

- [Collection entry point](https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/main.py): `client/src/rootmap_client/main.py`
- [System information](https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/scripts/host.py): `client/src/rootmap_client/scripts/host.py`
- [Service/config inventory](https://github.com/kaiden-bell/rootmap/blob/main/client/src/rootmap_client/scripts/service.py): `client/src/rootmap_client/scripts/service.py`

### Head Node API

- [API and account handling](https://github.com/kaiden-bell/rootmap/blob/main/backend/main.py): `backend/main.py`

### Persistence

- [Schema initialization](https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/init_db.py): `backend/src/db/init_db.py`
- [PostgreSQL connector](https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/connection.py): `backend/src/db/connection.py`
- [Database schema](https://github.com/kaiden-bell/rootmap/blob/main/backend/src/db/schema.sql): `backend/src/db/schema.sql`

### Web Dashboard

- [Login and host dashboard](https://github.com/kaiden-bell/rootmap/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Host table](https://github.com/kaiden-bell/rootmap/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Other components

- **Dashboard user**
- **Linux host**
- **PostgreSQL**
- **Dashboard operator**

## Connections

- Linux host → System information: provides host data (evidence: `client/src/rootmap_client/scripts/host.py`)
- Collection entry point → System information: collects system info (evidence: `client/src/rootmap_client/main.py`)
- Collection entry point → API and account handling: posts report (evidence: `client/src/rootmap_client/main.py`)
- API and account handling → PostgreSQL connector: opens connections (evidence: `backend/main.py`)
- API and account handling → PostgreSQL: reads/writes hosts and users (evidence: `backend/main.py`)
- Schema initialization → PostgreSQL connector: connects through (evidence: `backend/src/db/init_db.py`)
- Schema initialization → Database schema: executes schema (evidence: `backend/src/db/init_db.py`)
- PostgreSQL connector → PostgreSQL: connects to (evidence: `backend/src/db/connection.py`)
- Login and host dashboard → API and account handling: requests API data (evidence: `frontend/src/App.tsx`)
- Login and host dashboard → Host table: renders hosts (evidence: `frontend/src/App.tsx`)
- Dashboard operator → Login and host dashboard: uses dashboard (evidence: `README.md`)
- Dashboard user → Login and host dashboard: manages hosts (evidence: `README.md`)
