# adilmunawar/adicorp architecture

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

- Interactive diagram: https://gitdiagram.com/adilmunawar/adicorp
- Repository: https://github.com/adilmunawar/adicorp

## Overview

1. **What this repo is**
   - This is a **frontend-first HRMS SPA** for Adicorp, built with **React + TypeScript + Vite**.
   - The architecture is centered around **client-side routes, reusable UI modules, and a Supabase backend** for auth/data/storage. There is no traditional server app in this repo.

2. **Top-level application shape**
   - `src/main.tsx` bootstraps the app.
   - `src/App.tsx` and the `src/pages/*` directory define the route-level screens.
   - The app is split into two major experience areas:
     - **Admin/dashboard workspace**
     - **Employee portal** under `src/pages/portal/*`

3. **Routing and layout boundary**
   - Layout composition lives in `src/components/layout/*`:
     - `Dashboard.tsx`, `Sidebar.tsx`, `Header.tsx`, `PrivateRoute.tsx`
     - `EmployeePortalLayout.tsx` for the portal side
     - `AnimatedRoute.tsx`, `PageTransition.tsx` for navigation effects
   - This is the main boundary between **authenticated app shell** and **individual feature pages**.

4. **Authentication and access control**
   - `src/context/AuthContext.tsx` handles the main user/session auth state.
   - `src/context/EmployeeAuthContext.tsx` isolates the employee portal authentication flow.
   - Supporting auth screens include:
     - `src/components/auth/AuthForm.tsx`
     - `ForgotPasswordForm.tsx`
     - `BiometricLockScreen.tsx`
   - `src/lib/authRedirect.ts` and `PrivateRoute.tsx` suggest route guarding and role-based redirect logic.

5. **Core domain subsystems**
   - The feature folders under `src/components/*` map directly to business modules:
     - **Employees**: profiles, import/export, document management
     - **Attendance**: attendance table, bulk actions
     - **Leave**: requests, balances, leave-type configuration
     - **Overtime**: entry, records, policy/config panels
     - **Salary / payroll**: salary sheets, payslips, stats, history
     - **Events**: event managers, recurring/advanced scheduling
     - **Reports / timeline / backup / settings**
   - This is a modular HRMS, not a single monolithic page.

6. **Dashboard and analytics layer**
   - `src/components/dashboard/*` powers the main management overview:
     - stats cards, analytics widgets, activity feed, recent documents, attendance chart
   - These components aggregate data from multiple business domains to present operational status.
   - `src/pages/Dashboard.tsx` is the primary landing page for the admin workspace.

7. **Data access and backend integration**
   - `src/integrations/supabase/client.ts` is the main backend client entrypoint.
   - `src/integrations/supabase/types.ts` and `src/types/supabase.ts` indicate typed database access.
   - `supabase/migrations/*` and `supabase/config.toml` show the **database schema is managed as code** and lives outside the frontend bundle.
   - The backend boundary is therefore:
     - **React UI → hooks/services → Supabase client → Supabase Auth/Postgres/Storage**

8. **Service and computation boundary**
   - Business aggregation and non-UI logic are separated into:
     - `src/services/dataIntegrationService.ts`
     - `src/services/reportDataService.ts`
   - Calculation/utilities live in:
     - `src/utils/salaryCalculations.ts`
     - `src/utils/workingDays.ts`
     - `src/utils/cache.ts`
   - This is where payroll rules, report shaping, and working-day logic are kept out of components.

9. **Stateful hooks and cross-cutting concerns**
   - Custom hooks in `src/hooks/*` provide reusable state/data flows:
     - `useEmployeePortalData`, `useSalaryData`, `useSalaryDownloads`
     - `useActivityLogger`, `useBiometric`, `useCurrency`
     - `use-toast`, `use-mobile`
   - These act as the glue between UI and domain services, especially for derived data, downloads, and device-specific behavior.

10. **Shared UI system**
   - `src/components/ui/*` is a large design-system layer, likely based on **shadcn/ui + Radix + Tailwind**.
   - It supplies tables, dialogs, dropdowns, forms, toasts, sheets, calendars, charts, etc.
   - `src/components/common/*` adds app-specific shared pieces like loaders, month selector, error boundary, and permission error handling.

11. **Employee portal as a separate sub-application**
   - `src/pages/portal/*` implements a distinct employee-facing experience:
     - login, profile, attendance, overtime, payroll, records, reports, settings, password setup
   - `src/components/layout/EmployeePortalLayout.tsx` and `src/context/EmployeeAuthContext.tsx` show this is intentionally separated from the admin workspace.

12. **Static assets, uploads, and deployment**
   - `public/` contains static assets and uploaded/public files.
   - `vercel.json` indicates deployment is intended for **Vercel**.
   - `tailwind.config.ts`, `postcss.config.js`, and `components.json` indicate a Tailwind/shadcn-based frontend toolchain.

13. **What to draw in an architecture diagram**
   - Draw **two user entry paths**: Admin dashboard and Employee portal.
   - Show both paths going through **auth/context + private routing**.
   - Show feature pages using **shared UI components** and **domain hooks/services**.
   - Show services/hooks connecting to **Supabase** for auth, database, and storage.
   - Treat `supabase/migrations` as the **schema/infra source of truth**, separate from the React app.

Main entry points: [`src/pages`](https://github.com/adilmunawar/adicorp/tree/main/src/pages) (Admin pages), [`src/hooks`](https://github.com/adilmunawar/adicorp/tree/main/src/hooks) (Hooks), [`src/App.tsx`](https://github.com/adilmunawar/adicorp/blob/main/src/App.tsx) (App shell), [`src/pages/portal`](https://github.com/adilmunawar/adicorp/tree/main/src/pages/portal) (Employee portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["React app"]
  node_node_main(("Main<br/>bootstrap<br/>[main.tsx]"))
  node_node_app["App shell<br/>routing<br/>[App.tsx]"]
  node_node_admin_pages["Admin pages<br/>screens"]
  node_node_portal_pages["Employee portal<br/>sub-app"]
end

subgraph group_group_domain["HR modules"]
  node_node_dashboard["Dashboard<br/>analytics layer"]
  node_node_employees["Employees<br/>people module"]
  node_node_attendance["Attendance<br/>time tracking"]
  node_node_leave["Leave<br/>absence module"]
  node_node_overtime["Overtime<br/>policy module"]
  node_node_salary["Salary<br/>payroll module"]
  node_node_events["Events<br/>scheduling"]
  node_node_settings["Settings<br/>admin config"]
end

subgraph group_group_shared["Shared layer"]
  node_node_layouts["Layouts<br/>shells"]
  node_node_auth_ctx(("Auth state<br/>auth context"))
  node_node_auth_ui["Auth screens<br/>auth ui"]
  node_node_services["Services<br/>business logic"]
  node_node_hooks["Hooks<br/>state glue"]
  node_node_ui["UI kit<br/>design system"]
  node_node_utils["Utilities<br/>calc helpers"]
end

subgraph group_group_backend["Supabase backend"]
  node_node_supabase_client(("Supabase client<br/>backend client<br/>[client.ts]"))
  node_node_supabase_types["Supabase types<br/>db typings<br/>[types.ts]"]
  node_node_migrations[("Migrations<br/>schema source")]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"uses"| node_node_layouts
node_node_app -->|"routes to"| node_node_admin_pages
node_node_app -->|"routes to"| node_node_portal_pages
node_node_layouts -->|"protects"| node_node_auth_ctx
node_node_layouts -->|"renders"| node_node_auth_ui
node_node_admin_pages -->|"landing"| node_node_dashboard
node_node_admin_pages -->|"includes"| node_node_employees
node_node_admin_pages -->|"includes"| node_node_attendance
node_node_admin_pages -->|"includes"| node_node_leave
node_node_admin_pages -->|"includes"| node_node_overtime
node_node_admin_pages -->|"includes"| node_node_salary
node_node_admin_pages -->|"includes"| node_node_events
node_node_admin_pages -->|"includes"| node_node_settings
node_node_portal_pages -->|"uses"| node_node_auth_ctx
node_node_dashboard -->|"reads via"| node_node_hooks
node_node_employees -->|"uses"| node_node_hooks
node_node_attendance -->|"uses"| node_node_hooks
node_node_leave -->|"uses"| node_node_hooks
node_node_overtime -->|"uses"| node_node_hooks
node_node_salary -->|"calculates via"| node_node_services
node_node_portal_pages -->|"reads via"| node_node_services
node_node_hooks -->|"calls"| node_node_supabase_client
node_node_services -->|"calls"| node_node_supabase_client
node_node_supabase_client -->|"typed by"| node_node_supabase_types
node_node_supabase_client -->|"backed by"| node_node_migrations
node_node_ui -->|"supports"| node_node_admin_pages
node_node_ui -->|"supports"| node_node_portal_pages
node_node_utils -->|"supports"| node_node_services
node_node_utils -->|"supports"| node_node_hooks

click node_node_main "https://github.com/adilmunawar/adicorp/blob/main/src/main.tsx"
click node_node_app "https://github.com/adilmunawar/adicorp/blob/main/src/App.tsx"
click node_node_admin_pages "https://github.com/adilmunawar/adicorp/tree/main/src/pages"
click node_node_portal_pages "https://github.com/adilmunawar/adicorp/tree/main/src/pages/portal"
click node_node_layouts "https://github.com/adilmunawar/adicorp/tree/main/src/components/layout"
click node_node_auth_ctx "https://github.com/adilmunawar/adicorp/tree/main/src/context"
click node_node_auth_ui "https://github.com/adilmunawar/adicorp/tree/main/src/components/auth"
click node_node_dashboard "https://github.com/adilmunawar/adicorp/tree/main/src/components/dashboard"
click node_node_employees "https://github.com/adilmunawar/adicorp/tree/main/src/components/employees"
click node_node_attendance "https://github.com/adilmunawar/adicorp/tree/main/src/components/attendance"
click node_node_leave "https://github.com/adilmunawar/adicorp/tree/main/src/components/leave"
click node_node_overtime "https://github.com/adilmunawar/adicorp/tree/main/src/components/overtime"
click node_node_salary "https://github.com/adilmunawar/adicorp/tree/main/src/components/salary"
click node_node_events "https://github.com/adilmunawar/adicorp/tree/main/src/components/events"
click node_node_settings "https://github.com/adilmunawar/adicorp/tree/main/src/components/settings"
click node_node_services "https://github.com/adilmunawar/adicorp/tree/main/src/services"
click node_node_hooks "https://github.com/adilmunawar/adicorp/tree/main/src/hooks"
click node_node_ui "https://github.com/adilmunawar/adicorp/tree/main/src/components/ui"
click node_node_utils "https://github.com/adilmunawar/adicorp/tree/main/src/utils"
click node_node_supabase_client "https://github.com/adilmunawar/adicorp/blob/main/src/integrations/supabase/client.ts"
click node_node_supabase_types "https://github.com/adilmunawar/adicorp/blob/main/src/integrations/supabase/types.ts"
click node_node_migrations "https://github.com/adilmunawar/adicorp/tree/main/supabase/migrations"

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_node_main,node_node_app,node_node_admin_pages,node_node_portal_pages toneBlue
class node_node_dashboard,node_node_employees,node_node_attendance,node_node_leave,node_node_overtime,node_node_salary,node_node_events,node_node_settings toneAmber
class node_node_layouts,node_node_auth_ctx,node_node_auth_ui,node_node_services,node_node_hooks,node_node_ui,node_node_utils toneMint
class node_node_supabase_client,node_node_supabase_types,node_node_migrations toneRose
```

## Components

### React app

Frontend entrypoints, route screens, and application shell.

- [Main](https://github.com/adilmunawar/adicorp/blob/main/src/main.tsx): bootstrap · Vite entry that mounts the React app. · `src/main.tsx`
- [App shell](https://github.com/adilmunawar/adicorp/blob/main/src/App.tsx): routing · Top-level app composition and route wiring. · `src/App.tsx`
- [Admin pages](https://github.com/adilmunawar/adicorp/tree/main/src/pages): screens · Dashboard and admin workspace route screens. · `src/pages`
- [Employee portal](https://github.com/adilmunawar/adicorp/tree/main/src/pages/portal): sub-app · Employee-facing portal pages and flows. · `src/pages/portal`

### HR modules

Business feature areas for admin and portal workflows.

- [Dashboard](https://github.com/adilmunawar/adicorp/tree/main/src/components/dashboard): analytics layer · Operational overview aggregating activity, attendance, docs, and stats. · `src/components/dashboard`
- [Employees](https://github.com/adilmunawar/adicorp/tree/main/src/components/employees): people module · Profiles, import/export, documents, and employee lists/forms. · `src/components/employees`
- [Attendance](https://github.com/adilmunawar/adicorp/tree/main/src/components/attendance): time tracking · Attendance table and bulk action workflows. · `src/components/attendance`
- [Leave](https://github.com/adilmunawar/adicorp/tree/main/src/components/leave): absence module · Leave requests, balances, and leave-type configuration. · `src/components/leave`
- [Overtime](https://github.com/adilmunawar/adicorp/tree/main/src/components/overtime): policy module · Overtime entry, records, and policy configuration. · `src/components/overtime`
- [Salary](https://github.com/adilmunawar/adicorp/tree/main/src/components/salary): payroll module · Salary sheets, payslips, history, and payroll stats. · `src/components/salary`
- [Events](https://github.com/adilmunawar/adicorp/tree/main/src/components/events): scheduling · Event management with recurring and advanced scheduling. · `src/components/events`
- [Settings](https://github.com/adilmunawar/adicorp/tree/main/src/components/settings): admin config · Company, working time, currency, security, and password settings. · `src/components/settings`

### Shared layer

Reusable UI, hooks, context, services, and utilities.

- [Layouts](https://github.com/adilmunawar/adicorp/tree/main/src/components/layout): shells · Authenticated shells, navigation, transitions, and route guards. · `src/components/layout`
- [Auth state](https://github.com/adilmunawar/adicorp/tree/main/src/context): auth context · Main session/auth and employee portal auth contexts. · `src/context`
- [Auth screens](https://github.com/adilmunawar/adicorp/tree/main/src/components/auth): auth ui · Login, recovery, and biometric lock UI. · `src/components/auth`
- [Services](https://github.com/adilmunawar/adicorp/tree/main/src/services): business logic · Data integration and report shaping services. · `src/services`
- [Hooks](https://github.com/adilmunawar/adicorp/tree/main/src/hooks): state glue · Reusable data, device, biometric, currency, download, and logging hooks. · `src/hooks`
- [UI kit](https://github.com/adilmunawar/adicorp/tree/main/src/components/ui): design system · Reusable shadcn-style UI primitives and app-specific shared components. · `src/components/ui`
- [Utilities](https://github.com/adilmunawar/adicorp/tree/main/src/utils): calc helpers · Salary, working-day, cache, branding, and permission helpers. · `src/utils`

### Supabase backend

Client integration and schema/migration source of truth.

- [Supabase client](https://github.com/adilmunawar/adicorp/blob/main/src/integrations/supabase/client.ts): backend client · Frontend client entrypoint for auth, database, and storage access. · `src/integrations/supabase/client.ts`
- [Supabase types](https://github.com/adilmunawar/adicorp/blob/main/src/integrations/supabase/types.ts): db typings · Generated database types used by the frontend. · `src/integrations/supabase/types.ts`
- [Migrations](https://github.com/adilmunawar/adicorp/tree/main/supabase/migrations): schema source · Supabase SQL migrations and config managed as code. · `supabase/migrations`

## Connections

- Main → App shell: boots · Application bootstrap mounts the routed SPA.
- App shell → Layouts: uses · Routes compose the authenticated shell and portal layout.
- App shell → Admin pages: routes to · Admin workspace screens are routed from the app shell.
- App shell → Employee portal: routes to · Employee portal screens are routed separately.
- Layouts → Auth state: protects · Private routing and session state gate access.
- Layouts → Auth screens: renders · Layout and auth flows present sign-in and recovery screens.
- Admin pages → Dashboard: landing · Dashboard is the primary admin overview page.
- Admin pages → Employees: includes · Admin workspace exposes employee management.
- Admin pages → Attendance: includes · Admin workspace exposes attendance management.
- Admin pages → Leave: includes · Admin workspace exposes leave management.
- Admin pages → Overtime: includes · Admin workspace exposes overtime management.
- Admin pages → Salary: includes · Admin workspace exposes payroll management.
- Admin pages → Events: includes · Admin workspace exposes event scheduling.
- Admin pages → Settings: includes · Admin workspace exposes configuration screens.
- Employee portal → Auth state: uses · Employee portal has its own auth context and session flow.
- Dashboard → Hooks: reads via · Dashboard widgets aggregate state through hooks.
- Employees → Hooks: uses · Employee workflows use reusable data and logging hooks.
- Attendance → Hooks: uses · Attendance screens use shared state/data hooks.
- Leave → Hooks: uses · Leave flows rely on shared state and data hooks.
- Overtime → Hooks: uses · Overtime flows rely on shared state and data hooks.
- Salary → Services: calculates via · Payroll views rely on aggregation and report services.
- Employee portal → Services: reads via · Portal pages use shared report and data integration services.
- Hooks → Supabase client: calls · Hooks connect UI state to backend data and auth.
- Services → Supabase client: calls · Business services fetch and shape Supabase data.
- Supabase client → Supabase types: typed by · Client operations use generated database types.
- Supabase client → Migrations: backed by · Client data access corresponds to the managed schema.
- UI kit → Admin pages: supports · Feature pages are built from shared UI primitives.
- UI kit → Employee portal: supports · Portal pages also reuse the shared UI system.
- Utilities → Services: supports · Services depend on salary and reporting helpers.
- Utilities → Hooks: supports · Hooks reuse utility logic for device, currency, and cache concerns.
