# azix-khan/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/azix-khan/expense-tracker
- Repository: https://github.com/azix-khan/expense-tracker

## Overview

##### Project Type and Purpose
- This is a cross-platform mobile/desktop/web application built in Flutter.
- It tracks daily expenses, using Bloc for state management and Firebase as its backend.
- A custom Dart package (`expense_repository`) encapsulates data-access logic and entities.

##### File Structure Analysis
- Top-level folders for each Flutter platform: `android/`, `ios/`, `linux/`, `macos/`, `windows/`, `web/`.
- `lib/` holds the core application code:
- `main.dart`, `app.dart`, `app_view.dart` bootstrapping the app and routing.
- `data/` for any local data abstractions.
- `screens/` organized into feature modules (e.g., `add_expense/`, `home/`, `stats/`). Each module follows the Bloc pattern: separate folders for `blocs/` (events, states, bloc classes) and `views/`.
- `simple_bloc_observer.dart` for global Bloc event/state logging.
- `packages/expense_repository/` is a local package containing:
- `entities/` (domain objects like `ExpenseEntity`, `CategoryEntity`)
- `models/` (DTOs for Firebase, JSON)
- `expense_repo.dart` interface and `firebase_expense_repo.dart` implementation.
- Config files: `pubspec.yaml`, `firebase` config in Android (`google-services.json`) and iOS (`Info.plist` alterations).

a. Presentation Layer (Flutter UI)
- Platform Shells: Android, iOS, macOS, Windows, Linux, Web embedded Flutter shells.
- Widgets grouped by feature screens (Splash, Home, Add Expense, Stats).
b. State Management Layer
- Bloc instances per feature:
– `GetExpensesBloc`, `CreateExpenseBloc`, `CreateCategoryBloc`, `GetCategoriesBloc`.
c. Domain/Data Layer
- `expense_repository` package—exposes `ExpenseRepository` interface and returns domain entities.
d. External Services
- Firebase services (Firestore or Realtime Database) for persistence.
- Firebase Auth (if used for user identification).

##### Component Interactions
- UI Widgets dispatch Events → Bloc
- Bloc processes Events + current State → yields States
- Bloc calls `ExpenseRepository` methods (e.g., `getExpenses()`, `createExpense()`, `getCategories()`, `createCategory()`)
- `firebase_expense_repo` implements repository calls → interacts with Firebase SDK
- Firebase returns data → maps to domain Entities → propagates back up to Bloc → UI

##### Architectural Patterns & Principles
- Layered Architecture: Presentation → State Management → Domain/Data → External
- Separation of Concerns: UI purely declares views; Blocs hold business logic; repository abstracts data source.
- Dependency inversion: Feature Blocs depend on abstraction (`ExpenseRepository`), not concrete Firebase implementation.
- Modularization: Local package isolates data layer, making it re-usable/testable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform & Engine
    subgraph "Platform & Flutter Engine"
        Android["Android Shell"]:::presentation
        iOS["iOS Shell"]:::presentation
        Linux["Linux Shell"]:::presentation
        macOS["macOS Shell"]:::presentation
        Windows["Windows Shell"]:::presentation
        Web["Web Shell"]:::presentation
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        MainDart["main.dart"]:::presentation
        AppDart["app.dart"]:::presentation
        AppView["app_view.dart"]:::presentation
        Splash["Splash Screen"]:::presentation
        HomeView["Home Screen"]:::presentation
        MainView["Main Screen"]:::presentation
        AddExpenseView["Add Expense View"]:::presentation
        CategoryCreateView["Category Creation View"]:::presentation
        StatsView["Stats Screen"]:::presentation
        ChartView["Chart View"]:::presentation
    end

    %% State Management
    subgraph "State Management Layer"
        BlocObserver["SimpleBlocObserver"]:::business
        GetExpensesBloc["GetExpensesBloc"]:::business
        CreateExpenseBloc["CreateExpenseBloc"]:::business
        CreateCategoryBloc["CreateCategoryBloc"]:::business
        GetCategoriesBloc["GetCategoriesBloc"]:::business
    end

    %% Domain/Data Layer
    subgraph "Domain/Data Layer"
        ExpenseRepoAPI["ExpenseRepository Interface"]:::data
        FirebaseRepo["FirebaseExpenseRepo Implementation"]:::data
        Entities["Entities (ExpenseEntity, CategoryEntity)"]:::data
        Models["DTO Models (expense, category)"]:::data
    end

    %% External Services
    subgraph "External Services"
        FirebaseDB["Firebase Database"]:::external
        FirebaseAuth["Firebase Auth"]:::external
    end

    %% Connections
    Android -->|runs| MainDart
    iOS -->|runs| MainDart
    Linux -->|runs| MainDart
    macOS -->|runs| MainDart
    Windows -->|runs| MainDart
    Web -->|runs| MainDart

    MainDart -->|initializes| BlocObserver
    MainDart -->|initializes| AppDart
    AppDart -->|builds| AppView

    AppView -->|shows| Splash
    AppView -->|navigates| HomeView
    AppView -->|navigates| AddExpenseView
    AppView -->|navigates| StatsView

    Splash -->|dispatches| GetExpensesBloc
    HomeView -->|dispatches| GetExpensesBloc
    AddExpenseView -->|dispatches| CreateExpenseBloc
    CategoryCreateView -->|dispatches| CreateCategoryBloc
    AddExpenseView -->|dispatches| GetCategoriesBloc
    StatsView -->|dispatches| GetExpensesBloc

    GetExpensesBloc -->|uses| ExpenseRepoAPI
    CreateExpenseBloc -->|uses| ExpenseRepoAPI
    CreateCategoryBloc -->|uses| ExpenseRepoAPI
    GetCategoriesBloc -->|uses| ExpenseRepoAPI

    ExpenseRepoAPI -->|implemented by| FirebaseRepo
    FirebaseRepo -->|reads/writes| FirebaseDB
    FirebaseRepo -->|authenticates| FirebaseAuth
    FirebaseRepo -->|maps to/from| Entities
    FirebaseRepo -->|maps to/from| Models

    GetExpensesBloc -->|emits| HomeView
    CreateExpenseBloc -->|emits| AddExpenseView
    CreateCategoryBloc -->|emits| CategoryCreateView
    GetCategoriesBloc -->|emits| AddExpenseView

    %% Click Events
    click MainDart "https://github.com/azix-khan/expense-tracker/blob/main/lib/main.dart"
    click AppDart "https://github.com/azix-khan/expense-tracker/blob/main/lib/app.dart"
    click AppView "https://github.com/azix-khan/expense-tracker/blob/main/lib/app_view.dart"
    click BlocObserver "https://github.com/azix-khan/expense-tracker/blob/main/lib/simple_bloc_observer.dart"
    click Splash "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/splash_screen.dart"
    click HomeView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/home/views/home_screen.dart"
    click MainView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/home/views/main_screen.dart"
    click GetExpensesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/home/blocs/get_expenses_bloc/get_expenses_bloc.dart"
    click GetExpensesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/home/blocs/get_expenses_bloc/get_expenses_event.dart"
    click GetExpensesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/home/blocs/get_expenses_bloc/get_expenses_state.dart"
    click AddExpenseView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/views/add_expense.dart"
    click CategoryCreateView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/views/category_creation.dart"
    click CreateExpenseBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_expense_bloc/create_expense_bloc.dart"
    click CreateExpenseBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_expense_bloc/create_expense_event.dart"
    click CreateExpenseBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_expense_bloc/create_expense_state.dart"
    click CreateCategoryBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_categorybloc/create_category_bloc.dart"
    click CreateCategoryBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_categorybloc/create_category_event.dart"
    click CreateCategoryBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/create_categorybloc/create_category_state.dart"
    click GetCategoriesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/get_categories_bloc/get_categories_bloc.dart"
    click GetCategoriesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/get_categories_bloc/get_categories_event.dart"
    click GetCategoriesBloc "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/add_expense/blocs/get_categories_bloc/get_categories_state.dart"
    click StatsView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/stats/stats.dart"
    click ChartView "https://github.com/azix-khan/expense-tracker/blob/main/lib/screens/stats/chart.dart"
    click ExpenseRepoAPI "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/expense_repository.dart"
    click Entities "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/entities/expense_entity.dart"
    click Entities "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/entities/category_entity.dart"
    click Models "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/models/expense.dart"
    click Models "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/models/category.dart"
    click ExpenseRepoAPI "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/expense_repo.dart"
    click FirebaseRepo "https://github.com/azix-khan/expense-tracker/blob/main/packages/expense_repository/lib/src/firebase_expense_repo.dart"
    click FirebaseDB "https://github.com/azix-khan/expense-tracker/blob/main/android/app/google-services.json"
    click FirebaseAuth "https://github.com/azix-khan/expense-tracker/blob/main/ios/Runner/Info.plist"

    %% Styles
    classDef presentation fill:#cfe2f3,stroke:#0066cc,color:#000
    classDef business fill:#d9ead3,stroke:#38761d,color:#000
    classDef data fill:#fce5cd,stroke:#e69138,color:#000
    classDef external fill:#f4cccc,stroke:#cc0000,color:#000
```
