# jahaja/psdash architecture

> Architecture diagram of the GitHub repository jahaja/psdash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jahaja/psdash
- Repository: https://github.com/jahaja/psdash

## Overview

##### Project Type and Purpose
- psdash is a full-stack Python web application (Flask) that provides a real-time system information dashboard for Linux.
- It can run in two modes:
– **Web mode**: serves HTTP UI (overview, processes, network, disks, logs).
– **Agent mode**: runs an RPC server (zerorpc) to report metrics to a central web node.

##### File Structure
Top-level files & directories:
- setup.py, Vagrantfile, tests/ – build, development & CI.
- psdash/ – application package containing:
– __main__.py & run.py – CLI entry points.
– web.py – Flask app initialization & routing.
– node.py, helpers.py, net.py, log.py, run.py – “model” modules gathering metrics (via psutil).
– static/ – CSS, JS assets for the client UI.
– templates/ – Jinja2 views for each page.
- tests/ – unit tests for each module and web endpoints.

##### Extract Key Architectural Insights from README
- Uses Flask for webserver & routing.
- Uses psutil for gathering system metrics.
- Optional zerorpc for agent-to-web communications in multi-node setups.
- Configuration via environment / Flask config.
- UI built on Bootstrap, auto-refreshing data via AJAX (psdash.js).

##### Main Components
a. **Client (Browser)**
– HTML/CSS/JS (psdash.js) served by Flask → renders dashboard, polls REST endpoints.
b. **Flask Web Server**
– web.py holds route definitions: `/`, `/processes`, `/network`, `/logs`, etc.
– Controllers invoke model modules (node.py, net.py, log.py) to retrieve data.
c. **Model Modules**
– psutil-based gatherers: CPU, memory, disk, network, processes, logs.
d. **Agent RPC Servers (zerorpc)**
– Optional psdash instances in agent mode expose RPC interface.
e. **Configuration Store**
– Flask config + environment variables (PSDASH_*) controlling auth, nodes, intervals.
f. **External Dependencies**
– psutil library, zerorpc, Flask, Bootstrap.

##### Relationships & Data Flows
1) Browser → HTTP(S) GET/POST to Flask routes.
2) Flask controllers → call local model modules OR RPC calls to remote agents.
3) Model modules → fetch raw data from OS via psutil.
4) Flask → return JSON or render Jinja2 templates.
5) Browser JS → periodically poll JSON endpoints to update charts/tables.

##### Architectural Patterns & Design Principles
- **MVC-style** separation:
– Models: node.py, net.py, log.py
– Views: Jinja2 templates under templates/
– Controllers: route handlers in web.py
- **Plugin-style extensibility**: new metrics modules can be dropped in psdash/
- **Multi-node clustering**: central web node + agent nodes communicating via RPC.
- **12-factor config**: all settings via env vars or config file.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        Browser["Browser"]:::client
        PSJS["psdash.js"]:::client
        PSCSS["psdash.css"]:::client
        Fonts["fonts/"]:::client
    end

    %% Web Node
    subgraph "Web Node (Flask App)"
        direction TB
        Main["__main__.py"]:::web
        RunWeb["run.py"]:::web
        WebPy["web.py"]:::web
        Templates["templates/"]:::web
    end

    %% Model Modules
    subgraph "Model Modules (psutil Gatherers)"
        direction TB
        NodeMod["node.py"]:::model
        NetMod["net.py"]:::model
        LogMod["log.py"]:::model
        Helpers["helpers.py"]:::model
    end

    %% Agent Node
    subgraph "Agent Node (zerorpc)"
        direction TB
        AgentRun["run.py (agent mode)"]:::agent
    end

    %% Configuration Store
    Config["Configuration Store"]:::config

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        FlaskLib["Flask"]:::ext
        PsutilLib["psutil"]:::ext
        ZRPC["zerorpc"]:::ext
        Bootstrap["Bootstrap"]:::ext
    end

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        TestsDir["tests/"]:::tests
        Setup["setup.py"]:::build
        Vagrant["Vagrantfile"]:::build
        Travis[".travis.yml"]:::build
    end

    %% Relationships
    Browser -->|HTTP/HTTPS GET/POST| WebPy
    PSJS -->|AJAX Poll JSON| WebPy
    PSCSS -->|styles| Browser
    Fonts -->|fonts| Browser

    WebPy -->|loads| Main
    Main -->|invokes| RunWeb
    WebPy -->|renders| Templates
    WebPy -->|calls| NodeMod
    WebPy -->|calls| NetMod
    WebPy -->|calls| LogMod
    WebPy -->|calls| Helpers

    WebPy -->|uses config| Config
    Config -->|env vars| WebPy

    NodeMod -->|psutil calls| PsutilLib
    NetMod -->|psutil calls| PsutilLib
    LogMod -->|psutil calls| PsutilLib
    Helpers -->|utility| PsutilLib

    WebPy -->|optional RPC| AgentRun
    AgentRun -->|zerorpc| ZRPC
    WebPy -->|depends| FlaskLib
    Browser -->|UI CSS/JS| Bootstrap

    TestsDir -->|tests| NodeMod
    TestsDir -->|tests| NetMod
    TestsDir -->|tests| LogMod
    TestsDir -->|tests| RunWeb
    TestsDir -->|tests| WebPy

    Setup -->|build| WebPy
    Vagrant -->|dev env| WebPy
    Travis -->|CI| TestsDir

    %% Click Events
    click PSJS "https://github.com/jahaja/psdash/blob/master/psdash/static/js/psdash.js"
    click PSCSS "https://github.com/jahaja/psdash/blob/master/psdash/static/css/psdash.css"
    click Fonts "https://github.com/jahaja/psdash/tree/master/psdash/static/fonts/"
    click WebPy "https://github.com/jahaja/psdash/blob/master/psdash/web.py"
    click Main "https://github.com/jahaja/psdash/blob/master/psdash/__main__.py"
    click RunWeb "https://github.com/jahaja/psdash/blob/master/psdash/run.py"
    click NodeMod "https://github.com/jahaja/psdash/blob/master/psdash/node.py"
    click NetMod "https://github.com/jahaja/psdash/blob/master/psdash/net.py"
    click LogMod "https://github.com/jahaja/psdash/blob/master/psdash/log.py"
    click Helpers "https://github.com/jahaja/psdash/blob/master/psdash/helpers.py"
    click Templates "https://github.com/jahaja/psdash/tree/master/psdash/templates/"
    click AgentRun "https://github.com/jahaja/psdash/blob/master/psdash/run.py"
    click TestsDir "https://github.com/jahaja/psdash/tree/master/tests/"
    click Setup "https://github.com/jahaja/psdash/blob/master/setup.py"
    click Vagrant "https://github.com/jahaja/psdash/tree/master/Vagrantfile"
    click Travis "https://github.com/jahaja/psdash/blob/master/.travis.yml"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef web fill:#FFF3E0,stroke:#FFB74D,color:#E65100
    classDef model fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20
    classDef agent fill:#F3E5F5,stroke:#CE93D8,color:#4A148C
    classDef config fill:#ECEFF1,stroke:#B0BEC5,color:#37474F
    classDef ext fill:#FFEBEE,stroke:#EF9A9A,color:#B71C1C
    classDef tests fill:#FFFDE7,stroke:#FFF59D,color:#F57F17
    classDef build fill:#E1F5FE,stroke:#81D4FA,color:#01579B
```
