# maicollgomezsanchez/arca_project architecture

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

- Interactive diagram: https://gitdiagram.com/maicollgomezsanchez/arca_project
- Repository: https://github.com/maicollgomezsanchez/arca_project

## Overview

##### Project type and purpose
- This is a Python‐based embedded GUI application built with the Kivy framework, targeting a Raspberry Pi (or similar) platform. It provides a “Control Interface” with three operation modes (Manual, Semi, Auto), time‐control buttons, special function buttons (buzzer, “comer fichas”, descarga), and system state controls (START/PAUSE/STOP).

##### File structure
- Top‐level folders:
- babylandia, carrusel, escalestri, test
– Each contains a Kivy layout file (`game.kv`) and a main entry‐point (`main.py` or `game.py`).
– `escalestri` also includes a hardware abstraction module (`hardware.py`).
- kivy/config.ini – custom Kivy configuration.
- test/ – unit and integration tests for UI logic and hardware calls.
- videos/ – demonstration recordings.
- Config files and build artifacts:
- `main.spec` (PyInstaller spec)
- `.gitignore`
- systemd service definition under README instructions (game.service)

##### README for additional insights
- Core functionality breakdown (modes, timers, special buttons).
- Packaging and deployment steps: virtualenv, dependencies (Kivy, gpiozero, pigpio), PyInstaller bundling, systemd service setup.
- Touchscreen calibration and Kivy config tweaks.

##### Detail is key
- Explicitly show `hardware.py` as the abstraction over gpiozero/pigpio.
- Don’t omit the systemd service or PyInstaller packaging—they’re critical for deployment on the target hardware.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & Hardware Layer
    subgraph "User & Hardware Layer"
        Touch["Touchscreen Input"]:::external
        Actuators["Actuators (Motors, Buzzer, LEDs, Fichas)"]:::external
    end

    %% UI Layer
    subgraph "UI Layer"
        KivyFramework["Kivy Framework"]:::ui
        KV_baby["babylandia/game.kv"]:::ui
        KV_car["carrusel/game.kv"]:::ui
        KV_esc["escalestri/game.kv"]:::ui
    end

    %% Application Logic
    subgraph "Application Logic"
        Main_baby["babylandia/main.py"]:::logic
        Main_car["carrusel/main.py"]:::logic
        Main_esc["escalestri/main.py"]:::logic
        StateMachine["App State Machine"]:::logic
    end

    %% Hardware Abstraction Layer
    subgraph "Hardware Abstraction Layer"
        HardwarePy["escalestri/hardware.py"]:::hw
        GPIOlibs["gpiozero / pigpio"]:::external
    end

    %% Persistence & Logging
    Log["logs.txt"]:::storage

    %% Deployment & OS
    subgraph "Deployment & OS"
        Spec["escalestri/main.spec"]:::dep
        ServiceDoc["README.md (game.service)"]:::dep
        ConfigIni["kivy/config.ini"]:::dep
    end

    %% Testing Suite
    subgraph "Testing Suite"
        Test_game["test/game.py"]:::test
        Test_hw["test/hardware.py"]:::test
        Test_hmi["test/hmi.py"]:::test
        Test_pines["test/pines.py"]:::test
        Test_popup["test/popup.py"]:::test
        Test_kv["test/game.kv"]:::test
        Test_cambios["test/control_de_cambios"]:::test
    end

    %% Demonstrations
    subgraph "Demonstrations"
        Video["videos/Grabación de pantalla desde 2025-04-20 18-09-34.webm"]:::external
    end

    %% Connections
    Touch -->|"touch events"| KivyFramework
    KivyFramework -->|"loads KV"| KV_baby
    KivyFramework -->|"loads KV"| KV_car
    KivyFramework -->|"loads KV"| KV_esc
    KivyFramework -->|"dispatch events"| Main_baby
    KivyFramework -->|"dispatch events"| Main_car
    KivyFramework -->|"dispatch events"| Main_esc

    Main_baby -->|"uses"| StateMachine
    Main_car -->|"uses"| StateMachine
    Main_esc -->|"uses"| StateMachine

    StateMachine -->|"calls"| HardwarePy
    HardwarePy -->|"wraps"| GPIOlibs
    HardwarePy --> Actuators

    StateMachine -->|"logs events"| Log

    ConfigIni -->|"overrides"| KivyFramework
    Spec -->|"bundles"| Main_esc
    ServiceDoc -->|"launches"| Main_esc

    Test_game -->|"tests UI logic"| Main_baby
    Test_hw -->|"tests hardware"| HardwarePy
    Test_hmi -->|"tests UI events"| KivyFramework
    Test_pines -->|"tests GPIO pins"| GPIOlibs
    Test_popup -->|"tests popups"| KV_esc
    Test_kv -->|"validates KV"| KV_baby
    Test_cambios -->|"change control tests"| StateMachine

    Video -.->|"demos"| KivyFramework

    %% Click Events
    click KV_baby "https://github.com/maicollgomezsanchez/arca_project/blob/main/babylandia/game.kv"
    click KV_car "https://github.com/maicollgomezsanchez/arca_project/blob/main/carrusel/game.kv"
    click KV_esc "https://github.com/maicollgomezsanchez/arca_project/blob/main/escalestri/game.kv"
    click Main_baby "https://github.com/maicollgomezsanchez/arca_project/blob/main/babylandia/main.py"
    click Main_car "https://github.com/maicollgomezsanchez/arca_project/blob/main/carrusel/main.py"
    click Main_esc "https://github.com/maicollgomezsanchez/arca_project/blob/main/escalestri/main.py"
    click HardwarePy "https://github.com/maicollgomezsanchez/arca_project/blob/main/escalestri/hardware.py"
    click ConfigIni "https://github.com/maicollgomezsanchez/arca_project/blob/main/kivy/config.ini"
    click Spec "https://github.com/maicollgomezsanchez/arca_project/blob/main/escalestri/main.spec"
    click ServiceDoc "https://github.com/maicollgomezsanchez/arca_project/blob/main/README.md"
    click Test_game "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/game.py"
    click Test_hw "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/hardware.py"
    click Test_hmi "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/hmi.py"
    click Test_pines "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/pines.py"
    click Test_popup "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/popup.py"
    click Test_kv "https://github.com/maicollgomezsanchez/arca_project/blob/main/test/game.kv"
    click Test_cambios "https://github.com/maicollgomezsanchez/arca_project/tree/main/test/control_de_cambios"
    click Video "https://github.com/maicollgomezsanchez/arca_project/blob/main/videos/Grabación de pantalla desde 2025-04-20 18-09-34.webm"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef logic fill:#d4edda,stroke:#28a745,color:#000;
    classDef hw fill:#fff3cd,stroke:#ffc107,color:#000;
    classDef dep fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef storage fill:#f5c6cb,stroke:#dc3545,color:#000;
    classDef external fill:#d1ecf1,stroke:#17a2b8,color:#000;
    classDef test fill:#f8d7da,stroke:#721c24,color:#000;
```
