# kneranjan/unifra architecture

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

- Interactive diagram: https://gitdiagram.com/kneranjan/unifra
- Repository: https://github.com/kneranjan/unifra

## Overview

Unifra discovers network hosts, enriches them with port/OS scans, records gateway links, and inventories Docker containers; a periodic scan coordinator persists these results for API queries and topology output. The API also exposes basic item CRUD and a topology-view page. The graph separates discovery, scan orchestration, API presentation, and persistence. Source excerpts show the scan and API paths; the README is empty, and the topology HTML contents were not sampled, so no browser-to-topology-data link is asserted.

Main entry points: [`app/discovery_agent/storage.py`](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py) (Scan Coordinator), [`app/main.py`](https://github.com/kneranjan/unifra/blob/main/app/main.py) (REST API), [`app/database.py`](https://github.com/kneranjan/unifra/blob/main/app/database.py) (Database Sessions), [`app/models.py`](https://github.com/kneranjan/unifra/blob/main/app/models.py) (ORM Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery"]
  node_host_discovery["Host Discovery<br/>[scan.py]"]
  node_port_scan["Port and OS Scan<br/>[scan.py]"]
  node_container_discovery["Container Discovery<br/>[docker_scan.py]"]
end

subgraph group_scan["Scan Processing"]
  node_scan_coordinator["Scan Coordinator<br/>[storage.py]"]
  node_host_updates["Host and Link Updates<br/>[storage.py]"]
  node_container_updates["Container Updates<br/>[storage.py]"]
end

subgraph group_api["API Presentation"]
  node_api_routes["REST API<br/>[main.py]"]
  node_topology_page["Topology Page<br/>[topology.html]"]
end

subgraph group_persistence["Persistence"]
  node_session_layer["Database Sessions<br/>[database.py]"]
  node_orm_models["ORM Models<br/>[models.py]"]
  node_database_store[("Application Data")]
end

node_operator(("API Client"))
node_network{{"Scanned Network"}}
node_docker{{"Docker Engine"}}
node_postgres[("PostgreSQL")]

node_operator -->|"calls endpoints"| node_api_routes
node_api_routes -->|"gets sessions"| node_session_layer
node_api_routes -->|"queries and writes"| node_orm_models
node_api_routes -->|"serves page"| node_topology_page
node_scan_coordinator -->|"discovers hosts"| node_host_discovery
node_scan_coordinator -->|"scans ports"| node_port_scan
node_scan_coordinator -->|"discovers containers"| node_container_discovery
node_host_discovery -->|"probes hosts"| node_network
node_port_scan -->|"probes ports"| node_network
node_container_discovery -->|"lists containers"| node_docker
node_scan_coordinator -->|"runs host updates"| node_host_updates
node_scan_coordinator -->|"runs container updates"| node_container_updates
node_host_updates -->|"opens sessions"| node_session_layer
node_host_updates -->|"reads and writes"| node_orm_models
node_container_updates -->|"opens sessions"| node_session_layer
node_container_updates -->|"reads and writes"| node_orm_models
node_session_layer -->|"connects to"| node_postgres
node_orm_models -->|"uses base"| node_session_layer
node_api_routes -->|"reads and writes"| node_database_store
node_host_updates -->|"persists scan results"| node_database_store
node_container_updates -->|"persists inventory"| node_database_store

click node_host_discovery "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/scan.py"
click node_port_scan "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/scan.py"
click node_container_discovery "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/docker_scan.py"
click node_scan_coordinator "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py"
click node_host_updates "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py"
click node_container_updates "https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py"
click node_api_routes "https://github.com/kneranjan/unifra/blob/main/app/main.py"
click node_topology_page "https://github.com/kneranjan/unifra/blob/main/app/topology.html"
click node_session_layer "https://github.com/kneranjan/unifra/blob/main/app/database.py"
click node_orm_models "https://github.com/kneranjan/unifra/blob/main/app/models.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_host_discovery,node_port_scan,node_container_discovery,node_operator toneBlue
class node_scan_coordinator,node_host_updates,node_container_updates,node_postgres toneAmber
class node_api_routes,node_topology_page toneMint
class node_session_layer,node_orm_models,node_database_store toneRose
class node_network,node_docker toneIndigo
```

## Components

### Discovery

- [Host Discovery](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/scan.py): `app/discovery_agent/scan.py`
- [Port and OS Scan](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/scan.py): `app/discovery_agent/scan.py`
- [Container Discovery](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/docker_scan.py): `app/discovery_agent/docker_scan.py`

### Scan Processing

- [Scan Coordinator](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py): `app/discovery_agent/storage.py`
- [Host and Link Updates](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py): `app/discovery_agent/storage.py`
- [Container Updates](https://github.com/kneranjan/unifra/blob/main/app/discovery_agent/storage.py): `app/discovery_agent/storage.py`

### API Presentation

- [REST API](https://github.com/kneranjan/unifra/blob/main/app/main.py): `app/main.py`
- [Topology Page](https://github.com/kneranjan/unifra/blob/main/app/topology.html): `app/topology.html`

### Persistence

- [Database Sessions](https://github.com/kneranjan/unifra/blob/main/app/database.py): `app/database.py`
- [ORM Models](https://github.com/kneranjan/unifra/blob/main/app/models.py): `app/models.py`
- **Application Data**

### Other components

- **API Client**
- **Scanned Network**
- **Docker Engine**
- **PostgreSQL**

## Connections

- API Client → REST API: calls endpoints (evidence: `app/main.py`)
- REST API → Database Sessions: gets sessions (evidence: `app/main.py`)
- REST API → ORM Models: queries and writes (evidence: `app/main.py`)
- REST API → Topology Page: serves page (evidence: `app/main.py`)
- Scan Coordinator → Host Discovery: discovers hosts (evidence: `app/discovery_agent/storage.py`)
- Scan Coordinator → Port and OS Scan: scans ports (evidence: `app/discovery_agent/storage.py`)
- Scan Coordinator → Container Discovery: discovers containers (evidence: `app/discovery_agent/storage.py`)
- Host Discovery → Scanned Network: probes hosts (evidence: `app/discovery_agent/scan.py`)
- Port and OS Scan → Scanned Network: probes ports (evidence: `app/discovery_agent/scan.py`)
- Container Discovery → Docker Engine: lists containers (evidence: `app/discovery_agent/docker_scan.py`)
- Scan Coordinator → Host and Link Updates: runs host updates (evidence: `app/discovery_agent/storage.py`)
- Scan Coordinator → Container Updates: runs container updates (evidence: `app/discovery_agent/storage.py`)
- Host and Link Updates → Database Sessions: opens sessions (evidence: `app/discovery_agent/storage.py`)
- Host and Link Updates → ORM Models: reads and writes (evidence: `app/discovery_agent/storage.py`)
- Container Updates → Database Sessions: opens sessions (evidence: `app/discovery_agent/storage.py`)
- Container Updates → ORM Models: reads and writes (evidence: `app/discovery_agent/storage.py`)
- Database Sessions → PostgreSQL: connects to (evidence: `app/database.py`)
- ORM Models → Database Sessions: uses base (evidence: `app/models.py`)
- REST API → Application Data: reads and writes (evidence: `app/main.py`)
- Host and Link Updates → Application Data: persists scan results (evidence: `app/discovery_agent/storage.py`)
- Container Updates → Application Data: persists inventory (evidence: `app/discovery_agent/storage.py`)
