# badwanecr/advanced-library architecture

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

- Interactive diagram: https://gitdiagram.com/badwanecr/advanced-library
- Repository: https://github.com/badwanecr/advanced-library

## Overview

LibAssist is a library-management application with a React client, Spring Boot REST API, and PostgreSQL persistence. Patrons browse physical and digital titles, borrow books, rent ebooks or subscribe, and read ebooks; librarians manage catalogue and circulation, while admins can view reports and manage staff accounts. Ebook reading can additionally use ebook-grounded Q&A with page citations. The map preserves those branches and the payment, indexing, and retrieval stages. Some backend controllers and services were not sampled, so their internal wiring is omitted where the excerpts and README do not establish it.

Main entry points: [`frontend/src/App.js`](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/App.js) (React application), [`backend/src/main/java/com/libassist/library/rag/EbookRagService.java`](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/EbookRagService.java) (Grounded Q&A), [`backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java`](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java) (Order creation), [`backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java) (Payment verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_frontend["React application<br/>[App.js]"]
  node_book_ui["Book browsing<br/>[Library.js]"]
  node_ebook_ui["Ebook browsing<br/>[Ebooks.js]"]
  node_reader_ui["Ebook reader<br/>[index.js]"]
  node_ask_ui["Ask panel<br/>[AskPanel.js]"]
  node_profile_ui["Profile and reports<br/>[index.js]"]
end

subgraph group_library["Library operations"]
  node_book_api["Book endpoints"]
  node_book_service["Book catalogue<br/>[BookService.java]"]
  node_issue_api["Circulation endpoints"]
  node_issue_service["Issue and return<br/>[IssueService.java]"]
  node_report_api["Report endpoints"]
  node_report_service["Revenue reporting<br/>[ReportService.java]"]
end

subgraph group_digital["Ebook experience"]
  node_ebook_api["Ebook endpoints"]
  node_ebook_service["Ebook access and reading<br/>[EbookService.java]"]
  node_rag_api["Ebook question endpoint"]
  node_rag_service["Grounded Q&amp;A"]
  node_indexing["PDF indexing"]
  node_embeddings["Embedding client"]
  node_ebook_entity["Ebook records<br/>[Ebook.java]"]
  node_ebook_repository["Ebook repository"]
end

subgraph group_commerce["Access and payments"]
  node_payment_api["Payment endpoints"]
  node_payment_orders["Order creation"]
  node_payment_verify["Payment verification"]
  node_subscription["Subscription access"]
  node_payment_entity["Payment records<br/>[Payment.java]"]
  node_payment_repository["Payment repository"]
end

subgraph group_platform["Identity and persistence"]
  node_identity_api["User endpoints"]
  node_user_service["User accounts<br/>[UserService.java]"]
  node_jwt["JWT security<br/>[JwtAuthFilter.java]"]
  node_user_entity["User records<br/>[User.java]"]
  node_user_repository["User repository"]
end

node_patron(("Patron"))
node_razorpay["Razorpay"]
node_database[("PostgreSQL")]

node_patron -->|"uses"| node_frontend
node_frontend -->|"requests catalogue"| node_book_api
node_frontend -->|"requests borrowing"| node_issue_api
node_frontend -->|"requests ebook access"| node_ebook_api
node_frontend -->|"registers and logs in"| node_identity_api
node_frontend -->|"requests reports"| node_report_api
node_book_api -.-> node_book_service
node_issue_api -->|"delegates"| node_issue_service
node_report_api -.-> node_report_service
node_ebook_api -.-> node_ebook_service
node_rag_api -.-> node_rag_service
node_payment_api -.-> node_payment_orders
node_payment_api -.-> node_payment_verify
node_identity_api -.-> node_user_service
node_ebook_ui -.->|"opens reader"| node_reader_ui
node_reader_ui -.->|"offers questions"| node_ask_ui
node_payment_orders -->|"creates orders"| node_razorpay
node_payment_verify -->|"activates access"| node_subscription
node_payment_verify -->|"activates rental"| node_ebook_service
node_payment_verify -->|"loads payment"| node_payment_repository
node_payment_orders -->|"loads ebook"| node_ebook_repository
node_payment_orders -->|"loads patron"| node_user_repository
node_rag_service -->|"checks reading access"| node_ebook_service
node_rag_service -->|"embeds question"| node_embeddings
node_indexing -->|"embeds chunks"| node_embeddings
node_ebook_service -->|"starts indexing"| node_indexing
node_rag_service -->|"loads ebook"| node_ebook_repository
node_rag_service -->|"loads user"| node_user_repository
node_user_repository -->|"loads records"| node_user_entity
node_ebook_repository -->|"loads records"| node_ebook_entity
node_payment_repository -->|"loads records"| node_payment_entity
node_user_entity -->|"persists"| node_database
node_ebook_entity -->|"persists"| node_database
node_payment_entity -->|"persists"| node_database
node_payment_api -.->|"accepts webhook"| node_razorpay

click node_frontend "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/App.js"
click node_book_ui "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Home/Library.js"
click node_ebook_ui "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Home/Ebooks.js"
click node_reader_ui "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/EbookReader/index.js"
click node_ask_ui "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/EbookReader/AskPanel.js"
click node_profile_ui "https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Profile/index.js"
click node_book_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/BookController.java"
click node_book_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/BookService.java"
click node_issue_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/IssueController.java"
click node_issue_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/IssueService.java"
click node_report_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/ReportController.java"
click node_report_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/ReportService.java"
click node_ebook_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/EbookController.java"
click node_ebook_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/EbookService.java"
click node_rag_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/EbookAskController.java"
click node_rag_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/EbookRagService.java"
click node_indexing "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/EbookIndexingService.java"
click node_embeddings "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/OpenAiEmbeddingService.java"
click node_payment_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/PaymentController.java"
click node_payment_orders "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java"
click node_payment_verify "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java"
click node_subscription "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/SubscriptionService.java"
click node_identity_api "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/UserController.java"
click node_user_service "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/UserService.java"
click node_jwt "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/security/JwtAuthFilter.java"
click node_user_entity "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/User.java"
click node_ebook_entity "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/Ebook.java"
click node_payment_entity "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/Payment.java"
click node_user_repository "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/UserRepository.java"
click node_ebook_repository "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/EbookRepository.java"
click node_payment_repository "https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/PaymentRepository.java"

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_frontend,node_book_ui,node_ebook_ui,node_reader_ui,node_ask_ui,node_profile_ui toneBlue
class node_book_api,node_book_service,node_issue_api,node_issue_service,node_report_api,node_report_service,node_database toneAmber
class node_ebook_api,node_ebook_service,node_rag_api,node_rag_service,node_indexing,node_embeddings,node_ebook_entity,node_ebook_repository toneMint
class node_payment_api,node_payment_orders,node_payment_verify,node_subscription,node_payment_entity,node_payment_repository toneRose
class node_identity_api,node_user_service,node_jwt,node_user_entity,node_user_repository,node_patron,node_razorpay toneIndigo
```

## Components

### React client

- [React application](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Book browsing](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Home/Library.js): `frontend/src/pages/Home/Library.js`
- [Ebook browsing](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Home/Ebooks.js): `frontend/src/pages/Home/Ebooks.js`
- [Ebook reader](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/EbookReader/index.js): `frontend/src/pages/EbookReader/index.js`
- [Ask panel](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/EbookReader/AskPanel.js): `frontend/src/pages/EbookReader/AskPanel.js`
- [Profile and reports](https://github.com/badwanecr/advanced-library/blob/main/frontend/src/pages/Profile/index.js): `frontend/src/pages/Profile/index.js`

### Library operations

- [Book endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/BookController.java): `backend/src/main/java/com/libassist/library/controller/BookController.java`
- [Book catalogue](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/BookService.java): `backend/src/main/java/com/libassist/library/service/BookService.java`
- [Circulation endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/IssueController.java): `backend/src/main/java/com/libassist/library/controller/IssueController.java`
- [Issue and return](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/IssueService.java): `backend/src/main/java/com/libassist/library/service/IssueService.java`
- [Report endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/ReportController.java): `backend/src/main/java/com/libassist/library/controller/ReportController.java`
- [Revenue reporting](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/ReportService.java): `backend/src/main/java/com/libassist/library/service/ReportService.java`

### Ebook experience

- [Ebook endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/EbookController.java): `backend/src/main/java/com/libassist/library/controller/EbookController.java`
- [Ebook access and reading](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/EbookService.java): `backend/src/main/java/com/libassist/library/service/EbookService.java`
- [Ebook question endpoint](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/EbookAskController.java): `backend/src/main/java/com/libassist/library/controller/EbookAskController.java`
- [Grounded Q&A](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/EbookRagService.java): `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`
- [PDF indexing](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/EbookIndexingService.java): `backend/src/main/java/com/libassist/library/rag/EbookIndexingService.java`
- [Embedding client](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/rag/OpenAiEmbeddingService.java): `backend/src/main/java/com/libassist/library/rag/OpenAiEmbeddingService.java`
- [Ebook records](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/Ebook.java): `backend/src/main/java/com/libassist/library/entity/Ebook.java`
- [Ebook repository](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/EbookRepository.java): `backend/src/main/java/com/libassist/library/repository/EbookRepository.java`

### Access and payments

- [Payment endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/PaymentController.java): `backend/src/main/java/com/libassist/library/controller/PaymentController.java`
- [Order creation](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java): `backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java`
- [Payment verification](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java): `backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`
- [Subscription access](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/SubscriptionService.java): `backend/src/main/java/com/libassist/library/service/SubscriptionService.java`
- [Payment records](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/Payment.java): `backend/src/main/java/com/libassist/library/entity/Payment.java`
- [Payment repository](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/PaymentRepository.java): `backend/src/main/java/com/libassist/library/repository/PaymentRepository.java`

### Identity and persistence

- [User endpoints](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/controller/UserController.java): `backend/src/main/java/com/libassist/library/controller/UserController.java`
- [User accounts](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/service/UserService.java): `backend/src/main/java/com/libassist/library/service/UserService.java`
- [JWT security](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/security/JwtAuthFilter.java): `backend/src/main/java/com/libassist/library/security/JwtAuthFilter.java`
- [User records](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/entity/User.java): `backend/src/main/java/com/libassist/library/entity/User.java`
- [User repository](https://github.com/badwanecr/advanced-library/blob/main/backend/src/main/java/com/libassist/library/repository/UserRepository.java): `backend/src/main/java/com/libassist/library/repository/UserRepository.java`

### Other components

- **Patron**
- **Razorpay**
- **PostgreSQL**

## Connections

- Patron → React application: uses (evidence: `README.md`)
- React application → Book endpoints: requests catalogue (evidence: `README.md`)
- React application → Circulation endpoints: requests borrowing (evidence: `README.md`)
- React application → Ebook endpoints: requests ebook access (evidence: `README.md`)
- React application → User endpoints: registers and logs in (evidence: `README.md`)
- React application → Report endpoints: requests reports (evidence: `README.md`)
- Book endpoints → Book catalogue (evidence: `backend/src/main/java/com/libassist/library/controller/BookController.java`)
- Circulation endpoints → Issue and return: delegates (evidence: `backend/src/main/java/com/libassist/library/service/IssueService.java`)
- Report endpoints → Revenue reporting
- Ebook endpoints → Ebook access and reading (evidence: `backend/src/main/java/com/libassist/library/controller/EbookController.java`)
- Ebook question endpoint → Grounded Q&A
- Payment endpoints → Order creation (evidence: `backend/src/main/java/com/libassist/library/controller/PaymentController.java`)
- Payment endpoints → Payment verification (evidence: `backend/src/main/java/com/libassist/library/controller/PaymentController.java`)
- User endpoints → User accounts
- Ebook browsing → Ebook reader: opens reader
- Ebook reader → Ask panel: offers questions (evidence: `frontend/src/pages/EbookReader/index.js`)
- Order creation → Razorpay: creates orders (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java`)
- Payment verification → Subscription access: activates access (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`)
- Payment verification → Ebook access and reading: activates rental (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`)
- Payment verification → Payment repository: loads payment (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`)
- Order creation → Ebook repository: loads ebook (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java`)
- Order creation → User repository: loads patron (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentOrderService.java`)
- Grounded Q&A → Ebook access and reading: checks reading access (evidence: `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`)
- Grounded Q&A → Embedding client: embeds question (evidence: `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`)
- PDF indexing → Embedding client: embeds chunks (evidence: `backend/src/main/java/com/libassist/library/rag/EbookIndexingService.java`)
- Ebook access and reading → PDF indexing: starts indexing (evidence: `backend/src/main/java/com/libassist/library/service/EbookService.java`)
- Grounded Q&A → Ebook repository: loads ebook (evidence: `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`)
- Grounded Q&A → User repository: loads user (evidence: `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`)
- User repository → User records: loads records (evidence: `backend/src/main/java/com/libassist/library/repository/UserRepository.java`)
- Ebook repository → Ebook records: loads records (evidence: `backend/src/main/java/com/libassist/library/rag/EbookRagService.java`)
- Payment repository → Payment records: loads records (evidence: `backend/src/main/java/com/libassist/library/payment/PaymentVerificationService.java`)
- User records → PostgreSQL: persists (evidence: `README.md`)
- Ebook records → PostgreSQL: persists (evidence: `README.md`)
- Payment records → PostgreSQL: persists (evidence: `README.md`)
- Payment endpoints → Razorpay: accepts webhook
