# yv798an/jh-nas-os architecture

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

- Interactive diagram: https://gitdiagram.com/yv798an/jh-nas-os
- Repository: https://github.com/yv798an/jh-nas-os

## Overview

OrangePi NAS Web Server serves a browser-based file manager and system-monitoring UI over HTTP. The main workflow is browser request → HTTP server → router → file or system API → domain service and filesystem/platform state → HTTP response; file operations include safe shared-root resolution, browsing/search and mutations, while downloads support Range and an optional io_uring reader. Separate documented branches expose health checks and Prometheus metrics. The README documents these capabilities and the layers; some handler and metrics wiring is unsampled, so uncertain direct links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/yv798an/jh-nas-os/blob/main/src/main.cpp) (Service entry), [`src/io/AsyncFileReader.cpp`](https://github.com/yv798an/jh-nas-os/blob/main/src/io/AsyncFileReader.cpp) (Async file reader), [`src/http/Router.cpp`](https://github.com/yv798an/jh-nas-os/blob/main/src/http/Router.cpp) (HTTP router), [`src/http/FileApi.cpp`](https://github.com/yv798an/jh-nas-os/blob/main/src/http/FileApi.cpp) (File API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and HTTP"]
  node_main["Service entry<br/>[main.cpp]"]
  node_http_server["HTTP server"]
  node_router["HTTP router<br/>[Router.cpp]"]
  node_web_ui["Web UI<br/>[WebUi.cpp]"]
  node_system_api["System API<br/>[Api.cpp]"]
  node_health_probe["Health probe<br/>[HealthProbe.cpp]"]
  node_http_stats["HTTP metrics<br/>[HttpStats.h]"]
end

subgraph group_files["File management"]
  node_file_api["File API<br/>[FileApi.cpp]"]
  node_file_service["File service<br/>[FileService.cpp]"]
  node_shared_files[("Shared storage")]
end

subgraph group_monitoring["System monitoring"]
  node_system_monitor["System monitor<br/>[SystemMonitor.cpp]"]
  node_share_registry["Share registry<br/>[ShareRegistry.cpp]"]
  node_system_state["Platform state<br/>[ISystemState.h]"]
  node_linux_state["Linux state"]
  node_procfs[("Linux proc and mounts")]
end

subgraph group_io["Asynchronous I/O"]
  node_async_reader["Async file reader"]
  node_io_uring["io_uring backend<br/>[IoUring.cpp]"]
  node_buffer_pool["Buffer pool<br/>[BufferPool.cpp]"]
  node_ring_buffer["SPSC queue<br/>[SpscRingBuffer.h]"]
end

subgraph group_configuration["Configuration and logging"]
  node_config["Configuration<br/>[Config.cpp]"]
  node_logger["Logger<br/>[Logger.cpp]"]
end

node_browser(("Browser"))

node_browser -->|"sends requests"| node_http_server
node_http_server -->|"dispatches requests"| node_router
node_main -->|"creates and serves"| node_http_server
node_main -->|"registers routes"| node_router
node_router -->|"dispatches file routes"| node_file_api
node_router -->|"dispatches system routes"| node_system_api
node_router -->|"serves UI route"| node_web_ui
node_file_api -->|"calls file operations"| node_file_service
node_file_service -->|"reads and writes"| node_shared_files
node_system_api -->|"requests status"| node_system_monitor
node_system_monitor -->|"reads snapshots and usage"| node_system_state
node_system_monitor -->|"filters mounted shares"| node_share_registry
node_linux_state -->|"implements interface"| node_system_state
node_linux_state -->|"collects system data"| node_procfs
node_main -->|"starts and stops"| node_linux_state
node_main -->|"loads settings"| node_config
node_main -->|"initializes and shuts down"| node_logger
node_main -->|"runs health check"| node_health_probe
node_file_api -.->|"uses for eligible reads"| node_async_reader
node_async_reader -->|"submits reads"| node_io_uring
node_async_reader -->|"acquires buffers"| node_buffer_pool
node_async_reader -->|"passes completed blocks"| node_ring_buffer
node_async_reader -->|"reads file ranges"| node_shared_files

click node_main "https://github.com/yv798an/jh-nas-os/blob/main/src/main.cpp"
click node_http_server "https://github.com/yv798an/jh-nas-os/blob/main/src/http/HttplibHttpServer.cpp"
click node_router "https://github.com/yv798an/jh-nas-os/blob/main/src/http/Router.cpp"
click node_web_ui "https://github.com/yv798an/jh-nas-os/blob/main/src/http/WebUi.cpp"
click node_system_api "https://github.com/yv798an/jh-nas-os/blob/main/src/http/Api.cpp"
click node_file_api "https://github.com/yv798an/jh-nas-os/blob/main/src/http/FileApi.cpp"
click node_health_probe "https://github.com/yv798an/jh-nas-os/blob/main/src/http/HealthProbe.cpp"
click node_http_stats "https://github.com/yv798an/jh-nas-os/blob/main/include/http/HttpStats.h"
click node_file_service "https://github.com/yv798an/jh-nas-os/blob/main/src/file/FileService.cpp"
click node_system_monitor "https://github.com/yv798an/jh-nas-os/blob/main/src/system/SystemMonitor.cpp"
click node_share_registry "https://github.com/yv798an/jh-nas-os/blob/main/src/system/ShareRegistry.cpp"
click node_system_state "https://github.com/yv798an/jh-nas-os/blob/main/include/platform/ISystemState.h"
click node_linux_state "https://github.com/yv798an/jh-nas-os/blob/main/src/platform/linux/LinuxSystemState.cpp"
click node_config "https://github.com/yv798an/jh-nas-os/blob/main/src/config/Config.cpp"
click node_logger "https://github.com/yv798an/jh-nas-os/blob/main/src/common/Logger.cpp"
click node_async_reader "https://github.com/yv798an/jh-nas-os/blob/main/src/io/AsyncFileReader.cpp"
click node_io_uring "https://github.com/yv798an/jh-nas-os/blob/main/src/io/IoUring.cpp"
click node_buffer_pool "https://github.com/yv798an/jh-nas-os/blob/main/src/io/BufferPool.cpp"
click node_ring_buffer "https://github.com/yv798an/jh-nas-os/blob/main/include/concurrent/SpscRingBuffer.h"

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_main,node_http_server,node_router,node_web_ui,node_system_api,node_health_probe,node_http_stats,node_browser toneBlue
class node_file_api,node_file_service,node_shared_files toneAmber
class node_system_monitor,node_share_registry,node_system_state,node_linux_state,node_procfs toneMint
class node_async_reader,node_io_uring,node_buffer_pool,node_ring_buffer toneRose
class node_config,node_logger toneIndigo
```

## Components

### Runtime and HTTP

- [Service entry](https://github.com/yv798an/jh-nas-os/blob/main/src/main.cpp): `src/main.cpp`
- [HTTP server](https://github.com/yv798an/jh-nas-os/blob/main/src/http/HttplibHttpServer.cpp): `src/http/HttplibHttpServer.cpp`
- [HTTP router](https://github.com/yv798an/jh-nas-os/blob/main/src/http/Router.cpp): `src/http/Router.cpp`
- [Web UI](https://github.com/yv798an/jh-nas-os/blob/main/src/http/WebUi.cpp): `src/http/WebUi.cpp`
- [System API](https://github.com/yv798an/jh-nas-os/blob/main/src/http/Api.cpp): `src/http/Api.cpp`
- [Health probe](https://github.com/yv798an/jh-nas-os/blob/main/src/http/HealthProbe.cpp): `src/http/HealthProbe.cpp`
- [HTTP metrics](https://github.com/yv798an/jh-nas-os/blob/main/include/http/HttpStats.h): `include/http/HttpStats.h`

### File management

- [File API](https://github.com/yv798an/jh-nas-os/blob/main/src/http/FileApi.cpp): `src/http/FileApi.cpp`
- [File service](https://github.com/yv798an/jh-nas-os/blob/main/src/file/FileService.cpp): `src/file/FileService.cpp`
- **Shared storage**

### System monitoring

- [System monitor](https://github.com/yv798an/jh-nas-os/blob/main/src/system/SystemMonitor.cpp): `src/system/SystemMonitor.cpp`
- [Share registry](https://github.com/yv798an/jh-nas-os/blob/main/src/system/ShareRegistry.cpp): `src/system/ShareRegistry.cpp`
- [Platform state](https://github.com/yv798an/jh-nas-os/blob/main/include/platform/ISystemState.h): `include/platform/ISystemState.h`
- [Linux state](https://github.com/yv798an/jh-nas-os/blob/main/src/platform/linux/LinuxSystemState.cpp): `src/platform/linux/LinuxSystemState.cpp`
- **Linux proc and mounts**

### Asynchronous I/O

- [Async file reader](https://github.com/yv798an/jh-nas-os/blob/main/src/io/AsyncFileReader.cpp): `src/io/AsyncFileReader.cpp`
- [io_uring backend](https://github.com/yv798an/jh-nas-os/blob/main/src/io/IoUring.cpp): `src/io/IoUring.cpp`
- [Buffer pool](https://github.com/yv798an/jh-nas-os/blob/main/src/io/BufferPool.cpp): `src/io/BufferPool.cpp`
- [SPSC queue](https://github.com/yv798an/jh-nas-os/blob/main/include/concurrent/SpscRingBuffer.h): `include/concurrent/SpscRingBuffer.h`

### Configuration and logging

- [Configuration](https://github.com/yv798an/jh-nas-os/blob/main/src/config/Config.cpp): `src/config/Config.cpp`
- [Logger](https://github.com/yv798an/jh-nas-os/blob/main/src/common/Logger.cpp): `src/common/Logger.cpp`

### Other components

- **Browser**

## Connections

- Browser → HTTP server: sends requests
- HTTP server → HTTP router: dispatches requests
- Service entry → HTTP server: creates and serves
- Service entry → HTTP router: registers routes
- HTTP router → File API: dispatches file routes
- HTTP router → System API: dispatches system routes
- HTTP router → Web UI: serves UI route
- File API → File service: calls file operations
- File service → Shared storage: reads and writes
- System API → System monitor: requests status
- System monitor → Platform state: reads snapshots and usage
- System monitor → Share registry: filters mounted shares
- Linux state → Platform state: implements interface
- Linux state → Linux proc and mounts: collects system data
- Service entry → Linux state: starts and stops
- Service entry → Configuration: loads settings
- Service entry → Logger: initializes and shuts down
- Service entry → Health probe: runs health check
- File API → Async file reader: uses for eligible reads
- Async file reader → io_uring backend: submits reads
- Async file reader → Buffer pool: acquires buffers
- Async file reader → SPSC queue: passes completed blocks
- Async file reader → Shared storage: reads file ranges