# jawadzafar1045/attandance_system_based_on_qr architecture

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

- Interactive diagram: https://gitdiagram.com/jawadzafar1045/attandance_system_based_on_qr
- Repository: https://github.com/jawadzafar1045/attandance_system_based_on_qr

## Overview

1. **Overall shape**
   - This repo is split into two independently built apps: an Express/Node backend in `backend/` and a React/Vite frontend in `frontend/`.
   - The system is an employee attendance and HR workflow platform centered on **role-based access** and **server-side attendance validation**.

2. **Backend is the core business/API layer**
   - `backend/server.js` is the composition root: it wires environment config, database connection, middleware, and the route modules.
   - Routes are organized by domain: `auth`, `attendance`, `employee`, `leave`, `document`, `office`, `onboarding`, and `settings`.
   - Controllers implement the business actions, while middleware enforces authentication and role checks.

3. **Identity and authorization boundary**
   - `backend/controllers/authController.js` plus `backend/models/User.js` handle registration/login and JWT issuance.
   - `backend/middlewares/authMiddleware.js` protects authenticated endpoints, and `roleMiddleware.js` separates admin-only flows from employee flows.
   - The frontend mirrors this with `AuthContext.jsx`, which holds the signed-in user/session state and drives route/UI access.

4. **Attendance check-in flow**
   - Attendance is recorded through the `attendance` route/controller and persisted in `backend/models/Attendance.js`.
   - The product’s key security idea is **static QR + IP validation**: the QR code initiates the check-in flow, but the backend decides whether the request is valid based on the employee’s network/IP and office rules.
   - This means the trust boundary is server-side; the QR scanner is just an input mechanism, not the security gate.

5. **Office/network configuration**
   - Office-wide network rules are managed through `backend/models/OfficeConfig.js` and the `office` controller/routes.
   - The README’s flow shows admins creating allowed IP ranges such as localhost or office subnets; those ranges are what attendance validation checks against.
   - This is the main control point for “location” enforcement in the system.

6. **Employee administration**
   - The employee subsystem uses `backend/models/Employee.js` and `employeeController.js` for CRUD-style management.
   - The frontend exposes this as admin screens like `EmployeeList`, `EmployeeDetail`, and `EmployeeForm`.
   - This is clearly an admin-owned lifecycle: create, view, edit, and review employee records.

7. **Leave management**
   - Leave is modeled with a small cluster of entities: `LeaveRequest`, `LeaveBalance`, and `LeaveType`.
   - Admin-facing pages like `LeaveRequests` and `LeaveCalendar` suggest the backend supports both approval workflows and planning/reporting views.
   - The employee-facing side includes `MyLeaves` and `ApplyLeave`, indicating a self-service request flow with admin review.

8. **Document vault and file handling**
   - Document upload/storage is split across `documentController.js`, `Document.js`, `multerConfig.js`, and `cloudinary.js`.
   - The architecture here is: upload through Express/multer, then store or reference files in Cloudinary rather than keeping everything local.
   - Admin and employee document views (`DocumentVault`, `MyDocuments`, `ExpiringDocuments`) imply document lifecycle management, not just raw uploads.

9. **Onboarding and task scheduling**
   - Onboarding has its own domain with `OnboardingTemplate` and `OnboardingInstance` models plus matching routes/controllers.
   - The frontend includes `OnboardingDashboard`, `OnboardingDetail`, and `MyOnboarding`, so this is a full workflow rather than a one-off form.
   - Utilities like `scheduleIncomplete.js`, `seedOnboarding.js`, and `emailService.js` suggest background reminders and notification-driven onboarding progression.

10. **Settings and operational config**
   - `Settings.js` and `settingsController.js` indicate system-level configuration separate from office-specific config.
   - This is likely where defaults, policy values, or feature toggles live, while `OfficeConfig` handles network/location rules.
   - The split matters architecturally: global behavior vs. office-scoped behavior.

11. **Frontend structure**
   - The frontend is organized by audience: admin pages under `src/pages/Admin` and employee pages under `src/pages/Employee`.
   - `AdminLayout.jsx` provides the admin shell/navigation, while `Html5QrScanner.jsx` supports QR capture on the client.
   - `App.jsx` and `main.jsx` are the entry points that stitch routing, auth state, and page composition together.

12. **Frontend-to-backend communication**
   - API calls are centralized in `src/services/*.js` files, which wrap backend domains such as employees, leave, documents, onboarding, and settings.
   - This keeps pages thin: UI components call service modules, and service modules call the backend REST API.
   - The result is a clean boundary between presentation logic and business/API integration.

13. **Persistence and data model layer**
   - The backend uses a model-centric data layer under `backend/models/`, with separate entities for attendance, users, leave, onboarding, settings, office config, and documents.
   - The README mentions Firebase, but the repository structure reads like a conventional Express app with application-owned domain models and a dedicated DB config in `backend/config/db.js`.
   - For architecture diagrams, treat the backend as the system of record for all operational data.

14. **Automation, seeding, and CI**
   - `seed.js`, `fixLeaves.js`, and the utilities under `backend/utils/` support bootstrapping and maintenance tasks.
   - GitHub Actions are split by tier with separate backend and frontend CI workflows, reinforcing the repo’s two-app structure.
   - Deployment hints on the frontend side include `vercel.json`, suggesting the UI can be hosted independently from the API.

15. **Primary end-to-end data flows**
   - Admin signs in → JWT issued → admin configures office IP rules, employees, leave policies, onboarding, and documents.
   - Employee signs in → frontend scans static QR or submits attendance action → backend validates JWT, role, duplicate-day constraints, and IP range → attendance record is stored.
   - Admin and employee dashboards then read back from the same backend models for reporting, history, and workflow progress.

Main entry points: [`backend/server.js`](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/server.js) (Server), [`backend/models`](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/models) (Domain Models), [`frontend/src/App.jsx`](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/App.jsx) (App Shell), [`backend/routes/attendanceRoutes.js`](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/attendanceRoutes.js) (Attendance API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_server["Server<br/>composition root<br/>[server.js]"]
  node_backend_auth_routes["Auth API<br/>route/controller<br/>[authRoutes.js]"]
  node_backend_attendance["Attendance API<br/>validation flow"]
  node_backend_employee["Employee API<br/>admin CRUD<br/>[employeeRoutes.js]"]
  node_backend_leave["Leave API<br/>workflow<br/>[leaveRoutes.js]"]
  node_backend_document["Documents API<br/>upload/storage<br/>[documentRoutes.js]"]
  node_backend_office["Office API<br/>policy config<br/>[officeRoutes.js]"]
  node_backend_onboarding["Onboarding API<br/>workflow"]
  node_backend_settings["Settings API<br/>system config<br/>[settingsRoutes.js]"]
  node_backend_auth_mw(("Auth Guards<br/>middleware<br/>[authMiddleware.js]"))
  node_backend_models[("Domain Models<br/>data model layer")]
  node_backend_config["Runtime Config<br/>integration config"]
  node_backend_utils["Background Jobs<br/>automation"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App Shell<br/>router/bootstrap<br/>[App.jsx]"]
  node_frontend_auth(("Auth Context<br/>session state<br/>[AuthContext.jsx]"))
  node_frontend_layout["UI Shell<br/>layout/components"]
  node_frontend_services["API Clients<br/>service layer"]
  node_frontend_admin["Admin Views<br/>screens"]
  node_frontend_employee["Employee Views<br/>screens"]
  node_frontend_login["Login & Register<br/>entry screens<br/>[Login.jsx]"]
end

subgraph group_ci["Automation"]
  node_ci_backend["Backend CI<br/>automation<br/>[backend-ci.yml]"]
  node_ci_frontend["Frontend CI<br/>automation<br/>[frontend-ci.yml]"]
end

node_backend_server -->|"mounts"| node_backend_auth_routes
node_backend_server -->|"mounts"| node_backend_attendance
node_backend_server -->|"mounts"| node_backend_employee
node_backend_server -->|"mounts"| node_backend_leave
node_backend_server -->|"mounts"| node_backend_document
node_backend_server -->|"mounts"| node_backend_office
node_backend_server -->|"mounts"| node_backend_onboarding
node_backend_server -->|"mounts"| node_backend_settings
node_backend_server -->|"uses"| node_backend_auth_mw
node_backend_server -->|"loads"| node_backend_config
node_backend_server -->|"persists"| node_backend_models
node_backend_server -->|"starts"| node_backend_utils
node_backend_auth_routes -->|"authenticates"| node_backend_models
node_backend_attendance -->|"records"| node_backend_models
node_backend_attendance -->|"checks"| node_backend_office
node_backend_employee -->|"manages"| node_backend_models
node_backend_leave -->|"manages"| node_backend_models
node_backend_document -->|"uploads"| node_backend_config
node_backend_onboarding -->|"notifies"| node_backend_utils
node_frontend_app -->|"reads"| node_frontend_auth
node_frontend_app -->|"composes"| node_frontend_layout
node_frontend_app -->|"calls"| node_frontend_services
node_frontend_login -->|"sets"| node_frontend_auth
node_frontend_admin -->|"calls"| node_frontend_services
node_frontend_employee -->|"calls"| node_frontend_services
node_frontend_layout -->|"supports"| node_frontend_admin
node_frontend_layout -->|"supports"| node_frontend_employee
node_ci_backend -->|"validates"| node_backend_server
node_ci_frontend -->|"validates"| node_frontend_app

click node_backend_server "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/server.js"
click node_backend_auth_routes "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/authRoutes.js"
click node_backend_attendance "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/attendanceRoutes.js"
click node_backend_employee "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/employeeRoutes.js"
click node_backend_leave "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/leaveRoutes.js"
click node_backend_document "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/documentRoutes.js"
click node_backend_office "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/officeRoutes.js"
click node_backend_onboarding "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/onboardingRoutes.js"
click node_backend_settings "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/settingsRoutes.js"
click node_backend_auth_mw "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/middlewares/authMiddleware.js"
click node_backend_models "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/models"
click node_backend_config "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/config"
click node_backend_utils "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/utils"
click node_frontend_app "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/App.jsx"
click node_frontend_auth "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_layout "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/components"
click node_frontend_services "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/services"
click node_frontend_admin "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/pages/Admin"
click node_frontend_employee "https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/pages/Employee"
click node_frontend_login "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/pages/Login.jsx"
click node_ci_backend "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/.github/workflow/backend-ci.yml"
click node_ci_frontend "https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/.github/workflow/frontend-ci.yml"

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_backend_server,node_backend_auth_routes,node_backend_attendance,node_backend_employee,node_backend_leave,node_backend_document,node_backend_office,node_backend_onboarding,node_backend_settings,node_backend_auth_mw,node_backend_models,node_backend_config,node_backend_utils toneBlue
class node_frontend_app,node_frontend_auth,node_frontend_layout,node_frontend_services,node_frontend_admin,node_frontend_employee,node_frontend_login toneAmber
class node_ci_backend,node_ci_frontend toneMint
```

## Components

### Backend

Express/Node API and business rules

- [Server](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/server.js): composition root · Bootstraps the API, database, middleware, and routes. · `backend/server.js`
- [Auth API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/authRoutes.js): route/controller · Login, registration, and session/token issuance. · `backend/routes/authRoutes.js`
- [Attendance API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/attendanceRoutes.js): validation flow · Attendance check-in and server-side IP/office validation. · `backend/routes/attendanceRoutes.js`
- [Employee API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/employeeRoutes.js): admin CRUD · Employee administration endpoints and controller actions. · `backend/routes/employeeRoutes.js`
- [Leave API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/leaveRoutes.js): workflow · Leave requests, balances, and approval-related actions. · `backend/routes/leaveRoutes.js`
- [Documents API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/documentRoutes.js): upload/storage · Document upload, storage references, and lifecycle endpoints. · `backend/routes/documentRoutes.js`
- [Office API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/officeRoutes.js): policy config · Office-scoped network and location rules used for attendance validation. · `backend/routes/officeRoutes.js`
- [Onboarding API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/onboardingRoutes.js): workflow · Onboarding templates, instances, and progress tracking. · `backend/routes/onboardingRoutes.js`
- [Settings API](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/routes/settingsRoutes.js): system config · Global operational settings and policy defaults. · `backend/routes/settingsRoutes.js`
- [Auth Guards](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/backend/middlewares/authMiddleware.js): middleware · JWT authentication and role-based access checks. · `backend/middlewares/authMiddleware.js`
- [Domain Models](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/models): data model layer · User, employee, attendance, leave, onboarding, document, office, and settings records. · `backend/models`
- [Runtime Config](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/config): integration config · Database, Cloudinary, and file upload configuration. · `backend/config`
- [Background Jobs](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/backend/utils): automation · Token generation, email, seeding, and scheduled reminder helpers. · `backend/utils`

### Frontend

React/Vite user interface and API client

- [App Shell](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/App.jsx): router/bootstrap · Frontend entry points and route composition. · `frontend/src/App.jsx`
- [Auth Context](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/context/AuthContext.jsx): session state · Holds the signed-in user and drives UI access. · `frontend/src/context/AuthContext.jsx`
- [UI Shell](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/components): layout/components · Admin layout and QR scanner UI building blocks. · `frontend/src/components`
- [API Clients](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/services): service layer · Centralized frontend wrappers for backend domain APIs. · `frontend/src/services`
- [Admin Views](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/pages/Admin): screens · Employee, leave, document, onboarding, settings, and reporting pages for admins. · `frontend/src/pages/Admin`
- [Employee Views](https://github.com/jawadzafar1045/attandance_system_based_on_qr/tree/main/frontend/src/pages/Employee): screens · Self-service pages for profile, leave, documents, and onboarding. · `frontend/src/pages/Employee`
- [Login & Register](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/frontend/src/pages/Login.jsx): entry screens · Authentication entry pages for users and admins. · `frontend/src/pages/Login.jsx`

### Automation

Build, lint, and maintenance workflows

- [Backend CI](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/.github/workflow/backend-ci.yml): automation · Repository workflow for backend linting and validation. · `.github/workflow/backend-ci.yml`
- [Frontend CI](https://github.com/jawadzafar1045/attandance_system_based_on_qr/blob/main/.github/workflow/frontend-ci.yml): automation · Repository workflow for frontend linting and validation. · `.github/workflow/frontend-ci.yml`

## Connections

- Server → Auth API: mounts · Registers authentication routes on the API.
- Server → Attendance API: mounts · Registers attendance routes on the API.
- Server → Employee API: mounts · Registers employee routes on the API.
- Server → Leave API: mounts · Registers leave routes on the API.
- Server → Documents API: mounts · Registers document routes on the API.
- Server → Office API: mounts · Registers office rules routes on the API.
- Server → Onboarding API: mounts · Registers onboarding routes on the API.
- Server → Settings API: mounts · Registers settings routes on the API.
- Server → Auth Guards: uses · Applies authentication and role checks to protected endpoints.
- Server → Runtime Config: loads · Initializes database and external service config.
- Server → Domain Models: persists · Reads and writes domain state through application models.
- Server → Background Jobs: starts · Enables mail, token, seeding, and scheduling helpers.
- Auth API → Domain Models: authenticates · Uses user and invite records for login and registration.
- Attendance API → Domain Models: records · Stores attendance events and validations.
- Attendance API → Office API: checks · Validates requests against office IP/network rules.
- Employee API → Domain Models: manages · Operates on employee records.
- Leave API → Domain Models: manages · Operates on leave requests, balances, and types.
- Documents API → Runtime Config: uploads · Uses file upload and cloud storage configuration.
- Onboarding API → Background Jobs: notifies · Uses email and scheduled reminder helpers.
- App Shell → Auth Context: reads · Routes and UI state depend on the signed-in session.
- App Shell → UI Shell: composes · Builds the application shell from shared UI pieces.
- App Shell → API Clients: calls · Connects pages to backend API clients.
- Login & Register → Auth Context: sets · Updates session state after authentication.
- Admin Views → API Clients: calls · Uses API clients for admin operations and reporting.
- Employee Views → API Clients: calls · Uses API clients for self-service flows.
- UI Shell → Admin Views: supports · Provides admin navigation and scanner UI for admin flows.
- UI Shell → Employee Views: supports · Supports employee-facing navigation and QR-driven check-in UI.
- Backend CI → Server: validates · Checks backend build and lint health.
- Frontend CI → App Shell: validates · Checks frontend build and lint health.