# h3d1/finlens architecture

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

- Interactive diagram: https://gitdiagram.com/h3d1/finlens
- Repository: https://github.com/h3d1/finlens

## Overview

FinLens is a locally runnable personal-finance dashboard, not a bank-connected product. Users sign in to obtain a JWT, then the dashboard fetches accounts, spending insights, and anomaly flags; the two analysis services retrieve account data from the aggregation API. The graph preserves the documented rule-based insight stages and PostgreSQL persistence. Several service details are documented but not sampled, so their edges rely on the README rather than implying source inspection.

Main entry points: [`aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java`](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java) (Account API), [`frontend/src/api/client.ts`](https://github.com/h3d1/finlens/blob/master/frontend/src/api/client.ts) (API client), [`fraud-service/app/main.py`](https://github.com/h3d1/finlens/blob/master/fraud-service/app/main.py) (Fraud endpoint), [`aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java`](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Dashboard UI<br/>[DashboardPage.tsx]"]
  node_auth_ui["Auth UI<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_auth_routes["Auth routes<br/>[App.tsx]"]
end

subgraph group_aggregation["Aggregation API"]
  node_auth_controller["Authentication"]
  node_jwt_service["JWT tokens<br/>[JwtService.java]"]
  node_jwt_filter["JWT filter"]
  node_account_api["Account API"]
end

subgraph group_analytics["Financial Analysis"]
  node_fraud_api["Fraud endpoint<br/>[main.py]"]
  node_velocity["Velocity rule<br/>[fraud.py]"]
  node_fraud_models["Fraud schemas<br/>[models.py]"]
  node_insights_api["Insights service"]
  node_insight_rules["Insight analysis<br/>[insights.py]"]
  node_insight_models["Insight schemas<br/>[models.py]"]
end

subgraph group_persistence["Persistence"]
  node_account_store["Account data<br/>[Account.java]"]
  node_transaction_store["Transaction data<br/>[Transaction.java]"]
  node_user_store["User data<br/>[User.java]"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_auth_routes -->|"routes to"| node_auth_ui
node_auth_routes -->|"protects route"| node_dashboard
node_auth_ui -->|"login request"| node_auth_controller
node_auth_controller -->|"issues token"| node_jwt_service
node_auth_controller -->|"reads and saves"| node_user_store
node_jwt_filter -->|"validates token"| node_jwt_service
node_api_client -->|"fetches accounts"| node_account_api
node_api_client -->|"requests insights"| node_insights_api
node_api_client -->|"requests flags"| node_fraud_api
node_account_api -->|"reads accounts"| node_account_store
node_account_api -->|"reads transactions"| node_transaction_store
node_account_store -->|"persists"| node_postgres
node_transaction_store -->|"persists"| node_postgres
node_user_store -->|"persists"| node_postgres
node_fraud_api -->|"fetches data"| node_account_api
node_fraud_api -->|"parses response"| node_fraud_models
node_fraud_api -->|"runs check"| node_velocity
node_velocity -->|"evaluates records"| node_fraud_models
node_insights_api -.->|"fetches data"| node_account_api
node_insights_api -.->|"analyzes records"| node_insight_rules
node_insight_rules -.->|"returns observations"| node_insight_models

click node_dashboard "https://github.com/h3d1/finlens/blob/master/frontend/src/pages/DashboardPage.tsx"
click node_auth_ui "https://github.com/h3d1/finlens/blob/master/frontend/src/auth/AuthContext.tsx"
click node_api_client "https://github.com/h3d1/finlens/blob/master/frontend/src/api/client.ts"
click node_auth_routes "https://github.com/h3d1/finlens/blob/master/frontend/src/App.tsx"
click node_auth_controller "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java"
click node_jwt_service "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/security/JwtService.java"
click node_jwt_filter "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/security/JwtAuthenticationFilter.java"
click node_account_api "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java"
click node_account_store "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/Account.java"
click node_transaction_store "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/Transaction.java"
click node_user_store "https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/User.java"
click node_fraud_api "https://github.com/h3d1/finlens/blob/master/fraud-service/app/main.py"
click node_velocity "https://github.com/h3d1/finlens/blob/master/fraud-service/app/fraud.py"
click node_fraud_models "https://github.com/h3d1/finlens/blob/master/fraud-service/app/models.py"
click node_insights_api "https://github.com/h3d1/finlens/tree/master/insights-service/app"
click node_insight_rules "https://github.com/h3d1/finlens/blob/master/insights-service/app/insights.py"
click node_insight_models "https://github.com/h3d1/finlens/blob/master/insights-service/app/models.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_dashboard,node_auth_ui,node_api_client,node_auth_routes,node_user toneBlue
class node_auth_controller,node_jwt_service,node_jwt_filter,node_account_api toneAmber
class node_fraud_api,node_velocity,node_fraud_models,node_insights_api,node_insight_rules,node_insight_models toneMint
class node_account_store,node_transaction_store,node_user_store,node_postgres toneRose
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/h3d1/finlens/blob/master/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Auth UI](https://github.com/h3d1/finlens/blob/master/frontend/src/auth/AuthContext.tsx): `frontend/src/auth/AuthContext.tsx`
- [API client](https://github.com/h3d1/finlens/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Auth routes](https://github.com/h3d1/finlens/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### Aggregation API

- [Authentication](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java): `aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java`
- [JWT tokens](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/security/JwtService.java): `aggregation-service/src/main/java/com/finlens/aggregation/security/JwtService.java`
- [JWT filter](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/security/JwtAuthenticationFilter.java): `aggregation-service/src/main/java/com/finlens/aggregation/security/JwtAuthenticationFilter.java`
- [Account API](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java): `aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java`

### Financial Analysis

- [Fraud endpoint](https://github.com/h3d1/finlens/blob/master/fraud-service/app/main.py): `fraud-service/app/main.py`
- [Velocity rule](https://github.com/h3d1/finlens/blob/master/fraud-service/app/fraud.py): `fraud-service/app/fraud.py`
- [Fraud schemas](https://github.com/h3d1/finlens/blob/master/fraud-service/app/models.py): `fraud-service/app/models.py`
- [Insights service](https://github.com/h3d1/finlens/tree/master/insights-service/app): `insights-service/app`
- [Insight analysis](https://github.com/h3d1/finlens/blob/master/insights-service/app/insights.py): `insights-service/app/insights.py`
- [Insight schemas](https://github.com/h3d1/finlens/blob/master/insights-service/app/models.py): `insights-service/app/models.py`

### Persistence

- [Account data](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/Account.java): `aggregation-service/src/main/java/com/finlens/aggregation/model/Account.java`
- [Transaction data](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/Transaction.java): `aggregation-service/src/main/java/com/finlens/aggregation/model/Transaction.java`
- [User data](https://github.com/h3d1/finlens/blob/master/aggregation-service/src/main/java/com/finlens/aggregation/model/User.java): `aggregation-service/src/main/java/com/finlens/aggregation/model/User.java`
- **PostgreSQL**

### Other components

- **User**

## Connections

- User → Dashboard UI: uses (evidence: `README.md`)
- Dashboard UI → API client: requests data (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Auth routes → Auth UI: routes to (evidence: `frontend/src/App.tsx`)
- Auth routes → Dashboard UI: protects route (evidence: `frontend/src/App.tsx`)
- Auth UI → Authentication: login request (evidence: `README.md`)
- Authentication → JWT tokens: issues token (evidence: `aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java`)
- Authentication → User data: reads and saves (evidence: `aggregation-service/src/main/java/com/finlens/aggregation/api/AuthController.java`)
- JWT filter → JWT tokens: validates token (evidence: `aggregation-service/src/main/java/com/finlens/aggregation/security/JwtAuthenticationFilter.java`)
- API client → Account API: fetches accounts (evidence: `README.md`)
- API client → Insights service: requests insights (evidence: `frontend/src/api/client.ts`)
- API client → Fraud endpoint: requests flags (evidence: `frontend/src/api/client.ts`)
- Account API → Account data: reads accounts (evidence: `aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java`)
- Account API → Transaction data: reads transactions (evidence: `aggregation-service/src/main/java/com/finlens/aggregation/api/AccountController.java`)
- Account data → PostgreSQL: persists (evidence: `README.md`)
- Transaction data → PostgreSQL: persists (evidence: `README.md`)
- User data → PostgreSQL: persists (evidence: `README.md`)
- Fraud endpoint → Account API: fetches data (evidence: `fraud-service/app/main.py`)
- Fraud endpoint → Fraud schemas: parses response (evidence: `fraud-service/app/main.py`)
- Fraud endpoint → Velocity rule: runs check (evidence: `fraud-service/app/main.py`)
- Velocity rule → Fraud schemas: evaluates records (evidence: `fraud-service/app/fraud.py`)
- Insights service → Account API: fetches data (evidence: `README.md`)
- Insights service → Insight analysis: analyzes records (evidence: `README.md`)
- Insight analysis → Insight schemas: returns observations (evidence: `README.md`)
