# ivy-apps/ivy-wallet architecture

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

- Interactive diagram: https://gitdiagram.com/ivy-apps/ivy-wallet
- Repository: https://github.com/ivy-apps/ivy-wallet

## Overview

##### Project Type and Purpose
- The project is a modern, modular Android application for money management. It leverages 100% Kotlin and Jetpack Compose, and it is built using a multi-module architecture. Its structure supports different financial tracking features (accounts, budgets, reports, transactions, etc.) as well as widgets, shared libraries, and legacy code.
- The README clearly explains that Ivy Wallet is a manual expense tracker meant to replace spreadsheets and includes details of its tech stack (e.g., Kotlin, Compose, Hilt, Coroutines, Room, DataStore, and more).

##### Analyzing the File Structure
- Key top-level directories:
- “app”: Represents the main Android application including the AndroidManifest, dependency injection setups, and primary entry points (activities, application class).
- “screen”: Contains individual modules for each feature or UI flow (e.g., accounts, balance, budgets, categories, loans, transactions, onboarding, etc.). Each module has its own Gradle file and source code structured around presentation logic (Compose UI, view models, events, etc.).
- “shared”: Provides common code and reusable components across the app. This includes:
– shared/base: Core dependencies, DI bindings, utilities, and legacy helper classes.
– shared/data: Layers for data access, Room database implementations, repository layer, and network (Ktor client) integrations.
– shared/domain: Use Cases, business logic, and domain models.
– shared/ui and shared/navigation: The design system, navigation graph, and common UI elements.
- “widget”: Contains separate modules for Android home screen widgets (add transaction, balance) plus a shared base for widget code.
- Additional directories such as “buildSrc”, “ci-actions”, “docs”, “temp/legacy-code”, and “old-design” indicate build customizations, CI pipelines, documentation, and archival code/design approaches.
- The structure clearly follows a modular approach (often aligned with MVVM and clean architecture principles) where each screen or domain feature is isolated as its own module yet shares common resources from “shared”.

##### Key Components
- Main Application Module:
- “app”: The Android app module hosting the Application subclass, entry activities, and central DI (Hilt) configuration.
- Feature Modules:
- “screen”: Sub-modules for each feature (Accounts, Budgets, Categories, Loans, Transactions, Reports, etc.). Each screen module represents a self-contained UI flow, including its own view models, states, and events.
- Shared/Reusable Layers:
- “shared/base”: Utility classes, legacy support, and cross-cutting concerns (e.g., logging, thread management).
- “shared/data”: Data layer including Room implementation for local persistence and remote data sources using Ktor.
- “shared/domain”: Use cases and business logic that encapsulate financial calculations and core transactions.
- “shared/ui” and “shared/navigation”: Material3 design system, common UI components, and navigation flows across screens.
- Widgets:
- “widget”: Separate modules for home screen widgets, like the “add-transaction” and “balance” widgets.
- Build & Automation/CI:
- “buildSrc” and “ci-actions”: Represent build scripts and automated CI/CD processes.
- Legacy & Old Design:
- “temp/legacy-code” and “old-design”: Provide context on previous architectural attempts, helpful to understand historical evolution and possibly integration with legacy features.

##### Relationships and Interactions
- The main “app” module depends on various screen modules and the shared libraries.
- Screen modules (Presentation layer) interact with the domain layer (shared/domain) through view models and use cases.
- The domain layer handles business logic and communicates with the data layer (shared/data) which manages persistence (via Room/Datastore) and remote calls (via Ktor and Kotlinx Serialization).
- The navigation module (shared/navigation) provides a central route management system for the large number of screens.
- Widgets are built on the same base as the application (using shared resources from “widget/shared-base”) and interact with the data and potentially the domain layer.
- Build configuration and CI tools (from “buildSrc” and “ci-actions”) stand apart as infrastructure that automates the building, testing, and deployment of the entire project.

##### Architectural Patterns and Design Principles
- Modularization: The project is decomposed into several modules (screens, shared, widget, etc.) which can be individually built and tested.
- Clean/MVVM Architecture: Separation of concerns is evident with UI (screens), domain (business logic/use cases), and data (repositories and persistence) layers.
- Dependency Injection: Hilt is used for injecting repositories, use cases, and other dependencies.
- Reactive Programming: Kotlin Coroutines and Flow are used to handle data streams and asynchronous operations.
- Testing: There is robust support for unit tests and screenshot tests (using JUnit4, Kotest, Paparazzi) that validate individual components.

##### Elements
- Each component or module with clear names (e.g., App, Screen/Accounts, Screen/Budgets, Shared – Base, Data, Domain, UI, Navigation, Widgets).
- Annotations to briefly explain the role of each component or layer.

## Diagram (Mermaid)

```mermaid
graph TB

    %% Application Layer
    subgraph "Application Layer"
        App["App Module"]:::appStyle
        Screens["Screens Modules"]:::screenStyle
    end

    %% Shared Layers
    subgraph "Shared Layers"
        SharedBase["Shared Base"]:::sharedBaseStyle
        SharedData["Shared Data"]:::dataStyle
        SharedDomain["Shared Domain"]:::domainStyle
        SharedUI["Shared UI"]:::uiStyle
        SharedNav["Shared Navigation"]:::uiStyle
    end

    %% Widgets
    subgraph "Widgets"
        Widgets["Widgets Module"]:::widgetStyle
    end

    %% Infrastructure
    subgraph "Infrastructure"
        BuildSrc["buildSrc"]:::infraStyle
        CiActions["ci-actions"]:::infraStyle
    end

    %% Legacy & Old Design
    subgraph "Legacy & Old Design"
        LegacyCode["Legacy Code"]:::legacyStyle
        OldDesign["Old Design"]:::legacyStyle
    end

    %% Relationships
    App -->|"uses"| Screens
    App -->|"configures_DI"| SharedBase
    Screens -->|"calls_usecases"| SharedDomain
    Screens -->|"uses"| SharedUI
    Screens -->|"routes_via"| SharedNav
    SharedDomain -->|"accesses"| SharedData
    Widgets -->|"relies_on"| SharedDomain
    Widgets -->|"leverages"| SharedBase
    Widgets -->|"displays"| SharedUI
    BuildSrc -->|"builds"| App
    CiActions -->|"CI_CD"| App
    App -->|"backward_support"| LegacyCode
    LegacyCode -->|"integrates_with"| SharedBase
    App -->|"includes"| OldDesign

    %% Click Events
    click App "https://github.com/ivy-apps/ivy-wallet/tree/main/app/"
    click Screens "https://github.com/ivy-apps/ivy-wallet/tree/main/screen/"
    click SharedBase "https://github.com/ivy-apps/ivy-wallet/tree/main/shared/base/"
    click SharedData "https://github.com/ivy-apps/ivy-wallet/tree/main/shared/data/"
    click SharedDomain "https://github.com/ivy-apps/ivy-wallet/tree/main/shared/domain/"
    click SharedUI "https://github.com/ivy-apps/ivy-wallet/tree/main/shared/ui/"
    click SharedNav "https://github.com/ivy-apps/ivy-wallet/tree/main/shared/ui/navigation/"
    click Widgets "https://github.com/ivy-apps/ivy-wallet/tree/main/widget/"
    click BuildSrc "https://github.com/ivy-apps/ivy-wallet/tree/main/buildSrc/"
    click CiActions "https://github.com/ivy-apps/ivy-wallet/tree/main/ci-actions/"
    click LegacyCode "https://github.com/ivy-apps/ivy-wallet/tree/main/temp/legacy-code/"
    click OldDesign "https://github.com/ivy-apps/ivy-wallet/tree/main/temp/old-design/"

    %% Styles
    classDef appStyle fill:#fef2cc,stroke:#d4ac0d,stroke-width:2px;
    classDef screenStyle fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef sharedBaseStyle fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef dataStyle fill:#fcf3cf,stroke:#f39c12,stroke-width:2px;
    classDef domainStyle fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef uiStyle fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef widgetStyle fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef infraStyle fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef legacyStyle fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
```
