# ryvarma7/leaveflow architecture

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

- Interactive diagram: https://gitdiagram.com/ryvarma7/leaveflow
- Repository: https://github.com/ryvarma7/leaveflow

## Overview

LeaveFlow is a leave-management platform spanning employee requests, manager/HR decisions, peer coverage, entitlement accounting, and payroll impact. Employees use the React app to submit and track requests; the Spring API coordinates validation and workflow, persists decisions and ledger changes, and exposes role-specific queues and statements. The README documents automated SLA escalation, conflict/capacity checks, and HR administration as additional capabilities. Source excerpts are partial, so some documented subsystem wiring is shown only where supported; unsampled features are represented without speculative call chains.

Main entry points: [`frontend/src/lib/api.ts`](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/lib/api.ts) (REST client), [`backend/src/main/java/com/leaveflow/service/LeaveWorkflowService.java`](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/LeaveWorkflowService.java) (Request workflow), [`frontend/src/App.tsx`](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/App.tsx) (Role-based app), [`backend/src/main/java/com/leaveflow/repository/LeaveRequestRepository.java`](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/repository/LeaveRequestRepository.java) (Data repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Role-based app<br/>[App.tsx]"]
  node_authui["Session context<br/>[AuthContext.tsx]"]
  node_leaveui["Employee leave<br/>[ApplyLeave.tsx]"]
  node_managerui["Manager decisions<br/>[ManagerQueue.tsx]"]
  node_hrui["HR review"]
  node_payui["Payroll views<br/>[HrPayroll.tsx]"]
  node_api_client["REST client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_auth["JWT authentication<br/>[JwtService.java]"]
  node_leavecontroller["Leave endpoints"]
  node_coveragecontroller["Coverage endpoints"]
  node_payrollcontroller["Payroll endpoints"]
  node_hrcontroller["HR administration<br/>[HrController.java]"]
end

subgraph group_workflow["Leave workflow"]
  node_workflowservice["Request workflow"]
  node_statemachine["Five-state machine"]
  node_escalation["SLA escalation"]
  node_calculators["Leave calculations<br/>[PayCalculator.java]"]
end

subgraph group_operations["Coverage and balances"]
  node_coverage["Peer coverage"]
  node_balance["Balance ledger"]
  node_dashboard["Dashboard metrics"]
end

subgraph group_data["Persistence"]
  node_repos["Data repositories"]
  node_postgres[("PostgreSQL")]
end

node_employee(("Employee / HR"))
node_browser(("Web browser"))

node_employee -->|"uses"| node_browser
node_browser -->|"opens"| node_app
node_app -->|"provides session"| node_authui
node_app -->|"routes"| node_leaveui
node_app -->|"routes"| node_managerui
node_app -->|"routes"| node_hrui
node_app -->|"routes"| node_payui
node_leaveui -->|"requests"| node_api_client
node_managerui -->|"requests"| node_api_client
node_hrui -->|"submits actions"| node_api_client
node_payui -->|"fetches statement"| node_api_client
node_api_client -->|"HTTP requests"| node_leavecontroller
node_api_client -->|"HTTP requests"| node_coveragecontroller
node_api_client -->|"HTTP requests"| node_payrollcontroller
node_api_client -->|"HTTP requests"| node_hrcontroller
node_leavecontroller -->|"submits decisions"| node_workflowservice
node_coveragecontroller -->|"delegates coverage"| node_coverage
node_workflowservice -->|"declines overlaps"| node_coverage
node_workflowservice -->|"calculates pay"| node_calculators
node_workflowservice -->|"reserves balance"| node_balance
node_workflowservice -->|"applies transitions"| node_statemachine
node_escalation -->|"escalates due requests"| node_workflowservice
node_leavecontroller -->|"calculates preview"| node_calculators
node_workflowservice -->|"persists requests"| node_repos
node_coverage -->|"reads and writes assignments"| node_repos
node_balance -->|"writes ledger"| node_repos
node_repos -->|"reads and writes"| node_postgres
node_dashboard -->|"reads metrics"| node_repos
node_authui -->|"authenticates"| node_api_client
node_leavecontroller -->|"uses JWT identity"| node_auth

click node_app "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/context/AuthContext.tsx"
click node_leaveui "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/employee/ApplyLeave.tsx"
click node_managerui "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/manager/ManagerQueue.tsx"
click node_hrui "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/hr/HrRequestReview.tsx"
click node_payui "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/hr/HrPayroll.tsx"
click node_api_client "https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/lib/api.ts"
click node_auth "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/JwtService.java"
click node_leavecontroller "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/LeaveRequestController.java"
click node_coveragecontroller "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/CoverageController.java"
click node_payrollcontroller "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/PayrollController.java"
click node_hrcontroller "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/HrController.java"
click node_workflowservice "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/LeaveWorkflowService.java"
click node_statemachine "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/domain/statemachine/LeaveStateMachine.java"
click node_escalation "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/EscalationScheduler.java"
click node_calculators "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/domain/calculator/PayCalculator.java"
click node_coverage "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/CoverageService.java"
click node_balance "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/BalanceService.java"
click node_dashboard "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/DashboardController.java"
click node_repos "https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/repository/LeaveRequestRepository.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_app,node_authui,node_leaveui,node_managerui,node_hrui,node_payui,node_api_client,node_browser toneBlue
class node_auth,node_leavecontroller,node_coveragecontroller,node_payrollcontroller,node_hrcontroller toneAmber
class node_workflowservice,node_statemachine,node_escalation,node_calculators toneMint
class node_coverage,node_balance,node_dashboard toneRose
class node_repos,node_postgres,node_employee toneIndigo
```

## Components

### Web application

- [Role-based app](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session context](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Employee leave](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/employee/ApplyLeave.tsx): `frontend/src/pages/employee/ApplyLeave.tsx`
- [Manager decisions](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/manager/ManagerQueue.tsx): `frontend/src/pages/manager/ManagerQueue.tsx`
- [HR review](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/hr/HrRequestReview.tsx): `frontend/src/pages/hr/HrRequestReview.tsx`
- [Payroll views](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/pages/hr/HrPayroll.tsx): `frontend/src/pages/hr/HrPayroll.tsx`
- [REST client](https://github.com/ryvarma7/leaveflow/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and identity

- [JWT authentication](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/JwtService.java): `backend/src/main/java/com/leaveflow/service/JwtService.java`
- [Leave endpoints](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/LeaveRequestController.java): `backend/src/main/java/com/leaveflow/web/controller/LeaveRequestController.java`
- [Coverage endpoints](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/CoverageController.java): `backend/src/main/java/com/leaveflow/web/controller/CoverageController.java`
- [Payroll endpoints](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/PayrollController.java): `backend/src/main/java/com/leaveflow/web/controller/PayrollController.java`
- [HR administration](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/HrController.java): `backend/src/main/java/com/leaveflow/web/controller/HrController.java`

### Leave workflow

- [Request workflow](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/LeaveWorkflowService.java): `backend/src/main/java/com/leaveflow/service/LeaveWorkflowService.java`
- [Five-state machine](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/domain/statemachine/LeaveStateMachine.java): `backend/src/main/java/com/leaveflow/domain/statemachine/LeaveStateMachine.java`
- [SLA escalation](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/EscalationScheduler.java): `backend/src/main/java/com/leaveflow/service/EscalationScheduler.java`
- [Leave calculations](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/domain/calculator/PayCalculator.java): `backend/src/main/java/com/leaveflow/domain/calculator/PayCalculator.java`

### Coverage and balances

- [Peer coverage](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/CoverageService.java): `backend/src/main/java/com/leaveflow/service/CoverageService.java`
- [Balance ledger](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/service/BalanceService.java): `backend/src/main/java/com/leaveflow/service/BalanceService.java`
- [Dashboard metrics](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/web/controller/DashboardController.java): `backend/src/main/java/com/leaveflow/web/controller/DashboardController.java`

### Persistence

- [Data repositories](https://github.com/ryvarma7/leaveflow/blob/main/backend/src/main/java/com/leaveflow/repository/LeaveRequestRepository.java): `backend/src/main/java/com/leaveflow/repository/LeaveRequestRepository.java`
- **PostgreSQL**

### Other components

- **Employee / HR**
- **Web browser**

## Connections

- Employee / HR → Web browser: uses
- Web browser → Role-based app: opens
- Role-based app → Session context: provides session
- Role-based app → Employee leave: routes
- Role-based app → Manager decisions: routes
- Role-based app → HR review: routes
- Role-based app → Payroll views: routes
- Employee leave → REST client: requests
- Manager decisions → REST client: requests
- HR review → REST client: submits actions
- Payroll views → REST client: fetches statement
- REST client → Leave endpoints: HTTP requests
- REST client → Coverage endpoints: HTTP requests
- REST client → Payroll endpoints: HTTP requests
- REST client → HR administration: HTTP requests
- Leave endpoints → Request workflow: submits decisions
- Coverage endpoints → Peer coverage: delegates coverage
- Request workflow → Peer coverage: declines overlaps
- Request workflow → Leave calculations: calculates pay
- Request workflow → Balance ledger: reserves balance
- Request workflow → Five-state machine: applies transitions
- SLA escalation → Request workflow: escalates due requests
- Leave endpoints → Leave calculations: calculates preview
- Request workflow → Data repositories: persists requests
- Peer coverage → Data repositories: reads and writes assignments
- Balance ledger → Data repositories: writes ledger
- Data repositories → PostgreSQL: reads and writes
- Dashboard metrics → Data repositories: reads metrics
- Session context → REST client: authenticates
- Leave endpoints → JWT authentication: uses JWT identity
