# kianandz/hyperionos architecture

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

- Interactive diagram: https://gitdiagram.com/kianandz/hyperionos
- Repository: https://github.com/kianandz/hyperionos

## Overview

HyperionOS is a browser-based system administration platform. An administrator accesses the FastAPI application, whose registered routes expose monitoring and operational controls; feature handlers use service modules to inspect or change host and application state. The repository also includes database, file, container, network, website, Samba, and tunnel-management capabilities. The graph follows documented router registration and sampled route-to-service calls; several feature internals are unsampled, so their deeper execution paths are not inferred.

Main entry points: [`app/routes/__init__.py`](https://github.com/kianandz/hyperionos/blob/main/app/routes/__init__.py) (Route registry), [`app/core/security.py`](https://github.com/kianandz/hyperionos/blob/main/app/core/security.py) (Session verification), [`app/routes/websites`](https://github.com/kianandz/hyperionos/tree/main/app/routes/websites) (Website management), [`app/routes/files`](https://github.com/kianandz/hyperionos/tree/main/app/routes/files) (File manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry and access"]
  node_app["FastAPI application<br/>[main.py]"]
  node_router["Route registry<br/>[__init__.py]"]
  node_security["Session verification<br/>[security.py]"]
end

subgraph group_monitor["Monitoring and host"]
  node_dashboard["Metrics dashboard"]
  node_metrics["System metrics"]
  node_nodeops["Node management"]
  node_node_services["Node operations"]
  node_settings["System settings"]
  node_settings_services["Settings operations"]
end

subgraph group_workloads["Workload services"]
  node_docker["Docker controls"]
  node_docker_services["Docker operations"]
  node_websites["Website management"]
  node_website_services["Web server operations"]
  node_terminal["Web terminal"]
end

subgraph group_data["Data and files"]
  node_database_routes["Database console"]
  node_database_services["Database operations"]
  node_files_routes["File manager"]
  node_file_services["File operations"]
end

subgraph group_network["Network services"]
  node_samba["Samba management"]
  node_samba_services["Samba operations"]
  node_firewall["Firewall controls"]
  node_firewall_services["Firewall operations"]
  node_tunnel["Cloudflared controls"]
  node_tunnel_services["Cloudflared operations"]
end

node_admin(("Administrator"))

node_admin -->|"accesses"| node_app
node_app -->|"registers routes"| node_router
node_router -->|"registers"| node_dashboard
node_router -->|"registers"| node_nodeops
node_router -->|"registers"| node_settings
node_router -->|"registers"| node_database_routes
node_router -->|"registers"| node_files_routes
node_router -->|"registers"| node_docker
node_router -->|"registers"| node_websites
node_router -->|"registers"| node_samba
node_router -->|"registers"| node_firewall
node_router -->|"registers"| node_tunnel
node_router -->|"registers"| node_terminal
node_dashboard -.->|"reads metrics"| node_metrics
node_nodeops -->|"delegates"| node_node_services
node_settings -->|"delegates"| node_settings_services
node_database_routes -->|"executes query"| node_database_services
node_files_routes -->|"transfers files"| node_file_services
node_docker -.->|"manages containers"| node_docker_services
node_websites -->|"controls services"| node_website_services
node_samba -->|"controls service"| node_samba_services
node_firewall -.->|"manages rules"| node_firewall_services
node_tunnel -->|"starts or stops"| node_tunnel_services
node_files_routes -->|"verifies session"| node_security
node_websites -->|"verifies session"| node_security
node_samba -->|"verifies session"| node_security
node_tunnel -->|"verifies session"| node_security

click node_app "https://github.com/kianandz/hyperionos/blob/main/main.py"
click node_router "https://github.com/kianandz/hyperionos/blob/main/app/routes/__init__.py"
click node_security "https://github.com/kianandz/hyperionos/blob/main/app/core/security.py"
click node_dashboard "https://github.com/kianandz/hyperionos/tree/main/app/routes/dashboard"
click node_metrics "https://github.com/kianandz/hyperionos/tree/main/app/services/metrics"
click node_nodeops "https://github.com/kianandz/hyperionos/tree/main/app/routes/node"
click node_node_services "https://github.com/kianandz/hyperionos/tree/main/app/services/node"
click node_settings "https://github.com/kianandz/hyperionos/tree/main/app/routes/settings"
click node_settings_services "https://github.com/kianandz/hyperionos/tree/main/app/services/settings"
click node_database_routes "https://github.com/kianandz/hyperionos/tree/main/app/routes/database"
click node_database_services "https://github.com/kianandz/hyperionos/tree/main/app/services/database"
click node_files_routes "https://github.com/kianandz/hyperionos/tree/main/app/routes/files"
click node_file_services "https://github.com/kianandz/hyperionos/tree/main/app/services/files"
click node_docker "https://github.com/kianandz/hyperionos/tree/main/app/routes/docker"
click node_docker_services "https://github.com/kianandz/hyperionos/tree/main/app/services/docker"
click node_websites "https://github.com/kianandz/hyperionos/tree/main/app/routes/websites"
click node_website_services "https://github.com/kianandz/hyperionos/tree/main/app/services/website"
click node_samba "https://github.com/kianandz/hyperionos/tree/main/app/routes/samba"
click node_samba_services "https://github.com/kianandz/hyperionos/tree/main/app/services/samba"
click node_firewall "https://github.com/kianandz/hyperionos/tree/main/app/routes/firewall"
click node_firewall_services "https://github.com/kianandz/hyperionos/tree/main/app/services/ufw"
click node_tunnel "https://github.com/kianandz/hyperionos/tree/main/app/routes/cloudflared"
click node_tunnel_services "https://github.com/kianandz/hyperionos/tree/main/app/services/cloudflared"
click node_terminal "https://github.com/kianandz/hyperionos/tree/main/app/routes/terminal"

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_router,node_security toneBlue
class node_dashboard,node_metrics,node_nodeops,node_node_services,node_settings,node_settings_services toneAmber
class node_docker,node_docker_services,node_websites,node_website_services,node_terminal toneMint
class node_database_routes,node_database_services,node_files_routes,node_file_services toneRose
class node_samba,node_samba_services,node_firewall,node_firewall_services,node_tunnel,node_tunnel_services,node_admin toneIndigo
```

## Components

### Web entry and access

- [FastAPI application](https://github.com/kianandz/hyperionos/blob/main/main.py): `main.py`
- [Route registry](https://github.com/kianandz/hyperionos/blob/main/app/routes/__init__.py): `app/routes/__init__.py`
- [Session verification](https://github.com/kianandz/hyperionos/blob/main/app/core/security.py): `app/core/security.py`

### Monitoring and host

- [Metrics dashboard](https://github.com/kianandz/hyperionos/tree/main/app/routes/dashboard): `app/routes/dashboard`
- [System metrics](https://github.com/kianandz/hyperionos/tree/main/app/services/metrics): `app/services/metrics`
- [Node management](https://github.com/kianandz/hyperionos/tree/main/app/routes/node): `app/routes/node`
- [Node operations](https://github.com/kianandz/hyperionos/tree/main/app/services/node): `app/services/node`
- [System settings](https://github.com/kianandz/hyperionos/tree/main/app/routes/settings): `app/routes/settings`
- [Settings operations](https://github.com/kianandz/hyperionos/tree/main/app/services/settings): `app/services/settings`

### Workload services

- [Docker controls](https://github.com/kianandz/hyperionos/tree/main/app/routes/docker): `app/routes/docker`
- [Docker operations](https://github.com/kianandz/hyperionos/tree/main/app/services/docker): `app/services/docker`
- [Website management](https://github.com/kianandz/hyperionos/tree/main/app/routes/websites): `app/routes/websites`
- [Web server operations](https://github.com/kianandz/hyperionos/tree/main/app/services/website): `app/services/website`
- [Web terminal](https://github.com/kianandz/hyperionos/tree/main/app/routes/terminal): `app/routes/terminal`

### Data and files

- [Database console](https://github.com/kianandz/hyperionos/tree/main/app/routes/database): `app/routes/database`
- [Database operations](https://github.com/kianandz/hyperionos/tree/main/app/services/database): `app/services/database`
- [File manager](https://github.com/kianandz/hyperionos/tree/main/app/routes/files): `app/routes/files`
- [File operations](https://github.com/kianandz/hyperionos/tree/main/app/services/files): `app/services/files`

### Network services

- [Samba management](https://github.com/kianandz/hyperionos/tree/main/app/routes/samba): `app/routes/samba`
- [Samba operations](https://github.com/kianandz/hyperionos/tree/main/app/services/samba): `app/services/samba`
- [Firewall controls](https://github.com/kianandz/hyperionos/tree/main/app/routes/firewall): `app/routes/firewall`
- [Firewall operations](https://github.com/kianandz/hyperionos/tree/main/app/services/ufw): `app/services/ufw`
- [Cloudflared controls](https://github.com/kianandz/hyperionos/tree/main/app/routes/cloudflared): `app/routes/cloudflared`
- [Cloudflared operations](https://github.com/kianandz/hyperionos/tree/main/app/services/cloudflared): `app/services/cloudflared`

### Other components

- **Administrator**

## Connections

- Administrator → FastAPI application: accesses (evidence: `README.md`)
- FastAPI application → Route registry: registers routes (evidence: `main.py`)
- Route registry → Metrics dashboard: registers (evidence: `app/routes/__init__.py`)
- Route registry → Node management: registers (evidence: `app/routes/__init__.py`)
- Route registry → System settings: registers (evidence: `app/routes/__init__.py`)
- Route registry → Database console: registers (evidence: `app/routes/__init__.py`)
- Route registry → File manager: registers (evidence: `app/routes/__init__.py`)
- Route registry → Docker controls: registers (evidence: `app/routes/__init__.py`)
- Route registry → Website management: registers (evidence: `app/routes/__init__.py`)
- Route registry → Samba management: registers (evidence: `app/routes/__init__.py`)
- Route registry → Firewall controls: registers (evidence: `app/routes/__init__.py`)
- Route registry → Cloudflared controls: registers (evidence: `app/routes/__init__.py`)
- Route registry → Web terminal: registers (evidence: `app/routes/__init__.py`)
- Metrics dashboard → System metrics: reads metrics
- Node management → Node operations: delegates (evidence: `app/routes/node/project_route.py`)
- System settings → Settings operations: delegates (evidence: `app/routes/settings/system_route.py`)
- Database console → Database operations: executes query (evidence: `app/routes/database/query_route.py`)
- File manager → File operations: transfers files (evidence: `app/routes/files/transfer_route.py`)
- Docker controls → Docker operations: manages containers (evidence: `app/services/docker/client.py`)
- Website management → Web server operations: controls services (evidence: `app/routes/websites/service_route.py`)
- Samba management → Samba operations: controls service (evidence: `app/routes/samba/service_route.py`)
- Firewall controls → Firewall operations: manages rules
- Cloudflared controls → Cloudflared operations: starts or stops (evidence: `app/routes/cloudflared/service_route.py`)
- File manager → Session verification: verifies session (evidence: `app/routes/files/transfer_route.py`)
- Website management → Session verification: verifies session (evidence: `app/routes/websites/service_route.py`)
- Samba management → Session verification: verifies session (evidence: `app/routes/samba/service_route.py`)
- Cloudflared controls → Session verification: verifies session (evidence: `app/routes/cloudflared/service_route.py`)