# ygqygq2/easy-check architecture

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

- Interactive diagram: https://gitdiagram.com/ygqygq2/easy-check
- Repository: https://github.com/ygqygq2/easy-check

## Overview

##### Project Type and Purpose
- easy-check is a cross-platform (Windows, Linux, macOS) desktop application built with Go (backend) and React/TypeScript (frontend) via the Wails framework.
- It periodically pings a user-defined list of hosts, logs the results (time-series DB + log files), displays status on a UI, aggregates alert conditions, and sends notifications (e.g., Feishu). It also supports OS-level auto-start on boot.

##### File-Structure Analysis
- Top-level directories:
- cmd / main.go & main_*: entrypoints for different OS builds.
- internal/: Go packages implementing core logic (scheduler, checker, aggregator, notifier, logger, DB, config, etc.).
- frontend/: React/Vite app, bound to Go via Wails (bindings folder).
- configs/: YAML file for host list & intervals.
- build/ & scripts/: CI/CD pipelines and platform packaging (macOS .app, Linux AppImage/nfpm, Windows NSIS).
- Patterns: clear separation of UI (frontend) and service layer (internal), event-driven scheduling/queue modules, dependency injection via wire.

##### README Insights
- Configuration-driven host list and interval.
- Scripts to install as a service/auto-start.
- Features: UI, periodic pings, log persistence, aggregation, notification.

- UI Layer (React front end inside Wails webview)
- RPC / Binding Layer (Wails bridges)
- Core Services (Go internal packages):
– Scheduler: triggers ping jobs on interval
– Checker: executes ping logic per host (platform-specific implementations)
– Aggregator: processes raw results to detect alerts/recoveries
– Notifier: sends alerts via Feishu (external API) or noop
– Logger: writes to time-series DB + log files; exposes WebSocket for live UI updates
– Config Watcher: reads configs/config.yaml and hot-reloads
– Queue: internal job queue for decoupling
- Data Storage:
– Time-series DB (.tsdb)
– Flat log files
- External Dependencies:
– Target Hosts (network)
– Feishu (HTTP API)
– OS (auto-start service/install scripts)
1. UI → RPC → Core Services (user changes settings, requests data).
2. Config Watcher → Scheduler (provides host list & intervals).
3. Scheduler → Queue → Checker (job dispatch).
4. Checker → Logger (records timestamped results).
5. Logger → DB & log file (persistence).
6. Logger → WebSocket → UI (live updates).
7. Logger → Aggregator → Notifier → External Service (Feishu).
8. UI ↔ Config Watcher (edit & persist config).
c. Architectural Patterns & Principles:
- Modular, layered architecture (UI / RPC / Services / Data).
- Event-driven & queue-based decoupling between scheduler and checker.
- Dependency injection for testability (wire).
- Cross-platform abstractions for ping and restart.
- Filesystem + embedded DB for persistence; WebSocket for real-time UI.
d. Key Technologies & Frameworks:
- Go (backend), Wails (bindings & packaging), React + Vite (frontend), TypeScript, TSDB, NSIS/AppImage/nfpm, GitHub Actions, GoReleaser.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        UI["React/Vite UI"]:::frontend
    end

    subgraph "RPC Layer"
        RPC["Wails Bindings"]:::rpc
    end

    subgraph "Backend Services"
        ConfigWatcher["Config Watcher"]:::service
        Scheduler["Scheduler"]:::service
        Queue["Queue"]:::service
        Checker["Checker"]:::service
        Aggregator["Aggregator"]:::service
        Notifier["Notifier"]:::service
        Logger["Logger"]:::service
    end

    subgraph "Data Storage"
        TSDB["Time-series DB"]:::storage
        Logs["Flat Log Files"]:::storage
    end

    subgraph "External Systems"
        Hosts["Target Hosts"]:::external
        Feishu["Feishu API"]:::external
        OS["OS Auto-start Service"]:::external
    end

    UI --> RPC
    RPC -->|"invoke Config"| ConfigWatcher
    ConfigWatcher --> Scheduler
    Scheduler --> Queue
    Queue --> Checker
    Checker --> Logger
    Logger --> TSDB
    Logger --> Logs
    Logger -->|"WebSocket"| UI
    Logger --> Aggregator
    Aggregator --> Notifier
    Notifier --> Feishu
    UI <--> ConfigWatcher
    OS -.-> Scheduler

    click UI "https://github.com/ygqygq2/easy-check/tree/main/frontend/src"
    click RPC "https://github.com/ygqygq2/easy-check/tree/main/frontend/bindings/easy-check"
    click Scheduler "https://github.com/ygqygq2/easy-check/blob/main/internal/scheduler/scheduler.go"
    click ConfigWatcher "https://github.com/ygqygq2/easy-check/blob/main/internal/config/watcher.go"
    click Queue "https://github.com/ygqygq2/easy-check/blob/main/internal/queue/queue.go"
    click Checker "https://github.com/ygqygq2/easy-check/blob/main/internal/checker/checker.go"
    click Aggregator "https://github.com/ygqygq2/easy-check/blob/main/internal/aggregator/aggregator.go"
    click Notifier "https://github.com/ygqygq2/easy-check/blob/main/internal/notifier/notifier.go"
    click Logger "https://github.com/ygqygq2/easy-check/blob/main/internal/logger/logger.go"
    click TSDB "https://github.com/ygqygq2/easy-check/blob/main/internal/db/tsdb.go"
    click OS "https://github.com/ygqygq2/easy-check/blob/main/scripts/install.sh"

    classDef frontend fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef rpc fill:#c5cae9,stroke:#3f51b5,color:#1a237e
    classDef service fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
    classDef storage fill:#ffe0b2,stroke:#ff9800,color:#e65100
    classDef external fill:#e1bee7,stroke:#9c27b0,color:#4a148c
```
