# kumaraguru911/hr-document-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/kumaraguru911/hr-document-management-system
- Repository: https://github.com/kumaraguru911/hr-document-management-system

## Overview

OnboardIQ is an HR onboarding portal: HR configures requirements and invites employees; employees activate accounts and submit documents; HR reviews submissions; both roles track status and notifications. The React workspaces call a FastAPI backend, which coordinates PostgreSQL records and MinIO file storage. Readiness scoring, expiry tracking, audit history, tasks, and the assistant are distinct product capabilities. Some subsystem links are documented in the README or SOURCE INDEX; unsampled internals are represented at their known directory paths.

Main entry points: [`frontend/src/api/api.js`](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/api/api.js) (API client), [`backend/app/database/session.py`](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/database/session.py) (PostgreSQL), [`backend/app/documents/service.py`](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/documents/service.py) (Document lifecycle), [`backend/app/notifications/service.py`](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/notifications/service.py) (Notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workspaces"]
  node_app["Role-based portal<br/>[App.jsx]"]
  node_employee_ui["Employee workspace"]
  node_hr_ui["HR workspace"]
  node_document_ui["Document submission"]
  node_review_ui["Document review<br/>[DocumentReview.jsx]"]
  node_task_ui["Readiness tasks<br/>[Tasks.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_identity["Identity and workforce"]
  node_auth["Accounts and 2FA<br/>[router.py]"]
  node_employee_mgmt["Employee management<br/>[service.py]"]
  node_readiness["Readiness scoring<br/>[service.py]"]
end

subgraph group_documents["Document lifecycle"]
  node_documents_api["Document workflows<br/>[router.py]"]
  node_document_service["Document lifecycle<br/>[service.py]"]
  node_minio["MinIO files<br/>[minio.py]"]
end

subgraph group_operations["Onboarding operations"]
  node_notifications["Notifications<br/>[service.py]"]
  node_audit["Audit history<br/>[service.py]"]
  node_tasks["Task management<br/>[service.py]"]
  node_assistant["Onboarding assistant<br/>[service.py]"]
  node_automation["Webhook automation<br/>[service.py]"]
end

subgraph group_infrastructure["Persistence and services"]
  node_postgres[("PostgreSQL<br/>[session.py]")]
end

node_hr(("HR user"))
node_employee(("Employee user"))
node_n8n["n8n webhooks"]

node_hr -->|"uses portal"| node_app
node_employee -->|"uses portal"| node_app
node_app -->|"routes HR"| node_hr_ui
node_app -->|"routes employee"| node_employee_ui
node_hr_ui -->|"calls API"| node_api_client
node_employee_ui -->|"calls API"| node_api_client
node_document_ui -->|"calls API"| node_api_client
node_review_ui -->|"calls API"| node_api_client
node_task_ui -->|"calls API"| node_api_client
node_api_client -->|"HTTP API"| node_auth
node_api_client -->|"HTTP API"| node_documents_api
node_api_client -->|"HTTP API"| node_employee_mgmt
node_api_client -->|"HTTP API"| node_notifications
node_api_client -->|"HTTP API"| node_audit
node_api_client -.->|"HTTP API"| node_tasks
node_documents_api -->|"delegates to"| node_document_service
node_document_service -->|"stores files"| node_minio
node_document_service -->|"creates alerts"| node_notifications
node_document_service -->|"records events"| node_audit
node_employee_mgmt -->|"sends invitations"| node_automation
node_automation -->|"webhook request"| node_n8n
node_employee_mgmt -->|"computes readiness"| node_readiness
node_tasks -->|"creates alerts"| node_notifications
node_assistant -->|"uses notifications"| node_notifications
node_auth -->|"reads and writes"| node_postgres
node_document_service -->|"reads and writes"| node_postgres
node_employee_mgmt -->|"reads and writes"| node_postgres
node_notifications -->|"reads and writes"| node_postgres
node_audit -->|"reads records"| node_postgres
node_tasks -->|"reads and writes"| node_postgres

click node_app "https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/App.jsx"
click node_employee_ui "https://github.com/kumaraguru911/hr-document-management-system/tree/main/frontend/src/pages/employee"
click node_hr_ui "https://github.com/kumaraguru911/hr-document-management-system/tree/main/frontend/src/pages/hr"
click node_document_ui "https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/EmployeeDocuments.jsx"
click node_review_ui "https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/hr/DocumentReview.jsx"
click node_task_ui "https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/hr/Tasks.jsx"
click node_api_client "https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/api/api.js"
click node_auth "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/auth/router.py"
click node_employee_mgmt "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/employees/service.py"
click node_readiness "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/employees/service.py"
click node_documents_api "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/documents/router.py"
click node_document_service "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/documents/service.py"
click node_minio "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/storage/minio.py"
click node_notifications "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/notifications/service.py"
click node_audit "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/audit/service.py"
click node_tasks "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/tasks/service.py"
click node_assistant "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/assistant/service.py"
click node_automation "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/automation/service.py"
click node_postgres "https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/database/session.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_app,node_employee_ui,node_hr_ui,node_document_ui,node_review_ui,node_task_ui,node_api_client,node_hr,node_employee toneBlue
class node_auth,node_employee_mgmt,node_readiness toneAmber
class node_documents_api,node_document_service,node_minio,node_n8n toneMint
class node_notifications,node_audit,node_tasks,node_assistant,node_automation toneRose
class node_postgres toneIndigo
```

## Components

### Web workspaces

- [Role-based portal](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Employee workspace](https://github.com/kumaraguru911/hr-document-management-system/tree/main/frontend/src/pages/employee): `frontend/src/pages/employee`
- [HR workspace](https://github.com/kumaraguru911/hr-document-management-system/tree/main/frontend/src/pages/hr): `frontend/src/pages/hr`
- [Document submission](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/EmployeeDocuments.jsx): `frontend/src/pages/EmployeeDocuments.jsx`
- [Document review](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/hr/DocumentReview.jsx): `frontend/src/pages/hr/DocumentReview.jsx`
- [Readiness tasks](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/pages/hr/Tasks.jsx): `frontend/src/pages/hr/Tasks.jsx`
- [API client](https://github.com/kumaraguru911/hr-document-management-system/blob/main/frontend/src/api/api.js): `frontend/src/api/api.js`

### Identity and workforce

- [Accounts and 2FA](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/auth/router.py): `backend/app/auth/router.py`
- [Employee management](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/employees/service.py): `backend/app/employees/service.py`
- [Readiness scoring](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/employees/service.py): `backend/app/employees/service.py`

### Document lifecycle

- [Document workflows](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/documents/router.py): `backend/app/documents/router.py`
- [Document lifecycle](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/documents/service.py): `backend/app/documents/service.py`
- [MinIO files](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/storage/minio.py): `backend/app/storage/minio.py`

### Onboarding operations

- [Notifications](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/notifications/service.py): `backend/app/notifications/service.py`
- [Audit history](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/audit/service.py): `backend/app/audit/service.py`
- [Task management](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/tasks/service.py): `backend/app/tasks/service.py`
- [Onboarding assistant](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/assistant/service.py): `backend/app/assistant/service.py`
- [Webhook automation](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/automation/service.py): `backend/app/automation/service.py`

### Persistence and services

- [PostgreSQL](https://github.com/kumaraguru911/hr-document-management-system/blob/main/backend/app/database/session.py): `backend/app/database/session.py`

### Other components

- **HR user**
- **Employee user**
- **n8n webhooks**

## Connections

- HR user → Role-based portal: uses portal (evidence: `README.md`)
- Employee user → Role-based portal: uses portal (evidence: `README.md`)
- Role-based portal → HR workspace: routes HR (evidence: `frontend/src/App.jsx`)
- Role-based portal → Employee workspace: routes employee (evidence: `frontend/src/App.jsx`)
- HR workspace → API client: calls API (evidence: `frontend/src/pages/hr/Tasks.jsx`)
- Employee workspace → API client: calls API (evidence: `frontend/src/pages/employee/EmployeeDashboard.jsx`)
- Document submission → API client: calls API (evidence: `frontend/src/pages/EmployeeDocuments.jsx`)
- Document review → API client: calls API (evidence: `frontend/src/pages/hr/DocumentReview.jsx`)
- Readiness tasks → API client: calls API (evidence: `frontend/src/pages/hr/Tasks.jsx`)
- API client → Accounts and 2FA: HTTP API (evidence: `README.md`)
- API client → Document workflows: HTTP API (evidence: `README.md`)
- API client → Employee management: HTTP API (evidence: `README.md`)
- API client → Notifications: HTTP API (evidence: `README.md`)
- API client → Audit history: HTTP API (evidence: `README.md`)
- API client → Task management: HTTP API
- Document workflows → Document lifecycle: delegates to (evidence: `backend/app/documents/router.py`)
- Document lifecycle → MinIO files: stores files (evidence: `backend/app/documents/service.py`)
- Document lifecycle → Notifications: creates alerts (evidence: `backend/app/documents/service.py`)
- Document lifecycle → Audit history: records events (evidence: `backend/app/documents/service.py`)
- Employee management → Webhook automation: sends invitations (evidence: `backend/app/employees/service.py`)
- Webhook automation → n8n webhooks: webhook request (evidence: `backend/app/automation/service.py`)
- Employee management → Readiness scoring: computes readiness (evidence: `backend/app/employees/service.py`)
- Task management → Notifications: creates alerts (evidence: `backend/app/tasks/service.py`)
- Onboarding assistant → Notifications: uses notifications (evidence: `backend/app/assistant/service.py`)
- Accounts and 2FA → PostgreSQL: reads and writes (evidence: `backend/app/auth/router.py`)
- Document lifecycle → PostgreSQL: reads and writes (evidence: `backend/app/documents/service.py`)
- Employee management → PostgreSQL: reads and writes (evidence: `backend/app/employees/service.py`)
- Notifications → PostgreSQL: reads and writes (evidence: `backend/app/notifications/service.py`)
- Audit history → PostgreSQL: reads records (evidence: `backend/app/audit/service.py`)
- Task management → PostgreSQL: reads and writes (evidence: `backend/app/tasks/service.py`)
