# musharafam/payroll-employee-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/musharafam/payroll-employee-management-system
- Repository: https://github.com/musharafam/payroll-employee-management-system

## Overview

This is a Sri Lankan payroll and HR management system: users authenticate, enter a role-protected dashboard, and use it for employee, attendance, payroll, and related HR tasks. The documented attendance workflow uploads NGTimereport spreadsheets for parsing and hour calculations; payroll supports configurable rules and salary processing, while PDF payslips are planned. The graph preserves major frontend and backend capabilities. Several backend handler connections are documented only at a product level, so their internal call and persistence relationships are not asserted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/App.tsx) (Route access), [`backend/routes/routes.go`](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/routes/routes.go) (HTTP routes), [`frontend/src/pages/Login.tsx`](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Login.tsx) (Login), [`frontend/src/pages/Dashboard.tsx`](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Dashboard.tsx) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_login["Login<br/>[Login.tsx]"]
  node_app["Route access<br/>[App.tsx]"]
  node_dashboard["Dashboard shell<br/>[Dashboard.tsx]"]
  node_api_hook["API hook<br/>[useApi.ts]"]
  node_api_client["API client and types<br/>[api.ts]"]
end

subgraph group_backend["Backend API"]
  node_parser["Attendance parsers<br/>[ngtimereport.go]"]
  node_routes["HTTP routes<br/>[routes.go]"]
  node_auth_handler["User sync API<br/>[auth.go]"]
end

subgraph group_hr["HR operations"]
  node_employees_ui["Employee management<br/>[AdminEmployees.tsx]"]
  node_attendance_ui["Attendance management"]
  node_leave_ui["Leave requests"]
  node_holidays_ui["Holiday management<br/>[AdminHolidays.tsx]"]
  node_exits_ui["Exit management"]
  node_performance_ui["Performance reviews"]
  node_disciplinary["Disciplinary records"]
  node_loan["Advance loans<br/>[advance_loan.go]"]
  node_attendance_handler["Attendance API<br/>[attendance.go]"]
  node_leave_handler["Leave API<br/>[leave.go]"]
  node_exit_handler["Exit API<br/>[exit.go]"]
  node_performance_handler["Performance API<br/>[performance.go]"]
end

subgraph group_payroll["Payroll operations"]
  node_payroll_ui["Payroll workspace<br/>[AdminPayroll.tsx]"]
  node_settings_ui["Payroll settings<br/>[AdminSettings.tsx]"]
  node_overview["Payroll overview"]
  node_pdf["Payslip PDF<br/>[pdf.ts]"]
  node_payroll_handler["Payroll calculation API<br/>[payroll.go]"]
  node_settings_handler["Payroll rules API"]
end

subgraph group_platform["Identity and storage"]
  node_middleware["Token middleware<br/>[auth.go]"]
  node_asgardeo_service["Asgardeo verification<br/>[asgardeo.go]"]
  node_database[("GORM database<br/>[database.go]")]
end

node_employee(("Employee or admin"))
node_asgardeo(("Asgardeo identity"))
node_postgres[("PostgreSQL")]

node_employee -->|"signs in"| node_login
node_login -->|"starts SSO"| node_asgardeo
node_login -->|"navigates"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_employees_ui
node_app -->|"routes to"| node_attendance_ui
node_app -->|"routes to"| node_payroll_ui
node_app -->|"routes to"| node_leave_ui
node_app -->|"routes to"| node_holidays_ui
node_app -->|"routes to"| node_exits_ui
node_app -->|"routes to"| node_performance_ui
node_app -->|"routes to"| node_settings_ui
node_app -->|"routes to"| node_overview
node_dashboard -->|"requests through"| node_api_hook
node_api_hook -->|"creates client"| node_api_client
node_dashboard -->|"syncs user"| node_auth_handler
node_api_client -->|"calls REST API"| node_routes
node_routes -.->|"routes requests"| node_auth_handler
node_routes -.->|"routes requests"| node_attendance_handler
node_routes -.->|"routes requests"| node_payroll_handler
node_routes -.->|"routes requests"| node_settings_handler
node_middleware -.->|"verifies tokens"| node_asgardeo_service
node_attendance_handler -.->|"parses upload"| node_parser
node_attendance_ui -->|"uploads timecards"| node_parser
node_employees_ui -->|"manages records"| node_employee
node_payroll_ui -.->|"requests calculation"| node_payroll_handler
node_settings_ui -->|"configures rules"| node_settings_handler
node_payroll_ui -.->|"downloads payslips"| node_pdf
node_overview -.->|"summarizes payroll"| node_payroll_handler
node_database -->|"connects to"| node_postgres

click node_login "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Login.tsx"
click node_app "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Dashboard.tsx"
click node_api_hook "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/hooks/useApi.ts"
click node_api_client "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/lib/api.ts"
click node_employees_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminEmployees.tsx"
click node_attendance_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminAttendance.tsx"
click node_leave_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminLeaveRequests.tsx"
click node_holidays_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminHolidays.tsx"
click node_exits_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminExitManagement.tsx"
click node_performance_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminPerformanceReviews.tsx"
click node_disciplinary "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/DisciplinaryModal.tsx"
click node_loan "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/advance_loan.go"
click node_attendance_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/attendance.go"
click node_leave_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/leave.go"
click node_exit_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/exit.go"
click node_performance_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/performance.go"
click node_payroll_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminPayroll.tsx"
click node_settings_ui "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminSettings.tsx"
click node_overview "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/ManagerOverview.tsx"
click node_pdf "https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/lib/pdf.ts"
click node_payroll_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/payroll.go"
click node_settings_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/payroll_settings.go"
click node_parser "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/parsers/ngtimereport.go"
click node_routes "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/routes/routes.go"
click node_auth_handler "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/auth.go"
click node_middleware "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/middleware/auth.go"
click node_asgardeo_service "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/services/asgardeo.go"
click node_database "https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/database/database.go"

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_login,node_app,node_dashboard,node_api_hook,node_api_client toneBlue
class node_parser,node_routes,node_auth_handler,node_postgres toneAmber
class node_employees_ui,node_attendance_ui,node_leave_ui,node_holidays_ui,node_exits_ui,node_performance_ui,node_disciplinary,node_loan,node_attendance_handler,node_leave_handler,node_exit_handler,node_performance_handler toneMint
class node_payroll_ui,node_settings_ui,node_overview,node_pdf,node_payroll_handler,node_settings_handler toneRose
class node_middleware,node_asgardeo_service,node_database,node_employee,node_asgardeo toneIndigo
```

## Components

### Frontend experience

- [Login](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Login.tsx): `frontend/src/pages/Login.tsx`
- [Route access](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard shell](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [API hook](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/hooks/useApi.ts): `frontend/src/hooks/useApi.ts`
- [API client and types](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend API

- [Attendance parsers](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/parsers/ngtimereport.go): `backend/parsers/ngtimereport.go`
- [HTTP routes](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/routes/routes.go): `backend/routes/routes.go`
- [User sync API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/auth.go): `backend/handlers/auth.go`

### HR operations

- [Employee management](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminEmployees.tsx): `frontend/src/components/AdminEmployees.tsx`
- [Attendance management](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminAttendance.tsx): `frontend/src/components/AdminAttendance.tsx`
- [Leave requests](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminLeaveRequests.tsx): `frontend/src/components/AdminLeaveRequests.tsx`
- [Holiday management](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminHolidays.tsx): `frontend/src/components/AdminHolidays.tsx`
- [Exit management](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminExitManagement.tsx): `frontend/src/components/AdminExitManagement.tsx`
- [Performance reviews](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminPerformanceReviews.tsx): `frontend/src/components/AdminPerformanceReviews.tsx`
- [Disciplinary records](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/DisciplinaryModal.tsx): `frontend/src/components/DisciplinaryModal.tsx`
- [Advance loans](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/advance_loan.go): `backend/handlers/advance_loan.go`
- [Attendance API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/attendance.go): `backend/handlers/attendance.go`
- [Leave API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/leave.go): `backend/handlers/leave.go`
- [Exit API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/exit.go): `backend/handlers/exit.go`
- [Performance API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/performance.go): `backend/handlers/performance.go`

### Payroll operations

- [Payroll workspace](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminPayroll.tsx): `frontend/src/components/AdminPayroll.tsx`
- [Payroll settings](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/AdminSettings.tsx): `frontend/src/components/AdminSettings.tsx`
- [Payroll overview](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/components/ManagerOverview.tsx): `frontend/src/components/ManagerOverview.tsx`
- [Payslip PDF](https://github.com/musharafam/payroll-employee-management-system/blob/main/frontend/src/lib/pdf.ts): `frontend/src/lib/pdf.ts`
- [Payroll calculation API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/payroll.go): `backend/handlers/payroll.go`
- [Payroll rules API](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/handlers/payroll_settings.go): `backend/handlers/payroll_settings.go`

### Identity and storage

- [Token middleware](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/middleware/auth.go): `backend/middleware/auth.go`
- [Asgardeo verification](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/services/asgardeo.go): `backend/services/asgardeo.go`
- [GORM database](https://github.com/musharafam/payroll-employee-management-system/blob/main/backend/database/database.go): `backend/database/database.go`

### Other components

- **Employee or admin**
- **Asgardeo identity**
- **PostgreSQL**

## Connections

- Employee or admin → Login: signs in (evidence: `frontend/src/pages/Login.tsx`)
- Login → Asgardeo identity: starts SSO (evidence: `frontend/src/pages/Login.tsx`)
- Login → Route access: navigates (evidence: `frontend/src/pages/Login.tsx`)
- Route access → Dashboard shell: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Employee management: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Attendance management: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Payroll workspace: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Leave requests: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Holiday management: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Exit management: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Performance reviews: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Payroll settings: routes to (evidence: `frontend/src/App.tsx`)
- Route access → Payroll overview: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard shell → API hook: requests through (evidence: `frontend/src/pages/Dashboard.tsx`)
- API hook → API client and types: creates client (evidence: `frontend/src/hooks/useApi.ts`)
- Dashboard shell → User sync API: syncs user (evidence: `frontend/src/pages/Dashboard.tsx`)
- API client and types → HTTP routes: calls REST API (evidence: `README.md`)
- HTTP routes → User sync API: routes requests
- HTTP routes → Attendance API: routes requests
- HTTP routes → Payroll calculation API: routes requests
- HTTP routes → Payroll rules API: routes requests
- Token middleware → Asgardeo verification: verifies tokens
- Attendance API → Attendance parsers: parses upload
- Attendance management → Attendance parsers: uploads timecards (evidence: `README.md`)
- Employee management → Employee or admin: manages records (evidence: `README.md`)
- Payroll workspace → Payroll calculation API: requests calculation
- Payroll settings → Payroll rules API: configures rules (evidence: `README.md`)
- Payroll workspace → Payslip PDF: downloads payslips
- Payroll overview → Payroll calculation API: summarizes payroll
- GORM database → PostgreSQL: connects to (evidence: `README.md`)
