# codewithcrafter/buzzspireworkhub architecture

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

- Interactive diagram: https://gitdiagram.com/codewithcrafter/buzzspireworkhub
- Repository: https://github.com/codewithcrafter/buzzspireworkhub

## Overview

This repository is a workforce-management and HR web application: employees and administrators use its Next.js interface for attendance, staff records, leave, payroll, reporting, and administration. A key operational path is attendance capture and recalculation: the product includes employee attendance endpoints and a desktop agent, while the sampled HR engine delegates metric calculation to the working-hours service and persists the result. The tree shows additional payroll, activity-monitoring, and browser-extension capabilities. Because their implementation excerpts were not provided, the graph omits uncertain wiring between those components.

Main entry points: [`src/app/api/employees/route.ts`](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/employees/route.ts) (Employee API), [`src/services/hr-engine.service.ts`](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/hr-engine.service.ts) (HR recalculation), [`src/app/(dashboard)/my-history/page.tsx`](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/my-history/page.tsx) (Employee pages), [`src/app/(dashboard)/employees/page.tsx`](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/employees/page.tsx) (Admin pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_app["Web application<br/>[layout.tsx]"]
  node_employee_pages["Employee pages<br/>[page.tsx]"]
  node_admin_pages["Admin pages<br/>[page.tsx]"]
  node_login["Login pages<br/>[page.tsx]"]
end

subgraph group_workforce["Workforce operations"]
  node_employee_api["Employee API<br/>[route.ts]"]
  node_attendance_api["Attendance API<br/>[route.ts]"]
  node_leave_api["Leave API<br/>[route.ts]"]
  node_payroll_api["Payroll API<br/>[route.ts]"]
  node_employee_service["Employee service"]
  node_hr_engine["HR recalculation"]
  node_working_hours["Working-hours metrics"]
end

subgraph group_insight["Activity and insight"]
  node_reports["Reports<br/>[report.service.ts]"]
  node_timeline["Activity timeline"]
end

subgraph group_foundation["Identity and data"]
  node_auth["Authentication<br/>[permissions.ts]"]
  node_database[("Application database<br/>[prisma.ts]")]
end

subgraph group_capture["Activity capture"]
  node_agent["Desktop agent<br/>[agent_main.py]"]
  node_agent_queue["Local event queue<br/>[agent_storage.py]"]
  node_extension["Browser extension<br/>[worker.ts]"]
end

node_employee(("Employee"))
node_hr_admin(("HR / Admin"))

node_employee -->|"signs in"| node_login
node_hr_admin -->|"signs in"| node_login
node_employee -->|"uses"| node_employee_pages
node_hr_admin -->|"uses"| node_admin_pages
node_employee_pages -->|"renders within"| node_web_app
node_admin_pages -->|"renders within"| node_web_app
node_employee_api -->|"checks session"| node_auth
node_employee_api -->|"calls"| node_employee_service
node_employee_service -->|"reads / writes"| node_database
node_hr_engine -->|"delegates calculation"| node_working_hours
node_hr_engine -->|"reads / updates"| node_database
node_agent -->|"queues events"| node_agent_queue
node_employee -->|"submits attendance"| node_attendance_api

click node_web_app "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/layout.tsx"
click node_employee_pages "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/my-history/page.tsx"
click node_admin_pages "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/employees/page.tsx"
click node_login "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(auth)/login/page.tsx"
click node_employee_api "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/employees/route.ts"
click node_attendance_api "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/attendance/punch-in/route.ts"
click node_leave_api "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/leaves/route.ts"
click node_payroll_api "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/payroll/run/route.ts"
click node_employee_service "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/employee.service.ts"
click node_hr_engine "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/hr-engine.service.ts"
click node_working_hours "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/working-hours.service.ts"
click node_reports "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/report.service.ts"
click node_timeline "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/timeline.service.ts"
click node_agent "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-agent/agent_main.py"
click node_agent_queue "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-agent/agent_storage.py"
click node_extension "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-browser-extension/src/background/worker.ts"
click node_auth "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/lib/auth/permissions.ts"
click node_database "https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/lib/prisma.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_web_app,node_employee_pages,node_admin_pages,node_login toneBlue
class node_employee_api,node_attendance_api,node_leave_api,node_payroll_api,node_employee_service,node_hr_engine,node_working_hours toneAmber
class node_reports,node_timeline toneMint
class node_auth,node_database toneRose
class node_agent,node_agent_queue,node_extension,node_employee,node_hr_admin toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/layout.tsx): `src/app/(dashboard)/layout.tsx`
- [Employee pages](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/my-history/page.tsx): `src/app/(dashboard)/my-history/page.tsx`
- [Admin pages](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(dashboard)/employees/page.tsx): `src/app/(dashboard)/employees/page.tsx`
- [Login pages](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`

### Workforce operations

- [Employee API](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/employees/route.ts): `src/app/api/employees/route.ts`
- [Attendance API](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/attendance/punch-in/route.ts): `src/app/api/attendance/punch-in/route.ts`
- [Leave API](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/leaves/route.ts): `src/app/api/leaves/route.ts`
- [Payroll API](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/app/api/payroll/run/route.ts): `src/app/api/payroll/run/route.ts`
- [Employee service](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/employee.service.ts): `src/services/employee.service.ts`
- [HR recalculation](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/hr-engine.service.ts): `src/services/hr-engine.service.ts`
- [Working-hours metrics](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/working-hours.service.ts): `src/services/working-hours.service.ts`

### Activity and insight

- [Reports](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/report.service.ts): `src/services/report.service.ts`
- [Activity timeline](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/services/timeline.service.ts): `src/services/timeline.service.ts`

### Identity and data

- [Authentication](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/lib/auth/permissions.ts): `src/lib/auth/permissions.ts`
- [Application database](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`

### Activity capture

- [Desktop agent](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-agent/agent_main.py): `workhub-agent/agent_main.py`
- [Local event queue](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-agent/agent_storage.py): `workhub-agent/agent_storage.py`
- [Browser extension](https://github.com/codewithcrafter/buzzspireworkhub/blob/main/workhub-browser-extension/src/background/worker.ts): `workhub-browser-extension/src/background/worker.ts`

### Other components

- **Employee**
- **HR / Admin**

## Connections

- Employee → Login pages: signs in
- HR / Admin → Login pages: signs in
- Employee → Employee pages: uses
- HR / Admin → Admin pages: uses
- Employee pages → Web application: renders within
- Admin pages → Web application: renders within
- Employee API → Authentication: checks session
- Employee API → Employee service: calls
- Employee service → Application database: reads / writes
- HR recalculation → Working-hours metrics: delegates calculation
- HR recalculation → Application database: reads / updates
- Desktop agent → Local event queue: queues events
- Employee → Attendance API: submits attendance