# jawaid-aziz/attendance-system architecture

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

- Interactive diagram: https://gitdiagram.com/jawaid-aziz/attendance-system
- Repository: https://github.com/jawaid-aziz/attendance-system

## Overview

##### Project type and purpose
- This is a full-stack web application called “Office Attendance System.”
- Purpose: let admins and employees log in, record check-in/check-out, view attendance history, configure office timings and deductions, and enforce time-based salary adjustments.

##### File structure
- Top-level folders:
- client/ – React.js frontend (Tailwind CSS, Vite build)
- server/ – Node.js/Express backend
- Frontend patterns:
- src/Components, src/Pages, src/Context, src/lib, src/hooks → componentized UI with context providers and utility modules
- ProtectedRoutes for auth gating
- Backend patterns (server/):
- Routes/ – Express route definitions grouped by domain (auth, admin, attendance, common)
- controllers/ – route handlers organized by feature (attendanceController, adminController, TimezoneController)
- models/ – Mongoose (presumed) schemas: User.js, Attendance.js
- middleware/ – authMiddleware, authorizeAdmin, validateIP
- config/db.js – database connection setup
- utils/tokenUtils.js – JWT token helpers

##### Key architecture/stack notes from README
- Frontend: React.js + Tailwind CSS + Vite
- Backend: Node.js + Express
- Persistence: likely MongoDB (based on Mongoose-style models)
- Auth: JWT tokens; IP validation; role-based access

##### Main components
a. Frontend Client
- UI Modules (Components & Pages)
- Context Providers (Auth/Role/Theme)
- API Client (lib/api.jsx)
- Routing (React Router + ProtectedRoutes)
b. Backend Server
- API Gateway (Express app in server/index.js)
- Middleware Layer (authMiddleware, authorizeAdmin, validateIP)
- Route Handlers (Routes → controllers)
- Business Logic (controllers: attendance, admin, timezone)
- Data Access (models, config/db.js)
c. Database
- Collections: Users, AttendanceRecords
d. External/Infrastructure Services
- JWT token issuer/validator (tokenUtils)
- Environment config (.env)
- Possible third-party: IP geo-lookup (validateIP)

##### Relationships and data flows
1. User interacts with Frontend UI → triggers API calls via api.jsx
2. Frontend sends HTTP requests (Auth, Attendance, Admin config) → Backend Express
3. Express middleware sequence:
- validateIP → authMiddleware (JWT check) → authorizeAdmin (role check if needed)
4. After passing middleware, request reaches appropriate Route → Controller
5. Controller invokes Model to read/write DB
6. DB returns data → Controller packages JSON response → sent back to Frontend
7. Frontend Context providers store user session or theme preferences

##### Architectural patterns and principles
- Separation of concerns: UI layer vs. API layer vs. Data layer
- MVC-like on server: Routes → Controllers → Models
- Single-page application on client with component tree, hooks, and context
- Role-based access control and IP validation as cross-cutting concerns (middleware)
- Token-based stateless authentication

##### Elements
- Clear labels for each component (e.g., “AttendanceController,” “UserContext”)
- UI → API Client → Express → DB
- Express → Middleware → Controllers → Models → DB
- DB → Express → UI
- Frontend (blue rectangles)
- Backend (green rectangles)
- External/security services (JWT, IP validation) (gray)
- Technology next to each block (e.g., React.js, Node.js/Express, MongoDB)
- Environment/config (.env) feeding into Frontend build & Backend server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Tier
    subgraph "Frontend Client" 
        direction TB
        UIComponents["UI Components"]:::frontend
        Pages["Pages"]:::frontend
        ProtectedRoutes["ProtectedRoutes"]:::frontend
        subgraph "Context Providers" 
            direction TB
            AuthContext["IdProvider.jsx"]:::frontend
            RoleContext["RoleProvider.jsx"]:::frontend
            ThemeContext["theme-provider.jsx"]:::frontend
        end
        APIClient["api.jsx"]:::frontend
        subgraph "Custom Hooks & Data"
            direction TB
            Hooks1["use-mobile.jsx"]:::frontend
            Hooks2["use-toast.js"]:::frontend
            Data1["Timezones.json"]:::frontend
            Data2["UserData.js"]:::frontend
            JWTDecode["Decodejwt.jsx"]:::frontend
            TokenValid["isTokenValid.jsx"]:::frontend
            TokenExpire["tokenExpire.jsx"]:::frontend
        end
    end

    %% Backend Tier
    subgraph "Backend Server" 
        direction TB
        ExpressApp["server/index.js<br/>(Express API Gateway)"]:::backend
        subgraph "Middleware Layer"
            direction TB
            ValidateIP["validateIP.js"]:::backend
            AuthMiddleware["authMiddleware.js"]:::backend
            AuthorizeAdmin["authorizeAdmin.js"]:::backend
        end
        subgraph "Route Definitions"
            direction TB
            AuthRoutes["authRoutes.js"]:::backend
            AttendanceRoutes["attendanceRoutes.js"]:::backend
            AdminRoutes["adminRoutes.js"]:::backend
            CommonRoutes["commonRoutes.js"]:::backend
        end
        subgraph "Controllers (Business Logic)"
            direction TB
            AuthController["authController.js"]:::backend
            CheckIn["checkIn.js"]:::backend
            CheckOut["checkOut.js"]:::backend
            AttendanceStatus["attendanceStatus.js"]:::backend
            AttendanceRecord["attendanceRecord.js"]:::backend
            ServerTime["serverTime.js"]:::backend
            AdminController["adminController.js"]:::backend
            ConfigDeductions["configDeductions.js"]:::backend
            ConfigOfficeTiming["configOfficeTiming.js"]:::backend
            ConfigRouter["configRouter.js"]:::backend
            TimezoneController["Timezone.js"]:::backend
        end
        subgraph "Data Access Layer"
            direction TB
            UserModel["User.js"]:::backend
            AttendanceModel["Attendance.js"]:::backend
            DBConfig["db.js"]:::backend
        end
        TokenUtils["tokenUtils.js"]:::backend
    end

    %% Database Tier
    subgraph "Database (MongoDB)" 
        direction TB
        DB[(Collections)]:::database
        UsersColl["Users"]:::database
        AttendanceColl["AttendanceRecords"]:::database
    end

    %% Data Flows
    UIComponents -->|uses| Pages
    Pages -->|routes via| ProtectedRoutes
    ProtectedRoutes -->|calls| APIClient
    APIClient -->|HTTP/REST| ExpressApp
    AuthContext -->|provides session to| UIComponents
    RoleContext -->|provides roles to| UIComponents
    ThemeContext -->|provides theme to| UIComponents
    Hooks1 -->|utilized by| UIComponents
    Hooks2 -->|utilized by| UIComponents
    Data1 -->|static data to| UIComponents
    Data2 -->|static data to| UIComponents
    JWTDecode -->|utilized by| APIClient
    TokenValid -->|utilized by| APIClient
    TokenExpire -->|utilized by| APIClient

    ExpressApp -->|middleware chain| ValidateIP
    ValidateIP --> AuthMiddleware
    AuthMiddleware --> AuthorizeAdmin
    AuthorizeAdmin --> AuthRoutes
    AuthorizeAdmin --> AttendanceRoutes
    AuthorizeAdmin --> AdminRoutes
    AuthorizeAdmin --> CommonRoutes

    AuthRoutes --> AuthController
    AttendanceRoutes --> CheckIn
    AttendanceRoutes --> CheckOut
    AttendanceRoutes --> AttendanceStatus
    AttendanceRoutes --> AttendanceRecord
    AttendanceRoutes --> ServerTime
    AdminRoutes --> AdminController
    AdminRoutes --> ConfigDeductions
    AdminRoutes --> ConfigOfficeTiming
    AdminRoutes --> ConfigRouter
    CommonRoutes --> TimezoneController

    AuthController --> UserModel
    CheckIn --> AttendanceModel
    CheckOut --> AttendanceModel
    AttendanceStatus --> AttendanceModel
    AttendanceRecord --> AttendanceModel
    ServerTime --> DBConfig
    AdminController --> UserModel
    ConfigDeductions --> DBConfig
    ConfigOfficeTiming --> DBConfig
    ConfigRouter --> DBConfig
    TimezoneController --> DBConfig

    UserModel --> DB
    AttendanceModel --> DB
    DBConfig --> DB
    TokenUtils --> AuthMiddleware
    TokenUtils --> AuthController

    DB -->|data| UserModel
    DB -->|data| AttendanceModel

    %% Click Events - Frontend
    click UIComponents "https://github.com/jawaid-aziz/attendance-system/tree/main/client/src/Components"
    click Pages "https://github.com/jawaid-aziz/attendance-system/tree/main/client/src/Pages"
    click ProtectedRoutes "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Components/ProtectedRoutes.jsx"
    click AuthContext "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Context/IdProvider.jsx"
    click RoleContext "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Context/RoleProvider.jsx"
    click ThemeContext "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Context/theme-provider.jsx"
    click APIClient "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/lib/api.jsx"
    click JWTDecode "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/lib/Decodejwt.jsx"
    click TokenValid "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/lib/isTokenValid.jsx"
    click TokenExpire "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/lib/tokenExpire.jsx"
    click Hooks1 "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/hooks/use-mobile.jsx"
    click Hooks2 "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/hooks/use-toast.js"
    click Data1 "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Data/Timezones.json"
    click Data2 "https://github.com/jawaid-aziz/attendance-system/blob/main/client/src/Data/UserData.js"

    %% Click Events - Backend
    click ExpressApp "https://github.com/jawaid-aziz/attendance-system/blob/main/server/index.js"
    click ValidateIP "https://github.com/jawaid-aziz/attendance-system/blob/main/server/middleware/validateIP.js"
    click AuthMiddleware "https://github.com/jawaid-aziz/attendance-system/blob/main/server/middleware/authMiddleware.js"
    click AuthorizeAdmin "https://github.com/jawaid-aziz/attendance-system/blob/main/server/middleware/authorizeAdmin.js"
    click AuthRoutes "https://github.com/jawaid-aziz/attendance-system/blob/main/server/Routes/authRoutes.js"
    click AttendanceRoutes "https://github.com/jawaid-aziz/attendance-system/blob/main/server/Routes/attendanceRoutes.js"
    click AdminRoutes "https://github.com/jawaid-aziz/attendance-system/blob/main/server/Routes/adminRoutes.js"
    click CommonRoutes "https://github.com/jawaid-aziz/attendance-system/blob/main/server/Routes/commonRoutes.js"
    click AuthController "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/authController.js"
    click CheckIn "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/attendanceController/checkIn.js"
    click CheckOut "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/attendanceController/checkOut.js"
    click AttendanceStatus "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/attendanceController/attendanceStatus.js"
    click AttendanceRecord "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/attendanceController/attendanceRecord.js"
    click ServerTime "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/attendanceController/serverTime.js"
    click AdminController "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/adminController/adminController.js"
    click ConfigDeductions "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/adminController/configDeductions.js"
    click ConfigOfficeTiming "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/adminController/configOfficeTiming.js"
    click ConfigRouter "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/adminController/configRouter.js"
    click TimezoneController "https://github.com/jawaid-aziz/attendance-system/blob/main/server/controllers/TimezoneController/Timezone.js"
    click UserModel "https://github.com/jawaid-aziz/attendance-system/blob/main/server/models/User.js"
    click AttendanceModel "https://github.com/jawaid-aziz/attendance-system/blob/main/server/models/Attendance.js"
    click DBConfig "https://github.com/jawaid-aziz/attendance-system/blob/main/server/config/db.js"
    click TokenUtils "https://github.com/jawaid-aziz/attendance-system/blob/main/server/utils/tokenUtils.js"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef backend fill:#D6FFD6,stroke:#333,stroke-width:1px
    classDef database fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
