# jcgemina/library-classification-and-reporting-system architecture

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

- Interactive diagram: https://gitdiagram.com/jcgemina/library-classification-and-reporting-system
- Repository: https://github.com/jcgemina/library-classification-and-reporting-system

## Overview

This is a PHP library-management application for authenticated staff, covering inventory, academic organization and courses, user administration, reporting, and activity/security logs. Staff sign in, then the app shell loads role-appropriate pages; those pages perform domain operations against MySQL. Inventory also supports asynchronous AI course suggestions: a page queues work for a CLI worker, which processes it through the AI service. Source excerpts are incomplete and the README is empty, so the graph focuses on capabilities established by the file tree and shown relationships.

Main entry points: [`app.php`](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/app.php) (App shell), [`config/db.php`](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/config/db.php) (MySQL database), [`auth.php`](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/auth.php) (Authenticate), [`pages/ai_course.php`](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/ai_course.php) (AI course suggestions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and shell"]
  node_login["Sign in<br/>[login.php]"]
  node_auth["Authenticate<br/>[auth.php]"]
  node_app["App shell<br/>[app.php]"]
  node_navigation["Role navigation<br/>[nav.php]"]
end

subgraph group_catalog["Library and academics"]
  node_inventory["Book inventory<br/>[inventory.php]"]
  node_academics["Academic organization<br/>[organization.php]"]
  node_courses["Course catalog<br/>[course.php]"]
end

subgraph group_operations["Administration and insight"]
  node_users["User administration<br/>[user.php]"]
  node_user_service["User service<br/>[user_service.php]"]
  node_dashboard["Dashboard<br/>[dashboard.php]"]
  node_reports["Reports<br/>[report.php]"]
  node_logs["Activity and security logs<br/>[logs.php]"]
  node_log_export["Log export<br/>[logs_export.php]"]
end

subgraph group_ai["AI suggestions"]
  node_ai_page["AI course suggestions<br/>[ai_course.php]"]
  node_ai_service["AI job and ranking service"]
  node_worker["AI worker<br/>[ai_worker.php]"]
end

subgraph group_foundation["Shared foundation"]
  node_database[("MySQL database<br/>[db.php]")]
  node_shared["Shared functions<br/>[functions.php]"]
end

node_staff(("Library staff"))
node_ai_provider{{"AI provider"}}

node_staff -->|"opens"| node_login
node_login -->|"submits credentials"| node_auth
node_auth -->|"checks credentials"| node_database
node_auth -->|"redirects after sign-in"| node_app
node_app -->|"requires"| node_shared
node_app -->|"renders"| node_navigation
node_app -->|"fetches page"| node_inventory
node_app -->|"fetches page"| node_academics
node_app -->|"fetches page"| node_courses
node_app -->|"fetches page"| node_ai_page
node_app -->|"fetches page"| node_users
node_app -->|"fetches page"| node_dashboard
node_app -->|"fetches page"| node_reports
node_app -->|"fetches page"| node_logs
node_inventory -->|"reads and writes"| node_database
node_academics -->|"manages records"| node_database
node_courses -->|"reads and writes"| node_database
node_users -->|"uses"| node_user_service
node_users -->|"manages users"| node_database
node_user_service -->|"queries users"| node_database
node_logs -->|"reads logs"| node_database
node_logs -.->|"offers export"| node_log_export
node_inventory -->|"provides suggestions UI"| node_ai_page
node_ai_page -->|"requests suggestions"| node_ai_service
node_ai_page -.->|"queues and reads jobs"| node_database
node_worker -->|"claims and processes jobs"| node_ai_service
node_worker -->|"uses connection"| node_database
node_ai_service -.->|"stores job results"| node_database
node_ai_service -.->|"requests embeddings and relevance"| node_ai_provider
node_auth -->|"uses security helpers"| node_shared
node_app -->|"loads connection"| node_database

click node_login "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/login.php"
click node_auth "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/auth.php"
click node_app "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/app.php"
click node_navigation "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/nav.php"
click node_inventory "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/inventory.php"
click node_academics "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/organization.php"
click node_courses "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/course.php"
click node_ai_page "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/ai_course.php"
click node_ai_service "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/ai_course_service.php"
click node_worker "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/bin/ai_worker.php"
click node_users "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/user.php"
click node_user_service "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/user_service.php"
click node_dashboard "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/dashboard.php"
click node_reports "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/report.php"
click node_logs "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/logs.php"
click node_log_export "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/logs_export.php"
click node_database "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/config/db.php"
click node_shared "https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/functions.php"

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_login,node_auth,node_app,node_navigation toneBlue
class node_inventory,node_academics,node_courses toneAmber
class node_users,node_user_service,node_dashboard,node_reports,node_logs,node_log_export toneMint
class node_ai_page,node_ai_service,node_worker toneRose
class node_database,node_shared,node_staff,node_ai_provider toneIndigo
```

## Components

### Access and shell

- [Sign in](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/login.php): `login.php`
- [Authenticate](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/auth.php): `auth.php`
- [App shell](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/app.php): `app.php`
- [Role navigation](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/nav.php): `includes/nav.php`

### Library and academics

- [Book inventory](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/inventory.php): `pages/inventory.php`
- [Academic organization](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/organization.php): `pages/organization.php`
- [Course catalog](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/course.php): `pages/course.php`

### Administration and insight

- [User administration](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/user.php): `pages/user.php`
- [User service](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/user_service.php): `includes/user_service.php`
- [Dashboard](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/dashboard.php): `pages/dashboard.php`
- [Reports](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/report.php): `pages/report.php`
- [Activity and security logs](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/logs.php): `pages/logs.php`
- [Log export](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/logs_export.php): `pages/logs_export.php`

### AI suggestions

- [AI course suggestions](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/pages/ai_course.php): `pages/ai_course.php`
- [AI job and ranking service](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/ai_course_service.php): `includes/ai_course_service.php`
- [AI worker](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/bin/ai_worker.php): `bin/ai_worker.php`

### Shared foundation

- [MySQL database](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/config/db.php): `config/db.php`
- [Shared functions](https://github.com/jcgemina/library-classification-and-reporting-system/blob/main/includes/functions.php): `includes/functions.php`

### Other components

- **Library staff**
- **AI provider**

## Connections

- Library staff → Sign in: opens
- Sign in → Authenticate: submits credentials (evidence: `auth.php`)
- Authenticate → MySQL database: checks credentials (evidence: `auth.php`)
- Authenticate → App shell: redirects after sign-in (evidence: `auth.php`)
- App shell → Shared functions: requires (evidence: `app.php`)
- App shell → Role navigation: renders (evidence: `app.php`)
- App shell → Book inventory: fetches page (evidence: `app.php`)
- App shell → Academic organization: fetches page (evidence: `app.php`)
- App shell → Course catalog: fetches page (evidence: `app.php`)
- App shell → AI course suggestions: fetches page (evidence: `app.php`)
- App shell → User administration: fetches page (evidence: `app.php`)
- App shell → Dashboard: fetches page (evidence: `app.php`)
- App shell → Reports: fetches page (evidence: `app.php`)
- App shell → Activity and security logs: fetches page (evidence: `app.php`)
- Book inventory → MySQL database: reads and writes (evidence: `pages/inventory.php`)
- Academic organization → MySQL database: manages records (evidence: `pages/organization.php`)
- Course catalog → MySQL database: reads and writes (evidence: `pages/course.php`)
- User administration → User service: uses (evidence: `pages/user.php`)
- User administration → MySQL database: manages users (evidence: `pages/user.php`)
- User service → MySQL database: queries users (evidence: `includes/user_service.php`)
- Activity and security logs → MySQL database: reads logs (evidence: `pages/logs.php`)
- Activity and security logs → Log export: offers export
- Book inventory → AI course suggestions: provides suggestions UI (evidence: `pages/inventory.php`)
- AI course suggestions → AI job and ranking service: requests suggestions (evidence: `pages/ai_course.php`)
- AI course suggestions → MySQL database: queues and reads jobs (evidence: `pages/ai_course.php`)
- AI worker → AI job and ranking service: claims and processes jobs (evidence: `bin/ai_worker.php`)
- AI worker → MySQL database: uses connection (evidence: `bin/ai_worker.php`)
- AI job and ranking service → MySQL database: stores job results
- AI job and ranking service → AI provider: requests embeddings and relevance
- Authenticate → Shared functions: uses security helpers (evidence: `auth.php`)
- App shell → MySQL database: loads connection (evidence: `app.php`)
