# sehajgill23/trackspend architecture

> Architecture diagram of the GitHub repository sehajgill23/trackspend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sehajgill23/trackspend
- Repository: https://github.com/sehajgill23/trackspend

## Overview

TrackSpend is a single-client Android app: there is no custom backend in this repo. The app is built in Kotlin with Jetpack Compose and follows an MVVM-style flow from UI to ViewModel to repository to local/remote data sources.

1. **Presentation shell**
   - `MainActivity` is the app entry point.
   - `navigation/AppNavHost.kt` defines the screen graph, and `BottomNavBar.kt` provides the main tabbed navigation.
   - The main screens are organized by feature: Home, Add Package, Package Details/Edit, and Stats.

2. **UI layer**
   - The `ui/` package contains feature screens implemented with Compose.
   - `ui/home` shows the package dashboard.
   - `ui/add` handles manual package creation and Smart Import.
   - `ui/details` supports viewing, editing, pinning, and deleting a package.
   - `ui/stats` contains spending and order analytics, with custom chart components under `ui/stats/components`.

3. **State and ViewModel boundary**
   - `viewmodel/PackageViewModel.kt` is the main state holder for package-related UI.
   - `PackageViewModelFactory` wires its dependencies.
   - The UI is driven through reactive state updates using Kotlin Flow/State, rather than direct database or network access from screens.

4. **Repository as the orchestration layer**
   - `data/repository/PackageRepository.kt` is the central coordination point.
   - It bridges user actions from the ViewModel to:
     - local persistence for saved packages,
     - remote shipment tracking for live status,
     - parsing/import helpers for Smart Import.
   - This is the main architectural boundary worth drawing between presentation and data.

5. **Local persistence**
   - Room is used for on-device storage.
   - `AppDatabase`, `PackageDao`, and `PackageEntity` define the local database layer.
   - `DatabaseModule` provides database wiring.
   - This is where package records and their associated tracking/history data are persisted.

6. **Shipment tracking integration**
   - The app integrates with the external **17Track** service through `data/tracking/track17/`.
   - `Track17Api`, `Track17Client`, request/response models, and `TrackingRepository17` encapsulate the network boundary.
   - Live shipment status is fetched from this API rather than being computed locally.

7. **Smart Import / email parsing**
   - `data/remote/EmailParser.kt` and `ParsedEmailInfo.kt` implement deterministic regex-based extraction from pasted order emails.
   - `StoreLoader.kt` reads store metadata from `assets/stores.json`.
   - This feature is intentionally local: the app parses text on-device and does not send email content to an AI or third-party parsing service.

8. **Domain/data models**
   - `TrackingEvent`, `StoreCount`, and the types under `data/tracking/TrackingModels.kt` represent data used across UI and stats.
   - These models connect persisted package data, imported order metadata, and live shipment updates.

9. **Analytics and visualization**
   - The stats area is a separate feature boundary focused on spending insights.
   - `StatScreen` and its detail screens summarize monthly ordering/spending.
   - Custom Compose charts such as line, bar, and segmented ring visualizations turn stored package/order data into trends.

10. **Support utilities and app-wide configuration**
   - `ui/theme/` defines Material 3 styling.
   - `util/NetworkUtils.kt` likely guards remote tracking calls based on connectivity.
   - Resources and assets include launcher assets, theme values, and the store list used by Smart Import.

11. **Overall data flow**
   - User interaction starts in Compose screens.
   - Screens call into `PackageViewModel`.
   - The ViewModel delegates to `PackageRepository`.
   - The repository reads/writes Room, invokes the 17Track network client when live tracking is needed, and uses local parsing/asset loading for Smart Import.
   - Analytics screens read the same underlying package/order data to produce spending charts.

12. **Architecture summary for diagramming**
   - Draw the app as a mostly local, offline-first Android client with three external boundaries:
     - **Room database** for persistence,
     - **17Track API** for shipment tracking,
     - **assets/stores.json** for import enrichment.
   - Everything else is internal Compose/MVVM plumbing around those boundaries.

Main entry points: [`app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt`](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt) (Package VM), [`app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt`](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt) (Nav Host), [`app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt`](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt) (Package Repo), [`app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt`](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt) (Details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main_activity["MainActivity<br/>entrypoint<br/>[MainActivity.kt]"]
  node_nav_host["Nav Host<br/>navigation<br/>[AppNavHost.kt]"]
  node_bottom_nav["Bottom Nav<br/>navigation<br/>[BottomNavBar.kt]"]
  node_home_screen["Home<br/>compose screen<br/>[HomeScreen.kt]"]
  node_add_screen["Add Package<br/>compose screen"]
  node_detail_screens["Details<br/>compose screens"]
  node_stats_screen["Stats<br/>analytics ui<br/>[StatScreen.kt]"]
  node_stats_charts["Charts<br/>chart components<br/>[YearlyLineChart.kt]"]
  node_tracking_timeline["Timeline<br/>compose component"]
end

subgraph group_state["State"]
  node_package_vm["Package VM<br/>viewmodel"]
  node_vm_factory["VM Factory"]
end

subgraph group_data["Data"]
  node_package_repo["Package Repo"]
  node_db[("Room DB<br/>local storage<br/>[AppDatabase.kt]")]
  node_package_dao["Package DAO<br/>[PackageDao.kt]"]
  node_track17_repo["17Track Repo<br/>tracking client"]
  node_track17_api["17Track API<br/>network api<br/>[Track17Api.kt]"]
  node_email_parser["Email Parser<br/>[EmailParser.kt]"]
  node_store_loader["Store Loader<br/>asset loader<br/>[StoreLoader.kt]"]
  node_models["Models<br/>[TrackingModels.kt]"]
end

subgraph group_external["External"]
  node_stores_asset["stores.json<br/>asset<br/>[stores.json]"]
  node_track17_service(("17Track<br/>external service"))
end

node_main_activity -->|"hosts"| node_nav_host
node_nav_host -->|"uses"| node_bottom_nav
node_nav_host -->|"routes to"| node_home_screen
node_nav_host -->|"routes to"| node_add_screen
node_nav_host -->|"routes to"| node_detail_screens
node_nav_host -->|"routes to"| node_stats_screen
node_home_screen -->|"observes"| node_package_vm
node_add_screen -->|"updates"| node_package_vm
node_detail_screens -->|"updates"| node_package_vm
node_stats_screen -->|"reads"| node_package_vm
node_stats_screen -->|"renders"| node_stats_charts
node_detail_screens -->|"renders"| node_tracking_timeline
node_vm_factory -->|"creates"| node_package_vm
node_package_vm -->|"delegates"| node_package_repo
node_package_repo -->|"reads/writes"| node_db
node_db -->|"exposes"| node_package_dao
node_package_repo -->|"fetches status"| node_track17_repo
node_track17_repo -->|"calls"| node_track17_api
node_track17_api -.->|"remote"| node_track17_service
node_package_repo -->|"imports"| node_email_parser
node_package_repo -->|"enriches"| node_store_loader
node_store_loader -->|"reads"| node_stores_asset
node_package_repo -->|"shares"| node_models
node_package_vm -->|"publishes"| node_models

click node_main_activity "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/MainActivity.kt"
click node_nav_host "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt"
click node_bottom_nav "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/navigation/BottomNavBar.kt"
click node_home_screen "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/home/HomeScreen.kt"
click node_add_screen "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/add/AddPackageScreen.kt"
click node_detail_screens "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt"
click node_stats_screen "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/stats/StatScreen.kt"
click node_stats_charts "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/stats/components/YearlyLineChart.kt"
click node_tracking_timeline "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/components/TrackingTimeline.kt"
click node_package_vm "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt"
click node_vm_factory "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/viewmodel/PackageViewModelFactory.kt"
click node_package_repo "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt"
click node_db "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/local/AppDatabase.kt"
click node_package_dao "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/local/PackageDao.kt"
click node_track17_repo "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/track17/TrackingRepository17.kt"
click node_track17_api "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/track17/Track17Api.kt"
click node_email_parser "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/remote/EmailParser.kt"
click node_store_loader "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/remote/StoreLoader.kt"
click node_models "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/TrackingModels.kt"
click node_stores_asset "https://github.com/sehajgill23/trackspend/blob/main/app/src/main/assets/stores.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_activity,node_nav_host,node_bottom_nav,node_home_screen,node_add_screen,node_detail_screens,node_stats_screen,node_stats_charts,node_tracking_timeline toneBlue
class node_package_vm,node_vm_factory toneAmber
class node_package_repo,node_db,node_package_dao,node_track17_repo,node_track17_api,node_email_parser,node_store_loader,node_models toneMint
class node_stores_asset,node_track17_service toneRose
```

## Components

### Presentation

Compose UI, navigation, and app entry.

- [MainActivity](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/MainActivity.kt): entrypoint · App entry point. · `app/src/main/java/com/example/trackspend/MainActivity.kt`
- [Nav Host](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt): navigation · Defines the screen graph. · `app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt`
- [Bottom Nav](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/navigation/BottomNavBar.kt): navigation · Main tab bar. · `app/src/main/java/com/example/trackspend/navigation/BottomNavBar.kt`
- [Home](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/home/HomeScreen.kt): compose screen · Package dashboard. · `app/src/main/java/com/example/trackspend/ui/home/HomeScreen.kt`
- [Add Package](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/add/AddPackageScreen.kt): compose screen · Manual creation and smart import. · `app/src/main/java/com/example/trackspend/ui/add/AddPackageScreen.kt`
- [Details](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt): compose screens · View, edit, pin, delete package. · `app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt`
- [Stats](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/stats/StatScreen.kt): analytics ui · Spending and order insights. · `app/src/main/java/com/example/trackspend/ui/stats/StatScreen.kt`
- [Charts](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/stats/components/YearlyLineChart.kt): chart components · Custom visualizations for stats. · `app/src/main/java/com/example/trackspend/ui/stats/components/YearlyLineChart.kt`
- [Timeline](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/ui/components/TrackingTimeline.kt): compose component · Shipment progress visualization. · `app/src/main/java/com/example/trackspend/ui/components/TrackingTimeline.kt`

### State

ViewModel boundary and UI state orchestration.

- [Package VM](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt): viewmodel · Main state holder for package UI. · `app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt`
- [VM Factory](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/viewmodel/PackageViewModelFactory.kt): factory · Wires ViewModel dependencies. · `app/src/main/java/com/example/trackspend/viewmodel/PackageViewModelFactory.kt`

### Data

Local persistence, tracking integration, parsing, and repository orchestration.

- [Package Repo](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt): repository · Coordinates UI actions, storage, tracking, and import. · `app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt`
- [Room DB](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/local/AppDatabase.kt): local storage · On-device persistence boundary. · `app/src/main/java/com/example/trackspend/data/local/AppDatabase.kt`
- [Package DAO](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/local/PackageDao.kt): dao · Database access for packages and history. · `app/src/main/java/com/example/trackspend/data/local/PackageDao.kt`
- [17Track Repo](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/track17/TrackingRepository17.kt): tracking client · Fetches live shipment status. · `app/src/main/java/com/example/trackspend/data/tracking/track17/TrackingRepository17.kt`
- [17Track API](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/track17/Track17Api.kt): network api · Remote shipment tracking interface. · `app/src/main/java/com/example/trackspend/data/tracking/track17/Track17Api.kt`
- [Email Parser](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/remote/EmailParser.kt): parser · Deterministic regex-based import parsing. · `app/src/main/java/com/example/trackspend/data/remote/EmailParser.kt`
- [Store Loader](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/remote/StoreLoader.kt): asset loader · Loads store metadata from assets. · `app/src/main/java/com/example/trackspend/data/remote/StoreLoader.kt`
- [Models](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/java/com/example/trackspend/data/tracking/TrackingModels.kt): domain models · Shared tracking and stats types. · `app/src/main/java/com/example/trackspend/data/tracking/TrackingModels.kt`

### External

Non-code boundaries the app depends on.

- [stores.json](https://github.com/sehajgill23/trackspend/blob/main/app/src/main/assets/stores.json): asset · Store metadata used by Smart Import. · `app/src/main/assets/stores.json`
- **17Track**: external service · Shipment tracking service.

## Connections

- MainActivity → Nav Host: hosts · Activity sets up app navigation.
- Nav Host → Bottom Nav: uses · Navigation shell includes tab bar.
- Nav Host → Home: routes to · Defines entry to dashboard.
- Nav Host → Add Package: routes to · Defines entry to add flow.
- Nav Host → Details: routes to · Defines detail/edit flow.
- Nav Host → Stats: routes to · Defines analytics screens.
- Home → Package VM: observes · Reads reactive package state.
- Add Package → Package VM: updates · Submits create/import actions.
- Details → Package VM: updates · Submits edit/pin/delete actions.
- Stats → Package VM: reads · Uses shared package/order data.
- Stats → Charts: renders · Builds analytics views with charts.
- Details → Timeline: renders · Shows shipment progress UI.
- VM Factory → Package VM: creates · Provides repository-backed ViewModel.
- Package VM → Package Repo: delegates · Moves business actions into repository.
- Package Repo → Room DB: reads/writes · Persists package data locally.
- Room DB → Package DAO: exposes · Room database provides DAO access.
- Package Repo → 17Track Repo: fetches status · Requests live shipment updates when needed.
- 17Track Repo → 17Track API: calls · Uses the network API boundary.
- 17Track API → 17Track: remote · External shipment tracking service.
- Package Repo → Email Parser: imports · Parses pasted order emails locally.
- Package Repo → Store Loader: enriches · Loads store metadata for Smart Import.
- Store Loader → stores.json: reads · Loads packaged store list from assets.
- Package Repo → Models: shares · Creates and consumes domain models.
- Package VM → Models: publishes · Exposes UI state derived from shared models.
