# karmveershubham/syspulse architecture

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

## Overview

##### Project type and purpose
- This is a full-stack system-monitoring application (“SysPulse”) composed of:
- A cross-platform Go CLI agent (sysutility)
- An Express.js REST API (server)
- A Next.js dashboard UI (client)

##### File structure
- Top-level directories:
- sysutility/ (Go CLI utility)
- server/    (Express API with MVC pattern)
- client/    (Next.js UI)
- Key subdirectories:
- sysutility/internal/checks (platform-specific metric collectors)
- sysutility/internal/reporter (formats and posts reports)
- server/controllers, models, routes (Express MVC)
- client/app, client/components, client/lib, client/hooks (Next.js App Router and component library)
- Config & deployment files:
- sysutility/config/*.go, go.mod
- server/env.example, package.json
- client/next.config.js, tailwind.config.ts, package.json

##### Extract insights from README
- Tech stack: Go 1.20+, Node/Express, Next.js 14+, MongoDB
- Endpoints:
POST /api/register
POST /api/report
GET /api/systems

##### Main components
a. Go CLI Agent
- Platform checks (disk, OS update, antivirus, sleep)
- Reporter module (HTTP client)
- Configuration loader
b. Express API
- HTTP server (index.js)
- Routes layer (systemRoutes.js)
- Controllers (systemController.js)
- Models (systemModel.js, reportModel.js)
- Middleware (auth.js)
- Database connector (server/config/db.js)
c. MongoDB
d. Next.js Dashboard
- Pages (app/dashboard/*)
- Shared UI components (client/components/ui)
- Data-fetching in app routes or React hooks (client/lib/api.ts, client/hooks/use-toast.ts)
- Layout & theme provider
e. External flows
- CLI → API (HTTP POST)
- UI ↔ API (REST fetches)

##### Architectural patterns & design principles
- Three-tier architecture (agent, API backend, frontend)
- Modular Go packages for platform-specific checks (strategy pattern)
- MVC in Express (Routes → Controllers → Models)
- Component-driven design in Next.js (atomic UI components under client/components/ui)
- Separation of concerns: UI vs business logic vs data access vs system checks

##### Final advice
- Be exhaustive: break down into agent modules, API layers, UI modules
- External dependencies (MongoDB, HTTP)
- Use consistent naming that matches folder/file names for quick cross-reference

## Diagram (Mermaid)

```mermaid
graph TB
    %% Go CLI Agent Layer
    subgraph "Go CLI Agent" 
        direction TB
        entry["Entry Point\n(cmd/main.go)"]:::cli
        config["Configuration Loader\n(config/config.go)"]:::cli
        checks["Platform Checks\n(internal/checks)"]:::cli
        reporter["Reporter Module\n(internal/reporter/reporter.go)"]:::cli
        entry --> config
        config --> checks
        checks --> reporter
        reporter -->|HTTP POST| Internet
    end

    %% External HTTP/Internet
    Internet["Internet (HTTP)"]:::external

    %% Express API Layer
    subgraph "Express API" 
        direction TB
        apiServer["HTTP Server\n(index.js)"]:::api
        routes["Routes Layer\n(systemRoutes.js)"]:::api
        middleware["Middleware (auth)\n(auth.js)"]:::api
        controllers["Controllers\n(systemController.js)"]:::api
        models["Models\n(systemModel.js, reportModel.js)"]:::api
        dbConnector["DB Connector\n(config/db.js)"]:::api
        env["Env Config\n(env.example)"]:::api

        Internet -->|POST /api/register or /api/report| apiServer
        apiServer --> routes
        routes --> middleware
        middleware --> controllers
        controllers --> models
        models --> dbConnector
        dbConnector --> db
    end

    %% MongoDB
    db["MongoDB"]:::db

    %% Next.js UI Layer
    subgraph "Next.js Dashboard UI"
        direction TB
        rootLayout["Root Layout\n(app/layout.tsx)"]:::ui
        dashLayout["Dashboard Layout\n(app/dashboard/layout.tsx)"]:::ui
        pages["Pages\n(app/dashboard/*)"]:::ui
        uiLibrary["UI Components\n(components/ui)"]:::ui
        dashComponents["Dashboard Components\n(components/dashboard)"]:::ui
        themeProvider["Theme Provider\n(theme-provider.tsx)"]:::ui
        apiUtil["Data-Fetching\n(lib/api.ts)"]:::ui
        hooks["React Hooks\n(hooks/use-toast.ts)"]:::ui

        rootLayout --> themeProvider
        themeProvider --> dashLayout
        dashLayout --> pages
        uiLibrary --> pages
        dashComponents --> pages
        apiUtil --> pages
        hooks --> pages

        pages -->|GET /api/systems| Internet
    end

    %% Return flow from API to UI
    apiServer -->|JSON data| pages

    %% Click Events
    click entry "https://github.com/karmveershubham/syspulse/blob/main/sysutility/cmd/main.go"
    click config "https://github.com/karmveershubham/syspulse/blob/main/sysutility/config/config.go"
    click checks "https://github.com/karmveershubham/syspulse/tree/main/sysutility/internal/checks"
    click reporter "https://github.com/karmveershubham/syspulse/blob/main/sysutility/internal/reporter/reporter.go"
    click apiServer "https://github.com/karmveershubham/syspulse/blob/main/server/index.js"
    click routes "https://github.com/karmveershubham/syspulse/blob/main/server/routes/systemRoutes.js"
    click controllers "https://github.com/karmveershubham/syspulse/blob/main/server/controllers/systemController.js"
    click models "https://github.com/karmveershubham/syspulse/blob/main/server/models/systemModel.js"
    click models "https://github.com/karmveershubham/syspulse/blob/main/server/models/reportModel.js"
    click middleware "https://github.com/karmveershubham/syspulse/blob/main/server/middlewares/auth.js"
    click dbConnector "https://github.com/karmveershubham/syspulse/blob/main/server/config/db.js"
    click env "https://github.com/karmveershubham/syspulse/blob/main/server/env.example"
    click pages "https://github.com/karmveershubham/syspulse/tree/main/client/app/dashboard"
    click rootLayout "https://github.com/karmveershubham/syspulse/blob/main/client/app/layout.tsx"
    click dashLayout "https://github.com/karmveershubham/syspulse/blob/main/client/app/dashboard/layout.tsx"
    click uiLibrary "https://github.com/karmveershubham/syspulse/tree/main/client/components/ui"
    click dashComponents "https://github.com/karmveershubham/syspulse/tree/main/client/components/dashboard"
    click themeProvider "https://github.com/karmveershubham/syspulse/blob/main/client/components/theme-provider.tsx"
    click apiUtil "https://github.com/karmveershubham/syspulse/blob/main/client/lib/api.ts"
    click hooks "https://github.com/karmveershubham/syspulse/blob/main/client/hooks/use-toast.ts"

    %% Styles
    classDef cli fill:#ccffcc,stroke:#000;
    classDef api fill:#cce5ff,stroke:#000;
    classDef ui fill:#ffe5cc,stroke:#000;
    classDef db fill:#e5e5e5,stroke:#000;
    classDef external fill:#f2f2f2,stroke:#000;
```
