# dairoportillo/lamassu-machine architecture

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

- Interactive diagram: https://gitdiagram.com/dairoportillo/lamassu-machine
- Repository: https://github.com/dairoportillo/lamassu-machine

## Overview

##### Main Components
a. User Interface (UI) Layer:
- Located in the ui/ directory – includes HTML, CSS, JavaScript (both “src” and built output). This is what the user interacts with directly on the machine (touchscreen, etc.).
b. Business Logic & Core Application:
- Modules in lib/ implement functionality like hardware control (bill dispensers, coin acceptors, printers, cameras), compliance flows, pairing modules, and updates.
- You have dedicated submodules such as “ccnet” (for communication protocols), “f56”, “genmega”, “leds”, “compliance”, “graphql-client.js,” and others.
c. Hardware Interface & Configuration:
- The hardware/ directory is extensive and organizes device-specific configuration and scripts. It includes device configurations (JSON files), calibration scripts, udev rules, and supervisor configurations for managing hardware-related processes.
d. Command-Line Tools and Binaries:
- The bin/ directory contains executable scripts that start different services on the machine (like “cam.js” or “dispense.js”). These typically serve as entry points for controlling specific machine functions.
e. Deployment & Build Infrastructure:
- Dockerfiles, build-scripts, and deploy/ directories indicate containerization and automation for building and updating the system.
f. Additional Supporting Components:
- i18n/ for internationalization supporting multiple languages.
- Tools/ for diagnostics, testing, and utilities.
- Watchdog and update scripts for system health and recovery.

##### Relationships and Interactions
- The UI directly interacts with the core application via JavaScript calls (APIs or direct function calls) that trigger commands (e.g., dispensing cash, scanning IDs, verifying compliance).
- Business logic modules (found in lib/) serve as the glue between the UI and the lower-level hardware drivers. They implement state machines (e.g., in f56, ccnet, id003) and manage data flow to and from physical devices.
- Hardware configuration files and scripts in the hardware/ directory provide device-specific settings that the core application uses to communicate with the machines’ peripherals (bill dispenser, coin acceptors, printers, etc.).
- Deployment scripts and Dockerfiles ensure that when the system boots or updates, the correct services (including supervisor processes) start in the right order.
- Compliance modules (under lib/compliance and mock_data/compliance) also indicate interactions with external validation processes, adding another communication layer between the user interface and internal data flows.

##### Architectural Patterns and Design Principles
- Modularity: The separation of concerns is clear – UI, business logic, hardware interface, and deployment are all organized in separate directories and modules.
- State Management: Many modules (e.g., in f56 and ccnet) implement finite state machines (FSMs) to manage complex device interactions.
- Extensibility: The presence of numerous “device_config.json” files within subdirectories in hardware/ suggests that the system is designed to support a variety of hardware configurations dynamically.
- Containerization: Docker and CI/CD workflows (in .github/workflows/ and build-scripts/) promote easy deployment and consistent runtime environments.

##### Technologies, Frameworks, and Libraries
- Node.js – indicated by the JavaScript code and bin/ executables.
- Docker – multiple Dockerfiles and deployment scripts.
- Supervisor and udev configurations for hardware process management.
- GraphQL (there’s a graphql-client.js) for potential backend communications.
- Various compliance libraries and state machine implementations reflect the system’s protocol-handling.

##### Specific Elements
- Each major component should be clearly labeled:
– “User Interface” (with subcomponents: HTML, CSS, JS modules).
– “Core Logic” (listing important libraries – ccnet, f56, compliance, pairing, etc.).
– “Deployment & Update System” (Docker, CI/CD, supervisor).
– UI ➔ Business Logic: On user actions, commands are sent.
– Business Logic ➔ Hardware Interfaces: State machines processing hardware responses.
– Monitoring, update, and watchdog flows should also be depicted.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["User Interface (HTML/CSS/JS)"] 
    end

    %% Core Application Layer
    subgraph "Core Application Layer"
        Core["Core Logic (Node.js Modules: ccnet, f56, compliance, pairing, GraphQL)"]
    end

    %% Hardware Interface Layer
    subgraph "Hardware Interface Layer"
        HC["Hardware Controllers (e.g., Bill Dispenser, Coin Acceptor, Printer, Camera)"]
    end

    %% Command-Line Tools
    subgraph "Command-Line Tools"
        CLI["Command-Line Tools (Executable Scripts)"]
    end

    %% Deployment & Build Infrastructure
    subgraph "Deployment & Build Infrastructure"
        D1["Dockerfile"]
        D2["Build Scripts"]
        D3["Workflows"]
        D4["Deploy Directory"]
    end

    %% Supporting Components
    I18N["Internationalization (i18n)"]
    Diag["Diagnostics & Utilities"]

    %% Connections Between Layers
    UI -->|"commands"| Core
    Core -->|"controls"| HC
    Core -->|"executes"| CLI
    Core -->|"uses"| I18N
    Core -->|"monitors"| Diag

    %% Deployment updating core and CLI tools
    D1 -->|"updates"| Core
    D2 -->|"updates"| Core
    D3 -->|"updates"| Core
    D4 -->|"updates"| Core
    D1 -->|"deploys"| CLI

    %% Class definitions for colors
    classDef uiLayer fill:#DEF2F1,stroke:#079DA4,stroke-width:2px;
    classDef coreLayer fill:#FFEEAD,stroke:#F7AD06,stroke-width:2px;
    classDef hardwareLayer fill:#C4F1BE,stroke:#2F855A,stroke-width:2px;
    classDef cliLayer fill:#FED7D7,stroke:#E53E3E,stroke-width:2px;
    classDef deploymentLayer fill:#E9D8FD,stroke:#9F7AEA,stroke-width:2px;
    classDef i18nLayer fill:#FFF2CC,stroke:#B58900,stroke-width:2px;
    classDef diagnosticLayer fill:#FFDDEC,stroke:#ED64A6,stroke-width:2px;

    %% Apply styles to nodes
    class UI uiLayer;
    class Core coreLayer;
    class HC hardwareLayer;
    class CLI cliLayer;
    class D1,D2,D3,D4 deploymentLayer;
    class I18N i18nLayer;
    class Diag diagnosticLayer;

    %% Click Events for Component Mapping
    click UI "https://github.com/dairoportillo/lamassu-machine/tree/dev/ui/"
    click Core "https://github.com/dairoportillo/lamassu-machine/tree/dev/lib/"
    click HC "https://github.com/dairoportillo/lamassu-machine/tree/dev/hardware/"
    click CLI "https://github.com/dairoportillo/lamassu-machine/tree/dev/bin/"
    click D1 "https://github.com/dairoportillo/lamassu-machine/tree/dev/Dockerfile"
    click D2 "https://github.com/dairoportillo/lamassu-machine/tree/dev/build-scripts/"
    click D3 "https://github.com/dairoportillo/lamassu-machine/tree/dev/.github/workflows/"
    click D4 "https://github.com/dairoportillo/lamassu-machine/tree/dev/deploy/"
    click I18N "https://github.com/dairoportillo/lamassu-machine/tree/dev/i18n/"
    click Diag "https://github.com/dairoportillo/lamassu-machine/tree/dev/tools/"
```
