# macasteglione/cashscan architecture

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

- Interactive diagram: https://gitdiagram.com/macasteglione/cashscan
- Repository: https://github.com/macasteglione/cashscan

## Overview

##### Project Type and Purpose
- This is a mobile‐centric AI application (“reconocimiento-de-billetes”) with two main parts:
- A Python‐based classifier (under Clasificador/) that trains/tests/validates a TensorFlow Lite model for banknote recognition.
- An Android app (under movil/) written in Kotlin that embeds or invokes that TFLite model (and a helper Python script), displays UI screens, and stores scan history in a local SQLite database.

##### File Structure Analysis
- Top level:
- Clasificador/: Python virtual env + scripts (MCBIA7.py, test* scripts), model file (modelo_billetes.tflite), class mapping.
- movil/: full Android project with:
– app/: source code (domain, data, presentation, UI, adapters, factory for currency models), Python helper (main.py), raw assets (audio prompts), SQLite helper, resource files (layouts, strings).
– Gradle scripts, wrappers, config.
- Patterns & tech:
- Mobile uses MVVM/MVC–style separation: domain, data, factory, adapters, presentation, UITheme.
- Uses embedded Python via Chaquopy or similar (python/ folder).
- Local storage: SQLiteHelper.
- ML inference: TensorFlow Lite (.tflite).

##### C4 Approach

A. Level 1 – System Context
- The “ReconocimientoDeBilletes” system sits within users’ mobile devices.
- External actors: End User (scans bills), optionally a Developer (maintains classifier).
- External systems: none (fully on‐device).

1. Android App Container
– Language: Kotlin
– Framework: Android SDK
– Responsibilities: UI, camera preview, user flows, data persistence.
2. Python Classifier Container
– Language: Python 3.11 in virtualenv
– Frameworks: TensorFlow, TFLite Interpreter
– Responsibilities: preprocess image, run inference with modelo_billetes.tflite, return class.
3. Local SQLite Database
– Technology: SQLite
– Stores: scan history, user settings.
4. Model File
– TensorFlow Lite (.tflite) loaded by the Python container or directly by mobile.

- Android App → Python Classifier: send camera frame → inference result
- App ↔ SQLite: read/write scan history and config
- App loads .tflite from assets to classifier

Inside the Android App container, break out major components:
1. UI Layer
– Activities: MainActivity, ScanBillActivity, CountBillActivity, ConfigActivity, TutorialActivity, IntroActivity
– Adapters: BillsAdapter, ModelListAdapter, IntroViewPagerAdapter
2. Presentation Layer
– CameraPreview, Utils
3. Domain Layer
– Data classes: BillData, Model, ScreenItem
4. Data Layer
– SQLiteHelper for persistence
5. Factory Layer
– ModelFactory & ConcreteModelFactory choose correct currency model (ArsModel, UsdModel, BrlModel)
6. Python Integration
– main.py invoked via Chaquopy (or equivalent) bridging Android → Python
– classifier call and mapping via mapeo_clases.json

Interactions:
- UI → Presentation → Domain → Data / Python Integration → returns to UI
- Factory supplies domain models to UI

##### Architectural Patterns & Design Principles
- Separation of concerns: UI, presentation, domain, data, factory
- MVC/MVVM‐like layering in Android
- On‐device ML inference using TFLite
- Extensibility via Factory Method for currency models
- Local persistence (offline operation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% System Context
    subgraph "ReconocimientoDeBilletes System"
        direction TB
        User[/"End User"/]:::external
        App["Android App Container"]:::android
        PythonSvc["Python Classifier Container"]:::python
        DB["SQLite Database"]:::data
        ModelFile["TensorFlow Lite Model File"]:::data
    end

    %% Context Relationships
    User -->|"scans bills"| App
    App -->|"loads .tflite"| ModelFile
    App -->|"send camera frame"| PythonSvc
    PythonSvc -->|"inference result"| App
    App <-->|"read/write scan history"| DB

    %% Click Events for Container
    click App "https://github.com/macasteglione/cashscan/tree/main/movil/app/"
    click PythonSvc "https://github.com/macasteglione/cashscan/tree/main/Clasificador/"
    click DB "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/data/SQLiteHelper.kt"
    click ModelFile "https://github.com/macasteglione/cashscan/blob/main/Clasificador/modelo_billetes.tflite"

    %% Inside Android App Container - Component Diagram
    subgraph "Android App Container" 
        direction TB
        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            MainActivity["MainActivity"]:::android
            ScanBillActivity["ScanBillActivity"]:::android
            CountBillActivity["CountBillActivity"]:::android
            ConfigActivity["ConfigActivity"]:::android
            TutorialActivity["TutorialActivity"]:::android
            IntroActivity["IntroActivity"]:::android
            BillsAdapter["BillsAdapter"]:::android
            IntroViewPagerAdapter["IntroViewPagerAdapter"]:::android
            ModelListAdapter["ModelListAdapter"]:::android
        end

        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            CameraPreview["CameraPreview"]:::android
            Utils["Utils"]:::android
        end

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            BillData["BillData"]:::android
            ModelDomain["Model"]:::android
            ScreenItem["ScreenItem"]:::android
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            SQLiteHelper["SQLiteHelper"]:::android
        end

        %% Factory Layer
        subgraph "Factory Layer"
            direction TB
            ModelFactory["ModelFactory"]:::android
            ConcreteModelFactory["ConcreteModelFactory"]:::android
            ArsModel["ArsModel"]:::android
            UsdModel["UsdModel"]:::android
            BrlModel["BrlModel"]:::android
        end

        %% Python Integration
        PythonBridge["main.py (Chaquopy)"]:::python
    end

    %% Component Interactions
    MainActivity -->|"user actions"| CameraPreview
    ScanBillActivity -->|"capture frame"| CameraPreview
    CameraPreview -->|"frame data"| PythonBridge
    PythonBridge -->|"class result"| ScanBillActivity
    ScanBillActivity -->|"save history"| SQLiteHelper
    MainActivity -->|"load models"| ModelFactory
    ModelFactory --> ConcreteModelFactory
    ConcreteModelFactory --> ArsModel
    ConcreteModelFactory --> UsdModel
    ConcreteModelFactory --> BrlModel
    BillsAdapter --> ModelDomain
    IntroActivity --> IntroViewPagerAdapter
    ConfigActivity --> Utils

    %% Click Events for Components
    click MainActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/MainActivity.kt"
    click ScanBillActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/ScanBillActivity.kt"
    click CountBillActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/CountBillActivity.kt"
    click ConfigActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/ConfigActivity.kt"
    click TutorialActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/TutorialActivity.kt"
    click IntroActivity "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/IntroActivity.kt"
    click BillsAdapter "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/adapters/BillsAdapter.kt"
    click IntroViewPagerAdapter "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/adapters/IntroViewPagerAdapter.kt"
    click ModelListAdapter "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/adapters/ModelListAdapter.kt"
    click CameraPreview "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/presentation/CameraPreview.kt"
    click Utils "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/presentation/Utils.kt"
    click BillData "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/domain/BillData.kt"
    click ModelDomain "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/domain/Model.kt"
    click ScreenItem "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/domain/ScreenItem.kt"
    click SQLiteHelper "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/data/SQLiteHelper.kt"
    click ModelFactory "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/factory/ModelFactory.kt"
    click ConcreteModelFactory "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/factory/ConcreteModelFactory.kt"
    click ArsModel "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/models/ArsModel.kt"
    click UsdModel "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/models/UsdModel.kt"
    click BrlModel "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/java/com/example/reconocimiento_billetes/models/BrlModel.kt"
    click PythonBridge "https://github.com/macasteglione/cashscan/blob/main/movil/app/src/main/python/main.py"

    %% Python Classifier Details
    subgraph "Python Classifier Container"
        direction TB
        ClassifierScript["MCBIA7.py"]:::python
        TestScript1["testIAM.py"]:::python
        TestScript2["testModeloTFLite.py"]:::python
        TestScript3["testIA.py"]:::python
        ClassMap["mapeo_clases.json"]:::python
    end
    ClassifierScript --> ClassMap
    ClassifierScript --> ModelFile

    click ClassifierScript "https://github.com/macasteglione/cashscan/blob/main/Clasificador/src/main/MCBIA7.py"
    click TestScript1 "https://github.com/macasteglione/cashscan/blob/main/Clasificador/src/main/testIAM.py"
    click TestScript2 "https://github.com/macasteglione/cashscan/blob/main/Clasificador/src/main/testModeloTFLite.py"
    click TestScript3 "https://github.com/macasteglione/cashscan/blob/main/Clasificador/src/testIA.py"
    click ClassMap "https://github.com/macasteglione/cashscan/blob/main/Clasificador/src/mapeo_clases.json"

    %% Styles
    classDef android fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef python fill:#D0FFD6,stroke:#28A745,color:#1F6FEB
    classDef data fill:#FFF4B8,stroke:#DF7E07,color:#8A3FFC
    classDef external fill:#E0E0E0,stroke:#6A737D,color:#24292E
```
