# allwinpauldurai-creator/song-book-webapp architecture

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

- Interactive diagram: https://gitdiagram.com/allwinpauldurai-creator/song-book-webapp
- Repository: https://github.com/allwinpauldurai-creator/song-book-webapp

## Overview

Song Book Library provides a public catalogue, member accounts and requests, member-only PDF reading/download, and staff administration. The user journey runs from browsing books through sign-in and membership-gated reading; members can also manage profiles and submit modification requests, while staff review requests and manage books and users. The graph describes the sampled React frontend and its API boundary, not the unsampled Spring backend internals. Some page-to-service links rely on the SOURCE INDEX import references rather than inspected implementation excerpts.

Main entry points: [`frontend/src/services/api/endpoints.ts`](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/services/api/endpoints.ts) (Typed API endpoints), [`frontend/src/app/App.tsx`](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/app/App.tsx) (Route application), [`frontend/src/features/admin/AdminRoutes.tsx`](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/AdminRoutes.tsx) (Staff routes), [`frontend/src/features/reader/ReaderPage.tsx`](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/reader/ReaderPage.tsx) (PDF reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and access"]
  node_app["Route application<br/>[App.tsx]"]
  node_guards["Route guards<br/>[guards.tsx]"]
  node_auth["Session and roles<br/>[AuthContext.tsx]"]
  node_authpages["Sign-in and registration"]
end

subgraph group_catalogue["Catalogue and reading"]
  node_cataloguepages["Catalogue and details"]
  node_bookcard["Book card<br/>[BookCard.tsx]"]
  node_reader["PDF reader<br/>[ReaderPage.tsx]"]
  node_pdfhelpers["PDF access helpers"]
  node_download["PDF download<br/>[usePdfDownload.ts]"]
end

subgraph group_member["Member services"]
  node_memberpages["Member account"]
  node_profile["Profile management<br/>[ProfilePage.tsx]"]
  node_requests["Request submission<br/>[RequestsPage.tsx]"]
end

subgraph group_admin["Staff administration"]
  node_adminroutes["Staff routes<br/>[AdminRoutes.tsx]"]
  node_adminbooks["Book management<br/>[BookFormPage.tsx]"]
  node_adminreview["Request review"]
  node_adminusers["User and membership admin"]
  node_adminother["Categories and audit"]
end

subgraph group_platform["API client"]
  node_endpoints["Typed API endpoints<br/>[endpoints.ts]"]
  node_client["HTTP and token client<br/>[client.ts]"]
  node_contracts["API data contracts<br/>[api.ts]"]
  node_common["Shared UI and errors<br/>[common.tsx]"]
  node_mobile["Mobile normalization<br/>[mobile.ts]"]
end

node_visitor(("Visitor or member"))
node_staff(("Publisher or admin"))
node_api["Song Book API"]

node_visitor -->|"opens"| node_app
node_staff -->|"opens"| node_app
node_app -->|"routes to"| node_cataloguepages
node_app -->|"routes to"| node_authpages
node_app -->|"routes to"| node_memberpages
node_app -->|"routes to"| node_reader
node_app -->|"routes to"| node_adminroutes
node_app -->|"guards routes"| node_guards
node_guards -->|"checks session"| node_auth
node_auth -->|"loads user"| node_endpoints
node_authpages -->|"normalizes numbers"| node_mobile
node_cataloguepages -->|"loads catalogue"| node_endpoints
node_cataloguepages -->|"renders cards"| node_bookcard
node_reader -->|"requests access"| node_endpoints
node_reader -->|"uses"| node_pdfhelpers
node_reader -->|"offers download"| node_download
node_memberpages -->|"loads member data"| node_endpoints
node_profile -->|"updates profile"| node_endpoints
node_profile -->|"formats numbers"| node_mobile
node_requests -->|"submits requests"| node_endpoints
node_adminroutes -->|"routes to"| node_adminbooks
node_adminroutes -->|"routes to"| node_adminreview
node_adminroutes -->|"routes to"| node_adminusers
node_adminroutes -->|"routes to"| node_adminother
node_adminreview -->|"reviews requests"| node_endpoints
node_endpoints -->|"calls"| node_client
node_client -->|"sends HTTP"| node_api
node_client -->|"uses types"| node_contracts
node_endpoints -->|"types responses"| node_contracts
node_common -->|"formats errors"| node_client

click node_app "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/app/App.tsx"
click node_guards "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/routes/guards.tsx"
click node_auth "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_authpages "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/auth"
click node_cataloguepages "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/catalogue"
click node_bookcard "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/catalogue/BookCard.tsx"
click node_reader "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/reader/ReaderPage.tsx"
click node_pdfhelpers "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/reader"
click node_download "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/reader/usePdfDownload.ts"
click node_memberpages "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/member"
click node_profile "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/member/ProfilePage.tsx"
click node_requests "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/member/RequestsPage.tsx"
click node_adminroutes "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/AdminRoutes.tsx"
click node_adminbooks "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/BookFormPage.tsx"
click node_adminreview "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/RequestsReviewPage.tsx"
click node_adminusers "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/admin"
click node_adminother "https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/admin"
click node_endpoints "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/services/api/endpoints.ts"
click node_client "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/services/api/client.ts"
click node_contracts "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/types/api.ts"
click node_common "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/components/common.tsx"
click node_mobile "https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/utils/mobile.ts"

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_guards,node_auth,node_authpages toneBlue
class node_cataloguepages,node_bookcard,node_reader,node_pdfhelpers,node_download toneAmber
class node_memberpages,node_profile,node_requests,node_api toneMint
class node_adminroutes,node_adminbooks,node_adminreview,node_adminusers,node_adminother toneRose
class node_endpoints,node_client,node_contracts,node_common,node_mobile,node_visitor,node_staff toneIndigo
```

## Components

### App and access

- [Route application](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Route guards](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/routes/guards.tsx): `frontend/src/routes/guards.tsx`
- [Session and roles](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Sign-in and registration](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/auth): `frontend/src/features/auth`

### Catalogue and reading

- [Catalogue and details](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/catalogue): `frontend/src/features/catalogue`
- [Book card](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/catalogue/BookCard.tsx): `frontend/src/features/catalogue/BookCard.tsx`
- [PDF reader](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/reader/ReaderPage.tsx): `frontend/src/features/reader/ReaderPage.tsx`
- [PDF access helpers](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/reader): `frontend/src/features/reader`
- [PDF download](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/reader/usePdfDownload.ts): `frontend/src/features/reader/usePdfDownload.ts`

### Member services

- [Member account](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/member): `frontend/src/features/member`
- [Profile management](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/member/ProfilePage.tsx): `frontend/src/features/member/ProfilePage.tsx`
- [Request submission](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/member/RequestsPage.tsx): `frontend/src/features/member/RequestsPage.tsx`

### Staff administration

- [Staff routes](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/AdminRoutes.tsx): `frontend/src/features/admin/AdminRoutes.tsx`
- [Book management](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/BookFormPage.tsx): `frontend/src/features/admin/BookFormPage.tsx`
- [Request review](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/features/admin/RequestsReviewPage.tsx): `frontend/src/features/admin/RequestsReviewPage.tsx`
- [User and membership admin](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/admin): `frontend/src/features/admin`
- [Categories and audit](https://github.com/allwinpauldurai-creator/song-book-webapp/tree/main/frontend/src/features/admin): `frontend/src/features/admin`

### API client

- [Typed API endpoints](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/services/api/endpoints.ts): `frontend/src/services/api/endpoints.ts`
- [HTTP and token client](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/services/api/client.ts): `frontend/src/services/api/client.ts`
- [API data contracts](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`
- [Shared UI and errors](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/components/common.tsx): `frontend/src/components/common.tsx`
- [Mobile normalization](https://github.com/allwinpauldurai-creator/song-book-webapp/blob/main/frontend/src/utils/mobile.ts): `frontend/src/utils/mobile.ts`

### Other components

- **Visitor or member**
- **Publisher or admin**
- **Song Book API**

## Connections

- Visitor or member → Route application: opens (evidence: `frontend/src/app/App.tsx`)
- Publisher or admin → Route application: opens (evidence: `frontend/src/app/App.tsx`)
- Route application → Catalogue and details: routes to (evidence: `frontend/src/app/App.tsx`)
- Route application → Sign-in and registration: routes to (evidence: `frontend/src/app/App.tsx`)
- Route application → Member account: routes to (evidence: `frontend/src/app/App.tsx`)
- Route application → PDF reader: routes to (evidence: `frontend/src/app/App.tsx`)
- Route application → Staff routes: routes to (evidence: `frontend/src/app/App.tsx`)
- Route application → Route guards: guards routes (evidence: `frontend/src/app/App.tsx`)
- Route guards → Session and roles: checks session (evidence: `frontend/src/routes/guards.tsx`)
- Session and roles → Typed API endpoints: loads user (evidence: `frontend/src/contexts/AuthContext.tsx`)
- Sign-in and registration → Mobile normalization: normalizes numbers (evidence: `frontend/src/features/auth/LoginPage.tsx`)
- Catalogue and details → Typed API endpoints: loads catalogue (evidence: `frontend/src/features/catalogue/CataloguePage.tsx`)
- Catalogue and details → Book card: renders cards (evidence: `frontend/src/features/catalogue/CataloguePage.tsx`)
- PDF reader → Typed API endpoints: requests access (evidence: `frontend/src/features/reader/ReaderPage.tsx`)
- PDF reader → PDF access helpers: uses (evidence: `frontend/src/features/reader/ReaderPage.tsx`)
- PDF reader → PDF download: offers download (evidence: `frontend/src/features/reader/ReaderPage.tsx`)
- Member account → Typed API endpoints: loads member data (evidence: `frontend/src/features/member/MePage.tsx`)
- Profile management → Typed API endpoints: updates profile (evidence: `frontend/src/features/member/ProfilePage.tsx`)
- Profile management → Mobile normalization: formats numbers (evidence: `frontend/src/features/member/ProfilePage.tsx`)
- Request submission → Typed API endpoints: submits requests (evidence: `frontend/src/features/member/RequestsPage.tsx`)
- Staff routes → Book management: routes to (evidence: `frontend/src/features/admin/AdminRoutes.tsx`)
- Staff routes → Request review: routes to (evidence: `frontend/src/features/admin/AdminRoutes.tsx`)
- Staff routes → User and membership admin: routes to (evidence: `frontend/src/features/admin/AdminRoutes.tsx`)
- Staff routes → Categories and audit: routes to (evidence: `frontend/src/features/admin/AdminRoutes.tsx`)
- Request review → Typed API endpoints: reviews requests (evidence: `frontend/src/features/admin/RequestsReviewPage.tsx`)
- Typed API endpoints → HTTP and token client: calls (evidence: `frontend/src/services/api/endpoints.ts`)
- HTTP and token client → Song Book API: sends HTTP (evidence: `README.md`)
- HTTP and token client → API data contracts: uses types (evidence: `frontend/src/services/api/client.ts`)
- Typed API endpoints → API data contracts: types responses (evidence: `frontend/src/services/api/endpoints.ts`)
- Shared UI and errors → HTTP and token client: formats errors (evidence: `frontend/src/components/common.tsx`)
