# anmay-27/spendwise-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anmay-27/spendwise-ai
- Repository: https://github.com/anmay-27/spendwise-ai

## Overview

SpendWise AI is a personal-finance application: users authenticate, record income and expenses, manage budgets and goals, and review insights, reports, and payment activity. The browser UI calls the Spring finance core through a gateway; the core persists financial state, optionally requests transaction categorization, and publishes committed events for notifications. Payments are simulations or Razorpay test-mode checkout, not bank transfers. Edges are limited to README statements and shown source references/calls; unsampled domain implementations are represented by their exact enclosing paths.

Main entry points: [`frontend/src/App.jsx`](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/App.jsx) (React application), [`backend/src/main/java/com/anmay/spendwise/finance/FinanceController.java`](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/FinanceController.java) (Finance API), [`backend/src/main/java/com/anmay/spendwise/finance/TransactionCrudService.java`](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/TransactionCrudService.java) (Transaction management), [`backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java`](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java) (Checkout service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React application<br/>[App.jsx]"]
  node_authui["Sign-in UI<br/>[AuthPage.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_ledgerui["Ledger and finance screens<br/>[LedgerPage.jsx]"]
  node_budgetui["Budgets and goals<br/>[BudgetsPage.jsx]"]
  node_insightsui["Insights and reports<br/>[ReportsPage.jsx]"]
  node_payui["Payment screens"]
end

subgraph group_core["Finance core"]
  node_gateway["API gateway"]
  node_financeapi["Finance API"]
  node_transactions["Transaction management"]
  node_budgets["Budget management<br/>[BudgetService.java]"]
  node_goals["Savings goals<br/>[GoalService.java]"]
  node_analytics["Insights and reporting"]
  node_assistant["Spending assistant"]
  node_checkout["Checkout service"]
  node_razorpay["Razorpay test client"]
  node_financedb[("Finance database")]
end

subgraph group_identity["Identity and access"]
  node_auth["Auth service<br/>[AuthService.java]"]
  node_sessions["Session service"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_account["Account provisioning"]
end

subgraph group_intelligence["AI classification"]
  node_mlclient["ML service client"]
  node_mlapi["Classifier API<br/>[main.py]"]
  node_model["Category model<br/>[model.py]"]
end

subgraph group_async["Events and notifications"]
  node_outbox[("Transactional outbox<br/>[EventOutbox.java]")]
  node_publisher["Outbox publisher"]
  node_kafka["Kafka events"]
  node_consumer["Finance event consumer"]
  node_notifications["Notification service"]
  node_notificationdb[("Notification database")]
end

node_user(("Finance user"))

node_user -->|"uses"| node_web
node_web -->|"renders"| node_authui
node_authui -->|"submits credentials"| node_api
node_web -->|"checks session"| node_api
node_web -->|"renders"| node_ledgerui
node_web -->|"renders"| node_budgetui
node_web -->|"renders"| node_insightsui
node_web -->|"renders"| node_payui
node_api -.->|"calls REST"| node_gateway
node_gateway -.->|"routes requests"| node_financeapi
node_auth -->|"creates tokens"| node_sessions
node_sessions -->|"creates access token"| node_jwt
node_sessions -->|"stores sessions"| node_financedb
node_auth -->|"provisions account"| node_account
node_financeapi -.->|"handles writes"| node_transactions
node_transactions -.->|"persists transactions"| node_financedb
node_financeapi -.->|"serves budgets"| node_budgets
node_financeapi -.->|"serves goals"| node_goals
node_financeapi -.->|"serves insights"| node_analytics
node_financeapi -.->|"serves chat"| node_assistant
node_checkout -->|"creates and verifies orders"| node_razorpay
node_checkout -.->|"records captured expense"| node_financedb
node_transactions -.->|"requests categorization"| node_mlclient
node_mlclient -.->|"requests predictions"| node_mlapi
node_mlapi -->|"predicts and learns"| node_model
node_transactions -.->|"records events"| node_outbox
node_checkout -->|"records events"| node_outbox
node_publisher -.->|"reads pending events"| node_outbox
node_publisher -.->|"publishes events"| node_kafka
node_kafka -.->|"delivers events"| node_consumer
node_consumer -.->|"forwards notifications"| node_notifications
node_notifications -.->|"stores notifications"| node_notificationdb

click node_web "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/AuthPage.jsx"
click node_api "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/api.js"
click node_ledgerui "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/LedgerPage.jsx"
click node_budgetui "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/BudgetsPage.jsx"
click node_insightsui "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/ReportsPage.jsx"
click node_payui "https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/RazorpayPayPage.jsx"
click node_gateway "https://github.com/anmay-27/spendwise-ai/blob/main/services/api-gateway/src/main/java/com/anmay/gateway/GatewayApplication.java"
click node_auth "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AuthService.java"
click node_sessions "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/security/SessionService.java"
click node_jwt "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/security/JwtService.java"
click node_account "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AccountProvisioningService.java"
click node_financeapi "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/FinanceController.java"
click node_transactions "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/TransactionCrudService.java"
click node_budgets "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/BudgetService.java"
click node_goals "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/GoalService.java"
click node_analytics "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/FinanceInsights.java"
click node_assistant "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AssistantService.java"
click node_checkout "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java"
click node_razorpay "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/payments/RazorpayClient.java"
click node_financedb "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/entity/ExpenseTransaction.java"
click node_mlclient "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/MlServiceClient.java"
click node_mlapi "https://github.com/anmay-27/spendwise-ai/blob/main/ml-service/app/main.py"
click node_model "https://github.com/anmay-27/spendwise-ai/blob/main/ml-service/app/model.py"
click node_outbox "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/EventOutbox.java"
click node_publisher "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/OutboxPublisher.java"
click node_consumer "https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/FinanceEventConsumer.java"
click node_notifications "https://github.com/anmay-27/spendwise-ai/blob/main/services/notification-service/src/main/java/com/anmay/notifications/NotificationConsumer.java"
click node_notificationdb "https://github.com/anmay-27/spendwise-ai/blob/main/services/notification-service/src/main/java/com/anmay/notifications/NotificationController.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_web,node_authui,node_api,node_ledgerui,node_budgetui,node_insightsui,node_payui,node_user toneBlue
class node_gateway,node_financeapi,node_transactions,node_budgets,node_goals,node_analytics,node_assistant,node_checkout,node_razorpay,node_financedb toneAmber
class node_auth,node_sessions,node_jwt,node_account toneMint
class node_mlclient,node_mlapi,node_model toneRose
class node_outbox,node_publisher,node_kafka,node_consumer,node_notifications,node_notificationdb toneIndigo
```

## Components

### Web client

- [React application](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in UI](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/AuthPage.jsx): `frontend/src/features/AuthPage.jsx`
- [API client](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Ledger and finance screens](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/LedgerPage.jsx): `frontend/src/features/LedgerPage.jsx`
- [Budgets and goals](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/BudgetsPage.jsx): `frontend/src/features/BudgetsPage.jsx`
- [Insights and reports](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/ReportsPage.jsx): `frontend/src/features/ReportsPage.jsx`
- [Payment screens](https://github.com/anmay-27/spendwise-ai/blob/main/frontend/src/features/RazorpayPayPage.jsx): `frontend/src/features/RazorpayPayPage.jsx`

### Finance core

- [API gateway](https://github.com/anmay-27/spendwise-ai/blob/main/services/api-gateway/src/main/java/com/anmay/gateway/GatewayApplication.java): `services/api-gateway/src/main/java/com/anmay/gateway/GatewayApplication.java`
- [Finance API](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/FinanceController.java): `backend/src/main/java/com/anmay/spendwise/finance/FinanceController.java`
- [Transaction management](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/TransactionCrudService.java): `backend/src/main/java/com/anmay/spendwise/finance/TransactionCrudService.java`
- [Budget management](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/BudgetService.java): `backend/src/main/java/com/anmay/spendwise/service/BudgetService.java`
- [Savings goals](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/GoalService.java): `backend/src/main/java/com/anmay/spendwise/finance/GoalService.java`
- [Insights and reporting](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/finance/FinanceInsights.java): `backend/src/main/java/com/anmay/spendwise/finance/FinanceInsights.java`
- [Spending assistant](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AssistantService.java): `backend/src/main/java/com/anmay/spendwise/service/AssistantService.java`
- [Checkout service](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java): `backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java`
- [Razorpay test client](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/payments/RazorpayClient.java): `backend/src/main/java/com/anmay/spendwise/payments/RazorpayClient.java`
- [Finance database](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/entity/ExpenseTransaction.java): `backend/src/main/java/com/anmay/spendwise/entity/ExpenseTransaction.java`

### Identity and access

- [Auth service](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AuthService.java): `backend/src/main/java/com/anmay/spendwise/service/AuthService.java`
- [Session service](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/security/SessionService.java): `backend/src/main/java/com/anmay/spendwise/security/SessionService.java`
- [JWT service](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/security/JwtService.java): `backend/src/main/java/com/anmay/spendwise/security/JwtService.java`
- [Account provisioning](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/AccountProvisioningService.java): `backend/src/main/java/com/anmay/spendwise/service/AccountProvisioningService.java`

### AI classification

- [ML service client](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/service/MlServiceClient.java): `backend/src/main/java/com/anmay/spendwise/service/MlServiceClient.java`
- [Classifier API](https://github.com/anmay-27/spendwise-ai/blob/main/ml-service/app/main.py): `ml-service/app/main.py`
- [Category model](https://github.com/anmay-27/spendwise-ai/blob/main/ml-service/app/model.py): `ml-service/app/model.py`

### Events and notifications

- [Transactional outbox](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/EventOutbox.java): `backend/src/main/java/com/anmay/spendwise/events/EventOutbox.java`
- [Outbox publisher](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/OutboxPublisher.java): `backend/src/main/java/com/anmay/spendwise/events/OutboxPublisher.java`
- **Kafka events**
- [Finance event consumer](https://github.com/anmay-27/spendwise-ai/blob/main/backend/src/main/java/com/anmay/spendwise/events/FinanceEventConsumer.java): `backend/src/main/java/com/anmay/spendwise/events/FinanceEventConsumer.java`
- [Notification service](https://github.com/anmay-27/spendwise-ai/blob/main/services/notification-service/src/main/java/com/anmay/notifications/NotificationConsumer.java): `services/notification-service/src/main/java/com/anmay/notifications/NotificationConsumer.java`
- [Notification database](https://github.com/anmay-27/spendwise-ai/blob/main/services/notification-service/src/main/java/com/anmay/notifications/NotificationController.java): `services/notification-service/src/main/java/com/anmay/notifications/NotificationController.java`

### Other components

- **Finance user**

## Connections

- Finance user → React application: uses
- React application → Sign-in UI: renders (evidence: `frontend/src/App.jsx`)
- Sign-in UI → API client: submits credentials (evidence: `frontend/src/features/AuthPage.jsx`)
- React application → API client: checks session (evidence: `frontend/src/App.jsx`)
- React application → Ledger and finance screens: renders (evidence: `frontend/src/App.jsx`)
- React application → Budgets and goals: renders (evidence: `frontend/src/App.jsx`)
- React application → Insights and reports: renders (evidence: `frontend/src/App.jsx`)
- React application → Payment screens: renders (evidence: `frontend/src/App.jsx`)
- API client → API gateway: calls REST
- API gateway → Finance API: routes requests
- Auth service → Session service: creates tokens (evidence: `backend/src/main/java/com/anmay/spendwise/service/AuthService.java`)
- Session service → JWT service: creates access token (evidence: `backend/src/main/java/com/anmay/spendwise/security/SessionService.java`)
- Session service → Finance database: stores sessions (evidence: `backend/src/main/java/com/anmay/spendwise/security/SessionService.java`)
- Auth service → Account provisioning: provisions account (evidence: `backend/src/main/java/com/anmay/spendwise/service/AuthService.java`)
- Finance API → Transaction management: handles writes
- Transaction management → Finance database: persists transactions
- Finance API → Budget management: serves budgets
- Finance API → Savings goals: serves goals
- Finance API → Insights and reporting: serves insights
- Finance API → Spending assistant: serves chat
- Checkout service → Razorpay test client: creates and verifies orders (evidence: `backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java`)
- Checkout service → Finance database: records captured expense
- Transaction management → ML service client: requests categorization
- ML service client → Classifier API: requests predictions
- Classifier API → Category model: predicts and learns (evidence: `ml-service/app/main.py`)
- Transaction management → Transactional outbox: records events
- Checkout service → Transactional outbox: records events (evidence: `backend/src/main/java/com/anmay/spendwise/payments/CheckoutService.java`)
- Outbox publisher → Transactional outbox: reads pending events
- Outbox publisher → Kafka events: publishes events
- Kafka events → Finance event consumer: delivers events
- Finance event consumer → Notification service: forwards notifications
- Notification service → Notification database: stores notifications