# btaquee/cardsense architecture

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

- Interactive diagram: https://gitdiagram.com/btaquee/cardsense
- Repository: https://github.com/btaquee/cardsense

## Overview

CardSense is a personal-finance web app for tracking spending against monthly budgets and maximizing credit-card rewards. Users authenticate, add or import transactions, manage their card wallet and budgets, then review alerts, reward breakdowns, and recommendations. The React app calls a Django REST API; transaction and card data support reward calculations, while budget services aggregate monthly spend and create threshold events. The README also describes analytics and profile/settings capabilities. Some backend views and frontend pages were not sampled, so those subsystem links are included only where routing or explicit documentation supports them.

Main entry points: [`web/src/App.tsx`](https://github.com/btaquee/cardsense/blob/main/web/src/App.tsx) (Web routes), [`transactions/views.py`](https://github.com/btaquee/cardsense/blob/main/transactions/views.py) (Transaction endpoints), [`budgets/services.py`](https://github.com/btaquee/cardsense/blob/main/budgets/services.py) (Spend and thresholds), [`web/src/services/api.ts`](https://github.com/btaquee/cardsense/blob/main/web/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Web routes<br/>[App.tsx]"]
  node_auth_ui["Sign-in UI"]
  node_profile_ui["Profile settings"]
  node_transaction_ui["Transaction tools"]
  node_budget_ui["Budget views"]
  node_card_ui["Card management<br/>[CardManagement.tsx]"]
  node_rewards_ui["Rewards breakdown"]
  node_dashboard_ui["Dashboard<br/>[Dashboard.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_transaction_service["Transaction service"]
  node_budget_service["Budget service<br/>[budget.service.ts]"]
  node_card_service["Card service<br/>[card.service.ts]"]
end

subgraph group_ingest["Accounts and spending"]
  node_django_api["Django API routes<br/>[urls.py]"]
  node_accounts["Authentication<br/>[views.py]"]
  node_transactions["Transaction endpoints<br/>[views.py]"]
  node_transaction_store[("Transaction records<br/>[models.py]")]
end

subgraph group_budget["Budget tracking"]
  node_budget_endpoints["Budget endpoints<br/>[views.py]"]
  node_budget_service_impl["Spend and thresholds<br/>[services.py]"]
  node_budget_records[("Budgets and alerts<br/>[models.py]")]
  node_budget_signals["Budget signals<br/>[signals.py]"]
end

subgraph group_cards["Cards and rewards"]
  node_card_endpoints["Card endpoints<br/>[views.py]"]
  node_card_records[("Card catalog and wallet<br/>[models.py]")]
  node_optimizer["Card optimizer<br/>[services.py]"]
  node_reward_calc["Reward calculations<br/>[rewards.py]"]
end

subgraph group_analytics["Insights"]
  node_analytics_views["Spending analytics<br/>[analytics_views.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes"| node_auth_ui
node_app -->|"routes"| node_transaction_ui
node_app -->|"routes"| node_budget_ui
node_app -->|"routes"| node_card_ui
node_app -->|"routes"| node_rewards_ui
node_app -->|"routes"| node_dashboard_ui
node_app -->|"routes"| node_profile_ui
node_auth_ui -.->|"uses"| node_auth_service
node_transaction_ui -->|"uses"| node_transaction_service
node_budget_ui -->|"uses"| node_budget_service
node_card_ui -->|"uses"| node_card_service
node_rewards_ui -->|"requests cards"| node_card_service
node_rewards_ui -->|"requests transactions"| node_transaction_service
node_auth_service -->|"sends requests"| node_api_client
node_transaction_service -->|"sends requests"| node_api_client
node_budget_service -->|"sends requests"| node_api_client
node_card_service -->|"sends requests"| node_api_client
node_api_client -->|"HTTP requests"| node_django_api
node_django_api -->|"routes auth"| node_accounts
node_django_api -->|"routes analytics"| node_analytics_views
node_transaction_service -->|"HTTP requests"| node_transactions
node_budget_service -->|"HTTP requests"| node_budget_endpoints
node_card_service -->|"HTTP requests"| node_card_endpoints
node_transactions -->|"reads and writes"| node_transaction_store
node_transactions -->|"requests recommendation"| node_optimizer
node_transactions -->|"uses budget logic"| node_budget_service_impl
node_transactions -->|"uses reward logic"| node_reward_calc
node_budget_endpoints -->|"computes spend"| node_budget_service_impl
node_budget_service_impl -->|"aggregates spend"| node_transaction_store
node_budget_service_impl -->|"creates alerts"| node_budget_records
node_budget_signals -->|"evaluates thresholds"| node_budget_service_impl
node_budget_signals -->|"observes transactions"| node_transaction_store
node_budget_endpoints -.->|"manages"| node_budget_records
node_card_endpoints -->|"reads and writes"| node_card_records
node_card_endpoints -->|"requests rewards"| node_reward_calc
node_optimizer -->|"ranks wallet rules"| node_card_records
node_reward_calc -->|"reads reward rules"| node_card_records
node_analytics_views -->|"reads transactions"| node_transaction_store
node_analytics_views -->|"reads budgets"| node_budget_records
node_analytics_views -->|"uses reward logic"| node_reward_calc

click node_app "https://github.com/btaquee/cardsense/blob/main/web/src/App.tsx"
click node_auth_ui "https://github.com/btaquee/cardsense/tree/main/web/src/components/auth"
click node_profile_ui "https://github.com/btaquee/cardsense/tree/main/web/src/components/Profile"
click node_transaction_ui "https://github.com/btaquee/cardsense/tree/main/web/src/components/Transactions"
click node_budget_ui "https://github.com/btaquee/cardsense/tree/main/web/src/components/Budgets"
click node_card_ui "https://github.com/btaquee/cardsense/blob/main/web/src/components/Cards/CardManagement.tsx"
click node_rewards_ui "https://github.com/btaquee/cardsense/blob/main/web/src/components/Rewards/RewardsBreakdown.tsx"
click node_dashboard_ui "https://github.com/btaquee/cardsense/blob/main/web/src/components/Dashboard/Dashboard.tsx"
click node_api_client "https://github.com/btaquee/cardsense/blob/main/web/src/services/api.ts"
click node_auth_service "https://github.com/btaquee/cardsense/blob/main/web/src/services/auth.service.ts"
click node_transaction_service "https://github.com/btaquee/cardsense/blob/main/web/src/services/transaction.service.ts"
click node_budget_service "https://github.com/btaquee/cardsense/blob/main/web/src/services/budget.service.ts"
click node_card_service "https://github.com/btaquee/cardsense/blob/main/web/src/services/card.service.ts"
click node_django_api "https://github.com/btaquee/cardsense/blob/main/api/urls.py"
click node_accounts "https://github.com/btaquee/cardsense/blob/main/accounts/views.py"
click node_transactions "https://github.com/btaquee/cardsense/blob/main/transactions/views.py"
click node_transaction_store "https://github.com/btaquee/cardsense/blob/main/transactions/models.py"
click node_budget_endpoints "https://github.com/btaquee/cardsense/blob/main/budgets/views.py"
click node_budget_service_impl "https://github.com/btaquee/cardsense/blob/main/budgets/services.py"
click node_budget_records "https://github.com/btaquee/cardsense/blob/main/budgets/models.py"
click node_budget_signals "https://github.com/btaquee/cardsense/blob/main/budgets/signals.py"
click node_card_endpoints "https://github.com/btaquee/cardsense/blob/main/cards/views.py"
click node_card_records "https://github.com/btaquee/cardsense/blob/main/cards/models.py"
click node_optimizer "https://github.com/btaquee/cardsense/blob/main/optimizer/services.py"
click node_reward_calc "https://github.com/btaquee/cardsense/blob/main/transactions/rewards.py"
click node_analytics_views "https://github.com/btaquee/cardsense/blob/main/analytics_views.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_profile_ui,node_transaction_ui,node_budget_ui,node_card_ui,node_rewards_ui,node_dashboard_ui,node_api_client,node_auth_service,node_transaction_service,node_budget_service,node_card_service,node_user toneBlue
class node_django_api,node_accounts,node_transactions,node_transaction_store toneAmber
class node_budget_endpoints,node_budget_service_impl,node_budget_records,node_budget_signals toneMint
class node_card_endpoints,node_card_records,node_optimizer,node_reward_calc toneRose
class node_analytics_views toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/btaquee/cardsense/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Sign-in UI](https://github.com/btaquee/cardsense/tree/main/web/src/components/auth): `web/src/components/auth`
- [Profile settings](https://github.com/btaquee/cardsense/tree/main/web/src/components/Profile): `web/src/components/Profile`
- [Transaction tools](https://github.com/btaquee/cardsense/tree/main/web/src/components/Transactions): `web/src/components/Transactions`
- [Budget views](https://github.com/btaquee/cardsense/tree/main/web/src/components/Budgets): `web/src/components/Budgets`
- [Card management](https://github.com/btaquee/cardsense/blob/main/web/src/components/Cards/CardManagement.tsx): `web/src/components/Cards/CardManagement.tsx`
- [Rewards breakdown](https://github.com/btaquee/cardsense/blob/main/web/src/components/Rewards/RewardsBreakdown.tsx): `web/src/components/Rewards/RewardsBreakdown.tsx`
- [Dashboard](https://github.com/btaquee/cardsense/blob/main/web/src/components/Dashboard/Dashboard.tsx): `web/src/components/Dashboard/Dashboard.tsx`
- [API client](https://github.com/btaquee/cardsense/blob/main/web/src/services/api.ts): `web/src/services/api.ts`
- [Auth service](https://github.com/btaquee/cardsense/blob/main/web/src/services/auth.service.ts): `web/src/services/auth.service.ts`
- [Transaction service](https://github.com/btaquee/cardsense/blob/main/web/src/services/transaction.service.ts): `web/src/services/transaction.service.ts`
- [Budget service](https://github.com/btaquee/cardsense/blob/main/web/src/services/budget.service.ts): `web/src/services/budget.service.ts`
- [Card service](https://github.com/btaquee/cardsense/blob/main/web/src/services/card.service.ts): `web/src/services/card.service.ts`

### Accounts and spending

- [Django API routes](https://github.com/btaquee/cardsense/blob/main/api/urls.py): `api/urls.py`
- [Authentication](https://github.com/btaquee/cardsense/blob/main/accounts/views.py): `accounts/views.py`
- [Transaction endpoints](https://github.com/btaquee/cardsense/blob/main/transactions/views.py): `transactions/views.py`
- [Transaction records](https://github.com/btaquee/cardsense/blob/main/transactions/models.py): `transactions/models.py`

### Budget tracking

- [Budget endpoints](https://github.com/btaquee/cardsense/blob/main/budgets/views.py): `budgets/views.py`
- [Spend and thresholds](https://github.com/btaquee/cardsense/blob/main/budgets/services.py): `budgets/services.py`
- [Budgets and alerts](https://github.com/btaquee/cardsense/blob/main/budgets/models.py): `budgets/models.py`
- [Budget signals](https://github.com/btaquee/cardsense/blob/main/budgets/signals.py): `budgets/signals.py`

### Cards and rewards

- [Card endpoints](https://github.com/btaquee/cardsense/blob/main/cards/views.py): `cards/views.py`
- [Card catalog and wallet](https://github.com/btaquee/cardsense/blob/main/cards/models.py): `cards/models.py`
- [Card optimizer](https://github.com/btaquee/cardsense/blob/main/optimizer/services.py): `optimizer/services.py`
- [Reward calculations](https://github.com/btaquee/cardsense/blob/main/transactions/rewards.py): `transactions/rewards.py`

### Insights

- [Spending analytics](https://github.com/btaquee/cardsense/blob/main/analytics_views.py): `analytics_views.py`

### Other components

- **User**

## Connections

- User → Web routes: uses (evidence: `web/src/App.tsx`)
- Web routes → Sign-in UI: routes (evidence: `web/src/App.tsx`)
- Web routes → Transaction tools: routes (evidence: `web/src/App.tsx`)
- Web routes → Budget views: routes (evidence: `web/src/App.tsx`)
- Web routes → Card management: routes (evidence: `web/src/App.tsx`)
- Web routes → Rewards breakdown: routes (evidence: `web/src/App.tsx`)
- Web routes → Dashboard: routes (evidence: `web/src/App.tsx`)
- Web routes → Profile settings: routes (evidence: `web/src/App.tsx`)
- Sign-in UI → Auth service: uses
- Transaction tools → Transaction service: uses (evidence: `web/src/services/transaction.service.ts`)
- Budget views → Budget service: uses (evidence: `web/src/components/Budgets/BudgetList.tsx`)
- Card management → Card service: uses (evidence: `web/src/components/Cards/CardManagement.tsx`)
- Rewards breakdown → Card service: requests cards (evidence: `web/src/components/Rewards/RewardsBreakdown.tsx`)
- Rewards breakdown → Transaction service: requests transactions (evidence: `web/src/components/Rewards/RewardsBreakdown.tsx`)
- Auth service → API client: sends requests (evidence: `web/src/services/auth.service.ts`)
- Transaction service → API client: sends requests (evidence: `web/src/services/transaction.service.ts`)
- Budget service → API client: sends requests (evidence: `web/src/services/budget.service.ts`)
- Card service → API client: sends requests (evidence: `web/src/services/card.service.ts`)
- API client → Django API routes: HTTP requests (evidence: `web/src/services/api.ts`)
- Django API routes → Authentication: routes auth (evidence: `api/urls.py`)
- Django API routes → Spending analytics: routes analytics (evidence: `api/urls.py`)
- Transaction service → Transaction endpoints: HTTP requests (evidence: `web/src/services/transaction.service.ts`)
- Budget service → Budget endpoints: HTTP requests (evidence: `web/src/services/budget.service.ts`)
- Card service → Card endpoints: HTTP requests (evidence: `web/src/services/card.service.ts`)
- Transaction endpoints → Transaction records: reads and writes (evidence: `transactions/views.py`)
- Transaction endpoints → Card optimizer: requests recommendation (evidence: `transactions/views.py`)
- Transaction endpoints → Spend and thresholds: uses budget logic (evidence: `transactions/views.py`)
- Transaction endpoints → Reward calculations: uses reward logic (evidence: `transactions/views.py`)
- Budget endpoints → Spend and thresholds: computes spend (evidence: `budgets/services.py`)
- Spend and thresholds → Transaction records: aggregates spend (evidence: `budgets/services.py`)
- Spend and thresholds → Budgets and alerts: creates alerts (evidence: `budgets/services.py`)
- Budget signals → Spend and thresholds: evaluates thresholds (evidence: `budgets/signals.py`)
- Budget signals → Transaction records: observes transactions (evidence: `budgets/signals.py`)
- Budget endpoints → Budgets and alerts: manages
- Card endpoints → Card catalog and wallet: reads and writes (evidence: `cards/views.py`)
- Card endpoints → Reward calculations: requests rewards (evidence: `cards/views.py`)
- Card optimizer → Card catalog and wallet: ranks wallet rules (evidence: `optimizer/services.py`)
- Reward calculations → Card catalog and wallet: reads reward rules (evidence: `transactions/rewards.py`)
- Spending analytics → Transaction records: reads transactions (evidence: `analytics_views.py`)
- Spending analytics → Budgets and alerts: reads budgets (evidence: `analytics_views.py`)
- Spending analytics → Reward calculations: uses reward logic (evidence: `analytics_views.py`)
