# jayq23/librarymanagement architecture

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

- Interactive diagram: https://gitdiagram.com/jayq23/librarymanagement
- Repository: https://github.com/jayq23/librarymanagement

## Overview

Viva La Vida is a desktop library-management application. A librarian signs in, then uses the dashboard to manage the catalog, members, borrowing and returns, reservations, fines, and reports; a chatbot offers a parallel natural-language interface to selected library operations. Business managers execute the domain rules and query the database service. The graph includes major README-style product areas indicated by the source tree and module references; relationships for unsampled views are based on the SOURCE INDEX, not inspected implementations.

Main entry points: [`gui/dashboard.py`](https://github.com/jayq23/librarymanagement/blob/main/gui/dashboard.py) (Dashboard), [`ai_agent/tools.py`](https://github.com/jayq23/librarymanagement/blob/main/ai_agent/tools.py) (Library action tools), [`gui/borrow_return_view.py`](https://github.com/jayq23/librarymanagement/blob/main/gui/borrow_return_view.py) (Borrow and return), [`managers/book_manager.py`](https://github.com/jayq23/librarymanagement/blob/main/managers/book_manager.py) (Book catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_app["Application entry<br/>[main.py]"]
  node_login["Sign-in<br/>[login_window.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_catalog_ui["Catalog view"]
  node_circulation_ui["Borrow and return"]
  node_category_ui["Category view<br/>[category_view.py]"]
  node_member_ui["Member view<br/>[member_view.py]"]
  node_reservation_ui["Reservation view"]
  node_reports_ui["Reports view<br/>[reports_view.py]"]
  node_chat_ui["Chat window<br/>[chatbot_window.py]"]
end

subgraph group_domain["Library operations"]
  node_auth["Authentication<br/>[auth_manager.py]"]
  node_books["Book catalog<br/>[book_manager.py]"]
  node_categories["Categories"]
  node_members["Membership<br/>[member_manager.py]"]
  node_transactions["Circulation and reservations"]
  node_fines["Fines<br/>[fine_manager.py]"]
  node_reports["Reporting<br/>[report_manager.py]"]
end

subgraph group_assistant["AI assistant"]
  node_chatbot["Chatbot interface<br/>[chatbot.py]"]
  node_agent["AI agent<br/>[agent.py]"]
  node_tools["Library action tools<br/>[tools.py]"]
  node_receipts["Receipt queue<br/>[receipts.py]"]
  node_config["Application config<br/>[config.py]"]
end

subgraph group_persistence["Data and presentation"]
  node_database_service["Database service<br/>[db_manager.py]"]
  node_database[("PostgreSQL database")]
  node_invoice["Invoice model<br/>[invoice.py]"]
  node_receipt_ui["Receipt modal<br/>[receipt_modal.py]"]
  node_receipt_helpers["Receipt helpers<br/>[receipt_helpers.py]"]
end

node_librarian(("Librarian"))

node_librarian -->|"starts"| node_app
node_app -->|"opens"| node_login
node_login -->|"authenticates"| node_auth
node_login -->|"opens"| node_dashboard
node_dashboard -->|"shows"| node_catalog_ui
node_dashboard -->|"shows"| node_circulation_ui
node_dashboard -->|"shows"| node_category_ui
node_dashboard -->|"shows"| node_member_ui
node_dashboard -->|"shows"| node_reservation_ui
node_dashboard -->|"shows"| node_reports_ui
node_dashboard -->|"opens"| node_chat_ui
node_dashboard -->|"loads metrics"| node_reports
node_catalog_ui -->|"manages"| node_books
node_catalog_ui -->|"uses"| node_categories
node_circulation_ui -->|"uses"| node_books
node_circulation_ui -->|"uses"| node_members
node_circulation_ui -->|"processes loans"| node_transactions
node_circulation_ui -->|"uses"| node_invoice
node_circulation_ui -->|"opens"| node_receipt_ui
node_category_ui -->|"manages"| node_categories
node_member_ui -->|"manages"| node_members
node_reservation_ui -->|"uses"| node_books
node_reservation_ui -->|"uses"| node_members
node_reservation_ui -->|"manages reservations"| node_transactions
node_reservation_ui -->|"uses"| node_receipt_helpers
node_reports_ui -->|"requests reports"| node_reports
node_reports_ui -->|"reads fines"| node_fines
node_chat_ui -->|"sends messages"| node_chatbot
node_chatbot -->|"delegates"| node_agent
node_chatbot -->|"uses"| node_receipts
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"reads settings"| node_config
node_tools -->|"queries catalog"| node_books
node_tools -->|"queries categories"| node_categories
node_tools -->|"queries members"| node_members
node_tools -->|"requests reports"| node_reports
node_tools -->|"processes circulation"| node_transactions
node_tools -->|"queues receipts"| node_receipts
node_receipt_helpers -->|"uses"| node_books
node_receipt_helpers -->|"formats"| node_invoice
node_receipt_helpers -->|"opens"| node_receipt_ui
node_receipt_ui -->|"displays"| node_invoice
node_receipt_ui -->|"uses"| node_fines
node_auth -->|"queries users"| node_database_service
node_books -->|"queries catalog"| node_database_service
node_categories -->|"queries categories"| node_database_service
node_members -->|"queries members"| node_database_service
node_transactions -->|"reads and writes"| node_database_service

click node_app "https://github.com/jayq23/librarymanagement/blob/main/main.py"
click node_login "https://github.com/jayq23/librarymanagement/blob/main/gui/login_window.py"
click node_dashboard "https://github.com/jayq23/librarymanagement/blob/main/gui/dashboard.py"
click node_catalog_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/book_catalog_view.py"
click node_circulation_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/borrow_return_view.py"
click node_category_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/category_view.py"
click node_member_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/member_view.py"
click node_reservation_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/reservation_view.py"
click node_reports_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/reports_view.py"
click node_chat_ui "https://github.com/jayq23/librarymanagement/blob/main/gui/chatbot_window.py"
click node_auth "https://github.com/jayq23/librarymanagement/blob/main/managers/auth_manager.py"
click node_books "https://github.com/jayq23/librarymanagement/blob/main/managers/book_manager.py"
click node_categories "https://github.com/jayq23/librarymanagement/blob/main/managers/category_manager.py"
click node_members "https://github.com/jayq23/librarymanagement/blob/main/managers/member_manager.py"
click node_transactions "https://github.com/jayq23/librarymanagement/blob/main/managers/transaction_manager.py"
click node_fines "https://github.com/jayq23/librarymanagement/blob/main/managers/fine_manager.py"
click node_reports "https://github.com/jayq23/librarymanagement/blob/main/managers/report_manager.py"
click node_chatbot "https://github.com/jayq23/librarymanagement/blob/main/ai_agent/chatbot.py"
click node_agent "https://github.com/jayq23/librarymanagement/blob/main/ai_agent/agent.py"
click node_tools "https://github.com/jayq23/librarymanagement/blob/main/ai_agent/tools.py"
click node_receipts "https://github.com/jayq23/librarymanagement/blob/main/ai_agent/receipts.py"
click node_config "https://github.com/jayq23/librarymanagement/blob/main/config.py"
click node_database_service "https://github.com/jayq23/librarymanagement/blob/main/database/db_manager.py"
click node_invoice "https://github.com/jayq23/librarymanagement/blob/main/models/invoice.py"
click node_receipt_ui "https://github.com/jayq23/librarymanagement/blob/main/utils/receipt_modal.py"
click node_receipt_helpers "https://github.com/jayq23/librarymanagement/blob/main/utils/receipt_helpers.py"

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_login,node_dashboard,node_catalog_ui,node_circulation_ui,node_category_ui,node_member_ui,node_reservation_ui,node_reports_ui,node_chat_ui toneBlue
class node_auth,node_books,node_categories,node_members,node_transactions,node_fines,node_reports toneAmber
class node_chatbot,node_agent,node_tools,node_receipts,node_config toneMint
class node_database_service,node_database,node_invoice,node_receipt_ui,node_receipt_helpers toneRose
class node_librarian toneIndigo
```

## Components

### Desktop interface

- [Application entry](https://github.com/jayq23/librarymanagement/blob/main/main.py): `main.py`
- [Sign-in](https://github.com/jayq23/librarymanagement/blob/main/gui/login_window.py): `gui/login_window.py`
- [Dashboard](https://github.com/jayq23/librarymanagement/blob/main/gui/dashboard.py): `gui/dashboard.py`
- [Catalog view](https://github.com/jayq23/librarymanagement/blob/main/gui/book_catalog_view.py): `gui/book_catalog_view.py`
- [Borrow and return](https://github.com/jayq23/librarymanagement/blob/main/gui/borrow_return_view.py): `gui/borrow_return_view.py`
- [Category view](https://github.com/jayq23/librarymanagement/blob/main/gui/category_view.py): `gui/category_view.py`
- [Member view](https://github.com/jayq23/librarymanagement/blob/main/gui/member_view.py): `gui/member_view.py`
- [Reservation view](https://github.com/jayq23/librarymanagement/blob/main/gui/reservation_view.py): `gui/reservation_view.py`
- [Reports view](https://github.com/jayq23/librarymanagement/blob/main/gui/reports_view.py): `gui/reports_view.py`
- [Chat window](https://github.com/jayq23/librarymanagement/blob/main/gui/chatbot_window.py): `gui/chatbot_window.py`

### Library operations

- [Authentication](https://github.com/jayq23/librarymanagement/blob/main/managers/auth_manager.py): `managers/auth_manager.py`
- [Book catalog](https://github.com/jayq23/librarymanagement/blob/main/managers/book_manager.py): `managers/book_manager.py`
- [Categories](https://github.com/jayq23/librarymanagement/blob/main/managers/category_manager.py): `managers/category_manager.py`
- [Membership](https://github.com/jayq23/librarymanagement/blob/main/managers/member_manager.py): `managers/member_manager.py`
- [Circulation and reservations](https://github.com/jayq23/librarymanagement/blob/main/managers/transaction_manager.py): `managers/transaction_manager.py`
- [Fines](https://github.com/jayq23/librarymanagement/blob/main/managers/fine_manager.py): `managers/fine_manager.py`
- [Reporting](https://github.com/jayq23/librarymanagement/blob/main/managers/report_manager.py): `managers/report_manager.py`

### AI assistant

- [Chatbot interface](https://github.com/jayq23/librarymanagement/blob/main/ai_agent/chatbot.py): `ai_agent/chatbot.py`
- [AI agent](https://github.com/jayq23/librarymanagement/blob/main/ai_agent/agent.py): `ai_agent/agent.py`
- [Library action tools](https://github.com/jayq23/librarymanagement/blob/main/ai_agent/tools.py): `ai_agent/tools.py`
- [Receipt queue](https://github.com/jayq23/librarymanagement/blob/main/ai_agent/receipts.py): `ai_agent/receipts.py`
- [Application config](https://github.com/jayq23/librarymanagement/blob/main/config.py): `config.py`

### Data and presentation

- [Database service](https://github.com/jayq23/librarymanagement/blob/main/database/db_manager.py): `database/db_manager.py`
- **PostgreSQL database**
- [Invoice model](https://github.com/jayq23/librarymanagement/blob/main/models/invoice.py): `models/invoice.py`
- [Receipt modal](https://github.com/jayq23/librarymanagement/blob/main/utils/receipt_modal.py): `utils/receipt_modal.py`
- [Receipt helpers](https://github.com/jayq23/librarymanagement/blob/main/utils/receipt_helpers.py): `utils/receipt_helpers.py`

### Other components

- **Librarian**

## Connections

- Librarian → Application entry: starts (evidence: `main.py`)
- Application entry → Sign-in: opens (evidence: `main.py`)
- Sign-in → Authentication: authenticates (evidence: `gui/login_window.py`)
- Sign-in → Dashboard: opens (evidence: `gui/login_window.py`)
- Dashboard → Catalog view: shows (evidence: `gui/dashboard.py`)
- Dashboard → Borrow and return: shows (evidence: `gui/dashboard.py`)
- Dashboard → Category view: shows (evidence: `gui/dashboard.py`)
- Dashboard → Member view: shows (evidence: `gui/dashboard.py`)
- Dashboard → Reservation view: shows (evidence: `gui/dashboard.py`)
- Dashboard → Reports view: shows (evidence: `gui/dashboard.py`)
- Dashboard → Chat window: opens (evidence: `gui/dashboard.py`)
- Dashboard → Reporting: loads metrics (evidence: `gui/dashboard.py`)
- Catalog view → Book catalog: manages (evidence: `gui/book_catalog_view.py`)
- Catalog view → Categories: uses (evidence: `gui/book_catalog_view.py`)
- Borrow and return → Book catalog: uses (evidence: `gui/borrow_return_view.py`)
- Borrow and return → Membership: uses (evidence: `gui/borrow_return_view.py`)
- Borrow and return → Circulation and reservations: processes loans (evidence: `gui/borrow_return_view.py`)
- Borrow and return → Invoice model: uses (evidence: `gui/borrow_return_view.py`)
- Borrow and return → Receipt modal: opens (evidence: `gui/borrow_return_view.py`)
- Category view → Categories: manages (evidence: `gui/category_view.py`)
- Member view → Membership: manages (evidence: `gui/member_view.py`)
- Reservation view → Book catalog: uses (evidence: `gui/reservation_view.py`)
- Reservation view → Membership: uses (evidence: `gui/reservation_view.py`)
- Reservation view → Circulation and reservations: manages reservations (evidence: `gui/reservation_view.py`)
- Reservation view → Receipt helpers: uses (evidence: `gui/reservation_view.py`)
- Reports view → Reporting: requests reports (evidence: `gui/reports_view.py`)
- Reports view → Fines: reads fines (evidence: `gui/reports_view.py`)
- Chat window → Chatbot interface: sends messages (evidence: `gui/chatbot_window.py`)
- Chatbot interface → AI agent: delegates (evidence: `ai_agent/chatbot.py`)
- Chatbot interface → Receipt queue: uses (evidence: `ai_agent/chatbot.py`)
- AI agent → Library action tools: dispatches tools (evidence: `ai_agent/agent.py`)
- AI agent → Application config: reads settings (evidence: `ai_agent/agent.py`)
- Library action tools → Book catalog: queries catalog (evidence: `ai_agent/tools.py`)
- Library action tools → Categories: queries categories (evidence: `ai_agent/tools.py`)
- Library action tools → Membership: queries members (evidence: `ai_agent/tools.py`)
- Library action tools → Reporting: requests reports (evidence: `ai_agent/tools.py`)
- Library action tools → Circulation and reservations: processes circulation (evidence: `ai_agent/tools.py`)
- Library action tools → Receipt queue: queues receipts (evidence: `ai_agent/tools.py`)
- Receipt helpers → Book catalog: uses (evidence: `utils/receipt_helpers.py`)
- Receipt helpers → Invoice model: formats (evidence: `utils/receipt_helpers.py`)
- Receipt helpers → Receipt modal: opens (evidence: `utils/receipt_helpers.py`)
- Receipt modal → Invoice model: displays (evidence: `utils/receipt_modal.py`)
- Receipt modal → Fines: uses (evidence: `utils/receipt_modal.py`)
- Authentication → Database service: queries users (evidence: `managers/auth_manager.py`)
- Book catalog → Database service: queries catalog (evidence: `managers/book_manager.py`)
- Categories → Database service: queries categories (evidence: `managers/category_manager.py`)
- Membership → Database service: queries members (evidence: `managers/member_manager.py`)
- Circulation and reservations → Database service: reads and writes (evidence: `managers/transaction_manager.py`)
