# armanmaurya/balancr architecture

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

- Interactive diagram: https://gitdiagram.com/armanmaurya/balancr
- Repository: https://github.com/armanmaurya/balancr

## Overview

##### Project Type and Purpose
- **Type**: Cross-platform mobile & desktop application built with Flutter.
- **Purpose**: Manage shared expenses—add members, track transactions, view balances, and settle up.

##### File Structure
- **Top-Level Folders**
- android, ios, linux, macos, windows, web → platform-specific shell projects
- lib → core Dart code (UI, business logic, data models)
- .github/workflows → CI/CD definitions
- **Inside lib/**
- models → Person & Transaction classes, generated code (e.g. JSON serialization)
- providers → `LedgerProvider` (state-management/business logic)
- screens → UI pages (home, onboarding, add/search person, transactions)
- widgets → reusable UI controls (buttons, cards, lists, bottom sheets, inputs)
- **Configuration Files**
- pubspec.yaml/lock → dependencies (Flutter SDK, provider, build_runner, json_serializable, local-storage plugin)
- CI workflow → automated builds/releases

##### Key Insights from README
- Uses **Flutter ≥3.29.2**
- Core features: expense/member management, balance overview, settle-up
- No remote server—assumed local persistence (e.g., SQLite or Hive)

##### Main Components and Their Interactions
a. **Platform Shells**
- Android, iOS, macOS, Windows, Linux, Web projects serve as native wrappers for the Flutter Engine.
b. **Flutter Engine & Dart Runtime**
- The common runtime hosting UI and business logic across platforms.
c. **Presentation Layer (UI)**
- **Screens**: onboarding, home, add/search person, transaction
- **Widgets**: cards, buttons, lists, inputs, modals
d. **Business Logic Layer**
- **LedgerProvider** (Provider pattern): orchestrates state, exposes methods to add/edit persons & transactions, computes balances
e. **Data Layer**
- **Models**: Person & Transaction classes with JSON (de)serialization
- **Local Persistence**: plugin (SQLite, Hive, or similar) for storing/fetching model instances
f. **CI/CD**
- **GitHub Actions** workflow for testing, building, and releasing across platforms

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation between UI, business logic, and data
- **Provider Pattern**: for state management & dependency injection
- **MVVM-style** separation (Views in screens/widgets, ViewModel in providers)
- **Code Generation**: for model serialization (`.g.dart` files)
- **Cross-Platform Abstraction**: shared Dart code + platform channels/plugins

##### Putting It All Together
- **Center**: Flutter Engine hosting
- Presentation Layer (Screens → Widgets → Assets)
- Business Logic Layer (`LedgerProvider`)
- Data Layer (Models → Local DB)
- **Right side**: CI/CD pipeline (GitHub Actions)
- **External Plugins**: path_provider, sqflite/hive, device_info – connect to Flutter Engine or directly to data layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Shells
    subgraph "Platform Shells"
        direction LR
        Android["Android"]:::shell
        iOS["iOS"]:::shell
        Web["Web"]:::shell
        macOS["macOS"]:::shell
        Linux["Linux"]:::shell
        Windows["Windows"]:::shell
    end

    %% Flutter Engine
    FlutterEngine["Flutter Engine & Dart Runtime"]:::shell

    %% Presentation Layer
    subgraph "Presentation Layer (UI)" 
        direction TB
        subgraph Screens
            OnboardingScreen["OnboardingScreen"]:::ui
            OnboardingPage1["OnboardingPage1"]:::ui
            OnboardingPage2["OnboardingPage2"]:::ui
            HomeScreen["HomeScreen"]:::ui
            AddPerson["AddPersonScreen"]:::ui
            SearchPerson["SearchPersonScreen"]:::ui
            TransactionScreen["TransactionScreen"]:::ui
        end
        subgraph Widgets
            DeleteButton["DeleteButton"]:::ui
            UpdateButton["UpdateButton"]:::ui
            BalanceCard["BalanceCard"]:::ui
            BalanceSummaryCard["BalanceSummaryCard"]:::ui
            PersonCard["PersonCard"]:::ui
            PersonContactCard["PersonContactCard"]:::ui
            TransactionCard["TransactionCard"]:::ui
            SearchBar["SearchBar"]:::ui
            ContactList["ContactListWidget"]:::ui
            MenuSheet["MenuBottomSheet"]:::ui
            ConfirmSheet["ConfirmationBottomSheet"]:::ui
            DeleteSheet["DeletePersonBottomSheet"]:::ui
            EditSheet["EditPersonBottomSheet"]:::ui
        end
        AssetsIcons["assets/icons"]:::ui
        AssetsIllust["assets/illustrations"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer" 
        LedgerProvider["LedgerProvider"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        PersonModel["Person Model"]:::data
        TransactionModel["Transaction Model"]:::data
        DB[(Local DB)]:::data
    end

    %% CI/CD
    CICD["GitHub Actions CI/CD"]:::ci

    %% External Plugins
    subgraph "Plugins & Tools"
        PathProvider["path_provider"]:::plugin
        LocalStorage["sqflite/Hive"]:::plugin
        DeviceInfo["device_info"]:::plugin
    end

    %% Connections
    Android -->|wraps| FlutterEngine
    iOS -->|wraps| FlutterEngine
    Web -->|wraps| FlutterEngine
    macOS -->|wraps| FlutterEngine
    Linux -->|wraps| FlutterEngine
    Windows -->|wraps| FlutterEngine

    FlutterEngine -->|hosts UI| OnboardingScreen
    FlutterEngine --> HomeScreen
    FlutterEngine -->|hosts| Widgets
    FlutterEngine --> LedgerProvider
    FlutterEngine --> PersonModel
    FlutterEngine --> TransactionModel
    FlutterEngine --> PathProvider
    FlutterEngine --> LocalStorage
    FlutterEngine --> DeviceInfo

    OnboardingScreen --> OnboardingPage1
    OnboardingScreen --> OnboardingPage2

    %% UI to Business Logic
    HomeScreen -->|uses| LedgerProvider
    AddPerson -->|calls| LedgerProvider
    SearchPerson -->|calls| LedgerProvider
    TransactionScreen -->|calls| LedgerProvider

    %% Business Logic to Data
    LedgerProvider -->|reads/writes| PersonModel
    LedgerProvider -->|reads/writes| TransactionModel
    LedgerProvider -->|persists| DB

    %% Models to DB
    PersonModel --> DB
    TransactionModel --> DB

    %% CI/CD
    CICD -.-> Android
    CICD -.-> iOS
    CICD -.-> Web
    CICD -.-> macOS
    CICD -.-> Linux
    CICD -.-> Windows
    CICD -.-> FlutterEngine

    %% Click Events
    click Android "https://github.com/armanmaurya/balancr/tree/main/android/"
    click iOS "https://github.com/armanmaurya/balancr/tree/main/ios/"
    click Web "https://github.com/armanmaurya/balancr/tree/main/web/"
    click macOS "https://github.com/armanmaurya/balancr/tree/main/macos/"
    click Linux "https://github.com/armanmaurya/balancr/tree/main/linux/"
    click Windows "https://github.com/armanmaurya/balancr/tree/main/windows/"
    click FlutterEngine "https://github.com/armanmaurya/balancr/blob/main/lib/main.dart"
    click OnboardingScreen "https://github.com/armanmaurya/balancr/blob/main/lib/screens/onboarding/onboarding_screen.dart"
    click OnboardingPage1 "https://github.com/armanmaurya/balancr/blob/main/lib/screens/onboarding/onboarding_page1.dart"
    click OnboardingPage2 "https://github.com/armanmaurya/balancr/blob/main/lib/screens/onboarding/onboarding_page2.dart"
    click HomeScreen "https://github.com/armanmaurya/balancr/blob/main/lib/screens/home_screen.dart"
    click AddPerson "https://github.com/armanmaurya/balancr/blob/main/lib/screens/add_person.dart"
    click SearchPerson "https://github.com/armanmaurya/balancr/blob/main/lib/screens/search_person.dart"
    click TransactionScreen "https://github.com/armanmaurya/balancr/blob/main/lib/screens/transaction_screen.dart"
    click DeleteButton "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/buttons/delete_button.dart"
    click UpdateButton "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/buttons/update_button.dart"
    click BalanceCard "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/cards/balance_card.dart"
    click BalanceSummaryCard "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/cards/balance_summary_card.dart"
    click PersonCard "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/cards/person_card.dart"
    click PersonContactCard "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/cards/person_contact_card.dart"
    click TransactionCard "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/cards/transaction_card.dart"
    click SearchBar "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/inputs/search_bar.dart"
    click ContactList "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/lists/contact_list_widget.dart"
    click MenuSheet "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/menu/menu_bottom_sheet.dart"
    click ConfirmSheet "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/modal_bottom_sheets/confirmation_bottom_sheet.dart"
    click DeleteSheet "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/modal_bottom_sheets/delete_person_bottom_sheet.dart"
    click EditSheet "https://github.com/armanmaurya/balancr/blob/main/lib/widgets/modal_bottom_sheets/edit_person_bottom_sheet.dart"
    click AssetsIcons "https://github.com/armanmaurya/balancr/tree/main/assets/icons/"
    click AssetsIllust "https://github.com/armanmaurya/balancr/tree/main/assets/illustrations/"
    click LedgerProvider "https://github.com/armanmaurya/balancr/blob/main/lib/providers/ledger_provider.dart"
    click PersonModel "https://github.com/armanmaurya/balancr/blob/main/lib/models/person.dart"
    click TransactionModel "https://github.com/armanmaurya/balancr/blob/main/lib/models/transaction.dart"
    click DB "https://github.com/armanmaurya/balancr/blob/main/pubspec.yaml"
    click PathProvider "https://github.com/armanmaurya/balancr/blob/main/pubspec.yaml"
    click LocalStorage "https://github.com/armanmaurya/balancr/blob/main/pubspec.yaml"
    click CICD "https://github.com/armanmaurya/balancr/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef shell fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ci fill:#B0C4DE,stroke:#000,stroke-width:1px
    classDef plugin fill:#E0FFFF,stroke:#000,stroke-width:1px
```
