# mettlebyte-technologies/workhub architecture

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

- Interactive diagram: https://gitdiagram.com/mettlebyte-technologies/workhub
- Repository: https://github.com/mettlebyte-technologies/workhub

## Overview

This is a workforce-management application with a React frontend and a TypeScript backend. Users authenticate and reach role/onboarding-guarded screens, then manage employees, leave and attendance, projects and work logs, and payroll and finance. Backend controllers delegate to domain services; indexed references show several services using repositories, while payroll also generates downloadable exports. Frontend-to-backend HTTP wiring and server route registration were not shown, so those links are marked unverified rather than asserted.

Main entry points: [`frontend/src/app`](https://github.com/mettlebyte-technologies/workhub/tree/main/frontend/src/app) (Product screens), [`backend/src/modules/employees/employee.service.ts`](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.service.ts) (Employee service), [`frontend/src/App.tsx`](https://github.com/mettlebyte-technologies/workhub/blob/main/frontend/src/App.tsx) (Route guards), [`backend/src/modules/payroll/payroll.controller.ts`](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll/payroll.controller.ts) (Payroll controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["Route guards<br/>[App.tsx]"]
  node_screens["Product screens"]
  node_auth_ui["Auth state<br/>[use-auth.ts]"]
end

subgraph group_workforce["Identity and workforce"]
  node_auth_api["Auth controller<br/>[auth.service.ts]"]
  node_auth_store[("Auth repository<br/>[auth.repository.ts]")]
  node_employee_api["Employee controller"]
  node_employee_logic["Employee service"]
  node_employee_store[("Employee repository")]
  node_file_logic["File service<br/>[file.service.ts]"]
end

subgraph group_operations["Time and projects"]
  node_attendance["Attendance service"]
  node_holiday_api["Holiday controller"]
  node_holiday_logic["Holiday service<br/>[holiday.service.ts]"]
  node_holiday_store[("Holiday repository")]
  node_leave_api["Leave controller"]
  node_leave_logic["Leave service<br/>[leave.service.ts]"]
  node_adjustment["Leave adjustments"]
  node_project_api["Project controller"]
  node_project_logic["Project service<br/>[project.service.ts]"]
  node_tasks["Task service<br/>[task.service.ts]"]
  node_worklogs["Work-log service"]
end

subgraph group_compensation["Payroll and finance"]
  node_payroll_api["Payroll controller"]
  node_payroll_logic["Payroll service<br/>[payroll.service.ts]"]
  node_excel["Excel builder"]
  node_finance_api["Finance controller"]
  node_finance_logic["Finance service<br/>[finance.service.ts]"]
  node_slips["Payroll slips"]
  node_salary_components["Salary components"]
end

node_user(("Employee or admin"))

node_user -->|"uses"| node_app
node_app -->|"checks auth"| node_auth_ui
node_app -->|"routes to"| node_screens
node_user -.->|"manages workforce"| node_screens
node_screens -.->|"requests auth"| node_auth_api
node_screens -.->|"requests employee data"| node_employee_api
node_screens -.->|"requests attendance"| node_attendance
node_screens -.->|"requests holidays"| node_holiday_api
node_screens -.->|"requests leave"| node_leave_api
node_screens -.->|"requests adjustments"| node_adjustment
node_screens -.->|"requests projects"| node_project_api
node_screens -.->|"requests tasks"| node_tasks
node_screens -.->|"requests work logs"| node_worklogs
node_screens -.->|"requests payroll"| node_payroll_api
node_screens -.->|"requests finance"| node_finance_api
node_screens -.->|"requests payslips"| node_slips
node_screens -.->|"requests components"| node_salary_components
node_auth_api -->|"queries"| node_auth_store
node_employee_api -->|"delegates to"| node_employee_logic
node_employee_logic -->|"uses"| node_employee_store
node_employee_logic -->|"uses"| node_auth_store
node_employee_logic -->|"uses"| node_file_logic
node_attendance -.->|"uses"| node_employee_logic
node_holiday_api -->|"delegates to"| node_holiday_logic
node_holiday_logic -->|"uses"| node_holiday_store
node_leave_api -->|"delegates to"| node_leave_logic
node_leave_logic -.->|"uses"| node_employee_logic
node_project_api -->|"delegates to"| node_project_logic
node_tasks -.->|"uses"| node_project_logic
node_worklogs -.->|"uses"| node_project_logic
node_payroll_api -->|"delegates to"| node_payroll_logic
node_payroll_api -->|"builds exports"| node_excel
node_finance_api -->|"delegates to"| node_finance_logic
node_finance_logic -->|"uses"| node_employee_store

click node_app "https://github.com/mettlebyte-technologies/workhub/blob/main/frontend/src/App.tsx"
click node_screens "https://github.com/mettlebyte-technologies/workhub/tree/main/frontend/src/app"
click node_auth_ui "https://github.com/mettlebyte-technologies/workhub/blob/main/frontend/src/hooks/use-auth.ts"
click node_auth_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/auth/auth.service.ts"
click node_auth_store "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/auth/auth.repository.ts"
click node_employee_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.controller.ts"
click node_employee_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.service.ts"
click node_employee_store "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.repository.ts"
click node_file_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/files/file.service.ts"
click node_attendance "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/attendance/attendance.service.ts"
click node_holiday_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.controller.ts"
click node_holiday_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.service.ts"
click node_holiday_store "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.repository.ts"
click node_leave_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leaves/leave.controller.ts"
click node_leave_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leaves/leave.service.ts"
click node_adjustment "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leave-adjustment/leave-adjustment.service.ts"
click node_project_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/projects/project.controller.ts"
click node_project_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/projects/project.service.ts"
click node_tasks "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/tasks/task.service.ts"
click node_worklogs "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/work-logs/work-log.service.ts"
click node_payroll_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll/payroll.controller.ts"
click node_payroll_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll/payroll.service.ts"
click node_excel "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/shared/file-generation/excel-builder.service.ts"
click node_finance_api "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/finance/finance.controller.ts"
click node_finance_logic "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/finance/finance.service.ts"
click node_slips "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll-slips/payroll-slip.service.ts"
click node_salary_components "https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/salary-component/salary-component.service.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_app,node_screens,node_auth_ui toneBlue
class node_auth_api,node_auth_store,node_employee_api,node_employee_logic,node_employee_store,node_file_logic toneAmber
class node_attendance,node_holiday_api,node_holiday_logic,node_holiday_store,node_leave_api,node_leave_logic,node_adjustment,node_project_api,node_project_logic,node_tasks,node_worklogs toneMint
class node_payroll_api,node_payroll_logic,node_excel,node_finance_api,node_finance_logic,node_slips,node_salary_components toneRose
class node_user toneIndigo
```

## Components

### Web application

- [Route guards](https://github.com/mettlebyte-technologies/workhub/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Product screens](https://github.com/mettlebyte-technologies/workhub/tree/main/frontend/src/app): `frontend/src/app`
- [Auth state](https://github.com/mettlebyte-technologies/workhub/blob/main/frontend/src/hooks/use-auth.ts): `frontend/src/hooks/use-auth.ts`

### Identity and workforce

- [Auth controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`
- [Auth repository](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/auth/auth.repository.ts): `backend/src/modules/auth/auth.repository.ts`
- [Employee controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.controller.ts): `backend/src/modules/employees/employee.controller.ts`
- [Employee service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.service.ts): `backend/src/modules/employees/employee.service.ts`
- [Employee repository](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/employees/employee.repository.ts): `backend/src/modules/employees/employee.repository.ts`
- [File service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/files/file.service.ts): `backend/src/modules/files/file.service.ts`

### Time and projects

- [Attendance service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/attendance/attendance.service.ts): `backend/src/modules/attendance/attendance.service.ts`
- [Holiday controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.controller.ts): `backend/src/modules/holidays/holiday.controller.ts`
- [Holiday service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.service.ts): `backend/src/modules/holidays/holiday.service.ts`
- [Holiday repository](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/holidays/holiday.repository.ts): `backend/src/modules/holidays/holiday.repository.ts`
- [Leave controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leaves/leave.controller.ts): `backend/src/modules/leaves/leave.controller.ts`
- [Leave service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leaves/leave.service.ts): `backend/src/modules/leaves/leave.service.ts`
- [Leave adjustments](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/leave-adjustment/leave-adjustment.service.ts): `backend/src/modules/leave-adjustment/leave-adjustment.service.ts`
- [Project controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/projects/project.controller.ts): `backend/src/modules/projects/project.controller.ts`
- [Project service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/projects/project.service.ts): `backend/src/modules/projects/project.service.ts`
- [Task service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/tasks/task.service.ts): `backend/src/modules/tasks/task.service.ts`
- [Work-log service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/work-logs/work-log.service.ts): `backend/src/modules/work-logs/work-log.service.ts`

### Payroll and finance

- [Payroll controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll/payroll.controller.ts): `backend/src/modules/payroll/payroll.controller.ts`
- [Payroll service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll/payroll.service.ts): `backend/src/modules/payroll/payroll.service.ts`
- [Excel builder](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/shared/file-generation/excel-builder.service.ts): `backend/src/shared/file-generation/excel-builder.service.ts`
- [Finance controller](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/finance/finance.controller.ts): `backend/src/modules/finance/finance.controller.ts`
- [Finance service](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/finance/finance.service.ts): `backend/src/modules/finance/finance.service.ts`
- [Payroll slips](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/payroll-slips/payroll-slip.service.ts): `backend/src/modules/payroll-slips/payroll-slip.service.ts`
- [Salary components](https://github.com/mettlebyte-technologies/workhub/blob/main/backend/src/modules/salary-component/salary-component.service.ts): `backend/src/modules/salary-component/salary-component.service.ts`

### Other components

- **Employee or admin**

## Connections

- Employee or admin → Route guards: uses (evidence: `frontend/src/App.tsx`)
- Route guards → Auth state: checks auth (evidence: `frontend/src/App.tsx`)
- Route guards → Product screens: routes to (evidence: `frontend/src/App.tsx`)
- Employee or admin → Product screens: manages workforce
- Product screens → Auth controller: requests auth
- Product screens → Employee controller: requests employee data
- Product screens → Attendance service: requests attendance
- Product screens → Holiday controller: requests holidays
- Product screens → Leave controller: requests leave
- Product screens → Leave adjustments: requests adjustments
- Product screens → Project controller: requests projects
- Product screens → Task service: requests tasks
- Product screens → Work-log service: requests work logs
- Product screens → Payroll controller: requests payroll
- Product screens → Finance controller: requests finance
- Product screens → Payroll slips: requests payslips
- Product screens → Salary components: requests components
- Auth controller → Auth repository: queries (evidence: `backend/src/modules/auth/auth.service.ts`)
- Employee controller → Employee service: delegates to (evidence: `backend/src/modules/employees/employee.controller.ts`)
- Employee service → Employee repository: uses (evidence: `backend/src/modules/employees/employee.service.ts`)
- Employee service → Auth repository: uses (evidence: `backend/src/modules/employees/employee.service.ts`)
- Employee service → File service: uses (evidence: `backend/src/modules/employees/employee.service.ts`)
- Attendance service → Employee service: uses
- Holiday controller → Holiday service: delegates to (evidence: `backend/src/modules/holidays/holiday.controller.ts`)
- Holiday service → Holiday repository: uses (evidence: `backend/src/modules/holidays/holiday.service.ts`)
- Leave controller → Leave service: delegates to (evidence: `backend/src/modules/leaves/leave.controller.ts`)
- Leave service → Employee service: uses
- Project controller → Project service: delegates to (evidence: `backend/src/modules/projects/project.controller.ts`)
- Task service → Project service: uses
- Work-log service → Project service: uses
- Payroll controller → Payroll service: delegates to (evidence: `backend/src/modules/payroll/payroll.controller.ts`)
- Payroll controller → Excel builder: builds exports (evidence: `backend/src/modules/payroll/payroll.controller.ts`)
- Finance controller → Finance service: delegates to (evidence: `backend/src/modules/finance/finance.controller.ts`)
- Finance service → Employee repository: uses (evidence: `backend/src/modules/finance/finance.service.ts`)
