# sinawatra/smarthr-api architecture

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

- Interactive diagram: https://gitdiagram.com/sinawatra/smarthr-api
- Repository: https://github.com/sinawatra/smarthr-api

## Overview

SmartHR is a REST backend for HR administration. Users authenticate, receive JWTs, and call role-protected API endpoints to manage employee records and use attendance, leave, onboarding, evaluation, organisation, announcement, probation, and dashboard features. Sampled source confirms the employee and leave controller-to-service paths, and several service-to-repository interactions; other feature paths are retained from the README but their internal wiring was not sampled. PostgreSQL and the Cloudinary and Telegram integrations are documented external dependencies.

Main entry points: [`src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java`](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java) (Leave requests), [`src/main/java/com/smarthr/smarthr/controller/AuthController.java`](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/AuthController.java) (Authentication), [`src/main/java/com/smarthr/smarthr/service/EmployeeService.java`](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EmployeeService.java) (Employee management), [`src/main/java/com/smarthr/smarthr/controller/EmployeeController.java`](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/EmployeeController.java) (Employee endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and security"]
  node_auth["Authentication"]
  node_jwt["JWT security"]
end

subgraph group_people["People operations"]
  node_employees["Employee management"]
  node_employee_api["Employee endpoints"]
end

subgraph group_workforce["Workforce workflows"]
  node_attendance["Attendance"]
  node_leave_api["Leave endpoints"]
  node_leave["Leave requests"]
  node_onboarding["Onboarding tasks"]
  node_templates["Task templates"]
end

subgraph group_performance["Performance and insights"]
  node_evaluations["Evaluations"]
  node_criteria["Evaluation criteria"]
  node_probation["Probation tracking"]
  node_dashboard["HR dashboard"]
end

subgraph group_communications["Organisation and communications"]
  node_org_setup["Organisation setup"]
  node_announcements["Announcements"]
end

node_caller(("API caller"))
node_cloudinary["Cloudinary"]
node_telegram["Telegram"]
node_database[("PostgreSQL")]

node_caller -->|"authenticates"| node_auth
node_caller -->|"manages employees"| node_employee_api
node_caller -->|"requests leave"| node_leave_api
node_caller -->|"records attendance"| node_attendance
node_caller -->|"updates tasks"| node_onboarding
node_caller -->|"manages templates"| node_templates
node_caller -->|"submits evaluations"| node_evaluations
node_caller -->|"reads criteria"| node_criteria
node_caller -->|"views probation"| node_probation
node_caller -->|"views statistics"| node_dashboard
node_caller -->|"configures organisation"| node_org_setup
node_caller -->|"manages announcements"| node_announcements
node_auth -.->|"issues tokens"| node_jwt
node_employee_api -->|"calls"| node_employees
node_leave_api -->|"calls"| node_leave
node_leave -->|"uploads attachments"| node_cloudinary
node_announcements -->|"pushes announcements"| node_telegram
node_employees -.->|"reads and writes"| node_database
node_leave -.->|"reads and writes"| node_database
node_attendance -.->|"reads and writes"| node_database
node_evaluations -.->|"reads and writes"| node_database
node_dashboard -.->|"aggregates data"| node_database

click node_auth "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/AuthController.java"
click node_jwt "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/security/JwtAuthenticationFilter.java"
click node_employees "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EmployeeService.java"
click node_employee_api "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/EmployeeController.java"
click node_attendance "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/AttendanceService.java"
click node_leave_api "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/LeaveRequestController.java"
click node_leave "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java"
click node_onboarding "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/OnboardingTaskService.java"
click node_templates "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DefaultOnboardingTaskService.java"
click node_evaluations "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EvaluationService.java"
click node_criteria "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EvaluationCriteriaService.java"
click node_probation "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EmployeeService.java"
click node_dashboard "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DashboardService.java"
click node_org_setup "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DepartmentService.java"
click node_announcements "https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/AnnouncementService.java"

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_auth,node_jwt toneBlue
class node_employees,node_employee_api,node_database toneAmber
class node_attendance,node_leave_api,node_leave,node_onboarding,node_templates,node_caller toneMint
class node_evaluations,node_criteria,node_probation,node_dashboard toneRose
class node_org_setup,node_announcements,node_cloudinary,node_telegram toneIndigo
```

## Components

### Access and security

- [Authentication](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/AuthController.java): `src/main/java/com/smarthr/smarthr/controller/AuthController.java`
- [JWT security](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/security/JwtAuthenticationFilter.java): `src/main/java/com/smarthr/smarthr/security/JwtAuthenticationFilter.java`

### People operations

- [Employee management](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EmployeeService.java): `src/main/java/com/smarthr/smarthr/service/EmployeeService.java`
- [Employee endpoints](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/EmployeeController.java): `src/main/java/com/smarthr/smarthr/controller/EmployeeController.java`

### Workforce workflows

- [Attendance](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/AttendanceService.java): `src/main/java/com/smarthr/smarthr/service/AttendanceService.java`
- [Leave endpoints](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/controller/LeaveRequestController.java): `src/main/java/com/smarthr/smarthr/controller/LeaveRequestController.java`
- [Leave requests](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java): `src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java`
- [Onboarding tasks](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/OnboardingTaskService.java): `src/main/java/com/smarthr/smarthr/service/OnboardingTaskService.java`
- [Task templates](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DefaultOnboardingTaskService.java): `src/main/java/com/smarthr/smarthr/service/DefaultOnboardingTaskService.java`

### Performance and insights

- [Evaluations](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EvaluationService.java): `src/main/java/com/smarthr/smarthr/service/EvaluationService.java`
- [Evaluation criteria](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EvaluationCriteriaService.java): `src/main/java/com/smarthr/smarthr/service/EvaluationCriteriaService.java`
- [Probation tracking](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/EmployeeService.java): `src/main/java/com/smarthr/smarthr/service/EmployeeService.java`
- [HR dashboard](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DashboardService.java): `src/main/java/com/smarthr/smarthr/service/DashboardService.java`

### Organisation and communications

- [Organisation setup](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/DepartmentService.java): `src/main/java/com/smarthr/smarthr/service/DepartmentService.java`
- [Announcements](https://github.com/sinawatra/smarthr-api/blob/main/src/main/java/com/smarthr/smarthr/service/AnnouncementService.java): `src/main/java/com/smarthr/smarthr/service/AnnouncementService.java`

### Other components

- **API caller**
- **Cloudinary**
- **Telegram**
- **PostgreSQL**

## Connections

- API caller → Authentication: authenticates (evidence: `README.md`)
- API caller → Employee endpoints: manages employees (evidence: `README.md`)
- API caller → Leave endpoints: requests leave (evidence: `README.md`)
- API caller → Attendance: records attendance (evidence: `README.md`)
- API caller → Onboarding tasks: updates tasks (evidence: `README.md`)
- API caller → Task templates: manages templates (evidence: `README.md`)
- API caller → Evaluations: submits evaluations (evidence: `README.md`)
- API caller → Evaluation criteria: reads criteria (evidence: `README.md`)
- API caller → Probation tracking: views probation (evidence: `README.md`)
- API caller → HR dashboard: views statistics (evidence: `README.md`)
- API caller → Organisation setup: configures organisation (evidence: `README.md`)
- API caller → Announcements: manages announcements (evidence: `README.md`)
- Authentication → JWT security: issues tokens
- Employee endpoints → Employee management: calls (evidence: `src/main/java/com/smarthr/smarthr/controller/EmployeeController.java`)
- Leave endpoints → Leave requests: calls (evidence: `src/main/java/com/smarthr/smarthr/controller/LeaveRequestController.java`)
- Leave requests → Cloudinary: uploads attachments (evidence: `src/main/java/com/smarthr/smarthr/service/LeaveRequestService.java`)
- Announcements → Telegram: pushes announcements (evidence: `README.md`)
- Employee management → PostgreSQL: reads and writes
- Leave requests → PostgreSQL: reads and writes
- Attendance → PostgreSQL: reads and writes
- Evaluations → PostgreSQL: reads and writes
- HR dashboard → PostgreSQL: aggregates data