# gururagvesh/apex-os architecture

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

- Interactive diagram: https://gitdiagram.com/gururagvesh/apex-os
- Repository: https://github.com/gururagvesh/apex-os

## Overview

APEX is an internal business-management platform, with employee and manager workflows spanning authentication, work tracking, attendance, and administration. A common user journey enters through the web app, authenticates against the API, and uses domain screens whose requests are handled by backend modules and persisted through Prisma. The README documents ticket lifecycle/Kanban, projects, leave, RBAC, AI assistance, notifications, and role-based dashboards; attendance and sales CRM are also prominent in the repository tree. Connections are shown only where excerpts or README statements support them; undocumented frontend-to-API wiring is omitted.

Main entry points: [`backend/src/prisma/prisma.service.ts`](https://github.com/gururagvesh/apex-os/blob/main/backend/src/prisma/prisma.service.ts) (Prisma data access), [`backend/src/modules/operations/tickets/tickets.service.ts`](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/tickets/tickets.service.ts) (Ticket lifecycle), [`backend/src/modules/core/auth/auth.service.ts`](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/core/auth/auth.service.ts) (Authentication), [`backend/src/common/services/access-policy.service.ts`](https://github.com/gururagvesh/apex-os/blob/main/backend/src/common/services/access-policy.service.ts) (Access policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application"]
  node_punchui["Punch capture"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_userapi["User management<br/>[users.service.ts]"]
  node_access["Access policy"]
  node_roles["Role definitions<br/>[roles.ts]"]
end

subgraph group_operations["Work management"]
  node_ticketsapi["Ticket lifecycle<br/>[tickets.service.ts]"]
  node_ticketledger["Ticket timing ledger"]
  node_projects["Project tracking"]
  node_crm["Sales CRM<br/>[leads.service.ts]"]
end

subgraph group_workforce["Attendance and workforce"]
  node_leave["Leave approvals<br/>[leave.service.ts]"]
  node_attendance["Attendance operations"]
  node_photoapi["Punch photo upload"]
end

subgraph group_platform["Platform services"]
  node_ai["AI assistance<br/>[ai.service.ts]"]
  node_notifications["Notifications"]
  node_gateway["Realtime gateway<br/>[events.gateway.ts]"]
  node_email["Email service<br/>[email.service.ts]"]
  node_uploads["File uploads<br/>[uploads.service.ts]"]
  node_events["Activity events"]
  node_eventlog["Event logger"]
  node_prisma["Prisma data access<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL")]
end

node_employee(("Employee or manager"))
node_cloudinary["Cloudinary"]
node_openai["OpenAI"]
node_smtp["SMTP mail"]

node_employee -->|"uses"| node_webapp
node_webapp -->|"authenticates"| node_auth
node_auth -->|"reads users"| node_prisma
node_auth -->|"audits login"| node_eventlog
node_auth -->|"sends email"| node_email
node_userapi -->|"checks policy"| node_access
node_userapi -->|"uses"| node_email
node_userapi -->|"reads and writes"| node_prisma
node_access -->|"reads roles"| node_prisma
node_access -->|"uses ladder"| node_roles
node_ticketsapi -->|"uses timing"| node_ticketledger
node_ticketsapi -->|"logs actions"| node_eventlog
node_ticketsapi -->|"dispatches events"| node_notifications
node_ticketsapi -->|"emits updates"| node_gateway
node_ticketsapi -->|"reads and writes"| node_prisma
node_ticketsapi -->|"serves attachments"| node_uploads
node_projects -.->|"persists projects"| node_prisma
node_leave -.->|"persists requests"| node_prisma
node_attendance -.->|"stores attendance"| node_prisma
node_punchui -->|"uploads photo"| node_photoapi
node_photoapi -->|"stores photos"| node_cloudinary
node_crm -.->|"persists leads"| node_prisma
node_ai -.->|"requests assistance"| node_openai
node_notifications -.->|"broadcasts realtime"| node_gateway
node_email -.->|"sends messages"| node_smtp
node_events -->|"checks visibility"| node_access
node_events -->|"queries events"| node_prisma
node_events -->|"uses event history"| node_eventlog
node_eventlog -->|"writes events"| node_prisma
node_prisma -->|"connects"| node_postgres

click node_webapp "https://github.com/gururagvesh/apex-os/tree/main/frontend/app"
click node_auth "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/core/auth/auth.service.ts"
click node_userapi "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/core/users/users.service.ts"
click node_access "https://github.com/gururagvesh/apex-os/blob/main/backend/src/common/services/access-policy.service.ts"
click node_roles "https://github.com/gururagvesh/apex-os/blob/main/backend/src/shared/constants/roles.ts"
click node_ticketsapi "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/tickets/tickets.service.ts"
click node_ticketledger "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/tickets/ticket-ledger.service.ts"
click node_projects "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/projects/projects.service.ts"
click node_leave "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/leave/leave.service.ts"
click node_attendance "https://github.com/gururagvesh/apex-os/tree/main/backend/src/modules/platform/attendance"
click node_punchui "https://github.com/gururagvesh/apex-os/blob/main/frontend/components/attendance/useAttendanceCamera.ts"
click node_photoapi "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/attendance/punch/punch-photo.storage.ts"
click node_crm "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/business/sales-crm/leads.service.ts"
click node_ai "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/ai/ai.service.ts"
click node_notifications "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/notifications/notifications.service.ts"
click node_gateway "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/gateway/events.gateway.ts"
click node_email "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/email/email.service.ts"
click node_uploads "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/uploads/uploads.service.ts"
click node_events "https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/events/events.controller.ts"
click node_eventlog "https://github.com/gururagvesh/apex-os/blob/main/backend/src/common/services/event-logger.service.ts"
click node_prisma "https://github.com/gururagvesh/apex-os/blob/main/backend/src/prisma/prisma.service.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_webapp,node_punchui toneBlue
class node_auth,node_userapi,node_access,node_roles toneAmber
class node_ticketsapi,node_ticketledger,node_projects,node_crm toneMint
class node_leave,node_attendance,node_photoapi toneRose
class node_ai,node_notifications,node_gateway,node_email,node_uploads,node_events,node_eventlog,node_prisma,node_postgres,node_employee,node_cloudinary,node_openai,node_smtp toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/gururagvesh/apex-os/tree/main/frontend/app): `frontend/app`
- [Punch capture](https://github.com/gururagvesh/apex-os/blob/main/frontend/components/attendance/useAttendanceCamera.ts): `frontend/components/attendance/useAttendanceCamera.ts`

### Identity and access

- [Authentication](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/core/auth/auth.service.ts): `backend/src/modules/core/auth/auth.service.ts`
- [User management](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/core/users/users.service.ts): `backend/src/modules/core/users/users.service.ts`
- [Access policy](https://github.com/gururagvesh/apex-os/blob/main/backend/src/common/services/access-policy.service.ts): `backend/src/common/services/access-policy.service.ts`
- [Role definitions](https://github.com/gururagvesh/apex-os/blob/main/backend/src/shared/constants/roles.ts): `backend/src/shared/constants/roles.ts`

### Work management

- [Ticket lifecycle](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/tickets/tickets.service.ts): `backend/src/modules/operations/tickets/tickets.service.ts`
- [Ticket timing ledger](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/tickets/ticket-ledger.service.ts): `backend/src/modules/operations/tickets/ticket-ledger.service.ts`
- [Project tracking](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/projects/projects.service.ts): `backend/src/modules/operations/projects/projects.service.ts`
- [Sales CRM](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/business/sales-crm/leads.service.ts): `backend/src/modules/business/sales-crm/leads.service.ts`

### Attendance and workforce

- [Leave approvals](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/leave/leave.service.ts): `backend/src/modules/operations/leave/leave.service.ts`
- [Attendance operations](https://github.com/gururagvesh/apex-os/tree/main/backend/src/modules/platform/attendance): `backend/src/modules/platform/attendance`
- [Punch photo upload](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/attendance/punch/punch-photo.storage.ts): `backend/src/modules/platform/attendance/punch/punch-photo.storage.ts`

### Platform services

- [AI assistance](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/ai/ai.service.ts): `backend/src/modules/ai/ai.service.ts`
- [Notifications](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/operations/notifications/notifications.service.ts): `backend/src/modules/operations/notifications/notifications.service.ts`
- [Realtime gateway](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/gateway/events.gateway.ts): `backend/src/modules/platform/gateway/events.gateway.ts`
- [Email service](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/email/email.service.ts): `backend/src/modules/platform/email/email.service.ts`
- [File uploads](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/uploads/uploads.service.ts): `backend/src/modules/platform/uploads/uploads.service.ts`
- [Activity events](https://github.com/gururagvesh/apex-os/blob/main/backend/src/modules/platform/events/events.controller.ts): `backend/src/modules/platform/events/events.controller.ts`
- [Event logger](https://github.com/gururagvesh/apex-os/blob/main/backend/src/common/services/event-logger.service.ts): `backend/src/common/services/event-logger.service.ts`
- [Prisma data access](https://github.com/gururagvesh/apex-os/blob/main/backend/src/prisma/prisma.service.ts): `backend/src/prisma/prisma.service.ts`
- **PostgreSQL**

### Other components

- **Employee or manager**
- **Cloudinary**
- **OpenAI**
- **SMTP mail**

## Connections

- Employee or manager → Web application: uses
- Web application → Authentication: authenticates
- Authentication → Prisma data access: reads users (evidence: `backend/src/modules/core/auth/auth.service.ts`)
- Authentication → Event logger: audits login (evidence: `backend/src/modules/core/auth/auth.service.ts`)
- Authentication → Email service: sends email (evidence: `backend/src/modules/core/auth/auth.service.ts`)
- User management → Access policy: checks policy (evidence: `backend/src/modules/core/users/users.service.ts`)
- User management → Email service: uses (evidence: `backend/src/modules/core/users/users.service.ts`)
- User management → Prisma data access: reads and writes (evidence: `backend/src/modules/core/users/users.service.ts`)
- Access policy → Prisma data access: reads roles (evidence: `backend/src/common/services/access-policy.service.ts`)
- Access policy → Role definitions: uses ladder (evidence: `backend/src/common/services/access-policy.service.ts`)
- Ticket lifecycle → Ticket timing ledger: uses timing (evidence: `backend/src/modules/operations/tickets/tickets.service.ts`)
- Ticket lifecycle → Event logger: logs actions (evidence: `backend/src/modules/operations/tickets/tickets.service.ts`)
- Ticket lifecycle → Notifications: dispatches events (evidence: `backend/src/modules/operations/tickets/tickets.service.ts`)
- Ticket lifecycle → Realtime gateway: emits updates (evidence: `backend/src/modules/operations/tickets/tickets.service.ts`)
- Ticket lifecycle → Prisma data access: reads and writes (evidence: `backend/src/modules/operations/tickets/tickets.service.ts`)
- Ticket lifecycle → File uploads: serves attachments (evidence: `backend/src/modules/operations/tickets/tickets.controller.ts`)
- Project tracking → Prisma data access: persists projects
- Leave approvals → Prisma data access: persists requests
- Attendance operations → Prisma data access: stores attendance
- Punch capture → Punch photo upload: uploads photo (evidence: `frontend/components/attendance/useAttendanceCamera.ts`)
- Punch photo upload → Cloudinary: stores photos (evidence: `backend/src/modules/platform/attendance/punch/punch-photo.storage.ts`)
- Sales CRM → Prisma data access: persists leads
- AI assistance → OpenAI: requests assistance
- Notifications → Realtime gateway: broadcasts realtime
- Email service → SMTP mail: sends messages
- Activity events → Access policy: checks visibility (evidence: `backend/src/modules/platform/events/events.controller.ts`)
- Activity events → Prisma data access: queries events (evidence: `backend/src/modules/platform/events/events.controller.ts`)
- Activity events → Event logger: uses event history (evidence: `backend/src/modules/platform/events/events.controller.ts`)
- Event logger → Prisma data access: writes events (evidence: `backend/src/common/services/event-logger.service.ts`)
- Prisma data access → PostgreSQL: connects
