# wesleysamuvel/smart-mangement-system architecture

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

- Interactive diagram: https://gitdiagram.com/wesleysamuvel/smart-mangement-system
- Repository: https://github.com/wesleysamuvel/smart-mangement-system

## Overview

Smart Attendance Management System is a role-based attendance, workforce, and payroll application with AI-assisted analysis. Users enter through the web app, use role dashboards and management screens, and perform attendance, employee, payroll, and analytics tasks; documented AI tools add chat, predictions, insights, and payroll optimization. The source evidence confirms biometric routes invoke AI and Firestore, and several API routes use the shared database layer. Many UI-to-API connections and unsampled feature implementations are documented only at the README level, so they are represented without asserting unverified calls.

Main entry points: [`src/lib/db.ts`](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/db.ts) (Application database), [`src/components/dashboard`](https://github.com/wesleysamuvel/smart-mangement-system/tree/master/src/components/dashboard) (Role dashboards), [`src/lib/ai/deepseek.ts`](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/ai/deepseek.ts) (AI model client), [`src/app/api/biometric/route.ts`](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/biometric/route.ts) (Biometric verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and dashboards"]
  node_webapp["Web application<br/>[page.tsx]"]
  node_role_dashboards["Role dashboards"]
  node_authentication["Authentication<br/>[AuthContext.tsx]"]
end

subgraph group_workforce["Workforce operations"]
  node_employee_management["Employee management<br/>[route.ts]"]
  node_attendance["Attendance tracking<br/>[route.ts]"]
  node_biometric["Biometric verification<br/>[route.ts]"]
  node_face_voice["Face and voice scans<br/>[route.ts]"]
  node_location["Geofence and location<br/>[route.ts]"]
  node_payroll["Payroll management"]
  node_payroll_api["Payroll calculations<br/>[route.ts]"]
  node_timetable["Timetable management"]
  node_pdf["PDF reports<br/>[route.ts]"]
end

subgraph group_insights["AI and analytics"]
  node_ai_assistant["Assistant and commands<br/>[route.ts]"]
  node_ai_commands["Natural-language commands<br/>[route.ts]"]
  node_ai_service["AI model client<br/>[deepseek.ts]"]
  node_analytics["Analytics and insights<br/>[route.ts]"]
  node_ai_predictions["Predictions and optimization"]
end

subgraph group_platform["Runtime services"]
  node_database[("Application database<br/>[db.ts]")]
  node_firebase[("Firestore client<br/>[firebase-admin.ts]")]
  node_security["Security services<br/>[jwt.ts]"]
end

subgraph group_realtime["Realtime"]
  node_realtime_client["Realtime service<br/>[socket.ts]"]
  node_realtime_hook["Realtime hook<br/>[useRealtime.ts]"]
  node_socket_server["Socket server<br/>[server.ts]"]
end

node_user(("Workforce user"))
node_openrouter["OpenRouter service"]

node_user -->|"opens"| node_webapp
node_webapp -.->|"presents"| node_role_dashboards
node_role_dashboards -.->|"uses access"| node_authentication
node_role_dashboards -.->|"manages staff"| node_employee_management
node_role_dashboards -.->|"records attendance"| node_attendance
node_role_dashboards -.->|"manages payroll"| node_payroll
node_role_dashboards -.->|"views metrics"| node_analytics
node_attendance -->|"reads and writes"| node_database
node_biometric -->|"reads and writes"| node_database
node_biometric -->|"verifies with"| node_ai_service
node_face_voice -->|"reads and writes"| node_database
node_face_voice -->|"analyzes scans"| node_ai_service
node_location -->|"reads and writes"| node_database
node_payroll_api -->|"reads and writes"| node_database
node_analytics -->|"queries metrics"| node_database
node_ai_assistant -->|"queries records"| node_database
node_ai_commands -->|"queries records"| node_database
node_ai_commands -->|"dispatches prompts"| node_ai_service
node_ai_service -->|"sends requests"| node_openrouter
node_payroll -.->|"manages via"| node_payroll_api
node_ai_predictions -.->|"uses data"| node_database
node_pdf -.->|"provides reports"| node_user
node_realtime_hook -->|"subscribes"| node_realtime_client
node_socket_server -.->|"serves realtime"| node_realtime_client
node_database -->|"delegates Firestore"| node_firebase

click node_webapp "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/page.tsx"
click node_role_dashboards "https://github.com/wesleysamuvel/smart-mangement-system/tree/master/src/components/dashboard"
click node_authentication "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/contexts/AuthContext.tsx"
click node_employee_management "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/employees/route.ts"
click node_attendance "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/attendance/route.ts"
click node_biometric "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/biometric/route.ts"
click node_face_voice "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/face/route.ts"
click node_location "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/location/route.ts"
click node_payroll "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/components/payroll/PayrollManagement.tsx"
click node_payroll_api "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/payroll/route.ts"
click node_timetable "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/components/timetable/TimetableManager.tsx"
click node_ai_assistant "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/ai/chat/route.ts"
click node_ai_commands "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/ai/command/route.ts"
click node_ai_service "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/ai/deepseek.ts"
click node_analytics "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/analytics/route.ts"
click node_ai_predictions "https://github.com/wesleysamuvel/smart-mangement-system/tree/master/src/app/api/ai"
click node_pdf "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/pdf/editor/route.ts"
click node_database "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/db.ts"
click node_firebase "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/firebase-admin.ts"
click node_security "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/auth/jwt.ts"
click node_realtime_client "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/realtime/socket.ts"
click node_realtime_hook "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/hooks/useRealtime.ts"
click node_socket_server "https://github.com/wesleysamuvel/smart-mangement-system/blob/master/server.ts"

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_webapp,node_role_dashboards,node_authentication,node_user toneBlue
class node_employee_management,node_attendance,node_biometric,node_face_voice,node_location,node_payroll,node_payroll_api,node_timetable,node_pdf toneAmber
class node_ai_assistant,node_ai_commands,node_ai_service,node_analytics,node_ai_predictions,node_openrouter toneMint
class node_database,node_firebase,node_security toneRose
class node_realtime_client,node_realtime_hook,node_socket_server toneIndigo
```

## Components

### Access and dashboards

- [Web application](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [Role dashboards](https://github.com/wesleysamuvel/smart-mangement-system/tree/master/src/components/dashboard): `src/components/dashboard`
- [Authentication](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/contexts/AuthContext.tsx): `src/contexts/AuthContext.tsx`

### Workforce operations

- [Employee management](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/employees/route.ts): `src/app/api/employees/route.ts`
- [Attendance tracking](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/attendance/route.ts): `src/app/api/attendance/route.ts`
- [Biometric verification](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/biometric/route.ts): `src/app/api/biometric/route.ts`
- [Face and voice scans](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/face/route.ts): `src/app/api/face/route.ts`
- [Geofence and location](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/location/route.ts): `src/app/api/location/route.ts`
- [Payroll management](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/components/payroll/PayrollManagement.tsx): `src/components/payroll/PayrollManagement.tsx`
- [Payroll calculations](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/payroll/route.ts): `src/app/api/payroll/route.ts`
- [Timetable management](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/components/timetable/TimetableManager.tsx): `src/components/timetable/TimetableManager.tsx`
- [PDF reports](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/pdf/editor/route.ts): `src/app/api/pdf/editor/route.ts`

### AI and analytics

- [Assistant and commands](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/ai/chat/route.ts): `src/app/api/ai/chat/route.ts`
- [Natural-language commands](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/ai/command/route.ts): `src/app/api/ai/command/route.ts`
- [AI model client](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/ai/deepseek.ts): `src/lib/ai/deepseek.ts`
- [Analytics and insights](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/app/api/analytics/route.ts): `src/app/api/analytics/route.ts`
- [Predictions and optimization](https://github.com/wesleysamuvel/smart-mangement-system/tree/master/src/app/api/ai): `src/app/api/ai`

### Runtime services

- [Application database](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/db.ts): `src/lib/db.ts`
- [Firestore client](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/firebase-admin.ts): `src/lib/firebase-admin.ts`
- [Security services](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/auth/jwt.ts): `src/lib/auth/jwt.ts`

### Realtime

- [Realtime service](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/lib/realtime/socket.ts): `src/lib/realtime/socket.ts`
- [Realtime hook](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/src/hooks/useRealtime.ts): `src/hooks/useRealtime.ts`
- [Socket server](https://github.com/wesleysamuvel/smart-mangement-system/blob/master/server.ts): `server.ts`

### Other components

- **Workforce user**
- **OpenRouter service**

## Connections

- Workforce user → Web application: opens (evidence: `README.md`)
- Web application → Role dashboards: presents
- Role dashboards → Authentication: uses access
- Role dashboards → Employee management: manages staff
- Role dashboards → Attendance tracking: records attendance
- Role dashboards → Payroll management: manages payroll
- Role dashboards → Analytics and insights: views metrics
- Attendance tracking → Application database: reads and writes (evidence: `src/app/api/attendance/route.ts`)
- Biometric verification → Application database: reads and writes (evidence: `src/app/api/biometric/route.ts`)
- Biometric verification → AI model client: verifies with (evidence: `src/app/api/biometric/route.ts`)
- Face and voice scans → Application database: reads and writes (evidence: `src/app/api/face/route.ts`)
- Face and voice scans → AI model client: analyzes scans (evidence: `src/app/api/face/route.ts`)
- Geofence and location → Application database: reads and writes (evidence: `src/app/api/location/route.ts`)
- Payroll calculations → Application database: reads and writes (evidence: `src/app/api/payroll/route.ts`)
- Analytics and insights → Application database: queries metrics (evidence: `src/app/api/analytics/route.ts`)
- Assistant and commands → Application database: queries records (evidence: `src/app/api/ai/chat/route.ts`)
- Natural-language commands → Application database: queries records (evidence: `src/app/api/ai/command/route.ts`)
- Natural-language commands → AI model client: dispatches prompts (evidence: `src/app/api/ai/command/route.ts`)
- AI model client → OpenRouter service: sends requests (evidence: `src/lib/ai/deepseek.ts`)
- Payroll management → Payroll calculations: manages via
- Predictions and optimization → Application database: uses data (evidence: `src/app/api/ai/command/route.ts`)
- PDF reports → Workforce user: provides reports
- Realtime hook → Realtime service: subscribes (evidence: `src/hooks/useRealtime.ts`)
- Socket server → Realtime service: serves realtime
- Application database → Firestore client: delegates Firestore (evidence: `src/lib/db.ts`)
