# annaskhadafi/hero architecture

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

- Interactive diagram: https://gitdiagram.com/annaskhadafi/hero
- Repository: https://github.com/annaskhadafi/hero

## Overview

HERO is an employee-management and operations platform. A typical user signs in, enters the dashboard or mobile experience, completes a domain task—such as attendance, an HR request, learning, or safety reporting—and receives a recorded result or approval. The repository exposes these capabilities through App Router pages, API routes, and server actions, with PostgreSQL and shared approval logic underneath. The README documents the platform and database stack; sampled source confirms several route-to-service interactions, but not all module wiring, so uncertain links are omitted.

Main entry points: [`app/dashboard/page.tsx`](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/page.tsx) (Web dashboard), [`app/api/mobile/face-attendance/route.ts`](https://github.com/annaskhadafi/hero/blob/main/app/api/mobile/face-attendance/route.ts) (Attendance APIs), [`app/dashboard/scheduling-timesheet/page.tsx`](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/scheduling-timesheet/page.tsx) (Scheduling and timesheets), [`lib/summary-engine.ts`](https://github.com/annaskhadafi/hero/blob/main/lib/summary-engine.ts) (APD summaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and experience"]
  node_web["Web dashboard<br/>[page.tsx]"]
  node_mobile["Mobile experience<br/>[page.tsx]"]
  node_auth["Authentication<br/>[route.ts]"]
end

subgraph group_people["People operations"]
  node_hr["HR operations<br/>[page.tsx]"]
  node_recruitment["Recruitment<br/>[page.tsx]"]
  node_employee_records["Employee records<br/>[page.tsx]"]
  node_contracts["Contracts and letters<br/>[page.tsx]"]
end

subgraph group_work["Work and safety"]
  node_attendance["Attendance<br/>[page.tsx]"]
  node_timesheets["Scheduling and timesheets<br/>[page.tsx]"]
  node_safety["HSE and safety<br/>[page.tsx]"]
  node_warehouse["Warehouse and repair<br/>[page.tsx]"]
end

subgraph group_learning["Learning and activity"]
  node_lms["Learning management<br/>[page.tsx]"]
  node_activity["Activity hub<br/>[page.tsx]"]
  node_activity_docs["Activity documents<br/>[route.ts]"]
end

subgraph group_platform["Shared services"]
  node_approval["Approval engine<br/>[approval-engine.ts]"]
  node_legacy_approval["Legacy approvals"]
  node_summary["APD summaries<br/>[summary-engine.ts]"]
  node_attendance_api["Attendance APIs<br/>[route.ts]"]
  node_face_verify["Face verification<br/>[route.ts]"]
  node_db[("PostgreSQL")]
end

node_employee(("Employee"))
node_vision["Raray Vision"]
node_notifications["Email and push"]

node_employee -->|"signs in"| node_auth
node_auth -->|"grants access"| node_web
node_auth -->|"grants access"| node_mobile
node_employee -->|"uses"| node_web
node_employee -->|"uses"| node_mobile
node_web -->|"opens"| node_hr
node_web -->|"opens"| node_recruitment
node_web -->|"opens"| node_employee_records
node_web -->|"opens"| node_contracts
node_web -->|"opens"| node_attendance
node_web -->|"opens"| node_timesheets
node_web -->|"opens"| node_safety
node_web -->|"opens"| node_warehouse
node_web -->|"opens"| node_lms
node_web -->|"opens"| node_activity
node_mobile -->|"submits attendance"| node_attendance_api
node_attendance_api -->|"writes records"| node_db
node_attendance_api -.->|"checks liveness"| node_vision
node_attendance_api -->|"syncs attendance"| node_timesheets
node_face_verify -->|"reads and writes"| node_db
node_face_verify -.->|"checks liveness"| node_vision
node_face_verify -->|"syncs attendance"| node_timesheets
node_attendance -->|"reads records"| node_db
node_timesheets -->|"reads schedules"| node_db
node_hr -->|"manages records"| node_db
node_recruitment -->|"manages candidates"| node_db
node_employee_records -->|"reads records"| node_db
node_contracts -->|"reads requests"| node_db
node_contracts -->|"uses approvals"| node_legacy_approval
node_legacy_approval -->|"stores approval state"| node_db
node_legacy_approval -->|"sends updates"| node_notifications
node_safety -->|"records safety work"| node_db
node_warehouse -->|"reads and updates stock"| node_db
node_lms -->|"manages learning"| node_db
node_activity -->|"manages sessions"| node_db
node_activity_docs -->|"loads session data"| node_db
node_activity_docs -->|"returns PDF"| node_employee
node_approval -->|"resolves approval context"| node_db
node_summary -->|"manages summaries"| node_db
node_summary -->|"notifies approvers"| node_notifications
node_summary -->|"uses approval configuration"| node_approval

click node_web "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/page.tsx"
click node_mobile "https://github.com/annaskhadafi/hero/blob/main/app/mobile/dashboard/page.tsx"
click node_auth "https://github.com/annaskhadafi/hero/blob/main/app/api/auth/%5B...all%5D/route.ts"
click node_hr "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/page.tsx"
click node_recruitment "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/recruitment/page.tsx"
click node_employee_records "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/employee/page.tsx"
click node_contracts "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/contract-review/page.tsx"
click node_attendance "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/attendance/page.tsx"
click node_timesheets "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/scheduling-timesheet/page.tsx"
click node_safety "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hse/page.tsx"
click node_warehouse "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/warehouse-repair/page.tsx"
click node_lms "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/chitralearning-lms/page.tsx"
click node_activity "https://github.com/annaskhadafi/hero/blob/main/app/dashboard/activity-hub/page.tsx"
click node_activity_docs "https://github.com/annaskhadafi/hero/blob/main/app/api/activity-sessions/%5BsessionId%5D/pdf/route.ts"
click node_approval "https://github.com/annaskhadafi/hero/blob/main/lib/approval-engine.ts"
click node_legacy_approval "https://github.com/annaskhadafi/hero/blob/main/lib/legacy-approval-engine.ts"
click node_summary "https://github.com/annaskhadafi/hero/blob/main/lib/summary-engine.ts"
click node_attendance_api "https://github.com/annaskhadafi/hero/blob/main/app/api/mobile/face-attendance/route.ts"
click node_face_verify "https://github.com/annaskhadafi/hero/blob/main/app/api/mobile/face-verification/route.ts"

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_mobile,node_auth toneBlue
class node_hr,node_recruitment,node_employee_records,node_contracts toneAmber
class node_attendance,node_timesheets,node_safety,node_warehouse toneMint
class node_lms,node_activity,node_activity_docs toneRose
class node_approval,node_legacy_approval,node_summary,node_attendance_api,node_face_verify,node_db,node_employee,node_vision,node_notifications toneIndigo
```

## Components

### Access and experience

- [Web dashboard](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Mobile experience](https://github.com/annaskhadafi/hero/blob/main/app/mobile/dashboard/page.tsx): `app/mobile/dashboard/page.tsx`
- [Authentication](https://github.com/annaskhadafi/hero/blob/main/app/api/auth/%5B...all%5D/route.ts): `app/api/auth/[...all]/route.ts`

### People operations

- [HR operations](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/page.tsx): `app/dashboard/hc/page.tsx`
- [Recruitment](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/recruitment/page.tsx): `app/dashboard/hc/recruitment/page.tsx`
- [Employee records](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/employee/page.tsx): `app/dashboard/hc/employee/page.tsx`
- [Contracts and letters](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hc/contract-review/page.tsx): `app/dashboard/hc/contract-review/page.tsx`

### Work and safety

- [Attendance](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/attendance/page.tsx): `app/dashboard/attendance/page.tsx`
- [Scheduling and timesheets](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/scheduling-timesheet/page.tsx): `app/dashboard/scheduling-timesheet/page.tsx`
- [HSE and safety](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/hse/page.tsx): `app/dashboard/hse/page.tsx`
- [Warehouse and repair](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/warehouse-repair/page.tsx): `app/dashboard/warehouse-repair/page.tsx`

### Learning and activity

- [Learning management](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/chitralearning-lms/page.tsx): `app/dashboard/chitralearning-lms/page.tsx`
- [Activity hub](https://github.com/annaskhadafi/hero/blob/main/app/dashboard/activity-hub/page.tsx): `app/dashboard/activity-hub/page.tsx`
- [Activity documents](https://github.com/annaskhadafi/hero/blob/main/app/api/activity-sessions/%5BsessionId%5D/pdf/route.ts): `app/api/activity-sessions/[sessionId]/pdf/route.ts`

### Shared services

- [Approval engine](https://github.com/annaskhadafi/hero/blob/main/lib/approval-engine.ts): `lib/approval-engine.ts`
- [Legacy approvals](https://github.com/annaskhadafi/hero/blob/main/lib/legacy-approval-engine.ts): `lib/legacy-approval-engine.ts`
- [APD summaries](https://github.com/annaskhadafi/hero/blob/main/lib/summary-engine.ts): `lib/summary-engine.ts`
- [Attendance APIs](https://github.com/annaskhadafi/hero/blob/main/app/api/mobile/face-attendance/route.ts): `app/api/mobile/face-attendance/route.ts`
- [Face verification](https://github.com/annaskhadafi/hero/blob/main/app/api/mobile/face-verification/route.ts): `app/api/mobile/face-verification/route.ts`
- **PostgreSQL**

### Other components

- **Employee**
- **Raray Vision**
- **Email and push**

## Connections

- Employee → Authentication: signs in
- Authentication → Web dashboard: grants access
- Authentication → Mobile experience: grants access
- Employee → Web dashboard: uses
- Employee → Mobile experience: uses
- Web dashboard → HR operations: opens
- Web dashboard → Recruitment: opens
- Web dashboard → Employee records: opens
- Web dashboard → Contracts and letters: opens
- Web dashboard → Attendance: opens
- Web dashboard → Scheduling and timesheets: opens
- Web dashboard → HSE and safety: opens
- Web dashboard → Warehouse and repair: opens
- Web dashboard → Learning management: opens
- Web dashboard → Activity hub: opens
- Mobile experience → Attendance APIs: submits attendance
- Attendance APIs → PostgreSQL: writes records
- Attendance APIs → Raray Vision: checks liveness
- Attendance APIs → Scheduling and timesheets: syncs attendance
- Face verification → PostgreSQL: reads and writes
- Face verification → Raray Vision: checks liveness
- Face verification → Scheduling and timesheets: syncs attendance
- Attendance → PostgreSQL: reads records
- Scheduling and timesheets → PostgreSQL: reads schedules
- HR operations → PostgreSQL: manages records
- Recruitment → PostgreSQL: manages candidates
- Employee records → PostgreSQL: reads records
- Contracts and letters → PostgreSQL: reads requests
- Contracts and letters → Legacy approvals: uses approvals
- Legacy approvals → PostgreSQL: stores approval state
- Legacy approvals → Email and push: sends updates
- HSE and safety → PostgreSQL: records safety work
- Warehouse and repair → PostgreSQL: reads and updates stock
- Learning management → PostgreSQL: manages learning
- Activity hub → PostgreSQL: manages sessions
- Activity documents → PostgreSQL: loads session data
- Activity documents → Employee: returns PDF
- Approval engine → PostgreSQL: resolves approval context
- APD summaries → PostgreSQL: manages summaries
- APD summaries → Email and push: notifies approvers
- APD summaries → Approval engine: uses approval configuration