# sofia-m12/hsa-account-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/sofia-m12/hsa-account-simulation
- Repository: https://github.com/sofia-m12/hsa-account-simulation
- Video tour (about a minute): https://gitdiagram.com/sofia-m12/hsa-account-simulation/video

## Overview

HSA Account Simulation is a local web app for managing simulated HSA accounts, issuing virtual cards, recording deposits, and testing purchase outcomes. Users create an account from Home, then view its balance, issue a card, deposit funds, and submit purchases; the transactions view also supports single and concurrent simulations. The React pages call a FastAPI API, which applies account, card, deposit, and purchase logic against PostgreSQL. The graph includes the documented seed-data capability, but its runtime details and several implementation links are not shown in sampled source, so those links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/App.tsx) (Route shell), [`frontend/src/pages/AccountPage.tsx`](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/AccountPage.tsx) (Account details), [`frontend/src/pages/HomePage.tsx`](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/HomePage.tsx) (Home dashboard), [`frontend/src/pages/TransactionsPage.tsx`](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/TransactionsPage.tsx) (Transactions view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["Route shell<br/>[App.tsx]"]
  node_home["Home dashboard<br/>[HomePage.tsx]"]
  node_accountpage["Account details<br/>[AccountPage.tsx]"]
  node_transactionspage["Transactions view"]
  node_accountmodal["Account form"]
  node_depositmodal["Deposit form<br/>[DepositModal.tsx]"]
  node_purchasemodal["Purchase form<br/>[PurchaseModal.tsx]"]
  node_simulator["Purchase simulator"]
  node_tables["Activity tables"]
  node_formatters["Display formatting<br/>[formatters.ts]"]
  node_api["API client<br/>[api.ts]"]
  node_notfound["Not found view<br/>[NotFoundPage.tsx]"]
end

subgraph group_backend["API and domain"]
  node_api_routes["Account operations<br/>[accounts.py]"]
  node_schemas["Request and response models<br/>[schemas.py]"]
  node_models["Relational tables<br/>[models.py]"]
  node_db_dependency["Session dependency<br/>[dependencies.py]"]
  node_db_engine["Database engine<br/>[database.py]"]
  node_config["Database configuration<br/>[config.py]"]
end

subgraph group_storage["Persistent data"]
  node_postgres[("PostgreSQL")]
  node_seed["Sample data seed<br/>[seed.sql]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes"| node_home
node_app -->|"routes"| node_accountpage
node_app -->|"routes"| node_transactionspage
node_app -->|"routes"| node_notfound
node_home -->|"renders"| node_accountmodal
node_home -->|"requests accounts and activity"| node_api
node_home -->|"renders"| node_tables
node_accountpage -->|"requests account actions"| node_api
node_accountpage -->|"renders"| node_depositmodal
node_accountpage -->|"renders"| node_purchasemodal
node_accountpage -->|"renders"| node_tables
node_transactionspage -->|"requests activity and purchases"| node_api
node_transactionspage -->|"renders"| node_simulator
node_transactionspage -->|"renders"| node_tables
node_simulator -->|"renders"| node_purchasemodal
node_tables -->|"formats values"| node_formatters
node_api -->|"HTTP requests"| node_api_routes
node_api_routes -->|"validates and serializes"| node_schemas
node_api_routes -->|"gets session"| node_db_dependency
node_api_routes -->|"queries and mutates"| node_models
node_db_dependency -->|"uses engine"| node_db_engine
node_db_engine -->|"reads settings"| node_config
node_db_engine -.->|"connects"| node_postgres
node_models -.->|"maps tables"| node_postgres
node_seed -->|"initializes sample data"| node_postgres

click node_app "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/HomePage.tsx"
click node_accountpage "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/AccountPage.tsx"
click node_transactionspage "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/TransactionsPage.tsx"
click node_accountmodal "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/CreateAccountModal.tsx"
click node_depositmodal "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/DepositModal.tsx"
click node_purchasemodal "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/PurchaseModal.tsx"
click node_simulator "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/SimulateTransactionModal.tsx"
click node_tables "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/TransactionsTable.tsx"
click node_formatters "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/utils/formatters.ts"
click node_api "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/data/api.ts"
click node_notfound "https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/NotFoundPage.tsx"
click node_api_routes "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/routes/accounts.py"
click node_schemas "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/schemas.py"
click node_models "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/models.py"
click node_db_dependency "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/dependencies.py"
click node_db_engine "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/database.py"
click node_config "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/config.py"
click node_seed "https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/seed.sql"

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_home,node_accountpage,node_transactionspage,node_accountmodal,node_depositmodal,node_purchasemodal,node_simulator,node_tables,node_formatters,node_api,node_notfound,node_user toneBlue
class node_api_routes,node_schemas,node_models,node_db_dependency,node_db_engine,node_config toneAmber
class node_postgres,node_seed toneMint
```

## Components

### Web interface

- [Route shell](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Home dashboard](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [Account details](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/AccountPage.tsx): `frontend/src/pages/AccountPage.tsx`
- [Transactions view](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/TransactionsPage.tsx): `frontend/src/pages/TransactionsPage.tsx`
- [Account form](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/CreateAccountModal.tsx): `frontend/src/components/CreateAccountModal.tsx`
- [Deposit form](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/DepositModal.tsx): `frontend/src/components/DepositModal.tsx`
- [Purchase form](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/PurchaseModal.tsx): `frontend/src/components/PurchaseModal.tsx`
- [Purchase simulator](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/SimulateTransactionModal.tsx): `frontend/src/components/SimulateTransactionModal.tsx`
- [Activity tables](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/components/TransactionsTable.tsx): `frontend/src/components/TransactionsTable.tsx`
- [Display formatting](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/utils/formatters.ts): `frontend/src/utils/formatters.ts`
- [API client](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/data/api.ts): `frontend/src/data/api.ts`
- [Not found view](https://github.com/sofia-m12/hsa-account-simulation/blob/main/frontend/src/pages/NotFoundPage.tsx): `frontend/src/pages/NotFoundPage.tsx`

### API and domain

- [Account operations](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/routes/accounts.py): `backend/app/routes/accounts.py`
- [Request and response models](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Relational tables](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/models.py): `backend/app/models.py`
- [Session dependency](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [Database engine](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/database.py): `backend/app/database.py`
- [Database configuration](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/app/config.py): `backend/app/config.py`

### Persistent data

- **PostgreSQL**
- [Sample data seed](https://github.com/sofia-m12/hsa-account-simulation/blob/main/backend/seed.sql): `backend/seed.sql`

### Other components

- **User**

## Connections

- User → Route shell: uses (evidence: `frontend/src/App.tsx`)
- Route shell → Home dashboard: routes (evidence: `frontend/src/App.tsx`)
- Route shell → Account details: routes (evidence: `frontend/src/App.tsx`)
- Route shell → Transactions view: routes (evidence: `frontend/src/App.tsx`)
- Route shell → Not found view: routes (evidence: `frontend/src/App.tsx`)
- Home dashboard → Account form: renders (evidence: `frontend/src/pages/HomePage.tsx`)
- Home dashboard → API client: requests accounts and activity (evidence: `frontend/src/pages/HomePage.tsx`)
- Home dashboard → Activity tables: renders (evidence: `frontend/src/pages/HomePage.tsx`)
- Account details → API client: requests account actions (evidence: `frontend/src/pages/AccountPage.tsx`)
- Account details → Deposit form: renders (evidence: `frontend/src/pages/AccountPage.tsx`)
- Account details → Purchase form: renders (evidence: `frontend/src/pages/AccountPage.tsx`)
- Account details → Activity tables: renders (evidence: `frontend/src/pages/AccountPage.tsx`)
- Transactions view → API client: requests activity and purchases (evidence: `frontend/src/pages/TransactionsPage.tsx`)
- Transactions view → Purchase simulator: renders (evidence: `frontend/src/pages/TransactionsPage.tsx`)
- Transactions view → Activity tables: renders (evidence: `frontend/src/pages/TransactionsPage.tsx`)
- Purchase simulator → Purchase form: renders (evidence: `frontend/src/components/SimulateTransactionModal.tsx`)
- Activity tables → Display formatting: formats values (evidence: `frontend/src/components/TransactionsTable.tsx`)
- API client → Account operations: HTTP requests (evidence: `README.md`)
- Account operations → Request and response models: validates and serializes (evidence: `backend/app/routes/accounts.py`)
- Account operations → Session dependency: gets session (evidence: `backend/app/routes/accounts.py`)
- Account operations → Relational tables: queries and mutates (evidence: `backend/app/routes/accounts.py`)
- Session dependency → Database engine: uses engine (evidence: `backend/app/dependencies.py`)
- Database engine → Database configuration: reads settings (evidence: `backend/app/database.py`)
- Database engine → PostgreSQL: connects
- Relational tables → PostgreSQL: maps tables
- Sample data seed → PostgreSQL: initializes sample data (evidence: `README.md`)