How ivy-apps/ivy-wallet works
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.