# marcoxmarquez/scaling-couscous architecture

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

- Interactive diagram: https://gitdiagram.com/marcoxmarquez/scaling-couscous
- Repository: https://github.com/marcoxmarquez/scaling-couscous

## Overview

##### Project Type and Purpose
- This is a native Android mobile application (“VerificaMTC”) written in Java/Kotlin DSL for Gradle.
- It serves as a client-side identity verification tool for driving exams in Peru, integrating:
- RENIEC identity validation (external government API)
- On-device facial recognition using TensorFlow Lite (local biometric authentication)
- Administrative and user dashboards
- Real-time data synchronization via Firebase

##### File Structure Analysis
- Top-level “app” module: Android Studio project with Gradle build scripts (`build.gradle.kts`, `settings.gradle.kts`).
- `src/main/java/com/master/verificamtc`: subdivided into packages—
- `auth`: UI activities for login/registration flows
- `admin`: admin dashboard and face recognition activities
- `user`: user dashboards, payment, schedule, vehicle management
- `helpers`: data-access layer (Firebase helpers, local SQLite helper), face-recognition engine wrappers
- `utils`: cryptographic utilities (BCrypt, AES encryption)
- `src/main/assets`: TFLite models (`facenet.tflite`, `mobile_face_net.tflite`)
- Firebase configuration in `google-services.json` and related helpers (`FirebaseDatabaseHelper`, `FireDatabaseStore`)
- Local persistence via `LocalDatabaseHelper` (SQLite or Room)

##### Key Components
a. Mobile App (Android Device)
- UI Layer: Activities/Fragments in `auth`, `admin`, `user` packages
- Business Logic Layer: ViewModels/controllers coordinating flows
- Data Layer:
- Local Database (SQLite) – `LocalDatabaseHelper`
- On-device Face Recognition – `TFLiteFaceRecognition`, `FaceClassifier`, `FaceDatabaseHelper`
- Remote Backend – Firebase Auth, Firebase Realtime Database / Firestore (via `FirebaseDatabaseHelper`)
b. External Services
- RENIEC API (RESTful Government identity validation)
- Firebase Cloud Services (Auth, Database, Storage, Cloud Functions if any)
c. Security Components
- Encryption Module – `SecurityHelper` (AES/BCrypt for sensitive data at rest and in transit)

##### Relationships & Data Flows
- Startup/UI → Business Logic → Data Layer
- Authentication Flow: App ←→ Firebase Auth
- Registration Flow:
- App → RENIEC API (identity check)
- App → Firebase Database (store user profile)
- Biometric Flow:
- Camera input → `FaceDetectionActivity` → `TFLiteFaceRecognition` → local face embeddings store (`FaceDatabaseHelper`)
- Decision → App → Firebase (update authentication status)
- Real-time Sync: Data changes in Firebase Database ↔ App UI via listeners in `FirebaseDatabaseHelper`
- Local Persistence: Caching user/session data in SQLite to support offline scenarios

##### Architectural Patterns & Principles
- MVC/MVVM flavor: separation of UI (Activities) and data/business logic (helpers, classifiers)
- Repository pattern in helpers – abstracts data source (local vs. remote)
- Modular package structure: `auth`, `admin`, `user`, `helpers`, `utils`
- Secure data handling: encryption utilities, secure storage of credentials

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android App Container
    subgraph "Android App"
        direction TB

        subgraph "UI Layer" 
            direction TB
            AuthSelector["AuthSelectorActivity"]:::ui
            AuthUser["AuthUserActivity"]:::ui
            AuthAdmin["AuthAdminActivity"]:::ui
            AuthRegister["AuthRegisterActivity"]:::ui

            AdminDash["AdminDashboardActivity"]:::ui
            UserDetails["UserDetailsActivity"]:::ui

            FaceDetectUI["FaceDetectionActivity"]:::ui
            RecognitionUI["RecognitionActivity"]:::ui
            RegisterFaceUI["RegisterActivity"]:::ui

            UserDash["UserDashboardActivity"]:::ui

            ExamSelect["ExamSelectionActivity"]:::ui
            Payment["PaymentActivity"]:::ui
            UserPayment["UserPaymentActivity"]:::ui

            Schedule["UserScheduleActivity"]:::ui

            Circuit["UserCircuitActivity"]:::ui
            OverlayView["OverlayView"]:::ui

            Vehicle["UserVehicleActivity"]:::ui
        end

        subgraph "Business Logic Layer"
            direction TB
            FirebaseHelper["FirebaseDatabaseHelper"]:::logic
            FireStore["FireDatabaseStore"]:::logic
            LocalDBHelper["LocalDatabaseHelper"]:::logic
            TFLiteEngine["TFLiteFaceRecognition"]:::logic
            FaceClassifier["FaceClassifier"]:::logic
            FaceDBHelper["FaceDatabaseHelper"]:::logic
            GraphicOverlay["GraphicOverlay"]:::logic
            DBViewer["DatabaseViewerActivity"]:::logic
        end

        subgraph "Data Layer"
            direction TB
            LocalDB[(SQLite/Room)]:::data
            FaceDB[(Face Embeddings DB)]:::data
            MLModel["TFLite Models"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RENIEC["RENIEC API"]:::external
        FirebaseAuth["Firebase Auth"]:::external
        FirebaseDB["Firebase Realtime DB"]:::external
    end

    %% Security Module
    SecurityHelper["SecurityHelper (AES/BCrypt)"]:::security

    %% Flows
    AuthRegister -->|"identity check"| RENIEC
    RENIEC -->|"response"| AuthRegister

    AuthRegister -->|store profile| FirebaseDB
    AuthSelector -->|login| FirebaseAuth
    FirebaseAuth -->|auth result| AuthUser

    FaceDetectUI -->|capture→detect| TFLiteEngine
    TFLiteEngine -->|classify| FaceClassifier
    FaceClassifier -->|store embeddings| FaceDBHelper
    FaceDBHelper -->|local store| FaceDB

    RegisterFaceUI -->|register face| FaceDBHelper
    RecognitionUI -->|match| FaceDBHelper
    RecognitionUI -->|update status| FirebaseDB

    FirebaseHelper -->|sync data| UserDash
    FirebaseHelper -->|listen changes| AdminDash

    %% Data persistence
    LocalDBHelper -->|cache data| LocalDB
    FirebaseHelper -->|remote ops| FirebaseDB

    %% Security flows
    FirebaseDB -->|encrypt/decrypt| SecurityHelper
    LocalDB -->|encrypt/decrypt| SecurityHelper

    %% Click Events
    click AuthSelector "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/auth/AuthSelectorActivity.java"
    click AuthUser "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/auth/AuthUserActivity.java"
    click AuthAdmin "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/auth/AuthAdminActivity.java"
    click AuthRegister "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/auth/AuthRegisterActivity.java"
    click AdminDash "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/admin/dashboard/AdminDashboardActivity.java"
    click UserDetails "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/admin/dashboard/UserDetailsActivity.java"
    click FaceDetectUI "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/admin/recognition/FaceDetectionActivity.java"
    click RecognitionUI "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/admin/recognition/RecognitionActivity.java"
    click RegisterFaceUI "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/admin/recognition/RegisterActivity.java"
    click UserDash "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/dashboard/UserDashboardActivity.java"
    click ExamSelect "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/payment/ExamSelectionActivity.java"
    click Payment "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/payment/PaymentActivity.java"
    click UserPayment "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/payment/UserPaymentActivity.java"
    click Schedule "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/schedule/UserScheduleActivity.java"
    click Circuit "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/circuit/UserCircuitActivity.java"
    click OverlayView "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/circuit/OverlayView.java"
    click Vehicle "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/user/vehicle/UserVehicleActivity.java"
    click FirebaseHelper "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/FirebaseDatabaseHelper.java"
    click FireStore "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/FireDatabaseStore.java"
    click LocalDBHelper "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/LocalDatabaseHelper.java"
    click TFLiteEngine "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/facerecognition/TFLiteFaceRecognition.java"
    click FaceClassifier "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/facerecognition/FaceClassifier.java"
    click FaceDBHelper "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/facerecognition/FaceDatabaseHelper.java"
    click GraphicOverlay "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/vision/GraphicOverlay.java"
    click DBViewer "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/helpers/DatabaseViewerActivity.java"
    click SecurityHelper "https://github.com/marcoxmarquez/scaling-couscous/blob/main/app/src/main/java/com/master/verificamtc/utils/SecurityHelper.java"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef logic fill:#E8E8E8,stroke:#000,stroke-width:1px
    classDef data fill:#D0FFD6,stroke:#000,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef security fill:#E1D5E7,stroke:#000,stroke-width:1px
```
