# cuonvc/ex-money architecture

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

- Interactive diagram: https://gitdiagram.com/cuonvc/ex-money
- Repository: https://github.com/cuonvc/ex-money

## Overview

##### Project Type and Purpose
- This is a mobile-first expense tracking application built with Flutter. It targets both Android and iOS (with additional support for web, desktop, etc.). The project contains a well-organized UI and state management using the Bloc pattern, along with modular business logic located in the repository package.
- The README indicates that there is a separate backend (a Spring-based API or Docker image) that the mobile app communicates with. There’s also integration with Firebase for authentication (Google Sign-In) and likely push notifications.

##### Main Components
a. Mobile Frontend (Flutter Application):
- UI/Screens: All the views under lib/screens (authentication, main views, expense, wallet, etc.).
- State Management: Numerous Bloc modules (found under lib/screens/*/blocs) that handle events, states, and transitions.
- Reusable Widgets: Various widget files (lib/widgets) that provide common UI components.
- Utilities: Helper modules (lib/utils, lib/notification_service.dart) for platform-specific code and constants.
- External Assets: Assets directories for images and animations.
- Platform-Specific Directories: Directories for Android, iOS, web, etc., indicating platform customizations.

b. Repository/Business Logic:
- The packages/repository directory provides controllers, repositories, and models, encapsulating business logic and routing service calls (like expense, category, user, wallet, notifications, etc.). This forms the data integration layer in the app.

c. Backend Component (Separate):
- Although not within the current file tree, the README instructs to clone and run a separate backend (see provided GitHub link) using Spring or Docker image.
- A server-side component that exposes APIs for handling expense tracking, user authentication, notifications, and other CRUD operations.
- The backend is likely connected to one or more databases.

d. External Services:
- Firebase: Both for user authentication and client app configuration (google-services.json for Android, Info.plist configuration for iOS).
- Google Sign-In: Integrated as part of Firebase authentication.

##### Interactions and Relationships
- The Flutter App’s UI layer (screens, widgets) triggers user actions.
- These actions are managed by the Bloc layers (presentation/business logic) which then interact with the repository package.
- The repository package forms a client to interact with the backend’s RESTful APIs (or similar) to send or receive data (expense creation, category management, notifications, etc.).
- Firebase services, including authentication and possibly analytics or push notifications, interact with the mobile app directly.
- The Backend is standalone. It receives API calls from the mobile app and processes data requests/issues. It also interacts with a database for persistent storage.

##### Architectural Patterns and Design Principles
- MVC-like or layered architecture within the Flutter ecosystem: The separation between the UI (views/widgets), state management (BLoCs), and the data/service layer (repository).
- Repository Pattern: The “packages/repository” provides a clear abstraction over the backend APIs.
- Cross-Platform Development: Separate directories for Android, iOS, web, desktop all using the common business logic and UI components.
- Dependency Injection and Observer patterns: Notable with BLoC and utilities connections.
- Platform-specific configuration: Android, iOS, Linux, macOS, Windows directories hold their own build files and configurations, but share the core business logic.

##### Elements
- Clear Labels:
- “Flutter Mobile App” (with subcomponents: UI/Screens, BloC/State Management, Widgets)
- “Repository / Data Access Layer” (from the packages/repository)
- “Backend API” (Spring-based backend service, external to the current file tree)
- “Firebase Authentication & External Services”
- “Database” (connected to the backend)
- How the UI sends events to the BloCs.
- Communication between mobile service (Firebase integration) and the app.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services Section
    subgraph "External Services"
        EX("Firebase & Google Sign-In"):::external
    end

    %% Mobile Client Section
    subgraph "Mobile Client"
        UI("UI Screens"):::mobile
        BLOC("State Management (Bloc Modules)"):::mobile
        WIDGETS("Reusable Widgets"):::mobile
        UTILS("Utils (lib/utils)"):::mobile
        NOTIF("Notification Service (lib/notification_service.dart)"):::mobile
        ASSETS("External Assets"):::mobile
        REPO("Repository Package"):::mobile
        ANDROID("Android Configurations"):::mobile
        IOS("iOS Configurations"):::mobile
    end

    %% Backend Services Section
    subgraph "Backend Services"
        BACKEND("Backend API (Spring Boot)"):::backend
        DB("Database"):::backend
    end

    %% Connections - External to Mobile
    EX -->|"auth,notify"| UI

    %% Connections within Mobile Client
    UI -->|"triggersEvents"| BLOC
    UI -->|"usesWidgets"| WIDGETS
    UI -->|"usesUtils"| UTILS
    UI -->|"loadsAssets"| ASSETS
    UI -->|"platformConfig"| ANDROID
    UI -->|"platformConfig"| IOS
    BLOC -->|"apiCalls"| REPO

    %% Connection from Mobile to Backend
    REPO -->|"RESTCalls"| BACKEND

    %% Backend processing
    BACKEND -->|"storesData"| DB

    %% Click Events
    click UI "https://github.com/cuonvc/ex-money/tree/develop/lib/screens"
    click BLOC "https://github.com/cuonvc/ex-money/tree/develop/lib/screens/*/blocs"
    click WIDGETS "https://github.com/cuonvc/ex-money/tree/develop/lib/widgets"
    click UTILS "https://github.com/cuonvc/ex-money/tree/develop/lib/utils"
    click NOTIF "https://github.com/cuonvc/ex-money/blob/develop/lib/notification_service.dart"
    click ASSETS "https://github.com/cuonvc/ex-money/tree/develop/assets"
    click REPO "https://github.com/cuonvc/ex-money/tree/develop/packages/repository"
    click ANDROID "https://github.com/cuonvc/ex-money/tree/develop/android"
    click IOS "https://github.com/cuonvc/ex-money/tree/develop/ios"

    %% Styles
    classDef mobile fill:#C5E1A5,stroke:#33691E,stroke-width:2px;
    classDef external fill:#FFE082,stroke:#F57F17,stroke-width:2px;
    classDef backend fill:#BBDEFB,stroke:#1565C0,stroke-width:2px;
```
