# mploye/meditech-attendance-payroll-hr architecture

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

- Interactive diagram: https://gitdiagram.com/mploye/meditech-attendance-payroll-hr
- Repository: https://github.com/mploye/meditech-attendance-payroll-hr

## Overview

Genetics Meditech is a multi-tenant HR, attendance, and payroll SaaS. Users work through authenticated Next.js pages, which call a FastAPI API for workforce administration, attendance/device sync, and payroll outputs such as reports and payslips. The backend separates route registration, business services, payroll calculations, persistence models, and eSSL integration; an optional standalone connector uploads device transactions. Some domain routes and services are unsampled, so their documented capabilities are shown without asserting unverified internal calls.

Main entry points: [`backend/app/api/v1/endpoints`](https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/backend/app/api/v1/endpoints) (HR and payroll routes), [`backend/app/api/v1/router.py`](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/router.py) (API routes), [`backend/app/api/v1/endpoints/attendance.py`](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/attendance.py) (Attendance routes), [`backend/connector/sync_worker.py`](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/connector/sync_worker.py) (Device connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_web["HR pages"]
  node_webshell["App shell<br/>[Shell.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
  node_login["Login page<br/>[page.tsx]"]
end

subgraph group_api["API and services"]
  node_entry["FastAPI application<br/>[main.py]"]
  node_routes["API routes<br/>[router.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_attendance_routes["Attendance routes<br/>[attendance.py]"]
  node_domain_routes["HR and payroll routes"]
  node_device_sync["Device sync routes<br/>[device_sync.py]"]
end

subgraph group_domain["HR and payroll domains"]
  node_attendance["Attendance service"]
  node_employees["Employee service"]
  node_payroll["Payroll service<br/>[payroll_service.py]"]
  node_calculator["Payroll calculations<br/>[calculator.py]"]
  node_payslips["Payslip service<br/>[payslip_service.py]"]
  node_reports["Reports service<br/>[report_service.py]"]
  node_models["SQLAlchemy models"]
  node_database[("Relational database")]
end

subgraph group_device["Device synchronization"]
  node_essl["eSSL integration<br/>[service.py]"]
  node_esslclient["eSSL client<br/>[client.py]"]
  node_connector["Device connector<br/>[sync_worker.py]"]
  node_queue["File outbox<br/>[queue.py]"]
end

node_user(("HR user"))
node_device{{"eSSL terminals"}}

node_user -->|"uses"| node_web
node_user -->|"signs in"| node_login
node_web -->|"renders"| node_webshell
node_web -.->|"requests API"| node_apiclient
node_login -.->|"authenticates"| node_apiclient
node_entry -->|"registers"| node_routes
node_routes -->|"routes to"| node_authroutes
node_routes -->|"routes to"| node_attendance_routes
node_routes -->|"registers"| node_domain_routes
node_attendance_routes -->|"calls"| node_attendance
node_attendance_routes -->|"queries"| node_models
node_attendance_routes -->|"uses sync service"| node_device_sync
node_device_sync -.->|"accepts uploads"| node_connector
node_domain_routes -.->|"delegates"| node_employees
node_domain_routes -.->|"delegates"| node_payroll
node_domain_routes -.->|"delegates"| node_payslips
node_domain_routes -.->|"delegates"| node_reports
node_payroll -.->|"calculates with"| node_calculator
node_payslips -->|"reads payroll data"| node_models
node_database -->|"stores"| node_models
node_entry -->|"initializes"| node_database
node_essl -->|"dispatches"| node_esslclient
node_essl -.->|"reads transactions"| node_device
node_connector -->|"polls"| node_device
node_connector -->|"queues records"| node_queue
node_connector -->|"uploads transactions"| node_entry

click node_web "https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/frontend/app/(app)"
click node_webshell "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/components/Shell.tsx"
click node_apiclient "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/lib/api.ts"
click node_login "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/app/login/page.tsx"
click node_entry "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/main.py"
click node_routes "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/router.py"
click node_authroutes "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_attendance_routes "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/attendance.py"
click node_domain_routes "https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/backend/app/api/v1/endpoints"
click node_device_sync "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/device_sync.py"
click node_attendance "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/attendance_service.py"
click node_employees "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/employee_service.py"
click node_payroll "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/payroll_service.py"
click node_calculator "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/payroll/calculator.py"
click node_payslips "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/payslip_service.py"
click node_reports "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/report_service.py"
click node_models "https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/backend/app/models"
click node_essl "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/integrations/essl/service.py"
click node_esslclient "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/integrations/essl/client.py"
click node_connector "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/connector/sync_worker.py"
click node_queue "https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/connector/queue.py"

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,node_webshell,node_apiclient,node_login,node_user toneBlue
class node_entry,node_routes,node_authroutes,node_attendance_routes,node_domain_routes,node_device_sync toneAmber
class node_attendance,node_employees,node_payroll,node_calculator,node_payslips,node_reports,node_models,node_database toneMint
class node_essl,node_esslclient,node_connector,node_queue toneRose
class node_device toneIndigo
```

## Components

### Web application

- [HR pages](https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/frontend/app/(app)): `frontend/app/(app)`
- [App shell](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/components/Shell.tsx): `frontend/components/Shell.tsx`
- [API client](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Login page](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`

### API and services

- [FastAPI application](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication routes](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Attendance routes](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/attendance.py): `backend/app/api/v1/endpoints/attendance.py`
- [HR and payroll routes](https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/backend/app/api/v1/endpoints): `backend/app/api/v1/endpoints`
- [Device sync routes](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/api/v1/endpoints/device_sync.py): `backend/app/api/v1/endpoints/device_sync.py`

### HR and payroll domains

- [Attendance service](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/attendance_service.py): `backend/app/services/attendance_service.py`
- [Employee service](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/employee_service.py): `backend/app/services/employee_service.py`
- [Payroll service](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/payroll_service.py): `backend/app/services/payroll_service.py`
- [Payroll calculations](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/payroll/calculator.py): `backend/app/payroll/calculator.py`
- [Payslip service](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/payslip_service.py): `backend/app/services/payslip_service.py`
- [Reports service](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`
- [SQLAlchemy models](https://github.com/mploye/meditech-attendance-payroll-hr/tree/main/backend/app/models): `backend/app/models`
- **Relational database**

### Device synchronization

- [eSSL integration](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/integrations/essl/service.py): `backend/app/integrations/essl/service.py`
- [eSSL client](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/app/integrations/essl/client.py): `backend/app/integrations/essl/client.py`
- [Device connector](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/connector/sync_worker.py): `backend/connector/sync_worker.py`
- [File outbox](https://github.com/mploye/meditech-attendance-payroll-hr/blob/main/backend/connector/queue.py): `backend/connector/queue.py`

### Other components

- **HR user**
- **eSSL terminals**

## Connections

- HR user → HR pages: uses (evidence: `README.md`)
- HR user → Login page: signs in (evidence: `README.md`)
- HR pages → App shell: renders (evidence: `README.md`)
- HR pages → API client: requests API
- Login page → API client: authenticates
- FastAPI application → API routes: registers (evidence: `backend/app/main.py`)
- API routes → Authentication routes: routes to (evidence: `backend/app/api/v1/router.py`)
- API routes → Attendance routes: routes to (evidence: `backend/app/api/v1/router.py`)
- API routes → HR and payroll routes: registers (evidence: `backend/app/api/v1/router.py`)
- Attendance routes → Attendance service: calls (evidence: `backend/app/api/v1/endpoints/attendance.py`)
- Attendance routes → SQLAlchemy models: queries (evidence: `backend/app/api/v1/endpoints/attendance.py`)
- Attendance routes → Device sync routes: uses sync service (evidence: `backend/app/api/v1/endpoints/attendance.py`)
- Device sync routes → Device connector: accepts uploads
- HR and payroll routes → Employee service: delegates
- HR and payroll routes → Payroll service: delegates
- HR and payroll routes → Payslip service: delegates
- HR and payroll routes → Reports service: delegates
- Payroll service → Payroll calculations: calculates with
- Payslip service → SQLAlchemy models: reads payroll data (evidence: `backend/app/services/payslip_service.py`)
- Relational database → SQLAlchemy models: stores (evidence: `README.md`)
- FastAPI application → Relational database: initializes (evidence: `backend/app/main.py`)
- eSSL integration → eSSL client: dispatches (evidence: `backend/app/integrations/essl/service.py`)
- eSSL integration → eSSL terminals: reads transactions
- Device connector → eSSL terminals: polls (evidence: `backend/connector/sync_worker.py`)
- Device connector → File outbox: queues records (evidence: `backend/connector/sync_worker.py`)
- Device connector → FastAPI application: uploads transactions (evidence: `backend/connector/sync_worker.py`)
