# lamdayne/humify architecture

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

- Interactive diagram: https://gitdiagram.com/lamdayne/humify
- Repository: https://github.com/lamdayne/humify

## Overview

Humify is a multi-tenant HR and workforce-management backend. Its user-facing workflow centers on authenticated company users managing employees and organizational records, then handling attendance, leave, payroll, and performance reviews. The tree also exposes project/task management, media uploads, and mail capabilities. The supplied excerpts show the performance-review controller delegating review operations and KPI refresh, and Google OAuth coordinating identity and token creation. Most other feature paths are represented by the tree only, so their internal call links are left unverified rather than inferred.

Main entry points: [`src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java) (Google sign-in), [`src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java`](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java) (Review workflows), [`src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java`](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java) (Review API), [`src/main/java/com/lamdayne/humify/company/entity/Company.java`](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/company/entity/Company.java) (Company records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and Access"]
  node_auth["Authentication"]
  node_oauth["Google sign-in"]
  node_principal["User principal<br/>[UserPrincipal.java]"]
  node_roles["Roles and permissions"]
  node_user["User accounts<br/>[UserService.java]"]
end

subgraph group_workforce["Workforce Records"]
  node_company["Company records<br/>[Company.java]"]
  node_branch["Branches"]
  node_department["Departments"]
  node_employee["Employee records"]
end

subgraph group_operations["Attendance and Payroll"]
  node_attendance["Attendance tracking"]
  node_leave["Leave management"]
  node_shifts["Shift scheduling"]
  node_payroll["Payroll periods"]
  node_payslips["Payslips"]
end

subgraph group_performance["Performance Management"]
  node_reviews["Performance reviews"]
  node_reviewimpl["Review workflows"]
  node_reviewcontroller["Review API"]
  node_kpi["KPI calculation<br/>[KpiService.java]"]
end

subgraph group_work["Projects and Services"]
  node_projects["Projects and sprints"]
  node_tasks["Tasks and comments<br/>[TaskService.java]"]
  node_media["Media uploads<br/>[MediaService.java]"]
  node_mail["Email delivery<br/>[MailService.java]"]
end

node_actor(("Company user"))
node_google(("Google identity"))
node_store[("Relational database")]
node_cloudinary(("Cloudinary"))

node_actor -.->|"signs in"| node_auth
node_actor -.->|"manages reviews"| node_reviewcontroller
node_google -.->|"authenticates"| node_oauth
node_oauth -->|"finds or creates"| node_user
node_oauth -->|"links employee"| node_employee
node_oauth -->|"resolves company"| node_company
node_oauth -->|"loads identity"| node_principal
node_reviewcontroller -->|"delegates reviews"| node_reviews
node_reviewcontroller -->|"refreshes KPIs"| node_kpi
node_reviews -.->|"implemented by"| node_reviewimpl
node_reviewimpl -.->|"uses employee records"| node_employee
node_reviewimpl -.->|"uses company data"| node_company
node_employee -.->|"persists records"| node_store
node_company -.->|"persists records"| node_store
node_cloudinary -.->|"stores uploads"| node_media

click node_auth "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/auth/AuthenticationService.java"
click node_oauth "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java"
click node_principal "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/principal/UserPrincipal.java"
click node_roles "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/controller/RoleController.java"
click node_company "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/company/entity/Company.java"
click node_branch "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/branch/controller/BranchController.java"
click node_department "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/department/controller/DepartmentController.java"
click node_employee "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/employee/service/EmployeeService.java"
click node_user "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/user/service/UserService.java"
click node_attendance "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/AttendanceService.java"
click node_leave "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/LeaveBalanceService.java"
click node_shifts "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/WorkShiftService.java"
click node_payroll "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/payroll/service/PayrollPeriodService.java"
click node_payslips "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/payroll/service/PayslipService.java"
click node_reviews "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/PerformanceReviewService.java"
click node_reviewimpl "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java"
click node_reviewcontroller "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java"
click node_kpi "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/KpiService.java"
click node_projects "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/project/service/ProjectService.java"
click node_tasks "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/task/service/TaskService.java"
click node_media "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/media/service/MediaService.java"
click node_mail "https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/mail/service/MailService.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_oauth,node_principal,node_roles,node_user,node_actor toneBlue
class node_company,node_branch,node_department,node_employee,node_store toneAmber
class node_attendance,node_leave,node_shifts,node_payroll,node_payslips toneMint
class node_reviews,node_reviewimpl,node_reviewcontroller,node_kpi toneRose
class node_projects,node_tasks,node_media,node_mail,node_google,node_cloudinary toneIndigo
```

## Components

### Identity and Access

- [Authentication](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/auth/AuthenticationService.java): `src/main/java/com/lamdayne/humify/auth/security/auth/AuthenticationService.java`
- [Google sign-in](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java): `src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`
- [User principal](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/security/principal/UserPrincipal.java): `src/main/java/com/lamdayne/humify/auth/security/principal/UserPrincipal.java`
- [Roles and permissions](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/auth/controller/RoleController.java): `src/main/java/com/lamdayne/humify/auth/controller/RoleController.java`
- [User accounts](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/user/service/UserService.java): `src/main/java/com/lamdayne/humify/user/service/UserService.java`

### Workforce Records

- [Company records](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/company/entity/Company.java): `src/main/java/com/lamdayne/humify/company/entity/Company.java`
- [Branches](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/branch/controller/BranchController.java): `src/main/java/com/lamdayne/humify/branch/controller/BranchController.java`
- [Departments](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/department/controller/DepartmentController.java): `src/main/java/com/lamdayne/humify/department/controller/DepartmentController.java`
- [Employee records](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/employee/service/EmployeeService.java): `src/main/java/com/lamdayne/humify/employee/service/EmployeeService.java`

### Attendance and Payroll

- [Attendance tracking](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/AttendanceService.java): `src/main/java/com/lamdayne/humify/attendance/service/AttendanceService.java`
- [Leave management](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/LeaveBalanceService.java): `src/main/java/com/lamdayne/humify/attendance/service/LeaveBalanceService.java`
- [Shift scheduling](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/attendance/service/WorkShiftService.java): `src/main/java/com/lamdayne/humify/attendance/service/WorkShiftService.java`
- [Payroll periods](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/payroll/service/PayrollPeriodService.java): `src/main/java/com/lamdayne/humify/payroll/service/PayrollPeriodService.java`
- [Payslips](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/payroll/service/PayslipService.java): `src/main/java/com/lamdayne/humify/payroll/service/PayslipService.java`

### Performance Management

- [Performance reviews](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/PerformanceReviewService.java): `src/main/java/com/lamdayne/humify/performance/service/PerformanceReviewService.java`
- [Review workflows](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java): `src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java`
- [Review API](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java): `src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java`
- [KPI calculation](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/performance/service/KpiService.java): `src/main/java/com/lamdayne/humify/performance/service/KpiService.java`

### Projects and Services

- [Projects and sprints](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/project/service/ProjectService.java): `src/main/java/com/lamdayne/humify/project/service/ProjectService.java`
- [Tasks and comments](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/task/service/TaskService.java): `src/main/java/com/lamdayne/humify/task/service/TaskService.java`
- [Media uploads](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/media/service/MediaService.java): `src/main/java/com/lamdayne/humify/media/service/MediaService.java`
- [Email delivery](https://github.com/lamdayne/humify/blob/main/src/main/java/com/lamdayne/humify/mail/service/MailService.java): `src/main/java/com/lamdayne/humify/mail/service/MailService.java`

### Other components

- **Company user**
- **Google identity**
- **Relational database**
- **Cloudinary**

## Connections

- Company user → Authentication: signs in
- Company user → Review API: manages reviews
- Google identity → Google sign-in: authenticates
- Google sign-in → User accounts: finds or creates (evidence: `src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`)
- Google sign-in → Employee records: links employee (evidence: `src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`)
- Google sign-in → Company records: resolves company (evidence: `src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`)
- Google sign-in → User principal: loads identity (evidence: `src/main/java/com/lamdayne/humify/auth/security/oauth2/GoogleOAuthService.java`)
- Review API → Performance reviews: delegates reviews (evidence: `src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java`)
- Review API → KPI calculation: refreshes KPIs (evidence: `src/main/java/com/lamdayne/humify/performance/controller/PerformanceReviewController.java`)
- Performance reviews → Review workflows: implemented by (evidence: `src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java`)
- Review workflows → Employee records: uses employee records (evidence: `src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java`)
- Review workflows → Company records: uses company data (evidence: `src/main/java/com/lamdayne/humify/performance/service/impl/PerformanceReviewServiceImpl.java`)
- Employee records → Relational database: persists records
- Company records → Relational database: persists records
- Cloudinary → Media uploads: stores uploads
