# dhruv282/expense-manager architecture

> Architecture diagram of the GitHub repository dhruv282/expense-manager, 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/dhruv282/expense-manager
- Repository: https://github.com/dhruv282/expense-manager

## Overview

##### Project Type and Purpose
- This is an open-source expense tracking and visualization app built with Flutter.
- It is designed to run on multiple platforms (Android, iOS, Linux, macOS, and Windows) as seen from the platform-specific directories.
- The app connects to a self-hosted PostgreSQL database (configured and launched via Docker Compose) for storing and managing expense data.

##### File Structure for Architectural Elements
- The top-level directories like “android”, “ios”, “linux”, “macos”, “windows” represent platform-specific build targets and configurations.
- The “lib” directory holds the core Flutter code. Within “lib”, you have:
- Components (UI widgets like dashboard widgets, expense forms, navbar, etc.)
- Data (modules for database configuration and expense data)
- Data Sources (which likely deal with fetching and updating expense data)
- Pages (different screens for actions such as adding, editing, viewing expenses, etc.)
- Providers (for state management, e.g., expense_provider)
- Utilities (helpers for database access, logging, showing snackbars, etc.)
- The “db_helper” folder contains a Docker Compose YAML file to spin up a PostgreSQL container.

##### Main Components and Their Interactions
- Flutter Frontend (Client Application)
- UI Layer: Represented by the various “pages” (dashboard, add/edit expense, settings) and “components” (forms, charts, navigation bars).
- State Management: “providers” such as expense_provider manage application state.
- Utility Modules: “utils” (logger, database_manager, snackbars) and “form_helpers” for common UI functionality.
- Data Access Layer: “data” and “data_sources” modules (expense_data, database_config, expense_data_source) encapsulate logic for interfacing with the database.
- Database Configuration Component:
- “database_config_form” where users enter the DB connection details.
- “database_config_store” and “database_manager” manage and persist connection configurations.
- External Database:
- PostgreSQL instance (launched via Docker Compose from db_helper/docker-compose.yml). Note its interactions with the Flutter app through the connection settings provided by the user.
- Optional Scripts & Tools:
- Scripts directory (with CSV migration tool) that might be used for data import/export or migration tasks.

##### Relationships and Architectural Patterns
- The Flutter app is built using best practices for a multi-platform app:
- There’s a separation between presentation (UI components), business logic (providers), and data (data sources, models).
- The architecture reflects a configuration-first approach with an initial database configuration screen that sets up the connection.
- The dependency on an external PostgreSQL database is clearly defined via Docker (ensuring consistency in development and deployment).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter Client (UI & State Layer)
    subgraph "Flutter Client (UI & State Layer)"
        subgraph "UI Components"
            UI_BASE["Components Base"]
            DASH["Dashboard Page"]
            EXPF["Expense Form"]
        end
        STM["State Management"]
        DCF["DB Config UI"]
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        ED["Expense Data"]
        EDS["Expense Data Source"]
        DBC["Database Configuration"]
    end

    %% Utility Modules
    subgraph "Utility Modules"
        DM["Database Manager"]
        DCS["Database Config Store"]
        LS["Logging & Snackbar Utilities"]
        FH["Form Helpers"]
    end

    %% External Services
    subgraph "External Services"
        PG["PostgreSQL Database"]
    end

    %% Optional Scripts & Tools
    subgraph "Optional Scripts & Tools"
        CSV["CSV Migration Tool"]
    end

    %% Connections for Flutter Client
    DASH -->|"triggers"| STM
    EXPF -->|"triggers"| STM
    UI_BASE -->|"uses"| STM

    STM -->|"calls"| EDS
    EDS -->|"fetches"| ED
    STM -->|"notifies"| LS

    DCF -->|"provides config to"| DBC
    DBC -->|"initializes"| DM
    DBC -->|"persists config to"| DCS
    DM -->|"connects to"| PG

    %% Connections for Utility Interaction
    UI_BASE -->|"integrates"| FH

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef optional fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class UI_BASE,DASH,EXPF,STM,DCF frontend;
    class ED,EDS,DBC data;
    class DM,DCS,LS,FH utility;
    class PG external;
    class CSV optional;

    %% Click Events
    click UI_BASE "https://github.com/dhruv282/expense-manager/tree/main/lib/components"
    click DASH "https://github.com/dhruv282/expense-manager/blob/main/lib/pages/dashboard.dart"
    click EXPF "https://github.com/dhruv282/expense-manager/blob/main/lib/components/expense_form/expense_form.dart"
    click STM "https://github.com/dhruv282/expense-manager/blob/main/lib/providers/expense_provider.dart"

    click ED "https://github.com/dhruv282/expense-manager/blob/main/lib/data/expense_data.dart"
    click EDS "https://github.com/dhruv282/expense-manager/blob/main/lib/data_sources/expense_data_source.dart"
    click DBC "https://github.com/dhruv282/expense-manager/blob/main/lib/data/database_config.dart"

    click DM "https://github.com/dhruv282/expense-manager/blob/main/lib/utils/database_manager/database_manager.dart"
    click DCS "https://github.com/dhruv282/expense-manager/blob/main/lib/utils/database_config_store/database_config_store.dart"
    click LS "https://github.com/dhruv282/expense-manager/blob/main/lib/utils/logger/logger.dart"
    click LS "https://github.com/dhruv282/expense-manager/blob/main/lib/utils/snackbar/snackbar.dart"
    click FH "https://github.com/dhruv282/expense-manager/blob/main/lib/components/form_helpers/date_picker.dart"

    click DCF "https://github.com/dhruv282/expense-manager/blob/main/lib/components/database_config_form/database_config_form.dart"

    click PG "https://github.com/dhruv282/expense-manager/blob/main/db_helper/docker-compose.yml"

    click CSV "https://github.com/dhruv282/expense-manager/blob/main/scripts/csv_pg_migration_tool.py"
```
