# stephenworld/library-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/stephenworld/library-management-system
- Repository: https://github.com/stephenworld/library-management-system

## Overview

This is a console library-management application. The main workflow loads JSON-backed library state, lets members request and track loans, and lets librarians review requests and maintain the catalog; account creation and data synchronization are also exposed through the menus. `models.py` combines domain entities, library operations, and persistence, while `utils.py` implements the interactive workflows. The excerpts do not show every persistence or loan operation, so those relationships are included only where documented by the README.

Main entry points: [`models.py`](https://github.com/stephenworld/library-management-system/blob/main/models.py) (Library Service), [`utils.py`](https://github.com/stephenworld/library-management-system/blob/main/utils.py) (Role Menus), [`main.py`](https://github.com/stephenworld/library-management-system/blob/main/main.py) (Application Loop), [`database/books.json`](https://github.com/stephenworld/library-management-system/blob/main/database/books.json) (Book Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Console Entry"]
  node_console["Application Loop<br/>[main.py]"]
end

subgraph group_workflows["User Workflows"]
  node_menus["Role Menus<br/>[utils.py]"]
  node_accounts["Account Creation<br/>[utils.py]"]
  node_member_actions["Member Actions<br/>[utils.py]"]
  node_request_review["Request Review<br/>[utils.py]"]
  node_catalog_view["Catalog View<br/>[utils.py]"]
  node_sync["Data Sync<br/>[utils.py]"]
end

subgraph group_domain["Library Domain"]
  node_library["Library Service<br/>[models.py]"]
  node_entities["Books and Users<br/>[models.py]"]
  node_history["Request History<br/>[models.py]"]
end

subgraph group_storage["JSON Storage"]
  node_books_json[("Book Catalog<br/>[books.json]")]
  node_users_json[("Accounts and Loans<br/>[users.json]")]
  node_requests_json[("Request Records<br/>[requests.json]")]
end

node_person(("Member or Librarian"))

node_person -->|"starts"| node_console
node_console -->|"loads data"| node_library
node_console -->|"routes choices"| node_menus
node_menus -->|"creates account"| node_accounts
node_accounts -->|"registers user"| node_library
node_menus -->|"opens member menu"| node_member_actions
node_member_actions -->|"requests or returns"| node_library
node_member_actions -->|"reads status"| node_history
node_menus -->|"opens librarian menu"| node_request_review
node_request_review -->|"reviews requests"| node_library
node_menus -->|"shows books"| node_catalog_view
node_catalog_view -->|"displays catalog"| node_entities
node_menus -->|"syncs data"| node_sync
node_sync -->|"reloads data"| node_library
node_library -->|"reads and writes"| node_books_json
node_library -->|"reads and writes"| node_users_json
node_library -->|"reads and writes"| node_requests_json
node_library -->|"manages records"| node_entities
node_library -->|"maintains history"| node_history

click node_console "https://github.com/stephenworld/library-management-system/blob/main/main.py"
click node_menus "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_accounts "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_member_actions "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_request_review "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_catalog_view "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_sync "https://github.com/stephenworld/library-management-system/blob/main/utils.py"
click node_library "https://github.com/stephenworld/library-management-system/blob/main/models.py"
click node_entities "https://github.com/stephenworld/library-management-system/blob/main/models.py"
click node_history "https://github.com/stephenworld/library-management-system/blob/main/models.py"
click node_books_json "https://github.com/stephenworld/library-management-system/blob/main/database/books.json"
click node_users_json "https://github.com/stephenworld/library-management-system/blob/main/database/users.json"
click node_requests_json "https://github.com/stephenworld/library-management-system/blob/main/database/requests.json"

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_console toneBlue
class node_menus,node_accounts,node_member_actions,node_request_review,node_catalog_view,node_sync toneAmber
class node_library,node_entities,node_history toneMint
class node_books_json,node_users_json,node_requests_json toneRose
class node_person toneIndigo
```

## Components

### Console Entry

- [Application Loop](https://github.com/stephenworld/library-management-system/blob/main/main.py): `main.py`

### User Workflows

- [Role Menus](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`
- [Account Creation](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`
- [Member Actions](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`
- [Request Review](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`
- [Catalog View](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`
- [Data Sync](https://github.com/stephenworld/library-management-system/blob/main/utils.py): `utils.py`

### Library Domain

- [Library Service](https://github.com/stephenworld/library-management-system/blob/main/models.py): `models.py`
- [Books and Users](https://github.com/stephenworld/library-management-system/blob/main/models.py): `models.py`
- [Request History](https://github.com/stephenworld/library-management-system/blob/main/models.py): `models.py`

### JSON Storage

- [Book Catalog](https://github.com/stephenworld/library-management-system/blob/main/database/books.json): `database/books.json`
- [Accounts and Loans](https://github.com/stephenworld/library-management-system/blob/main/database/users.json): `database/users.json`
- [Request Records](https://github.com/stephenworld/library-management-system/blob/main/database/requests.json): `database/requests.json`

### Other components

- **Member or Librarian**

## Connections

- Member or Librarian → Application Loop: starts (evidence: `README.md`)
- Application Loop → Library Service: loads data (evidence: `main.py`)
- Application Loop → Role Menus: routes choices (evidence: `main.py`)
- Role Menus → Account Creation: creates account (evidence: `utils.py`)
- Account Creation → Library Service: registers user (evidence: `utils.py`)
- Role Menus → Member Actions: opens member menu (evidence: `utils.py`)
- Member Actions → Library Service: requests or returns (evidence: `utils.py`)
- Member Actions → Request History: reads status (evidence: `utils.py`)
- Role Menus → Request Review: opens librarian menu (evidence: `utils.py`)
- Request Review → Library Service: reviews requests (evidence: `utils.py`)
- Role Menus → Catalog View: shows books (evidence: `utils.py`)
- Catalog View → Books and Users: displays catalog (evidence: `utils.py`)
- Role Menus → Data Sync: syncs data (evidence: `utils.py`)
- Data Sync → Library Service: reloads data (evidence: `utils.py`)
- Library Service → Book Catalog: reads and writes (evidence: `README.md`)
- Library Service → Accounts and Loans: reads and writes (evidence: `README.md`)
- Library Service → Request Records: reads and writes (evidence: `README.md`)
- Library Service → Books and Users: manages records (evidence: `models.py`)
- Library Service → Request History: maintains history (evidence: `models.py`)