# ishaq-5012/sutra-fintech-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ishaq-5012/sutra-fintech-ai
- Repository: https://github.com/ishaq-5012/sutra-fintech-ai

## Overview

Sutra AI is a financial-management application for small and rural businesses. Users register or sign in, record transactions by form or voice, then review cash-flow forecasts, financial-health scores, risk alerts, and recommendations. The frontend manages session and transaction state and calls a FastAPI backend; backend routes delegate analysis to services that use transaction history and persist results. The excerpts establish the app’s routing, selected service calls, and database setup. Several UI and backend links are based only on indexed imports or API endpoint names, so those are marked unverified where appropriate.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/App.tsx) (App routes), [`backend/app/core/database.py`](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/core/database.py) (SQL database), [`backend/app/main.py`](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/services/risk_service.py`](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/risk_service.py) (Health and risk analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routes<br/>[App.tsx]"]
  node_auth_ui["Auth state<br/>[useAuth.tsx]"]
  node_tx_state["Transaction state"]
  node_api_client["API client<br/>[api.ts]"]
  node_tx_form["Transaction entry"]
  node_voice["Voice entry<br/>[VoiceInput.tsx]"]
  node_dashboard["Business dashboard<br/>[Dashboard.tsx]"]
  node_health_ui["Health view"]
  node_risk_ui["Risk alerts<br/>[RiskAlerts.tsx]"]
  node_recs_ui["Recommendations view"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_auth_route["Authentication routes<br/>[auth.py]"]
  node_tx_route["Transaction routes<br/>[transactions.py]"]
  node_pred_route["Prediction routes<br/>[predictions.py]"]
  node_rec_route["Recommendation routes<br/>[recommendations.py]"]
  node_auth_security["Token security<br/>[security.py]"]
end

subgraph group_analysis["Financial analysis"]
  node_prediction["Cash-flow forecasts"]
  node_risk["Health and risk analysis<br/>[risk_service.py]"]
  node_recommendation["Recommendation generation"]
  node_weather["Weather and season<br/>[weather_service.py]"]
  node_nlp["Transaction text parsing<br/>[nlp_service.py]"]
  node_mockdata["Historical data generation"]
end

subgraph group_data["Persistence and domain"]
  node_user_model["User records<br/>[user.py]"]
  node_transaction_model["Transactions<br/>[transaction.py]"]
  node_prediction_model["Analysis records<br/>[prediction.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_user(("Business user"))

node_user -->|"uses"| node_app
node_app -->|"provides"| node_auth_ui
node_app -->|"provides"| node_tx_state
node_app -->|"routes to"| node_tx_form
node_app -->|"routes to"| node_voice
node_app -.->|"routes to"| node_dashboard
node_app -->|"renders"| node_health_ui
node_app -->|"renders"| node_risk_ui
node_app -->|"renders"| node_recs_ui
node_auth_ui -->|"calls auth API"| node_api_client
node_tx_state -->|"calls transaction API"| node_api_client
node_tx_form -->|"creates transactions"| node_tx_state
node_voice -->|"creates transactions"| node_tx_state
node_voice -->|"parses voice text"| node_api_client
node_health_ui -->|"requests health"| node_api_client
node_api_client -.->|"sends API requests"| node_server
node_server -->|"registers"| node_auth_route
node_server -->|"registers"| node_tx_route
node_server -->|"registers"| node_pred_route
node_server -->|"registers"| node_rec_route
node_auth_route -->|"uses tokens"| node_auth_security
node_auth_route -->|"accesses users"| node_user_model
node_auth_route -->|"initializes sample history"| node_mockdata
node_tx_route -->|"parses transaction text"| node_nlp
node_tx_route -->|"accesses transactions"| node_transaction_model
node_pred_route -->|"requests forecasts"| node_prediction
node_pred_route -->|"requests risk analysis"| node_risk
node_pred_route -->|"accesses analysis records"| node_prediction_model
node_rec_route -->|"requests recommendations"| node_recommendation
node_prediction -->|"generates history"| node_mockdata
node_risk -->|"requests weather factors"| node_weather
node_risk -->|"uses forecasts"| node_prediction
node_recommendation -->|"uses risk analysis"| node_risk
node_recommendation -->|"uses seasonal data"| node_weather
node_prediction -->|"reads history"| node_transaction_model
node_prediction -->|"caches forecasts"| node_prediction_model
node_risk -->|"reads history"| node_transaction_model
node_risk -->|"stores health scores"| node_prediction_model
node_mockdata -->|"creates transactions"| node_transaction_model
node_mockdata -->|"creates health score"| node_prediction_model
node_database -->|"defines base"| node_user_model
node_database -->|"defines base"| node_transaction_model
node_database -->|"defines base"| node_prediction_model
node_server -->|"creates tables"| node_database
node_auth_route -.->|"uses database session"| node_database
node_tx_route -.->|"uses database session"| node_database
node_pred_route -.->|"uses database session"| node_database
node_rec_route -.->|"uses database session"| node_database

click node_app "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/hooks/useAuth.tsx"
click node_tx_state "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/hooks/useTransactions.tsx"
click node_api_client "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/services/api.ts"
click node_tx_form "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/TransactionForm.tsx"
click node_voice "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/VoiceInput.tsx"
click node_dashboard "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/Dashboard.tsx"
click node_health_ui "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/FinancialHealth.tsx"
click node_risk_ui "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/RiskAlerts.tsx"
click node_recs_ui "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/Recommendations.tsx"
click node_server "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/main.py"
click node_auth_route "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/auth.py"
click node_tx_route "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/transactions.py"
click node_pred_route "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/predictions.py"
click node_rec_route "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/recommendations.py"
click node_prediction "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/prediction_service.py"
click node_risk "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/risk_service.py"
click node_recommendation "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/recommendation_service.py"
click node_weather "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/weather_service.py"
click node_nlp "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/nlp_service.py"
click node_mockdata "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/mock_data_service.py"
click node_user_model "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/user.py"
click node_transaction_model "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/transaction.py"
click node_prediction_model "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/prediction.py"
click node_database "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/core/database.py"
click node_auth_security "https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/core/security.py"

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_app,node_auth_ui,node_tx_state,node_api_client,node_tx_form,node_voice,node_dashboard,node_health_ui,node_risk_ui,node_recs_ui,node_user toneBlue
class node_server,node_auth_route,node_tx_route,node_pred_route,node_rec_route,node_auth_security toneAmber
class node_prediction,node_risk,node_recommendation,node_weather,node_nlp,node_mockdata toneMint
class node_user_model,node_transaction_model,node_prediction_model,node_database toneRose
```

## Components

### Web application

- [App routes](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth state](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/hooks/useAuth.tsx): `frontend/src/hooks/useAuth.tsx`
- [Transaction state](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/hooks/useTransactions.tsx): `frontend/src/hooks/useTransactions.tsx`
- [API client](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Transaction entry](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/TransactionForm.tsx): `frontend/src/components/TransactionForm.tsx`
- [Voice entry](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/VoiceInput.tsx): `frontend/src/components/VoiceInput.tsx`
- [Business dashboard](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/Dashboard.tsx): `frontend/src/components/Dashboard.tsx`
- [Health view](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/FinancialHealth.tsx): `frontend/src/components/FinancialHealth.tsx`
- [Risk alerts](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/RiskAlerts.tsx): `frontend/src/components/RiskAlerts.tsx`
- [Recommendations view](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/frontend/src/components/Recommendations.tsx): `frontend/src/components/Recommendations.tsx`

### Backend API

- [FastAPI app](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Transaction routes](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/transactions.py): `backend/app/api/routes/transactions.py`
- [Prediction routes](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/predictions.py): `backend/app/api/routes/predictions.py`
- [Recommendation routes](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/api/routes/recommendations.py): `backend/app/api/routes/recommendations.py`
- [Token security](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Financial analysis

- [Cash-flow forecasts](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`
- [Health and risk analysis](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/risk_service.py): `backend/app/services/risk_service.py`
- [Recommendation generation](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Weather and season](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`
- [Transaction text parsing](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/nlp_service.py): `backend/app/services/nlp_service.py`
- [Historical data generation](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/services/mock_data_service.py): `backend/app/services/mock_data_service.py`

### Persistence and domain

- [User records](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Transactions](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/transaction.py): `backend/app/models/transaction.py`
- [Analysis records](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/models/prediction.py): `backend/app/models/prediction.py`
- [SQL database](https://github.com/ishaq-5012/sutra-fintech-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Business user**

## Connections

- Business user → App routes: uses (evidence: `frontend/src/App.tsx`)
- App routes → Auth state: provides (evidence: `frontend/src/App.tsx`)
- App routes → Transaction state: provides (evidence: `frontend/src/App.tsx`)
- App routes → Transaction entry: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Voice entry: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Business dashboard: routes to
- App routes → Health view: renders (evidence: `frontend/src/App.tsx`)
- App routes → Risk alerts: renders (evidence: `frontend/src/App.tsx`)
- App routes → Recommendations view: renders (evidence: `frontend/src/App.tsx`)
- Auth state → API client: calls auth API (evidence: `frontend/src/hooks/useAuth.tsx`)
- Transaction state → API client: calls transaction API (evidence: `frontend/src/hooks/useTransactions.tsx`)
- Transaction entry → Transaction state: creates transactions (evidence: `frontend/src/components/TransactionForm.tsx`)
- Voice entry → Transaction state: creates transactions (evidence: `frontend/src/components/VoiceInput.tsx`)
- Voice entry → API client: parses voice text (evidence: `frontend/src/components/VoiceInput.tsx`)
- Health view → API client: requests health (evidence: `frontend/src/components/FinancialHealth.tsx`)
- API client → FastAPI app: sends API requests
- FastAPI app → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Transaction routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Prediction routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Recommendation routes: registers (evidence: `backend/app/main.py`)
- Authentication routes → Token security: uses tokens (evidence: `backend/app/api/routes/auth.py`)
- Authentication routes → User records: accesses users (evidence: `backend/app/api/routes/auth.py`)
- Authentication routes → Historical data generation: initializes sample history (evidence: `backend/app/api/routes/auth.py`)
- Transaction routes → Transaction text parsing: parses transaction text (evidence: `backend/app/api/routes/transactions.py`)
- Transaction routes → Transactions: accesses transactions (evidence: `backend/app/api/routes/transactions.py`)
- Prediction routes → Cash-flow forecasts: requests forecasts (evidence: `backend/app/api/routes/predictions.py`)
- Prediction routes → Health and risk analysis: requests risk analysis (evidence: `backend/app/api/routes/predictions.py`)
- Prediction routes → Analysis records: accesses analysis records (evidence: `backend/app/api/routes/predictions.py`)
- Recommendation routes → Recommendation generation: requests recommendations (evidence: `backend/app/api/routes/recommendations.py`)
- Cash-flow forecasts → Historical data generation: generates history (evidence: `backend/app/services/prediction_service.py`)
- Health and risk analysis → Weather and season: requests weather factors (evidence: `backend/app/services/risk_service.py`)
- Health and risk analysis → Cash-flow forecasts: uses forecasts (evidence: `backend/app/services/risk_service.py`)
- Recommendation generation → Health and risk analysis: uses risk analysis (evidence: `backend/app/services/recommendation_service.py`)
- Recommendation generation → Weather and season: uses seasonal data (evidence: `backend/app/services/recommendation_service.py`)
- Cash-flow forecasts → Transactions: reads history (evidence: `backend/app/services/prediction_service.py`)
- Cash-flow forecasts → Analysis records: caches forecasts (evidence: `backend/app/services/prediction_service.py`)
- Health and risk analysis → Transactions: reads history (evidence: `backend/app/services/risk_service.py`)
- Health and risk analysis → Analysis records: stores health scores (evidence: `backend/app/services/risk_service.py`)
- Historical data generation → Transactions: creates transactions (evidence: `backend/app/services/mock_data_service.py`)
- Historical data generation → Analysis records: creates health score (evidence: `backend/app/services/mock_data_service.py`)
- SQL database → User records: defines base (evidence: `backend/app/models/user.py`)
- SQL database → Transactions: defines base (evidence: `backend/app/models/transaction.py`)
- SQL database → Analysis records: defines base (evidence: `backend/app/models/prediction.py`)
- FastAPI app → SQL database: creates tables (evidence: `backend/app/main.py`)
- Authentication routes → SQL database: uses database session
- Transaction routes → SQL database: uses database session
- Prediction routes → SQL database: uses database session
- Recommendation routes → SQL database: uses database session
