# bobhuang666/ledger architecture

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

- Interactive diagram: https://gitdiagram.com/bobhuang666/ledger
- Repository: https://github.com/bobhuang666/ledger

## Overview

This is a web system for managing and exploring historical Shantou charity intake records. Users search or browse records, inspect multi-field statistics, and view analytics; search and statistics results can also be exported as Excel files. The React pages call a FastAPI backend, which reads the CSV record set and serves search, statistics, field, and analytics data. Analytics are cleaned and aggregated separately, then cached by the API layer. The graph reflects documented capabilities; backend excerpts are partial, so internal endpoint details not shown are grouped under the API module.

Main entry points: [`frontend/src/api/api.ts`](https://github.com/bobhuang666/ledger/blob/main/frontend/src/api/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/bobhuang666/ledger/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/components/SearchPage.tsx`](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/SearchPage.tsx) (Record search), [`frontend/src/components/StatsPage.tsx`](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/StatsPage.tsx) (Multi-field statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["App routing<br/>[App.tsx]"]
  node_search_page["Record search<br/>[SearchPage.tsx]"]
  node_stats_page["Multi-field statistics<br/>[StatsPage.tsx]"]
  node_visualization_page["Data visualization"]
  node_api_client["API client<br/>[api.ts]"]
  node_download["Excel download<br/>[download.ts]"]
  node_pagination["Pagination controls<br/>[Pagination.tsx]"]
end

subgraph group_backend["API services"]
  node_backend_api["FastAPI endpoints<br/>[main.py]"]
  node_excel_export["Excel response<br/>[main.py]"]
end

subgraph group_analysis["Record analysis"]
  node_analytics_service["Analytics aggregation"]
end

subgraph group_records["Record data"]
  node_records_csv[("Intake records<br/>[people.csv]")]
end

node_visitor(("Records user"))

node_visitor -->|"opens"| node_app
node_app -->|"routes to"| node_search_page
node_app -->|"routes to"| node_stats_page
node_app -->|"routes to"| node_visualization_page
node_search_page -->|"requests search"| node_api_client
node_stats_page -->|"requests stats"| node_api_client
node_visualization_page -->|"requests analytics"| node_api_client
node_search_page -->|"uses controls"| node_pagination
node_stats_page -->|"uses controls"| node_pagination
node_api_client -->|"calls endpoints"| node_backend_api
node_backend_api -->|"reads records"| node_records_csv
node_backend_api -->|"requests overview"| node_analytics_service
node_analytics_service -->|"aggregates records"| node_records_csv
node_search_page -->|"downloads export"| node_download
node_stats_page -->|"downloads export"| node_download
node_api_client -->|"requests export"| node_excel_export
node_backend_api -->|"builds workbook"| node_excel_export

click node_app "https://github.com/bobhuang666/ledger/blob/main/frontend/src/App.tsx"
click node_search_page "https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/SearchPage.tsx"
click node_stats_page "https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/StatsPage.tsx"
click node_visualization_page "https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/VisualizationPage.tsx"
click node_api_client "https://github.com/bobhuang666/ledger/blob/main/frontend/src/api/api.ts"
click node_download "https://github.com/bobhuang666/ledger/blob/main/frontend/src/utils/download.ts"
click node_pagination "https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/Pagination.tsx"
click node_backend_api "https://github.com/bobhuang666/ledger/blob/main/backend/main.py"
click node_excel_export "https://github.com/bobhuang666/ledger/blob/main/backend/main.py"
click node_analytics_service "https://github.com/bobhuang666/ledger/blob/main/backend/analytics_service.py"
click node_records_csv "https://github.com/bobhuang666/ledger/blob/main/backend/data/people.csv"

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_search_page,node_stats_page,node_visualization_page,node_api_client,node_download,node_pagination,node_visitor toneBlue
class node_backend_api,node_excel_export toneAmber
class node_analytics_service toneMint
class node_records_csv toneRose
```

## Components

### Web interface

- [App routing](https://github.com/bobhuang666/ledger/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Record search](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/SearchPage.tsx): `frontend/src/components/SearchPage.tsx`
- [Multi-field statistics](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/StatsPage.tsx): `frontend/src/components/StatsPage.tsx`
- [Data visualization](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/VisualizationPage.tsx): `frontend/src/components/VisualizationPage.tsx`
- [API client](https://github.com/bobhuang666/ledger/blob/main/frontend/src/api/api.ts): `frontend/src/api/api.ts`
- [Excel download](https://github.com/bobhuang666/ledger/blob/main/frontend/src/utils/download.ts): `frontend/src/utils/download.ts`
- [Pagination controls](https://github.com/bobhuang666/ledger/blob/main/frontend/src/components/Pagination.tsx): `frontend/src/components/Pagination.tsx`

### API services

- [FastAPI endpoints](https://github.com/bobhuang666/ledger/blob/main/backend/main.py): `backend/main.py`
- [Excel response](https://github.com/bobhuang666/ledger/blob/main/backend/main.py): `backend/main.py`

### Record analysis

- [Analytics aggregation](https://github.com/bobhuang666/ledger/blob/main/backend/analytics_service.py): `backend/analytics_service.py`

### Record data

- [Intake records](https://github.com/bobhuang666/ledger/blob/main/backend/data/people.csv): `backend/data/people.csv`

### Other components

- **Records user**

## Connections

- Records user → App routing: opens
- App routing → Record search: routes to
- App routing → Multi-field statistics: routes to
- App routing → Data visualization: routes to
- Record search → API client: requests search
- Multi-field statistics → API client: requests stats
- Data visualization → API client: requests analytics
- Record search → Pagination controls: uses controls
- Multi-field statistics → Pagination controls: uses controls
- API client → FastAPI endpoints: calls endpoints
- FastAPI endpoints → Intake records: reads records
- FastAPI endpoints → Analytics aggregation: requests overview
- Analytics aggregation → Intake records: aggregates records
- Record search → Excel download: downloads export
- Multi-field statistics → Excel download: downloads export
- API client → Excel response: requests export
- FastAPI endpoints → Excel response: builds workbook