How sehajgill23/trackspend works
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: PackageViewModel.kt Package VM · AppNavHost.kt Nav Host · PackageRepository.kt Package Repo · PackageDetailScreen.kt Details
Components 21
Presentation
Compose UI, navigation, and app entry.
- MainActivity · App entry point.
app/src/main/java/com/example/trackspend/MainActivity.kt - Nav Host · Defines the screen graph.
app/src/main/java/com/example/trackspend/navigation/AppNavHost.kt - Bottom Nav · Main tab bar.
app/src/main/java/com/example/trackspend/navigation/BottomNavBar.kt - Home · Package dashboard.
app/src/main/java/com/example/trackspend/ui/home/HomeScreen.kt - Add Package · Manual creation and smart import.
app/src/main/java/com/example/trackspend/ui/add/AddPackageScreen.kt - Details · View, edit, pin, delete package.
app/src/main/java/com/example/trackspend/ui/details/PackageDetailScreen.kt - Stats · Spending and order insights.
app/src/main/java/com/example/trackspend/ui/stats/StatScreen.kt - Charts · Custom visualizations for stats.
app/src/main/java/com/example/trackspend/ui/stats/components/YearlyLineChart.kt - Timeline · Shipment progress visualization.
app/src/main/java/com/example/trackspend/ui/components/TrackingTimeline.kt
State
ViewModel boundary and UI state orchestration.
- Package VM · Main state holder for package UI.
app/src/main/java/com/example/trackspend/viewmodel/PackageViewModel.kt - VM 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 · Coordinates UI actions, storage, tracking, and import.
app/src/main/java/com/example/trackspend/data/repository/PackageRepository.kt - Room DB · On-device persistence boundary.
app/src/main/java/com/example/trackspend/data/local/AppDatabase.kt - Package DAO · Database access for packages and history.
app/src/main/java/com/example/trackspend/data/local/PackageDao.kt - 17Track Repo · Fetches live shipment status.
app/src/main/java/com/example/trackspend/data/tracking/track17/TrackingRepository17.kt - 17Track API · Remote shipment tracking interface.
app/src/main/java/com/example/trackspend/data/tracking/track17/Track17Api.kt - Email Parser · Deterministic regex-based import parsing.
app/src/main/java/com/example/trackspend/data/remote/EmailParser.kt - Store Loader · Loads store metadata from assets.
app/src/main/java/com/example/trackspend/data/remote/StoreLoader.kt - 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 · Store metadata used by Smart Import.
app/src/main/assets/stores.json - 17Track · Shipment tracking service.
Connections 24
- 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.