# chaos-zhu/easynode architecture

> Architecture diagram of the GitHub repository chaos-zhu/easynode, 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/chaos-zhu/easynode
- Repository: https://github.com/chaos-zhu/easynode

## Overview

##### Project Type & Purpose
- Full-stack web application + light agent (“client”)
- Purpose: provide webSSH & webSFTP panel + server monitoring via a browser SPA

##### High-Level Component Identification
a. Web UI (“web” folder)
– Vue 3 SPA, Element Plus UI, communicates via REST + WebSockets
b. Backend API Server (“server” folder)
– Node.js/Express app with:
- Controllers (SSH, SFTP, AI-shell, notifications, scripts, user, group, etc.)
- Middlewares (auth, CORS, body parsing, logging, IP filtering, static files)
- Socket handlers (real-time terminal data, monitoring streams)
- Scheduler for on-demand tasks
- Embedded DB (file under `/easynode/app/db` or similar)
c. Monitoring Agent (“client” folder)
– Shell/Python/Node agent installed on each target Linux host
– Collects CPU/memory/disk/network/IP data, pushes to API server over port 22022
d. External Systems
– Managed SSH targets (through server acting as a jump-host)
– Optional Docker Engine (via socket) for container-terminal features
e. Orchestration & Deployment
– docker-compose.yml orchestrates 3 containers: web, server, client (optional)
– CI/CD workflows for building images (.github/workflows)

##### Interactions & Data Flows
1. Browser → Web UI (HTTP/HTTPS)
2. Web UI → API Server
- REST calls for CRUD (servers, scripts, users)
- WebSocket for live terminal/SFTP & monitoring
3. API Server → SSH/SFTP targets
- spawns pty processes, streams data back over WebSocket
4. Monitoring Agent → API Server
- Periodic push of metrics (JSON over TCP/WebSocket)
5. API Server ↔ Database
- read/write persistent configs, credentials, logs

##### Architectural Patterns & Design Principles
- Layered MVC-ish structure in server: Routes → Controllers → Utils/DB
- Event-driven real-time I/O via Socket.IO
- Single-page app (SPA) front-end, decoupled from API
- Agent-server model for monitoring

##### Essential Elements
- Ports (8082 for web/API, 22022 for agent)
- Docker-Compose boundary around containers

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Presentation Layer"
        BROWSER["Browser"]:::presentation
        WEB["Vue 3 SPA"]:::presentation
    end

    subgraph "Application Layer"
        API["Node.js/Express API Server"]:::application
        CTRL["Controllers"]:::application
        MW["Middlewares"]:::application
        SOCKET["Socket Handlers"]:::application
        SCHED["Scheduler"]:::application
        DBFILE["Embedded DB (file)"]:::application
        ENTRY1["Entry: main.js"]:::application
        ENTRY2["Entry: bin/www"]:::application
    end

    subgraph "Data/Edge Layer"
        AGENT_APP["Monitoring Agent"]:::dataedge
        AGENT_SOCKET["Agent Socket Module"]:::dataedge
        AGENT_UTILS["Agent Utilities"]:::dataedge
        AGENT_CONFIG["Agent Config"]:::dataedge
        AGENT_ENTRY1["Entry: server.js"]:::dataedge
        AGENT_ENTRY2["Entry: bin/www"]:::dataedge
        SSH["SSH/SFTP Targets"]:::dataedge
        DOCKER["Docker Engine"]:::dataedge
    end

    subgraph "Orchestration & CI/CD"
        COMPOSE["docker-compose.yml"]:::orchestration
        WORKFLOW1["docker-builder.yml"]:::orchestration
        WORKFLOW2["client-builder.yml"]:::orchestration
    end

    %% Connections
    BROWSER -->|"HTTP/HTTPS"| WEB
    WEB -->|"REST (CRUD)"| API
    WEB -->|"WS/WSS"| SOCKET

    API -->|"uses"| CTRL
    API -->|"uses"| MW
    API -->|"uses"| SOCKET
    API -->|"uses"| SCHED
    API -->|"read/write"| DBFILE
    API -->|"spawns PTY streams"| SSH
    API -->|"Docker socket"| DOCKER
    API -->|"startup"| ENTRY1
    API -->|"startup"| ENTRY2

    AGENT_APP -->|"internal"| AGENT_SOCKET
    AGENT_APP -->|"internal"| AGENT_UTILS
    AGENT_APP -->|"internal"| AGENT_CONFIG
    AGENT_APP -->|"startup"| AGENT_ENTRY1
    AGENT_APP -->|"startup"| AGENT_ENTRY2
    AGENT_APP -->|"TCP/WS metrics"| API

    %% Click Events
    click WEB "https://github.com/chaos-zhu/easynode/tree/main/web/"
    click API "https://github.com/chaos-zhu/easynode/tree/main/server/"
    click CTRL "https://github.com/chaos-zhu/easynode/tree/main/server/app/controller/"
    click MW "https://github.com/chaos-zhu/easynode/tree/main/server/app/middlewares/"
    click SOCKET "https://github.com/chaos-zhu/easynode/tree/main/server/app/socket/"
    click SCHED "https://github.com/chaos-zhu/easynode/tree/main/server/app/schedule/"
    click DBFILE "https://github.com/chaos-zhu/easynode/blob/main/server/app/db.js"
    click ENTRY1 "https://github.com/chaos-zhu/easynode/blob/main/server/app/main.js"
    click ENTRY2 "https://github.com/chaos-zhu/easynode/tree/main/server/bin/www"
    click AGENT_APP "https://github.com/chaos-zhu/easynode/tree/main/client/app/"
    click AGENT_SOCKET "https://github.com/chaos-zhu/easynode/blob/main/client/app/socket/monitor.js"
    click AGENT_UTILS "https://github.com/chaos-zhu/easynode/tree/main/client/app/utils/"
    click AGENT_CONFIG "https://github.com/chaos-zhu/easynode/blob/main/client/app/config/index.js"
    click AGENT_ENTRY1 "https://github.com/chaos-zhu/easynode/blob/main/client/app/server.js"
    click AGENT_ENTRY2 "https://github.com/chaos-zhu/easynode/tree/main/client/bin/www"
    click COMPOSE "https://github.com/chaos-zhu/easynode/blob/main/docker-compose.yml"
    click WORKFLOW1 "https://github.com/chaos-zhu/easynode/blob/main/.github/workflows/docker-builder.yml"
    click WORKFLOW2 "https://github.com/chaos-zhu/easynode/blob/main/.github/workflows/client-builder.yml"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef application fill:#90EE90,stroke:#000,stroke-width:1px
    classDef dataedge fill:#FFA500,stroke:#000,stroke-width:1px
    classDef orchestration fill:#D3D3D3,stroke:#000,stroke-width:1px
```
