# adityakeerti/pustak-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/adityakeerti/pustak-tracker
- Repository: https://github.com/adityakeerti/pustak-tracker

## Overview

Pustak Tracker manages library accounts, book catalogues, circulation, fines, and librarian reporting through a web dashboard, with a documented mobile-user API. The main workflow is librarian sign-in, catalog and user management, issuing or returning books, then reviewing overdue items and statistics; mobile users authenticate and access their account through the API. The tree documents scanning, notifications, categories, and transactions as additional capabilities. API-to-page wiring and mobile client implementation are not shown in the sampled source, so those links are limited to explicit documentation and observed calls.

Main entry points: [`frontend/src/App.tsx`](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/App.tsx) (Web app routing), [`frontend/src/state/authStore.ts`](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/state/authStore.ts) (Web auth state), [`backend/app/routes/api`](https://github.com/adityakeerti/pustak-tracker/tree/main/backend/app/routes/api) (Mobile and web API), [`backend/app/routes/api/auth.py`](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/routes/api/auth.py) (API authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Librarian web"]
  node_app["Web app routing<br/>[App.tsx]"]
  node_authstore["Web auth state<br/>[authStore.ts]"]
  node_booksui["Book catalogue UI<br/>[Books.tsx]"]
  node_webpages["Dashboard and pages"]
  node_backendstore["Web data state<br/>[backendStore.ts]"]
end

subgraph group_api["Backend API"]
  node_webauth["Web session routes<br/>[auth.py]"]
  node_api_routes["Mobile and web API"]
  node_authapi["API authentication<br/>[auth.py]"]
end

subgraph group_domain["Library domain"]
  node_catalog["Book services<br/>[book_service.py]"]
  node_fines["Fine and reminder service<br/>[fine_service.py]"]
  node_stats["Dashboard statistics<br/>[stats_service.py]"]
  node_models["Library entities<br/>[models.py]"]
  node_scanstore["Scan storage<br/>[scan_store.py]"]
end

subgraph group_data["Persistent data"]
  node_mysql[("MySQL database")]
end

node_librarian(("Librarian"))
node_mobileuser(("Mobile user"))
node_mobileclient["Flutter mobile app"]

node_librarian -->|"uses"| node_app
node_app -->|"routes to"| node_webpages
node_app -->|"initializes"| node_authstore
node_booksui -->|"reads and updates"| node_backendstore
node_authstore -->|"posts login"| node_authapi
node_authapi -->|"reads and writes users"| node_mysql
node_webauth -->|"reads users"| node_mysql
node_mobileuser -->|"uses"| node_mobileclient
node_mobileclient -->|"calls documented API"| node_api_routes
node_api_routes -->|"serves library data"| node_mysql
node_catalog -->|"reads and writes circulation"| node_mysql
node_fines -->|"updates transactions"| node_mysql
node_stats -->|"aggregates records"| node_mysql

click node_app "https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/App.tsx"
click node_authstore "https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/state/authStore.ts"
click node_booksui "https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/pages/Books.tsx"
click node_webpages "https://github.com/adityakeerti/pustak-tracker/tree/main/frontend/src/pages"
click node_backendstore "https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/state/backendStore.ts"
click node_webauth "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/routes/auth.py"
click node_api_routes "https://github.com/adityakeerti/pustak-tracker/tree/main/backend/app/routes/api"
click node_authapi "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/routes/api/auth.py"
click node_catalog "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/book_service.py"
click node_fines "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/fine_service.py"
click node_stats "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/stats_service.py"
click node_models "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/models.py"
click node_scanstore "https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/scan_store.py"
click node_mobileclient "https://github.com/adityakeerti/pustak-tracker/tree/main/mobile_app"

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_authstore,node_booksui,node_webpages,node_backendstore,node_mobileuser toneBlue
class node_webauth,node_api_routes,node_authapi toneAmber
class node_catalog,node_fines,node_stats,node_models,node_scanstore toneMint
class node_mysql toneRose
class node_librarian toneIndigo
class node_mobileclient toneTeal
```

## Components

### Librarian web

- [Web app routing](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Web auth state](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/state/authStore.ts): `frontend/src/state/authStore.ts`
- [Book catalogue UI](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/pages/Books.tsx): `frontend/src/pages/Books.tsx`
- [Dashboard and pages](https://github.com/adityakeerti/pustak-tracker/tree/main/frontend/src/pages): `frontend/src/pages`
- [Web data state](https://github.com/adityakeerti/pustak-tracker/blob/main/frontend/src/state/backendStore.ts): `frontend/src/state/backendStore.ts`

### Backend API

- [Web session routes](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Mobile and web API](https://github.com/adityakeerti/pustak-tracker/tree/main/backend/app/routes/api): `backend/app/routes/api`
- [API authentication](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/routes/api/auth.py): `backend/app/routes/api/auth.py`

### Library domain

- [Book services](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/book_service.py): `backend/app/services/book_service.py`
- [Fine and reminder service](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/fine_service.py): `backend/app/services/fine_service.py`
- [Dashboard statistics](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/services/stats_service.py): `backend/app/services/stats_service.py`
- [Library entities](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/models.py): `backend/app/models.py`
- [Scan storage](https://github.com/adityakeerti/pustak-tracker/blob/main/backend/app/scan_store.py): `backend/app/scan_store.py`

### Persistent data

- **MySQL database**

### Other components

- **Librarian**
- **Mobile user**
- [Flutter mobile app](https://github.com/adityakeerti/pustak-tracker/tree/main/mobile_app): `mobile_app`

## Connections

- Librarian → Web app routing: uses
- Web app routing → Dashboard and pages: routes to
- Web app routing → Web auth state: initializes
- Book catalogue UI → Web data state: reads and updates
- Web auth state → API authentication: posts login
- API authentication → MySQL database: reads and writes users
- Web session routes → MySQL database: reads users
- Mobile user → Flutter mobile app: uses
- Flutter mobile app → Mobile and web API: calls documented API
- Mobile and web API → MySQL database: serves library data
- Book services → MySQL database: reads and writes circulation
- Fine and reminder service → MySQL database: updates transactions
- Dashboard statistics → MySQL database: aggregates records