# shahedpy/py-lms architecture

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

- Interactive diagram: https://gitdiagram.com/shahedpy/py-lms
- Repository: https://github.com/shahedpy/py-lms

## Overview

1. **Overall shape**
   - This is a **desktop Library Management System** built in **Python 3.13+**.
   - The architecture is a classic **presentation layer + controller + data access layer** split, with **SQLite** as the embedded persistence store.

2. **Application entry and mode selection**
   - `main.py` is the entry point.
   - It appears to support two execution paths:
     - launching the **GUI application**
     - running **administrative console-style commands** such as `createsuperuser` and `resetpassword`
   - This makes startup a small orchestration boundary between user-facing app flow and admin maintenance tasks.

3. **Presentation layer**
   - The `gui/` package contains the full UI surface.
   - `gui/controller.py` is the central coordinator between screens and backend operations.
   - `gui/pages/` contains one screen per major workflow: login, dashboard, book management, member management, user management, issue/return, fines, password change, member details, and reports.
   - The UI is Tkinter-based, so the presentation layer is a native desktop interface rather than a browser app.

4. **Authentication and access control boundary**
   - Authentication is handled through the login and user-management pages, backed by `database/user.py`.
   - The presence of `createsuperuser.py` and `resetpassword.py` suggests explicit administrative account lifecycle flows.
   - Role-based access is implied by separate user administration screens and the need to log in before reaching the dashboard.

5. **Domain-oriented data layer**
   - The `database/` package is not just persistence plumbing; it is organized by business entity:
     - `book.py` for catalog/inventory data
     - `member.py` for patron records
     - `transaction.py` for issue/return workflows and fines
     - `report.py` for analytics and summaries
     - `user.py` for accounts and authentication
   - This indicates a **manual data-access pattern** rather than a heavyweight ORM.

6. **Persistence and database boundary**
   - `database/db_connection.py` centralizes connection handling to the embedded SQLite file `database/database.db`.
   - That database file is the system-of-record for books, members, users, and circulation transactions.
   - The architecture is therefore self-contained: no external DB server is required.

7. **Core circulation workflow**
   - The main operational path runs through the **issue book** and **return book** screens.
   - Those flows likely coordinate with `transaction.py` to:
     - create issue records
     - calculate due dates
     - mark returns
     - compute overdue fines
     - update book availability
   - This is the key state-changing subsystem in the application.

8. **Inventory and member management**
   - `manage_books.py` and `manage_members.py` map to the library’s master data.
   - These modules likely read/write through `book.py` and `member.py`, updating the persistent catalog and patron registry.
   - `member_details.py` provides a read-focused view that likely aggregates a member’s profile and borrowing history.

9. **Reporting and analytics subsystem**
   - `gui/pages/reports.py` plus `database/report.py` form a reporting boundary distinct from transactional workflows.
   - Reports are generated from existing book/member/transaction data, likely producing dashboard metrics, overdue lists, lending trends, and fine summaries.
   - The README mentions CSV export, so reporting is not only visual but also intended for external analysis.

10. **Dashboard as aggregation layer**
   - `dashboard.py` is the main post-login landing page.
   - It likely surfaces summary counts and operational indicators pulled from the reporting/data layer.
   - In architectural terms, it serves as the application’s **read-only overview** of the underlying transaction state.

11. **Static assets**
   - `assets/images/` contains logos and branding used by the UI.
   - These are purely presentation resources and do not affect domain logic, but they are part of the desktop app’s visual layer.

12. **Primary data flow**
   - The common flow is: **user interacts with a Tkinter page → controller routes action → database module performs query/update → SQLite persists state → results return to UI**.
   - Reporting follows a mostly **read-only** version of the same path, while issue/return and management screens are **write-heavy** and mutate the database.

13. **Architectural boundaries to draw**
   - **UI boundary**: `gui/pages/*`
   - **Orchestration boundary**: `gui/controller.py`
   - **Data access/business rules boundary**: `database/*.py`
   - **Persistence boundary**: `database/database.db`
   - **Admin maintenance boundary**: `createsuperuser.py`, `resetpassword.py`, invoked from `main.py`

14. **What is notably absent**
   - There is no sign of a separate server process, REST API, or external cloud service.
   - No queueing system, message broker, or third-party analytics platform is present in the tree.
   - The system is therefore a **single-machine, self-contained desktop application** with local persistence.

Main entry points: [`gui/controller.py`](https://github.com/shahedpy/py-lms/blob/main/gui/controller.py) (Controller), [`database/db_connection.py`](https://github.com/shahedpy/py-lms/blob/main/database/db_connection.py) (DB connection), [`database/book.py`](https://github.com/shahedpy/py-lms/blob/main/database/book.py) (Book data), [`database/transaction.py`](https://github.com/shahedpy/py-lms/blob/main/database/transaction.py) (Transaction data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & admin"]
  node_main(("main.py<br/>app entry<br/>[main.py]"))
  node_create_superuser["Create superuser<br/>admin task<br/>[createsuperuser.py]"]
  node_reset_password["Reset password<br/>admin task<br/>[resetpassword.py]"]
end

subgraph group_ui["Presentation layer"]
  node_controller["Controller<br/>ui coordinator<br/>[controller.py]"]
  node_login["Login<br/>auth screen<br/>[login.py]"]
  node_dashboard["Dashboard<br/>overview screen<br/>[dashboard.py]"]
  node_manage_books["Books<br/>catalog screen<br/>[manage_books.py]"]
  node_manage_members["Members<br/>patron screen<br/>[manage_members.py]"]
  node_manage_users["Users<br/>admin screen<br/>[manage_users.py]"]
  node_issue_book["Issue book<br/>circulation screen<br/>[issue_book.py]"]
  node_return_book["Return book<br/>circulation screen<br/>[return_book.py]"]
  node_fine_management["Fines<br/>circulation screen<br/>[fine_management.py]"]
  node_member_details["Member details<br/>lookup screen<br/>[member_details.py]"]
  node_reports["Reports<br/>analytics screen<br/>[reports.py]"]
  node_change_password["Change password<br/>account screen<br/>[change_password.py]"]
end

subgraph group_data["Domain data layer"]
  node_book_data["Book data<br/>catalog DAO<br/>[book.py]"]
  node_member_data["Member data<br/>patron DAO<br/>[member.py]"]
  node_transaction_data["Transaction data<br/>circulation DAO<br/>[transaction.py]"]
  node_user_data["User data<br/>auth DAO<br/>[user.py]"]
  node_report_data["Report data<br/>report DAO<br/>[report.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_connection[("DB connection<br/>sqlite connector<br/>[db_connection.py]")]
  node_sqlite_db[("database.db<br/>sqlite file<br/>[database.db]")]
end

subgraph group_assets["Static assets"]
  node_images{{"Images<br/>ui assets"}}
end

node_main -->|"launch GUI"| node_controller
node_main -->|"admin mode"| node_create_superuser
node_main -->|"admin mode"| node_reset_password
node_controller -->|"open"| node_login
node_controller -->|"navigate"| node_dashboard
node_controller -->|"navigate"| node_manage_books
node_controller -->|"navigate"| node_manage_members
node_controller -->|"navigate"| node_manage_users
node_controller -->|"navigate"| node_issue_book
node_controller -->|"navigate"| node_return_book
node_controller -->|"navigate"| node_fine_management
node_controller -->|"navigate"| node_member_details
node_controller -->|"navigate"| node_reports
node_controller -->|"navigate"| node_change_password
node_login -->|"authenticate"| node_user_data
node_manage_users -->|"crud"| node_user_data
node_change_password -->|"update"| node_user_data
node_manage_books -->|"crud"| node_book_data
node_manage_members -->|"crud"| node_member_data
node_member_details -->|"read"| node_member_data
node_issue_book -->|"create loan"| node_transaction_data
node_issue_book -->|"reserve stock"| node_book_data
node_return_book -->|"close loan"| node_transaction_data
node_return_book -->|"restore stock"| node_book_data
node_fine_management -->|"read fines"| node_transaction_data
node_dashboard -->|"summaries"| node_report_data
node_reports -->|"generate"| node_report_data
node_book_data -->|"use"| node_db_connection
node_member_data -->|"use"| node_db_connection
node_transaction_data -->|"use"| node_db_connection
node_user_data -->|"use"| node_db_connection
node_report_data -->|"use"| node_db_connection
node_db_connection -->|"persist"| node_sqlite_db
node_dashboard -->|"decorate"| node_images
node_login -->|"decorate"| node_images

click node_main "https://github.com/shahedpy/py-lms/blob/main/main.py"
click node_create_superuser "https://github.com/shahedpy/py-lms/blob/main/database/createsuperuser.py"
click node_reset_password "https://github.com/shahedpy/py-lms/blob/main/database/resetpassword.py"
click node_controller "https://github.com/shahedpy/py-lms/blob/main/gui/controller.py"
click node_login "https://github.com/shahedpy/py-lms/blob/main/gui/pages/login.py"
click node_dashboard "https://github.com/shahedpy/py-lms/blob/main/gui/pages/dashboard.py"
click node_manage_books "https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_books.py"
click node_manage_members "https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_members.py"
click node_manage_users "https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_users.py"
click node_issue_book "https://github.com/shahedpy/py-lms/blob/main/gui/pages/issue_book.py"
click node_return_book "https://github.com/shahedpy/py-lms/blob/main/gui/pages/return_book.py"
click node_fine_management "https://github.com/shahedpy/py-lms/blob/main/gui/pages/fine_management.py"
click node_member_details "https://github.com/shahedpy/py-lms/blob/main/gui/pages/member_details.py"
click node_reports "https://github.com/shahedpy/py-lms/blob/main/gui/pages/reports.py"
click node_change_password "https://github.com/shahedpy/py-lms/blob/main/gui/pages/change_password.py"
click node_book_data "https://github.com/shahedpy/py-lms/blob/main/database/book.py"
click node_member_data "https://github.com/shahedpy/py-lms/blob/main/database/member.py"
click node_transaction_data "https://github.com/shahedpy/py-lms/blob/main/database/transaction.py"
click node_user_data "https://github.com/shahedpy/py-lms/blob/main/database/user.py"
click node_report_data "https://github.com/shahedpy/py-lms/blob/main/database/report.py"
click node_db_connection "https://github.com/shahedpy/py-lms/blob/main/database/db_connection.py"
click node_sqlite_db "https://github.com/shahedpy/py-lms/blob/main/database/database.db"
click node_images "https://github.com/shahedpy/py-lms/tree/main/assets/images"

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_main,node_create_superuser,node_reset_password toneBlue
class node_controller,node_login,node_dashboard,node_manage_books,node_manage_members,node_manage_users,node_issue_book,node_return_book,node_fine_management,node_member_details,node_reports,node_change_password toneAmber
class node_book_data,node_member_data,node_transaction_data,node_user_data,node_report_data toneMint
class node_db_connection,node_sqlite_db toneRose
class node_images toneIndigo
```

## Components

### Entry & admin

Application startup and maintenance commands

- [main.py](https://github.com/shahedpy/py-lms/blob/main/main.py): app entry · Starts the desktop app and dispatches admin commands · `main.py`
- [Create superuser](https://github.com/shahedpy/py-lms/blob/main/database/createsuperuser.py): admin task · Command-style account bootstrap flow · `database/createsuperuser.py`
- [Reset password](https://github.com/shahedpy/py-lms/blob/main/database/resetpassword.py): admin task · Command-style password recovery and maintenance flow · `database/resetpassword.py`

### Presentation layer

Tkinter desktop interface and screen navigation

- [Controller](https://github.com/shahedpy/py-lms/blob/main/gui/controller.py): ui coordinator · Routes UI actions to data operations and screen transitions · `gui/controller.py`
- [Login](https://github.com/shahedpy/py-lms/blob/main/gui/pages/login.py): auth screen · Authenticates users before dashboard access · `gui/pages/login.py`
- [Dashboard](https://github.com/shahedpy/py-lms/blob/main/gui/pages/dashboard.py): overview screen · Post-login summary and navigation hub · `gui/pages/dashboard.py`
- [Books](https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_books.py): catalog screen · Adds and edits catalog inventory · `gui/pages/manage_books.py`
- [Members](https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_members.py): patron screen · Maintains member records · `gui/pages/manage_members.py`
- [Users](https://github.com/shahedpy/py-lms/blob/main/gui/pages/manage_users.py): admin screen · Manages application accounts and roles · `gui/pages/manage_users.py`
- [Issue book](https://github.com/shahedpy/py-lms/blob/main/gui/pages/issue_book.py): circulation screen · Creates lending transactions and availability updates · `gui/pages/issue_book.py`
- [Return book](https://github.com/shahedpy/py-lms/blob/main/gui/pages/return_book.py): circulation screen · Closes loans, updates stock, and triggers fines · `gui/pages/return_book.py`
- [Fines](https://github.com/shahedpy/py-lms/blob/main/gui/pages/fine_management.py): circulation screen · Reviews and manages overdue charges · `gui/pages/fine_management.py`
- [Member details](https://github.com/shahedpy/py-lms/blob/main/gui/pages/member_details.py): lookup screen · Shows a member profile and borrowing history · `gui/pages/member_details.py`
- [Reports](https://github.com/shahedpy/py-lms/blob/main/gui/pages/reports.py): analytics screen · Displays operational summaries and exportable reports · `gui/pages/reports.py`
- [Change password](https://github.com/shahedpy/py-lms/blob/main/gui/pages/change_password.py): account screen · Lets logged-in users update credentials · `gui/pages/change_password.py`

### Domain data layer

Entity-oriented access to books, members, users, circulation, and reports

- [Book data](https://github.com/shahedpy/py-lms/blob/main/database/book.py): catalog DAO · Persistence operations for books and availability · `database/book.py`
- [Member data](https://github.com/shahedpy/py-lms/blob/main/database/member.py): patron DAO · Persistence operations for member records · `database/member.py`
- [Transaction data](https://github.com/shahedpy/py-lms/blob/main/database/transaction.py): circulation DAO · Issue/return records, due dates, and fines · `database/transaction.py`
- [User data](https://github.com/shahedpy/py-lms/blob/main/database/user.py): auth DAO · Accounts, authentication, and role handling · `database/user.py`
- [Report data](https://github.com/shahedpy/py-lms/blob/main/database/report.py): report DAO · Aggregations and summaries for dashboards and exports · `database/report.py`

### Persistence

Embedded SQLite store and connection management

- [DB connection](https://github.com/shahedpy/py-lms/blob/main/database/db_connection.py): sqlite connector · Centralized SQLite connection handling · `database/db_connection.py`
- [database.db](https://github.com/shahedpy/py-lms/blob/main/database/database.db): sqlite file · Embedded system-of-record for the application · `database/database.db`

### Static assets

Images and branding used by the UI

- [Images](https://github.com/shahedpy/py-lms/tree/main/assets/images): ui assets · Branding and illustration assets for the desktop UI · `assets/images`

## Connections

- main.py → Controller: launch GUI · Starts the desktop application through the UI coordinator
- main.py → Create superuser: admin mode · Invokes superuser bootstrap command
- main.py → Reset password: admin mode · Invokes password reset command
- Controller → Login: open · Shows the authentication screen
- Controller → Dashboard: navigate · Routes successful logins to the dashboard
- Controller → Books: navigate · Opens catalog maintenance
- Controller → Members: navigate · Opens patron maintenance
- Controller → Users: navigate · Opens account administration
- Controller → Issue book: navigate · Opens lending workflow
- Controller → Return book: navigate · Opens return workflow
- Controller → Fines: navigate · Opens fine review workflow
- Controller → Member details: navigate · Opens member lookup
- Controller → Reports: navigate · Opens reporting views
- Controller → Change password: navigate · Opens password change flow
- Login → User data: authenticate · Validates credentials and role access
- Users → User data: crud · Creates, updates, and removes accounts
- Change password → User data: update · Updates stored credentials
- Books → Book data: crud · Maintains catalog records
- Members → Member data: crud · Maintains member records
- Member details → Member data: read · Loads the selected member profile
- Issue book → Transaction data: create loan · Creates issue transactions and due dates
- Issue book → Book data: reserve stock · Marks books unavailable while on loan
- Return book → Transaction data: close loan · Records returns and completed circulation
- Return book → Book data: restore stock · Makes returned books available again
- Fines → Transaction data: read fines · Reads overdue and penalty data
- Dashboard → Report data: summaries · Pulls counts and operational indicators
- Reports → Report data: generate · Builds reports and exports from stored data
- Book data → DB connection: use · Uses shared SQLite connection handling
- Member data → DB connection: use · Uses shared SQLite connection handling
- Transaction data → DB connection: use · Uses shared SQLite connection handling
- User data → DB connection: use · Uses shared SQLite connection handling
- Report data → DB connection: use · Uses shared SQLite connection handling
- DB connection → database.db: persist · Connects application operations to the embedded database file
- Dashboard → Images: decorate · Uses visual assets in the desktop interface
- Login → Images: decorate · Uses branding and imagery in the login screen