# jayy2kok/budgetly architecture

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

- Interactive diagram: https://gitdiagram.com/jayy2kok/budgetly
- Repository: https://github.com/jayy2kok/budgetly

## Overview

Budgetly is a personal and family budgeting product with a mobile app and a Spring-based API. Its principal flow is authenticated users managing family budgets and transactions, then viewing spending summaries; bank-message ingestion can analyze SMS text, create or queue a transaction, and let users confirm or reject it. The tree also shows category management and a shared SMS-pattern registry. The README is empty and excerpts are partial, so several service-to-storage and mobile-to-API links are not asserted; unsampled capabilities are represented by their source paths without speculative wiring.

Main entry points: [`budgetly_api/src/main/java/com/budgetly/api/service/AuthService.java`](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/AuthService.java) (Sign-in and tokens), [`budgetly_api/src/main/java/com/budgetly/api/service/MessageService.java`](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/MessageService.java) (Message review and parsing), [`budgetly_api/src/main/java/com/budgetly/api/controller/AuthController.java`](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/AuthController.java) (Auth endpoints), [`app/android/app/src/main/kotlin/com/budgetly/app/MainActivity.kt`](https://github.com/jayy2kok/budgetly/blob/main/app/android/app/src/main/kotlin/com/budgetly/app/MainActivity.kt) (Android app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile clients"]
  node_android["Android app<br/>[MainActivity.kt]"]
  node_ios["iOS app<br/>[AppDelegate.swift]"]
end

subgraph group_api["API and identity"]
  node_auth_controller["Auth endpoints"]
  node_auth_service["Sign-in and tokens<br/>[AuthService.java]"]
  node_google_verify["Google token check"]
  node_jwt["JWT handling"]
end

subgraph group_budget["Budgeting"]
  node_family_controller["Family endpoints"]
  node_family_service["Family membership"]
  node_transaction_controller["Transaction endpoints"]
  node_transaction_service["Transaction handling"]
  node_category_controller["Category endpoints"]
  node_category_service["Category management"]
  node_dashboard_controller["Dashboard endpoints"]
  node_dashboard_service["Budget summaries"]
end

subgraph group_ingest["Message processing"]
  node_message_controller["Message endpoints"]
  node_message_service["Message review and parsing"]
  node_llm["LLM analysis"]
  node_pattern_controller["Pattern endpoints"]
  node_pattern_service["Pattern registry"]
end

subgraph group_storage["Persistence"]
  node_mongo[("MongoDB")]
  node_repositories["Mongo repositories"]
  node_documents["Stored domain records"]
end

node_user(("Budget user"))
node_gemini["Gemini API"]

node_user -->|"uses"| node_android
node_user -->|"uses"| node_ios
node_android -.->|"API requests"| node_auth_controller
node_ios -.->|"API requests"| node_auth_controller
node_auth_controller -->|"delegates"| node_auth_service
node_auth_service -->|"verifies token"| node_google_verify
node_auth_service -->|"issues tokens"| node_jwt
node_family_controller -->|"delegates"| node_family_service
node_transaction_controller -->|"delegates"| node_transaction_service
node_message_controller -->|"delegates"| node_message_service
node_message_service -->|"analyzes text"| node_llm
node_llm -->|"sends prompt"| node_gemini
node_message_service -->|"creates transaction"| node_transaction_service
node_pattern_controller -->|"delegates"| node_pattern_service
node_repositories -->|"reads and writes"| node_mongo

click node_android "https://github.com/jayy2kok/budgetly/blob/main/app/android/app/src/main/kotlin/com/budgetly/app/MainActivity.kt"
click node_ios "https://github.com/jayy2kok/budgetly/blob/main/app/ios/Runner/AppDelegate.swift"
click node_auth_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/AuthController.java"
click node_auth_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/AuthService.java"
click node_google_verify "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/security/GoogleTokenVerifier.java"
click node_jwt "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/security/JwtTokenProvider.java"
click node_family_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/FamilyGroupController.java"
click node_family_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/FamilyGroupService.java"
click node_transaction_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/TransactionController.java"
click node_transaction_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/TransactionService.java"
click node_category_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/CategoryController.java"
click node_category_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/CategoryService.java"
click node_dashboard_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/DashboardController.java"
click node_dashboard_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/DashboardService.java"
click node_message_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/MessageController.java"
click node_message_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/MessageService.java"
click node_llm "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/llm/GeminiLlmProvider.java"
click node_pattern_controller "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/PatternRegistryController.java"
click node_pattern_service "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/PatternRegistryService.java"
click node_repositories "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/repository/TransactionRepository.java"
click node_documents "https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/document/TransactionDocument.java"

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_android,node_ios,node_user toneBlue
class node_auth_controller,node_auth_service,node_google_verify,node_jwt toneAmber
class node_family_controller,node_family_service,node_transaction_controller,node_transaction_service,node_category_controller,node_category_service,node_dashboard_controller,node_dashboard_service,node_gemini toneMint
class node_message_controller,node_message_service,node_llm,node_pattern_controller,node_pattern_service toneRose
class node_mongo,node_repositories,node_documents toneIndigo
```

## Components

### Mobile clients

- [Android app](https://github.com/jayy2kok/budgetly/blob/main/app/android/app/src/main/kotlin/com/budgetly/app/MainActivity.kt): `app/android/app/src/main/kotlin/com/budgetly/app/MainActivity.kt`
- [iOS app](https://github.com/jayy2kok/budgetly/blob/main/app/ios/Runner/AppDelegate.swift): `app/ios/Runner/AppDelegate.swift`

### API and identity

- [Auth endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/AuthController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/AuthController.java`
- [Sign-in and tokens](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/AuthService.java): `budgetly_api/src/main/java/com/budgetly/api/service/AuthService.java`
- [Google token check](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/security/GoogleTokenVerifier.java): `budgetly_api/src/main/java/com/budgetly/api/security/GoogleTokenVerifier.java`
- [JWT handling](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/security/JwtTokenProvider.java): `budgetly_api/src/main/java/com/budgetly/api/security/JwtTokenProvider.java`

### Budgeting

- [Family endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/FamilyGroupController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/FamilyGroupController.java`
- [Family membership](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/FamilyGroupService.java): `budgetly_api/src/main/java/com/budgetly/api/service/FamilyGroupService.java`
- [Transaction endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/TransactionController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/TransactionController.java`
- [Transaction handling](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/TransactionService.java): `budgetly_api/src/main/java/com/budgetly/api/service/TransactionService.java`
- [Category endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/CategoryController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/CategoryController.java`
- [Category management](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/CategoryService.java): `budgetly_api/src/main/java/com/budgetly/api/service/CategoryService.java`
- [Dashboard endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/DashboardController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/DashboardController.java`
- [Budget summaries](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/DashboardService.java): `budgetly_api/src/main/java/com/budgetly/api/service/DashboardService.java`

### Message processing

- [Message endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/MessageController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/MessageController.java`
- [Message review and parsing](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/MessageService.java): `budgetly_api/src/main/java/com/budgetly/api/service/MessageService.java`
- [LLM analysis](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/llm/GeminiLlmProvider.java): `budgetly_api/src/main/java/com/budgetly/api/llm/GeminiLlmProvider.java`
- [Pattern endpoints](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/controller/PatternRegistryController.java): `budgetly_api/src/main/java/com/budgetly/api/controller/PatternRegistryController.java`
- [Pattern registry](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/service/PatternRegistryService.java): `budgetly_api/src/main/java/com/budgetly/api/service/PatternRegistryService.java`

### Persistence

- **MongoDB**
- [Mongo repositories](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/repository/TransactionRepository.java): `budgetly_api/src/main/java/com/budgetly/api/repository/TransactionRepository.java`
- [Stored domain records](https://github.com/jayy2kok/budgetly/blob/main/budgetly_api/src/main/java/com/budgetly/api/document/TransactionDocument.java): `budgetly_api/src/main/java/com/budgetly/api/document/TransactionDocument.java`

### Other components

- **Budget user**
- **Gemini API**

## Connections

- Budget user → Android app: uses
- Budget user → iOS app: uses
- Android app → Auth endpoints: API requests
- iOS app → Auth endpoints: API requests
- Auth endpoints → Sign-in and tokens: delegates
- Sign-in and tokens → Google token check: verifies token
- Sign-in and tokens → JWT handling: issues tokens
- Family endpoints → Family membership: delegates
- Transaction endpoints → Transaction handling: delegates
- Message endpoints → Message review and parsing: delegates
- Message review and parsing → LLM analysis: analyzes text
- LLM analysis → Gemini API: sends prompt
- Message review and parsing → Transaction handling: creates transaction
- Pattern endpoints → Pattern registry: delegates
- Mongo repositories → MongoDB: reads and writes