sabit303/qr-code-based-library-manager

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.