# xzb-1248/spark architecture

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

- Interactive diagram: https://gitdiagram.com/xzb-1248/spark
- Repository: https://github.com/xzb-1248/spark

## Overview

##### Main Components
- Client:
- Found in the “client” directory with several sub-modules like basic, desktop, file, process, screenshot, and terminal.
- Each service is implemented with platform-specific support (e.g., separate files for Windows, Linux, and others).
- The client module manages device-specific operations and communicates directly with the server.
- Server:
- Located in the “server” directory, it handles authentication (“server/auth”), configuration (“server/config”), logging (“server/common/log.go”), and various request handlers (desktop, file, process, terminal, etc.).
- It embeds static resources (the front-end) using statik (see “server/embed/web”) and uses frameworks like gin-gonic and gorilla/websocket to handle HTTP routing and real-time communication.
- Front-End:
- The “web” directory contains the React-based interface, built with components from directories like “web/src/components”.
- It uses libraries and frameworks such as React, Ant-Design, axios, and others.
- After the build process (using npm and webpack as configured in “web/webpack.config.js”), the compiled assets are embedded into the server so the interface is served directly from it.

##### Relationships and Interactions
- The Client connects directly to the Server using the network (configured by the “listen” address and port from the config.json).
- The Server acts as the central hub to:
- Receive and process requests from remote Clients.
- Serve the Web Front-End (embedded static assets) to browsers.
- Handle authentication and routing of various commands (file operations, process management, desktop/control functions, etc.) via dedicated API endpoints.
- The Web Front-End communicates with the Server using RESTful APIs and WebSocket connections (for real-time updates and terminal interactions).

##### Architectural Patterns and Technologies
- Modular Design: Both client and server are split into multiple modules (e.g., separate subdirectories for different services) allowing platform-specific implementations.
- Client-Server Model: A direct communication channel exists between client devices and the server, with the web interface acting as a control dashboard.
- Embedded Resources: The static front-end is embedded into the server using a tool (statik), ensuring the server can directly serve the UI without an external dependency.
- Technology Stack:
- Backend: Go (with gin-gonic, gorilla/websocket, etc.)
- Front-End: React, Ant-Design, xterm.js
- Cross-component utilities: Modules in “modules” and “utils” facilitating shared functionality.

##### Instructing the Principal Software Engineer
- The Authentication module (server/auth)
- Common utilities and logging (server/common)
- API Handlers (e.g., server/handler/bridge, server/handler/file, etc.)
- Configuration reading and management (server/config)
- Embedded static content (server/embed/web)
- File Explorer, Desktop Monitor, Terminal, Process Manager, and any other UI components.
- Interdependencies where the front-end is built with React, uses webpack, and communicates via WebSocket/RESTful APIs.
- Configuration file (config.json) and its role as the glue that holds the server settings (address, salt, authentication credentials, logging parameters).
- The client establishing a connection to the server based on the configuration (IP:Port).
- The web interface retrieving assets and data from the server.
- Internal data flows within the Server (e.g., authentication leading to proper routing to different handlers).
- Finally, annotate major dependencies or frameworks (gin-gonic, gorilla/websocket, React, etc.) near their respective modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        C_core["Core (client/core)"]:::client
        C_basic["Basic Service (client/service/basic)"]:::client
        C_desktop["Desktop Service (client/service/desktop)"]:::client
        C_file["File Service (client/service/file)"]:::client
        C_process["Process Service (client/service/process)"]:::client
        C_screenshot["Screenshot Service (client/service/screenshot)"]:::client
        C_terminal["Terminal Service (client/service/terminal)"]:::client
    end

    %% Server Layer
    subgraph "Server"
        S_auth["Authentication (server/auth)"]:::server
        S_common["Logging & Utilities (server/common)"]:::server
        S_config["Configuration Mgmt (server/config)"]:::server
        
        S_handler_bridge["Bridge Handler (server/handler/bridge)"]:::server
        S_handler_file["File Handler (server/handler/file)"]:::server
        S_handler_desktop["Desktop Handler (server/handler/desktop)"]:::server
        S_handler_process["Process Handler (server/handler/process)"]:::server
        S_handler_screenshot["Screenshot Handler (server/handler/screenshot)"]:::server
        S_handler_terminal["Terminal Handler (server/handler/terminal)"]:::server
        S_handler_utility["Utility Handler (server/handler/utility)"]:::server

        S_web_embed["Embedded Web Content (server/embed/web)"]:::server
        S_hub["Server Hub"]:::server
    end

    %% Web Front-End Layer
    subgraph "Web Front-End"
        W_components["React UI Components (web/src/components)"]:::frontend
        W_webpack["Webpack & Build Config (web/webpack.config.js)"]:::frontend
        W_packages["Package Config (web/package.json, web/package-lock.json)"]:::frontend
        W_public["Static Assets (web/public)"]:::frontend
    end

    %% Connections from Client to Server Hub (Network Communication)
    C_core ---|"network"| S_hub
    C_basic ---|"network"| S_hub
    C_desktop ---|"network"| S_hub
    C_file ---|"network"| S_hub
    C_process ---|"network"| S_hub
    C_screenshot ---|"network"| S_hub
    C_terminal ---|"network"| S_hub

    %% Server Hub delivers data to Web Front-End
    S_hub -->|"REST_API/WebSocket"| W_components
    S_web_embed --> W_components

    %% Internal Server Interactions
    S_auth -->|"routes"| S_handler_bridge
    S_auth -->|"routes"| S_handler_file
    S_auth -->|"routes"| S_handler_desktop
    S_auth -->|"routes"| S_handler_process
    S_auth -->|"routes"| S_handler_screenshot
    S_auth -->|"routes"| S_handler_terminal
    S_auth -->|"routes"| S_handler_utility

    S_config --> S_auth
    S_common --> S_handler_file
    S_common --> S_handler_desktop
    S_common --> S_handler_process
    S_common --> S_handler_terminal

    %% Web Build Process
    W_webpack --> S_web_embed
    W_packages --> W_webpack
    W_public --> W_components

    %% Click Events for Client Components
    click C_core "https://github.com/xzb-1248/spark/tree/master/client/core"
    click C_basic "https://github.com/xzb-1248/spark/tree/master/client/service/basic"
    click C_desktop "https://github.com/xzb-1248/spark/tree/master/client/service/desktop"
    click C_file "https://github.com/xzb-1248/spark/tree/master/client/service/file"
    click C_process "https://github.com/xzb-1248/spark/tree/master/client/service/process"
    click C_screenshot "https://github.com/xzb-1248/spark/tree/master/client/service/screenshot"
    click C_terminal "https://github.com/xzb-1248/spark/tree/master/client/service/terminal"

    %% Click Events for Server Components
    click S_auth "https://github.com/xzb-1248/spark/tree/master/server/auth"
    click S_common "https://github.com/xzb-1248/spark/tree/master/server/common"
    click S_config "https://github.com/xzb-1248/spark/tree/master/server/config"
    click S_handler_bridge "https://github.com/xzb-1248/spark/tree/master/server/handler/bridge"
    click S_handler_file "https://github.com/xzb-1248/spark/tree/master/server/handler/file"
    click S_handler_desktop "https://github.com/xzb-1248/spark/tree/master/server/handler/desktop"
    click S_handler_process "https://github.com/xzb-1248/spark/tree/master/server/handler/process"
    click S_handler_screenshot "https://github.com/xzb-1248/spark/tree/master/server/handler/screenshot"
    click S_handler_terminal "https://github.com/xzb-1248/spark/tree/master/server/handler/terminal"
    click S_handler_utility "https://github.com/xzb-1248/spark/tree/master/server/handler/utility"
    click S_web_embed "https://github.com/xzb-1248/spark/tree/master/server/embed/web"

    %% Click Events for Web Front-End Components
    click W_components "https://github.com/xzb-1248/spark/tree/master/web/src/components"
    click W_webpack "https://github.com/xzb-1248/spark/blob/master/web/webpack.config.js"
    click W_packages "https://github.com/xzb-1248/spark/blob/master/web/package.json"
    click W_public "https://github.com/xzb-1248/spark/tree/master/web/public"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef frontend fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    class C_core,C_basic,C_desktop,C_file,C_process,C_screenshot,C_terminal client;
    class S_auth,S_common,S_config,S_handler_bridge,S_handler_file,S_handler_desktop,S_handler_process,S_handler_screenshot,S_handler_terminal,S_handler_utility,S_web_embed,S_hub server;
    class W_components,W_webpack,W_packages,W_public frontend
```
