# kaimkaur/smart-hr architecture

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

- Interactive diagram: https://gitdiagram.com/kaimkaur/smart-hr
- Repository: https://github.com/kaimkaur/smart-hr

## Overview

Smart HR is a role-based HR platform: employees, managers, HR, recruiters, and administrators use the Next.js application to manage workforce operations and recruitment. The principal workflow runs from browser pages through frontend services to FastAPI routes/controllers and domain services, which persist records in PostgreSQL and return results to the UI. Recruitment adds optional AI-assisted resume screening; reporting supports operational summaries and exports. Backend wiring is described at the module level because most service implementations were not sampled.

Main entry points: [`backend/app/main.py`](https://github.com/kaimkaur/smart-hr/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/core/database.py`](https://github.com/kaimkaur/smart-hr/blob/main/backend/app/core/database.py) (PostgreSQL), [`backend/app/modules/recruitment`](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/recruitment) (Recruitment), [`frontend/src/services`](https://github.com/kaimkaur/smart-hr/tree/main/frontend/src/services) (API services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Role-based pages"]
  node_webservices["API services"]
  node_authstorage["Token storage<br/>[auth-storage.ts]"]
end

subgraph group_platform["API platform"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Authentication"]
  node_usersadmin["Users and roles"]
  node_audit["Audit logs"]
end

subgraph group_workforce["Workforce operations"]
  node_employees["Employee records"]
  node_organization["Org structure"]
  node_attendance["Attendance"]
  node_leave["Leave management"]
  node_performance["Performance reviews"]
  node_notifications["Notifications"]
end

subgraph group_talent["Talent and insights"]
  node_recruitment["Recruitment"]
  node_ai["AI screening"]
  node_reporting["Reports and exports"]
end

subgraph group_data["Persistence and AI"]
  node_database[("PostgreSQL<br/>[database.py]")]
end

node_users(("HR platform users"))
node_llm{{"LLM provider"}}

node_users -->|"use"| node_web
node_web -->|"request"| node_webservices
node_webservices -->|"HTTP calls"| node_api
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_usersadmin
node_api -->|"dispatches"| node_employees
node_api -->|"dispatches"| node_organization
node_api -->|"dispatches"| node_attendance
node_api -->|"dispatches"| node_leave
node_api -->|"dispatches"| node_performance
node_api -->|"dispatches"| node_notifications
node_api -->|"dispatches"| node_recruitment
node_api -->|"dispatches"| node_reporting
node_api -->|"dispatches"| node_audit
node_auth -->|"returns tokens"| node_authstorage
node_authstorage -->|"provides tokens"| node_webservices
node_employees -->|"reads/writes"| node_database
node_organization -->|"reads/writes"| node_database
node_attendance -->|"reads/writes"| node_database
node_leave -->|"reads/writes"| node_database
node_performance -->|"reads/writes"| node_database
node_notifications -->|"reads/writes"| node_database
node_recruitment -->|"reads/writes"| node_database
node_usersadmin -->|"reads/writes"| node_database
node_reporting -->|"queries"| node_database
node_audit -->|"reads/writes"| node_database
node_recruitment -.->|"screens candidates"| node_ai
node_ai -.->|"requests analysis"| node_llm

click node_web "https://github.com/kaimkaur/smart-hr/tree/main/frontend/src/app"
click node_webservices "https://github.com/kaimkaur/smart-hr/tree/main/frontend/src/services"
click node_authstorage "https://github.com/kaimkaur/smart-hr/blob/main/frontend/src/lib/auth-storage.ts"
click node_api "https://github.com/kaimkaur/smart-hr/blob/main/backend/app/main.py"
click node_auth "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/auth"
click node_usersadmin "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/user"
click node_employees "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/employee"
click node_organization "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/organization"
click node_attendance "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/attendance"
click node_leave "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/leave"
click node_performance "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/performance"
click node_notifications "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/notifications"
click node_recruitment "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/recruitment"
click node_ai "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/ai"
click node_reporting "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/reporting"
click node_audit "https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/audit_logs"
click node_database "https://github.com/kaimkaur/smart-hr/blob/main/backend/app/core/database.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_webservices,node_authstorage,node_users toneBlue
class node_api,node_auth,node_usersadmin,node_audit toneAmber
class node_employees,node_organization,node_attendance,node_leave,node_performance,node_notifications toneMint
class node_recruitment,node_ai,node_reporting toneRose
class node_database,node_llm toneIndigo
```

## Components

### Web experience

- [Role-based pages](https://github.com/kaimkaur/smart-hr/tree/main/frontend/src/app): `frontend/src/app`
- [API services](https://github.com/kaimkaur/smart-hr/tree/main/frontend/src/services): `frontend/src/services`
- [Token storage](https://github.com/kaimkaur/smart-hr/blob/main/frontend/src/lib/auth-storage.ts): `frontend/src/lib/auth-storage.ts`

### API platform

- [FastAPI application](https://github.com/kaimkaur/smart-hr/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/auth): `backend/app/modules/auth`
- [Users and roles](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/user): `backend/app/modules/user`
- [Audit logs](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/audit_logs): `backend/app/modules/audit_logs`

### Workforce operations

- [Employee records](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/employee): `backend/app/modules/employee`
- [Org structure](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/organization): `backend/app/modules/organization`
- [Attendance](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/attendance): `backend/app/modules/attendance`
- [Leave management](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/leave): `backend/app/modules/leave`
- [Performance reviews](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/performance): `backend/app/modules/performance`
- [Notifications](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/notifications): `backend/app/modules/notifications`

### Talent and insights

- [Recruitment](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/recruitment): `backend/app/modules/recruitment`
- [AI screening](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/ai): `backend/app/ai`
- [Reports and exports](https://github.com/kaimkaur/smart-hr/tree/main/backend/app/modules/reporting): `backend/app/modules/reporting`

### Persistence and AI

- [PostgreSQL](https://github.com/kaimkaur/smart-hr/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **HR platform users**
- **LLM provider**

## Connections

- HR platform users → Role-based pages: use
- Role-based pages → API services: request
- API services → FastAPI application: HTTP calls
- FastAPI application → Authentication: dispatches
- FastAPI application → Users and roles: dispatches
- FastAPI application → Employee records: dispatches
- FastAPI application → Org structure: dispatches
- FastAPI application → Attendance: dispatches
- FastAPI application → Leave management: dispatches
- FastAPI application → Performance reviews: dispatches
- FastAPI application → Notifications: dispatches
- FastAPI application → Recruitment: dispatches
- FastAPI application → Reports and exports: dispatches
- FastAPI application → Audit logs: dispatches
- Authentication → Token storage: returns tokens
- Token storage → API services: provides tokens
- Employee records → PostgreSQL: reads/writes
- Org structure → PostgreSQL: reads/writes
- Attendance → PostgreSQL: reads/writes
- Leave management → PostgreSQL: reads/writes
- Performance reviews → PostgreSQL: reads/writes
- Notifications → PostgreSQL: reads/writes
- Recruitment → PostgreSQL: reads/writes
- Users and roles → PostgreSQL: reads/writes
- Reports and exports → PostgreSQL: queries
- Audit logs → PostgreSQL: reads/writes
- Recruitment → AI screening: screens candidates
- AI screening → LLM provider: requests analysis