How dairoportillo/lamassu-machine works
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.