# midorin-linux/guardian-web architecture

> Architecture diagram of the GitHub repository midorin-linux/guardian-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/midorin-linux/guardian-web
- Repository: https://github.com/midorin-linux/guardian-web

## Overview

##### Main Components
a. Front-end (ts-src)
- Built with React + TypeScript, bundled by Vite.
- UI components under ts-src/components (dashboard, monitor, device_info, etc.).
- Served as static assets (index.html, CSS, JS) in `static/assets` or via the Vite dev server.
b. Back-end (src/)
- Rust web server (main.rs).
- Configuration loader (`src/app/config.rs`, `settings.toml`, `.env`).
- Request handlers in `src/handles/` (specifications API, stream_monitor for real-time streams).
- Business models in `src/models/`.
- Utility modules (logging, shutdown coordination).
c. External Targets / Services
- Managed computers or agents (over SSH, HTTP, gRPC, or custom protocol).
- Potential external storage or telemetry stores (if introduced later).

##### Interactions & Data Flow
- Browser requests front-end assets → HTTP GET to web server or static host.
- Browser UI → HTTP REST calls or WebSocket/SSE for real-time monitoring → Rust API endpoints (`/api/specifications`, `/api/stream`).
- Rust handlers → business logic using `models` and `utils/logging`.
- Rust server → remote managed computers (polling, streaming metrics) via `stream_monitor`.
- Rust server → graceful shutdown coordination (shutdown.rs).

##### Architectural Patterns & Design Principles
- Clear separation of concerns:
- “config” layer for settings
- “handles” for HTTP layer
- “models” for domain data
- “utils” for cross-cutting concerns (logging, shutdown)
- Modular code structure for testability and future microservice extraction.
- Front-end: component-based UI with hooks and utility libs.

##### Technologies & Frameworks to Call Out
- Back-end: Rust (Cargo.toml), likely using an async web framework (Actix, Axum or similar).
- Front-end: React + TypeScript, Vite bundler (vite.config.ts), ESLint.
- Configuration: .env, settings.toml.
- Build & CI: GitHub Actions (`.github/workflows/rust.yml`), bun.lock (JS runtime?), package.json.

##### Essential Elements
- Clear labels (e.g., “React App”, “Vite Dev Server”, “Rust API Server”, “Specification Handler”, “Stream Monitor Handler”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Front-end (React + TypeScript)"
        direction TB
        ReactApp["React App"]:::frontend
        Vite["Vite Dev Server"]:::frontend
        UIComp["UI Components"]:::frontend
        Hooks["Hooks & Utils"]:::frontend
        StaticBuild["Built Assets (JS/CSS/HTML)"]:::frontend
        PKG["package.json"]:::frontend
        ESLint["eslint.config.js"]:::frontend
        TSBase["tsconfig.json"]:::frontend
        TSApp["tsconfig.app.json"]:::frontend
        TSNode["tsconfig.node.json"]:::frontend
        ReactApp -->|Renders UI| UIComp
        ReactApp -->|Uses Hooks| Hooks
        Vite -->|Bundles| StaticBuild
        UIComp --> StaticBuild
    end

    StaticBuild -->|HTTP GET| Server["Rust API Server"]:::backend

    subgraph "Rust API Server"
        direction TB
        ServerEntry["Server Entry (main.rs)"]:::backend
        Cfg["Config Loader"]:::backend
        Env[".env & settings.toml"]:::backend
        Boot["Application Runner"]:::backend
        HandlesMod["Handler Module"]:::backend
        SpecAPI["Specifications Handler"]:::backend
        StreamAPI["Stream Monitor Handler"]:::backend
        ModelsMod["Model Module"]:::backend
        SpecsModel["Specifications Model"]:::backend
        UtilsMod["Utility Module"]:::backend
        Logging["Logging Utility"]:::backend
        Shutdown["Shutdown Manager"]:::backend

        ServerEntry -->|Loads| Cfg
        Env -->|Provides| Cfg
        ServerEntry -->|Starts| Boot
        Boot --> ServerEntry
        ServerEntry -->|Routes| HandlesMod
        HandlesMod -->|Imports| SpecAPI
        HandlesMod -->|Imports| StreamAPI
        SpecAPI -->|Uses| SpecsModel
        HandlesMod -->|Uses| ModelsMod
        ModelsMod --> SpecsModel
        HandlesMod -->|Uses| UtilsMod
        UtilsMod --> Logging
        ServerEntry -->|Graceful Stop| Shutdown
    end

    HandlesMod -->|polls/streams metrics| Hosts["Managed Computers / Agents"]:::external

    subgraph "Managed Computers"
        direction TB
        Hosts
    end

    %% Click Events
    click ReactApp "https://github.com/midorin-linux/guardian-web/tree/master/ts-src/"
    click Vite "https://github.com/midorin-linux/guardian-web/blob/master/vite.config.ts"
    click UIComp "https://github.com/midorin-linux/guardian-web/tree/master/ts-src/components/"
    click Hooks "https://github.com/midorin-linux/guardian-web/blob/master/ts-src/hooks/use-mobile.ts"
    click StaticBuild "https://github.com/midorin-linux/guardian-web/tree/master/static/assets/"
    click PKG "https://github.com/midorin-linux/guardian-web/blob/master/package.json"
    click ESLint "https://github.com/midorin-linux/guardian-web/blob/master/eslint.config.js"
    click TSBase "https://github.com/midorin-linux/guardian-web/blob/master/tsconfig.json"
    click TSApp "https://github.com/midorin-linux/guardian-web/blob/master/tsconfig.app.json"
    click TSNode "https://github.com/midorin-linux/guardian-web/blob/master/tsconfig.node.json"
    click ServerEntry "https://github.com/midorin-linux/guardian-web/blob/master/src/main.rs"
    click Cfg "https://github.com/midorin-linux/guardian-web/blob/master/src/app/config.rs"
    click Env "https://github.com/midorin-linux/guardian-web/blob/master/.env"
    click Env "https://github.com/midorin-linux/guardian-web/blob/master/settings.toml"
    click Boot "https://github.com/midorin-linux/guardian-web/blob/master/src/app/runner.rs"
    click HandlesMod "https://github.com/midorin-linux/guardian-web/blob/master/src/handles/mod.rs"
    click SpecAPI "https://github.com/midorin-linux/guardian-web/blob/master/src/handles/specifications.rs"
    click StreamAPI "https://github.com/midorin-linux/guardian-web/blob/master/src/handles/stream_monitor.rs"
    click ModelsMod "https://github.com/midorin-linux/guardian-web/blob/master/src/models/mod.rs"
    click SpecsModel "https://github.com/midorin-linux/guardian-web/blob/master/src/models/specifications.rs"
    click UtilsMod "https://github.com/midorin-linux/guardian-web/blob/master/src/utils/mod.rs"
    click Logging "https://github.com/midorin-linux/guardian-web/blob/master/src/utils/logging.rs"
    click Shutdown "https://github.com/midorin-linux/guardian-web/blob/master/src/app/shutdown.rs"
    click StaticBuild "https://github.com/midorin-linux/guardian-web/blob/master/static/index.html"
    click StaticBuild "https://github.com/midorin-linux/guardian-web/blob/master/index.html"
    click ServerEntry "https://github.com/midorin-linux/guardian-web/blob/master/Cargo.toml"
    click ServerEntry "https://github.com/midorin-linux/guardian-web/blob/master/Cargo.lock"
    click ServerEntry "https://github.com/midorin-linux/guardian-web/blob/master/bun.lock"
    click ServerEntry "https://github.com/midorin-linux/guardian-web/blob/master/.github/workflows/rust.yml"

    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef backend fill:#90EE90,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
