# sabit303/qr-code-based-library-manager architecture

> Architecture diagram of the GitHub repository sabit303/qr-code-based-library-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sabit303/qr-code-based-library-manager
- Repository: https://github.com/sabit303/qr-code-based-library-manager

## Overview

1. **Repository shape**
   - This is a two-part monorepo: `api/` is a Node.js/TypeScript backend, and `ui/` is a Flutter client that targets mobile and other Flutter platforms.
   - The architecture is centered on a REST API consumed by the Flutter app; there is no shared runtime between the two.

2. **Backend entry and request pipeline**
   - The API starts at `src/server.ts`, which boots the Express app defined in `src/app.ts`.
   - Requests flow through middleware first: request logging, authentication, role authorization, and centralized error handling.
   - The API exposes route modules by domain: auth, books, students, librarians, and borrowing.

3. **Layered backend design**
   - The backend follows a clear controller → service → repository split.
   - Controllers in `src/Controller` adapt HTTP requests/responses.
   - Services in `src/Services` hold business rules like login, book operations, student management, borrowing logic, and QR code generation.
   - Repositories in `src/Repositories` isolate MySQL access behind interfaces in `src/Interfaces`.

4. **Domain model and transport layer**
   - Core entities are `Book`, `Student`, `Librarian`, and `Transaction`.
   - DTOs define request/response shapes for login, logged-in state, books, students, and librarians, which keeps HTTP payloads separate from persistence models.
   - This separation matters for diagramming because data changes shape as it moves from client payloads to service logic to database records.

5. **Authentication and authorization boundary**
   - Authentication is JWT-based, handled by the auth controller/service pair and enforced by `authMiddleware`.
   - `authorizeRoleMiddleware` adds role-based access control, splitting student actions from librarian actions.
   - Password hashing is handled in `src/Helper/passHash.ts`, so raw credentials never reach storage.

6. **Borrowing and transaction flow**
   - Borrowing is its own subsystem, not just a book update.
   - The borrow service and borrow repository manage loan lifecycle events and persist them as transactions.
   - The transaction entity is the audit trail for active borrowings, returns, and history queries.

7. **QR code subsystem**
   - QR code support is a cross-cutting feature rather than a separate app.
   - On the backend, `QRCodeService` generates QR content, likely for student identification.
   - On the client, scanner views use the device camera to read QR codes for student or book workflows.
   - This creates an interaction loop between physical items/IDs and API-driven records.

8. **Database and persistence**
   - The backend uses MySQL through `mysql2`, configured in `src/config/database.ts`.
   - `src/config/init-db.sql` and `src/init-database.ts` indicate that schema initialization is part of the backend workflow.
   - The repository layer is the only part that should touch SQL, which keeps schema concerns out of controllers and services.

9. **Error handling and operational concerns**
   - Errors are standardized through `AppError` and the `errorHandler` middleware.
   - Logging is separated into `requestLogger` and `src/utils/logger.ts`, which is important for tracing API activity.
   - These concerns sit around the main request path, not inside domain logic.

10. **Backend deployment and environment**
   - The API is container-ready with `Dockerfile` and `docker-compose.yml`.
   - Runtime behavior is environment-driven via `.env` variables for port, database, JWT, CORS, and optional Cloudflare image credentials.
   - Cloudflare Images integration appears to be an external service used for media uploads or image delivery.

11. **Flutter client structure**
   - The Flutter app is organized by feature: `screens`, `widgets`, `data`, and `core`.
   - `data/services` handles API calls, `data/providers` manages state, and `data/models` mirrors backend payloads.
   - `core` contains shared constants, theming, and utility functions such as image upload or response parsing helpers.

12. **Client-side user flows**
   - The UI splits into two role-based experiences: librarian and student.
   - Librarian screens include dashboards, books, students, transactions, and scanner views.
   - Student screens include dashboard, books, borrowing history, profile, and QR code display.
   - This mirrors the backend RBAC model, so the diagram should show two client branches sharing the same API.

13. **Client-to-server data flow**
   - The Flutter app authenticates against the API, stores session state locally, and attaches bearer tokens to requests.
   - It consumes book, student, and borrowing endpoints through service classes, with providers bridging the network layer to the UI.
   - QR scanning actions from the UI typically trigger API lookups or transaction operations on the backend.

14. **Cross-platform and tooling**
   - The client includes Android, iOS, web, and Windows platform scaffolding, so the UI is a single codebase with multiple targets.
   - A GitHub Actions workflow exists at the repo root, indicating CI automation alongside Docker-based backend deployment.
   - The documentation files in `api/` suggest the backend has dedicated setup, error-handling, and implementation notes that support the architecture.

Main entry points: [`ui/lib/data`](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/data) (Data layer), [`api/src/Routes`](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Routes) (Routes), [`api/src/Services`](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Services) (Domain svcs), [`ui/lib/screens/librarian`](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/screens/librarian) (Librarian UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
end

subgraph group_api["Backend API"]
  node_api_server(("Server<br/>bootstrap<br/>[server.ts]"))
  node_api_app["Express app<br/>http app<br/>[app.ts]"]
  node_api_middleware{{"Middleware<br/>request pipeline"}}
  node_api_routes["Routes<br/>route layer"]
  node_api_auth_controller["Auth ctrl<br/>controller<br/>[authController.ts]"]
  node_api_domain_controllers["Domain ctrls<br/>controllers"]
  node_api_login_service["Login svc<br/>auth service<br/>[LoginService.ts]"]
  node_api_domain_services["Domain svcs<br/>business logic"]
  node_api_repositories[("Repositories<br/>mysql access")]
  node_api_interfaces["Interfaces<br/>repo contracts"]
  node_api_dtos["DTOs<br/>transport models"]
  node_api_entities["Entities<br/>domain models"]
  node_api_db[("MySQL<br/>database<br/>[database.ts]")]
  node_api_initdb["DB init<br/>schema setup<br/>[init-database.ts]"]
  node_api_errors["Errors<br/>error handling<br/>[AppError.ts]"]
  node_api_utils["Utilities<br/>support utils"]
end

subgraph group_ui["Flutter UI"]
  node_ui_main(("App entry<br/>flutter bootstrap<br/>[main.dart]"))
  node_ui_core["Core<br/>shared UI support"]
  node_ui_data["Data layer<br/>client data"]
  node_ui_auth["Auth flow<br/>screen flow<br/>[login_screen.dart]"]
  node_ui_librarian["Librarian UI<br/>role UI"]
  node_ui_student["Student UI<br/>role UI"]
  node_ui_widgets["Widgets"]
end

subgraph group_ops["Ops"]
  node_github_actions["CI workflow<br/>automation<br/>[main.yml]"]
end

node_github_actions -.->|"builds"| node_api_server
node_github_actions -.->|"builds"| node_ui_main
node_api_server -->|"boots"| node_api_app
node_api_app -->|"uses"| node_api_middleware
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"dispatches"| node_api_auth_controller
node_api_routes -->|"dispatches"| node_api_domain_controllers
node_api_auth_controller -->|"calls"| node_api_login_service
node_api_domain_controllers -->|"calls"| node_api_domain_services
node_api_domain_services -->|"depends on"| node_api_interfaces
node_api_interfaces -->|"implemented by"| node_api_repositories
node_api_repositories -->|"queries"| node_api_db
node_api_db -.->|"initialized by"| node_api_initdb
node_api_domain_services -->|"maps"| node_api_dtos
node_api_domain_services -->|"persists"| node_api_entities
node_api_middleware -->|"handles"| node_api_errors
node_api_utils -.->|"supports"| node_api_login_service
node_ui_main -->|"loads"| node_ui_core
node_ui_main -->|"uses"| node_ui_data
node_ui_data -->|"calls API"| node_api_app
node_ui_data -->|"drives"| node_ui_auth
node_ui_data -->|"drives"| node_ui_librarian
node_ui_data -->|"drives"| node_ui_student
node_ui_librarian -.->|"reuses"| node_ui_widgets
node_ui_student -.->|"reuses"| node_ui_widgets
node_ui_student -.->|"uses"| node_ui_core
node_ui_librarian -.->|"uses"| node_ui_core
node_ui_librarian -.->|"scans/queries"| node_api_routes
node_ui_student -.->|"scans/queries"| node_api_routes

click node_github_actions "https://github.com/sabit303/qr-code-based-library-manager/blob/main/.github/workflows/main.yml"
click node_api_server "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/server.ts"
click node_api_app "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/app.ts"
click node_api_middleware "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/middlewares"
click node_api_routes "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Routes"
click node_api_auth_controller "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/Controller/authController.ts"
click node_api_domain_controllers "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Controller"
click node_api_login_service "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/Services/LoginService.ts"
click node_api_domain_services "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Services"
click node_api_repositories "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Repositories"
click node_api_interfaces "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Interfaces"
click node_api_dtos "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/DTOs"
click node_api_entities "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Entities"
click node_api_db "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/config/database.ts"
click node_api_initdb "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/init-database.ts"
click node_api_errors "https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/errors/AppError.ts"
click node_api_utils "https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/utils"
click node_ui_main "https://github.com/sabit303/qr-code-based-library-manager/blob/main/ui/lib/main.dart"
click node_ui_core "https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/core"
click node_ui_data "https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/data"
click node_ui_auth "https://github.com/sabit303/qr-code-based-library-manager/blob/main/ui/lib/screens/auth/login_screen.dart"
click node_ui_librarian "https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/screens/librarian"
click node_ui_student "https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/screens/student"
click node_ui_widgets "https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/widgets"

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_api_server,node_api_app,node_api_middleware,node_api_routes,node_api_auth_controller,node_api_domain_controllers,node_api_login_service,node_api_domain_services,node_api_repositories,node_api_interfaces,node_api_dtos,node_api_entities,node_api_db,node_api_initdb,node_api_errors,node_api_utils toneAmber
class node_ui_main,node_ui_core,node_ui_data,node_ui_auth,node_ui_librarian,node_ui_student,node_ui_widgets toneMint
class node_github_actions toneRose
```

## Components

### Backend API

Node.js/TypeScript REST backend

- [Server](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/server.ts): bootstrap · Bootstraps the Express application · `api/src/server.ts`
- [Express app](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/app.ts): http app · Wires middleware and routes · `api/src/app.ts`
- [Middleware](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/middlewares): request pipeline · Logging, auth, role checks, and error handling · `api/src/middlewares`
- [Routes](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Routes): route layer · Domain route modules exposed by the API · `api/src/Routes`
- [Auth ctrl](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/Controller/authController.ts): controller · Login and session endpoints · `api/src/Controller/authController.ts`
- [Domain ctrls](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Controller): controllers · HTTP adapters for books, students, librarians, and borrowing · `api/src/Controller`
- [Login svc](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/Services/LoginService.ts): auth service · JWT login and session logic · `api/src/Services/LoginService.ts`
- [Domain svcs](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Services): business logic · Books, students, librarians, borrowing, and QR code rules · `api/src/Services`
- [Repositories](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Repositories): mysql access · MySQL persistence implementations · `api/src/Repositories`
- [Interfaces](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Interfaces): repo contracts · Repository abstractions used by services · `api/src/Interfaces`
- [DTOs](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/DTOs): transport models · Request and response shapes for HTTP payloads · `api/src/DTOs`
- [Entities](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/Entities): domain models · Book, student, librarian, and transaction records · `api/src/Entities`
- [MySQL](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/config/database.ts): database · Relational persistence for library data · `api/src/config/database.ts`
- [DB init](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/init-database.ts): schema setup · Schema bootstrap and initialization workflow · `api/src/init-database.ts`
- [Errors](https://github.com/sabit303/qr-code-based-library-manager/blob/main/api/src/errors/AppError.ts): error handling · AppError and centralized HTTP error responses · `api/src/errors/AppError.ts`
- [Utilities](https://github.com/sabit303/qr-code-based-library-manager/tree/main/api/src/utils): support utils · Logging, hashing, and Cloudflare image helpers · `api/src/utils`

### Flutter UI

Cross-platform client app

- [App entry](https://github.com/sabit303/qr-code-based-library-manager/blob/main/ui/lib/main.dart): flutter bootstrap · Flutter application entry point · `ui/lib/main.dart`
- [Core](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/core): shared UI support · Constants, theme, and utility helpers · `ui/lib/core`
- [Data layer](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/data): client data · Models, providers, and API service wrappers · `ui/lib/data`
- [Auth flow](https://github.com/sabit303/qr-code-based-library-manager/blob/main/ui/lib/screens/auth/login_screen.dart): screen flow · Login and session entry experience · `ui/lib/screens/auth/login_screen.dart`
- [Librarian UI](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/screens/librarian): role UI · Dashboard, books, students, transactions, and scanners · `ui/lib/screens/librarian`
- [Student UI](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/screens/student): role UI · Dashboard, books, history, profile, and QR display · `ui/lib/screens/student`
- [Widgets](https://github.com/sabit303/qr-code-based-library-manager/tree/main/ui/lib/widgets): shared widgets · Reusable UI components and dialogs · `ui/lib/widgets`

### Ops

CI and deployment automation

- [CI workflow](https://github.com/sabit303/qr-code-based-library-manager/blob/main/.github/workflows/main.yml): automation · GitHub Actions pipeline for repo checks · `.github/workflows/main.yml`

## Connections

- CI workflow → Server: builds · CI covers backend and app checks
- CI workflow → App entry: builds · CI covers Flutter app checks
- Server → Express app: boots · Server starts the Express app
- Express app → Middleware: uses · Request pipeline applies cross-cutting middleware
- Express app → Routes: mounts · App registers domain route modules
- Routes → Auth ctrl: dispatches · Auth routes reach auth controller
- Routes → Domain ctrls: dispatches · Domain routes reach feature controllers
- Auth ctrl → Login svc: calls · Controller delegates auth logic
- Domain ctrls → Domain svcs: calls · HTTP layer delegates business rules
- Domain svcs → Interfaces: depends on · Services use repository contracts
- Interfaces → Repositories: implemented by · MySQL repositories fulfill interfaces
- Repositories → MySQL: queries · Persistence layer talks to MySQL
- MySQL → DB init: initialized by · Schema bootstrap prepares database
- Domain svcs → DTOs: maps · Services transform HTTP payloads and responses
- Domain svcs → Entities: persists · Domain logic works with core records
- Middleware → Errors: handles · Errors are normalized centrally
- Utilities → Login svc: supports · Password hashing supports authentication
- App entry → Core: loads · App initializes shared theme and constants
- App entry → Data layer: uses · App wires data layer and state
- Data layer → Express app: calls API · Client services consume REST endpoints
- Data layer → Auth flow: drives · Auth provider/service backs login flow
- Data layer → Librarian UI: drives · Providers and services back librarian screens
- Data layer → Student UI: drives · Providers and services back student screens
- Librarian UI → Widgets: reuses · Role screens share common widgets
- Student UI → Widgets: reuses · Role screens share common widgets
- Student UI → Core: uses · Student flows use core utilities such as QR helpers
- Librarian UI → Core: uses · Librarian flows use shared utilities
- Librarian UI → Routes: scans/queries · Librarian scanner and detail views trigger backend lookups
- Student UI → Routes: scans/queries · Student QR and history flows trigger backend requests