# magicinuse/cnc-tank architecture

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

- Interactive diagram: https://gitdiagram.com/magicinuse/cnc-tank
- Repository: https://github.com/magicinuse/cnc-tank

## Overview

##### Main Components
- Frontend (Client):
- This is located in the “client” directory and built using React, Tailwind CSS, and Vite.
- It includes various UI components like the Dashboard, Configuration Menu, Real-time Console, Map, and File Comparison interface.
- It also employs Socket.IO client integration for real-time bidirectional communication.
- Backend (Server):
- Found in the “server” directory. It is built on Node.js with Express.
- It provides a RESTful API with multiple endpoints for commands, configuration updates, status polling, and firmware updates.
- It uses Socket.IO to manage real-time events and communications with the client.
- Microcontroller Integration (ESP32):
- The “_ESP32” folder contains firmware and code (e.g., machine.cpp, preferences.cpp, and mapping docs) for controlling the ESP32 microcontroller.
- This component represents the embedded system that directly drives and monitors the CNC machine, interfacing with GRBL settings.

##### Relationships and Data Flow
- The Frontend communicates with the Backend primarily via:
- HTTP/RESTful API calls for initiating commands, update processes, and configuration changes.
- WebSocket (Socket.IO) connections for real-time data such as machine status updates and real-time console feedback.
- The Backend, in turn, communicates with the ESP32 microcontroller:
- It sends commands (movement, configuration changes) and receives feedback/status updates.
- It also manages mapping and configuration via files and dedicated controllers (e.g., configController, movementController).

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- The project cleanly separates the presentation layer (client) from the business logic and API (server) and the hardware interface (ESP32).
- MVC-Like Structure on the Backend:
- Controllers, routes, and configuration files indicate an organized structure for processing requests.
- Real-Time Communication:
- Integration of Socket.IO ensures low-latency, bidirectional communications between client and server.
- Modularization:
- Different directories for specific functionalities (e.g., components in the client, separate controllers in the server) enhance maintainability.

##### Technologies to Highlight
- Frontend: React, Tailwind CSS, Vite, and Socket.IO Client.
- Backend: Node.js, Express, Socket.IO server library, and Axios for API calls.
- Embedded: ESP32 microcontroller with GRBL firmware for CNC control.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Components
    subgraph "Frontend (Client Application)"
        FE_index["Index.html (UI)"]:::frontend
        FE_app["App.jsx (React Application)"]:::frontend
        FE_config["Config Files (Vite & Tailwind)"]:::frontend
        FE_components["UI Components (Dashboard, Console, Map, FileCompare)"]:::frontend
    end

    %% Backend Components
    subgraph "Backend (API Server)"
        BE_server["Server (Express)"]:::backend
        BE_ctrl["Controllers (config, movement, status, update)"]:::backend
        BE_routes["API Routes"]:::backend
        BE_config["ESP32 Config (esp32.js)"]:::backend
        BE_socket["Socket.IO Server"]:::backend
    end

    %% ESP32 Components
    subgraph "ESP32 Microcontroller"
        ESP_machine["Machine Firmware (machine.cpp)"]:::esp32
        ESP_preferences["Preferences (preferences.cpp)"]:::esp32
        ESP_pinmap["Pin Map Documentation"]:::esp32
        ESP_grbl["GRBL Map Documentation"]:::esp32
    end

    %% Data Flow Arrows
    FE_components -->|"HTTP/REST"| BE_server
    FE_components -->|"Socket.IO"| BE_socket
    BE_server -->|"Delegates-to"| BE_ctrl
    BE_server -->|"Handles"| BE_routes
    BE_ctrl -->|"Reads"| BE_config
    BE_server -->|"Sends Commands/Receives Status"| ESP_machine
    BE_socket -->|"RealTime Events"| ESP_machine

    %% Click Events
    click FE_index "https://github.com/magicinuse/cnc-tank/blob/main/client/index.html"
    click FE_app "https://github.com/magicinuse/cnc-tank/blob/main/client/src/App.jsx"
    click FE_config "https://github.com/magicinuse/cnc-tank/blob/main/client/vite.config.js"
    click BE_server "https://github.com/magicinuse/cnc-tank/blob/main/server/src/server.js"
    click BE_ctrl "https://github.com/magicinuse/cnc-tank/blob/main/server/src/controllers/configController.js"
    click BE_routes "https://github.com/magicinuse/cnc-tank/tree/main/server/src/routes/api"
    click BE_config "https://github.com/magicinuse/cnc-tank/blob/main/server/src/config/esp32.js"
    click ESP_machine "https://github.com/magicinuse/cnc-tank/blob/main/_ESP32/machine.cpp"
    click ESP_preferences "https://github.com/magicinuse/cnc-tank/blob/main/_ESP32/preferences.cpp"
    click ESP_pinmap "https://github.com/magicinuse/cnc-tank/blob/main/_ESP32/PinMap.md"
    click ESP_grbl "https://github.com/magicinuse/cnc-tank/blob/main/_ESP32/grblMap.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef esp32 fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
