# anshgupta517/system-diagnostics-app architecture

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

- Interactive diagram: https://gitdiagram.com/anshgupta517/system-diagnostics-app
- Repository: https://github.com/anshgupta517/system-diagnostics-app

## Overview

##### What this project is (type + purpose)
From the tree, this is a **full-stack “system diagnostics” web app**:

- **Frontend**: `frontend/` is a **React + Vite** SPA (components, charts, `src/services/api.js` for backend calls).
- **Backend**: `backend/` is a **Python API/service** that:
- collects machine metrics via “collectors” (`cpu.py`, `memory.py`, `process.py`)
- contains an **LLM integration** (`llm_service.py`) and a **tool routing layer** (`tool_router.py`) that likely decides when to call collectors vs. answer directly via LLM
- The app’s core value: **view system status + ask questions / request diagnostics**, potentially with LLM-assisted interpretation.

Given the presence of `collectors/` + `llm_service.py` + `tool_router.py`, the architecture is not just “dashboard”; it’s “dashboard + intelligent assistant that can call tools to fetch live system state”.

##### Frontend (`frontend/src/`)
- `App.jsx`, `main.jsx`: application entry + composition root
- `components/`
- `SystemStatus.jsx`: likely the main metrics panel
- `DataVisualizer.jsx`: orchestrates chart rendering
- `InputBox.jsx`, `MessageBubble.jsx`: implies a chat-like UI
- `components/charts/` (`CpuChart.jsx`, `MemoryChart.jsx`, `ProcessChart.jsx`): explicit visualization modules

##### Backend (`backend/`)
- `main.py`: likely the API server entrypoint (FastAPI/Flask). Treat this as the **API surface**.
- `collectors/`: **system data acquisition layer** (calls OS APIs / `psutil`-like libraries)
- `tool_router.py`: **orchestration** between LLM and collectors (tool selection / dispatch)
- `llm_service.py`: **integration to external LLM provider** (OpenAI, local model, etc.)
- `requirements.txt`: confirms this is a deployable Python service with explicit dependencies

##### Frontend SPA (React/Vite)
- key submodules: UI components + Charts + `api.js`
##### Backend Python API Service
- API endpoints (in `main.py`)
- orchestration (`tool_router.py`)
- system collectors (`collectors/*.py`)
- LLM integration (`llm_service.py`)
##### Host Operating System
- source of CPU/memory/process metrics (what collectors read)
##### External LLM Provider
- network dependency used by `llm_service.py`

##### Metrics/Status flow (dashboard)
- Browser → React UI (`SystemStatus`, charts)
- React UI → `src/services/api.js`
- `api.js` → Backend API (`main.py`) via HTTP (REST-style is most likely)
- Backend (`main.py`) → `collectors/*` (CPU, memory, process)
- Collectors → OS (read system stats)
- Response returns back:
- Backend → Frontend → Charts render

##### “Ask diagnostics” / chat + LLM tool calling
- Browser → React chat UI (`InputBox`, `MessageBubble`)
- React → `api.js` → Backend API (`main.py`)
- Backend → `tool_router.py`
- `tool_router.py` decides:
- call `llm_service.py` (LLM completion)
- and/or call collectors as “tools” to fetch live data
- `llm_service.py` → External LLM Provider (network call)
- Collectors → OS (live metrics)
- Backend assembles final message → Frontend chat UI

##### Important architectural pattern to highlight

- **API Layer**: `main.py` (request/response boundary)
- **Orchestration/Tooling Layer**: `tool_router.py` (decides which capability to invoke)
- **Integrations**:
- **System integration**: `collectors/*` (reads OS metrics)
- **External AI integration**: `llm_service.py` (calls LLM provider)

Frontend similarly has a clean separation:
- **Presentation components** vs **chart components** vs **API client** (`api.js`)

This is worth showing either as:

##### Get System Status
- UI → `api.js` → backend route → collector → OS → collector → backend → UI → chart render

##### Chat/Diagnostics with tool usage
- UI → backend → `tool_router` → (LLM call) → (collector call) → compose answer → UI

##### Don’t overthink it: split into as many components as possible
For this repo, the “maximally separated but still accurate” decomposition is:

**Frontend**
- App shell (`App.jsx`)
- System status panel (`SystemStatus.jsx`)
- Visualizer (`DataVisualizer.jsx`)
- Charts (`CpuChart`, `MemoryChart`, `ProcessChart`)
- Chat UI (`InputBox`, `MessageBubble`)
- API client (`services/api.js`)

**Backend**
- API entry/routes (`main.py`)
- Tool dispatcher (`tool_router.py`)
- LLM client (`llm_service.py`)
- Collectors (`cpu.py`, `memory.py`, `process.py`)
- Dependencies (`requirements.txt`)

**External**
- Host OS (metrics source)
- LLM provider (network)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors / Systems
    U["User"]:::external
    B["Web Browser"]:::external
    OS["Host Operating System\n(CPU/Memory/Process table)"]:::external
    LLMX["External LLM Provider\n(LLM API)"]:::external

    %% =========================
    %% Frontend (React/Vite SPA)
    %% =========================
    subgraph "Frontend SPA (React + Vite)"
        direction TB

        FEEntry["Entry / Composition Root\n(main.jsx)"]:::frontend
        FEShell["App Shell\n(App.jsx)"]:::frontend

        subgraph "UI Components"
            direction TB
            FEStatus["System Status Panel\n(SystemStatus.jsx)"]:::frontend
            FEVis["Data Visualizer\n(DataVisualizer.jsx)"]:::frontend

            subgraph "Charts"
                direction TB
                FECpu["CPU Chart\n(CpuChart.jsx)"]:::frontend
                FEMem["Memory Chart\n(MemoryChart.jsx)"]:::frontend
                FEProc["Process Chart\n(ProcessChart.jsx)"]:::frontend
            end

            subgraph "Chat UI"
                direction TB
                FEInput["Input Box\n(InputBox.jsx)"]:::frontend
                FEMsg["Message Bubble\n(MessageBubble.jsx)"]:::frontend
            end
        end

        FEApi["Frontend API Client\n(services/api.js)"]:::api
    end

    %% ======================
    %% Backend (Python API)
    %% ======================
    subgraph "Backend Python API Service"
        direction TB

        BEApi["API Entry / Routes\n(main.py)"]:::backend
        BERouter["Tool Router / Orchestrator\n(tool_router.py)"]:::backend
        BELLm["LLM Service\n(llm_service.py)"]:::backend

        subgraph "System Collectors"
            direction TB
            BECpu["CPU Collector\n(collectors/cpu.py)"]:::collector
            BEMem["Memory Collector\n(collectors/memory.py)"]:::collector
            BEProc["Process Collector\n(collectors/process.py)"]:::collector
        end

        BEReq["Dependencies\n(requirements.txt)"]:::note
    end

    %% ===========
    %% Relationships
    %% ===========
    U -->|"uses"| B
    B -->|"loads SPA assets"| FEEntry
    FEEntry -->|"renders"| FEShell

    %% UI composition
    FEShell -->|"shows"| FEStatus
    FEShell -->|"shows"| FEVis
    FEShell -->|"shows"| FEInput
    FEShell -->|"shows"| FEMsg

    %% Charts under visualizer/status
    FEStatus -->|"updates"| FEVis
    FEVis -->|"renders"| FECpu
    FEVis -->|"renders"| FEMem
    FEVis -->|"renders"| FEProc

    %% Frontend-to-backend boundary
    FEStatus -->|"GET_/metrics"| FEApi
    FEInput -->|"POST_/chat"| FEApi
    FEApi -->|"HTTP/JSON"| BEApi

    %% Backend orchestration
    BEApi -->|"dispatches"| BERouter

    %% Metrics flow (collectors)
    BERouter -->|"calls_tool"| BECpu
    BERouter -->|"calls_tool"| BEMem
    BERouter -->|"calls_tool"| BEProc

    %% LLM flow (optional)
    BERouter -.->|"calls_LLM"| BELLm
    BELLm -->|"HTTPS API"| LLMX

    %% Collectors read OS
    BECpu -->|"read_CPU_stats"| OS
    BEMem -->|"read_memory_stats"| OS
    BEProc -->|"read_process_list"| OS

    %% Responses back (implicit in HTTP)
    BEApi -->|"metrics/chat_response"| FEApi
    FEApi -->|"state_update"| FEStatus
    FEApi -->|"messages_update"| FEMsg

    %% ===========
    %% Click events (mapped paths)
    %% ===========
    click FEEntry "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/main.jsx"
    click FEShell "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/App.jsx"
    click FEStatus "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/SystemStatus.jsx"
    click FEVis "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/DataVisualizer.jsx"
    click FEInput "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/InputBox.jsx"
    click FEMsg "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/MessageBubble.jsx"
    click FEApi "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/services/api.js"
    click FECpu "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/charts/CpuChart.jsx"
    click FEMem "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/charts/MemoryChart.jsx"
    click FEProc "https://github.com/anshgupta517/system-diagnostics-app/blob/main/frontend/src/components/charts/ProcessChart.jsx"

    click BEApi "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/main.py"
    click BERouter "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/tool_router.py"
    click BELLm "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/llm_service.py"
    click BECpu "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/collectors/cpu.py"
    click BEMem "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/collectors/memory.py"
    click BEProc "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/collectors/process.py"
    click BEReq "https://github.com/anshgupta517/system-diagnostics-app/blob/main/backend/requirements.txt"

    %% Directory click mappings (as additional coverage)
    click FEStatus "https://github.com/anshgupta517/system-diagnostics-app/tree/main/frontend/src/components/"
    click FECpu "https://github.com/anshgupta517/system-diagnostics-app/tree/main/frontend/src/components/charts/"
    click BECpu "https://github.com/anshgupta517/system-diagnostics-app/tree/main/backend/collectors/"

    %% ===========
    %% Styles
    %% ===========
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1.5px,color:#263238;
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,stroke-width:1.5px,color:#0D47A1;
    classDef api fill:#BBDEFB,stroke:#1565C0,stroke-width:2px,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20;
    classDef collector fill:#F1F8E9,stroke:#558B2F,stroke-width:1.5px,color:#33691E;
    classDef note fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100;
```
