# geoffreymainadigital/gmdparser architecture

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

- Interactive diagram: https://gitdiagram.com/geoffreymainadigital/gmdparser
- Repository: https://github.com/geoffreymainadigital/gmdparser

## Overview

GMDParser is an Android-first personal-finance app that turns M-PESA SMS messages into reviewed, user-confirmed transactions, then sends them through a Vercel API gateway to a Google Apps Script backend and Google Sheets ledger. Android also supports financial dashboards, history, taxonomy, savings, accounts, debts, goals, PIN protection, themes, and reminders; the web portal provides an additional interface. Backend implementation files are absent from the supplied tree, so Apps Script and Sheets are represented as documented external services. Some subsystem links are based on README statements rather than sampled implementation.

Main entry points: [`android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt`](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt) (Transaction repository), [`android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/MainActivity.kt) (App navigation), [`web/api`](https://github.com/geoffreymainadigital/gmdparser/tree/main/web/api) (Vercel API routes), [`android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt) (Review and confirm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and review"]
  node_sms_receive["SMS receiver<br/>[SmsReceiver.kt]"]
  node_parser["M-PESA parser<br/>[MpesaParser.kt]"]
  node_review["Review and confirm"]
  node_scan["SMS scan dialog<br/>[SmsScanDialog.kt]"]
end

subgraph group_mobile["Android finance app"]
  node_transactions["Transaction repository"]
  node_transaction_model["Transaction model<br/>[Transaction.kt]"]
  node_app_shell["App navigation<br/>[MainActivity.kt]"]
  node_dashboard["Dashboard<br/>[DashboardScreen.kt]"]
  node_finance_screens["Finance screens"]
  node_taxonomy["Taxonomy repository"]
  node_network["Network client<br/>[NetworkClient.kt]"]
  node_api_service["API service<br/>[ApiService.kt]"]
  node_preferences[("App preferences<br/>[AppPreferences.kt]")]
  node_pin["PIN lock<br/>[PinLockScreen.kt]"]
  node_theme["Theme manager<br/>[ThemeManager.kt]"]
  node_reminders["Review reminders"]
end

subgraph group_gateway["Web gateway"]
  node_web_portal["Web portal<br/>[app.js]"]
  node_web_api["Vercel API routes"]
  node_auth_guard["API auth guard<br/>[auth-guard.js]"]
end

subgraph group_ledger["Financial backend"]
  node_apps_script["Apps Script backend"]
  node_sheets[("Google Sheets ledger")]
end

node_sms(("M-PESA SMS"))
node_android_os(("Android OS<br/>external system"))

node_sms -->|"arrives at"| node_sms_receive
node_sms_receive -.->|"parses message"| node_parser
node_scan -->|"scans message"| node_parser
node_review -->|"parses entered SMS"| node_parser
node_review -->|"stages transaction"| node_transactions
node_review -.->|"submits confirmation"| node_transactions
node_transactions -->|"stores transaction data"| node_transaction_model
node_app_shell -->|"routes to"| node_dashboard
node_app_shell -->|"routes to"| node_finance_screens
node_app_shell -->|"gates app access"| node_pin
node_app_shell -->|"initializes and fetches"| node_transactions
node_dashboard -->|"reads financial data"| node_transactions
node_finance_screens -.->|"uses transaction data"| node_transactions
node_finance_screens -.->|"uses taxonomy"| node_taxonomy
node_transactions -->|"submits API requests"| node_api_service
node_transactions -->|"uses API client"| node_network
node_taxonomy -->|"fetches taxonomy"| node_network
node_network -->|"provides service"| node_api_service
node_api_service -->|"calls HTTPS endpoints"| node_web_api
node_web_portal -.->|"uses API"| node_web_api
node_web_api -->|"checks authorization"| node_auth_guard
node_web_api -.->|"proxies requests"| node_apps_script
node_apps_script -->|"validates and writes"| node_sheets
node_pin -.->|"uses stored settings"| node_preferences
node_theme -->|"reads and saves theme"| node_preferences
node_reminders -.->|"schedules notifications"| node_android_os

click node_sms_receive "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/receiver/SmsReceiver.kt"
click node_parser "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/parser/MpesaParser.kt"
click node_review "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt"
click node_scan "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/components/SmsScanDialog.kt"
click node_transactions "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt"
click node_transaction_model "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/model/Transaction.kt"
click node_app_shell "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/MainActivity.kt"
click node_dashboard "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/DashboardScreen.kt"
click node_finance_screens "https://github.com/geoffreymainadigital/gmdparser/tree/main/android/app/src/main/java/com/gmdparser/ui/screens"
click node_taxonomy "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/repository/TaxonomyRepository.kt"
click node_network "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/network/NetworkClient.kt"
click node_api_service "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/network/ApiService.kt"
click node_preferences "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/util/AppPreferences.kt"
click node_pin "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/PinLockScreen.kt"
click node_theme "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/theme/ThemeManager.kt"
click node_reminders "https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/util/ReviewReminderManager.kt"
click node_web_portal "https://github.com/geoffreymainadigital/gmdparser/blob/main/public/app.js"
click node_web_api "https://github.com/geoffreymainadigital/gmdparser/tree/main/web/api"
click node_auth_guard "https://github.com/geoffreymainadigital/gmdparser/blob/main/web/api/auth-guard.js"

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_sms_receive,node_parser,node_review,node_scan toneBlue
class node_transactions,node_transaction_model,node_app_shell,node_dashboard,node_finance_screens,node_taxonomy,node_network,node_api_service,node_preferences,node_pin,node_theme,node_reminders toneAmber
class node_web_portal,node_web_api,node_auth_guard toneMint
class node_apps_script,node_sheets toneRose
class node_sms,node_android_os toneIndigo
```

## Components

### Capture and review

- [SMS receiver](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/receiver/SmsReceiver.kt): `android/app/src/main/java/com/gmdparser/receiver/SmsReceiver.kt`
- [M-PESA parser](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/parser/MpesaParser.kt): `android/app/src/main/java/com/gmdparser/parser/MpesaParser.kt`
- [Review and confirm](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt): `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`
- [SMS scan dialog](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/components/SmsScanDialog.kt): `android/app/src/main/java/com/gmdparser/ui/components/SmsScanDialog.kt`

### Android finance app

- [Transaction repository](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt): `android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt`
- [Transaction model](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/model/Transaction.kt): `android/app/src/main/java/com/gmdparser/data/model/Transaction.kt`
- [App navigation](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/MainActivity.kt): `android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`
- [Dashboard](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/DashboardScreen.kt): `android/app/src/main/java/com/gmdparser/ui/screens/DashboardScreen.kt`
- [Finance screens](https://github.com/geoffreymainadigital/gmdparser/tree/main/android/app/src/main/java/com/gmdparser/ui/screens): `android/app/src/main/java/com/gmdparser/ui/screens`
- [Taxonomy repository](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/repository/TaxonomyRepository.kt): `android/app/src/main/java/com/gmdparser/data/repository/TaxonomyRepository.kt`
- [Network client](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/network/NetworkClient.kt): `android/app/src/main/java/com/gmdparser/data/network/NetworkClient.kt`
- [API service](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/data/network/ApiService.kt): `android/app/src/main/java/com/gmdparser/data/network/ApiService.kt`
- [App preferences](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/util/AppPreferences.kt): `android/app/src/main/java/com/gmdparser/util/AppPreferences.kt`
- [PIN lock](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/screens/PinLockScreen.kt): `android/app/src/main/java/com/gmdparser/ui/screens/PinLockScreen.kt`
- [Theme manager](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/ui/theme/ThemeManager.kt): `android/app/src/main/java/com/gmdparser/ui/theme/ThemeManager.kt`
- [Review reminders](https://github.com/geoffreymainadigital/gmdparser/blob/main/android/app/src/main/java/com/gmdparser/util/ReviewReminderManager.kt): `android/app/src/main/java/com/gmdparser/util/ReviewReminderManager.kt`

### Web gateway

- [Web portal](https://github.com/geoffreymainadigital/gmdparser/blob/main/public/app.js): `public/app.js`
- [Vercel API routes](https://github.com/geoffreymainadigital/gmdparser/tree/main/web/api): `web/api`
- [API auth guard](https://github.com/geoffreymainadigital/gmdparser/blob/main/web/api/auth-guard.js): `web/api/auth-guard.js`

### Financial backend

- **Apps Script backend**
- **Google Sheets ledger**

### Other components

- **M-PESA SMS**
- **Android OS**: external system

## Connections

- M-PESA SMS → SMS receiver: arrives at (evidence: `README.md`)
- SMS receiver → M-PESA parser: parses message
- SMS scan dialog → M-PESA parser: scans message (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Review and confirm → M-PESA parser: parses entered SMS (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Review and confirm → Transaction repository: stages transaction (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Review and confirm → Transaction repository: submits confirmation (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Transaction repository → Transaction model: stores transaction data (evidence: `android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt`)
- App navigation → Dashboard: routes to (evidence: `android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`)
- App navigation → Finance screens: routes to (evidence: `android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`)
- App navigation → PIN lock: gates app access (evidence: `android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`)
- App navigation → Transaction repository: initializes and fetches (evidence: `android/app/src/main/java/com/gmdparser/ui/MainActivity.kt`)
- Dashboard → Transaction repository: reads financial data (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/DashboardScreen.kt`)
- Finance screens → Transaction repository: uses transaction data (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Finance screens → Taxonomy repository: uses taxonomy (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/ReviewConfirmScreen.kt`)
- Transaction repository → API service: submits API requests (evidence: `android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt`)
- Transaction repository → Network client: uses API client (evidence: `android/app/src/main/java/com/gmdparser/data/repository/TransactionRepository.kt`)
- Taxonomy repository → Network client: fetches taxonomy (evidence: `android/app/src/main/java/com/gmdparser/data/repository/TaxonomyRepository.kt`)
- Network client → API service: provides service (evidence: `android/app/src/main/java/com/gmdparser/data/network/NetworkClient.kt`)
- API service → Vercel API routes: calls HTTPS endpoints (evidence: `android/app/src/main/java/com/gmdparser/data/network/ApiService.kt`)
- Web portal → Vercel API routes: uses API
- Vercel API routes → API auth guard: checks authorization (evidence: `web/api/taxonomy.js`)
- Vercel API routes → Apps Script backend: proxies requests (evidence: `README.md`)
- Apps Script backend → Google Sheets ledger: validates and writes (evidence: `README.md`)
- PIN lock → App preferences: uses stored settings (evidence: `android/app/src/main/java/com/gmdparser/ui/screens/PinLockScreen.kt`)
- Theme manager → App preferences: reads and saves theme (evidence: `android/app/src/main/java/com/gmdparser/ui/theme/ThemeManager.kt`)
- Review reminders → Android OS: schedules notifications