# abeyakilesh/elgis-production architecture

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

- Interactive diagram: https://gitdiagram.com/abeyakilesh/elgis-production
- Repository: https://github.com/abeyakilesh/elgis-production

## Overview

#### Purpose and Runtime
This is an internal workforce and operations platform, not the generic Vite template described by the README. It combines HR attendance/payroll, sales CRM, orders/invoicing/delivery fulfillment, support tickets, live delivery tracking, and operational diagnostics.

The primary runtime is a React + TypeScript single-page application built with Vite. Browser clients use Supabase for authentication, Postgres data/RPCs, Realtime, Storage, and Edge Functions. Deployment is configured for Vercel. Entry points: `src/main.tsx`, `src/App.tsx`, `src/lib/supabaseClient.ts`, and `vercel.json`.

#### Application Shell, Navigation, and Access Boundary
`src/App.tsx` is the route composition point for the operational workspaces. `src/components/layout/AppLayout.tsx` provides the authenticated shell and app launcher; route boundaries are enforced in `src/components/ProtectedRoute.tsx` and `src/components/RoleRoute.tsx`.

Authentication identity is mapped to employee/role data through `src/lib/useCurrentEmployee.ts` and `src/lib/roles.ts`. The database is the authoritative authorization boundary: migrations establish RLS, scoped policies, auth helper requirements, and revoked public privileges, notably `supabase/migrations/20260835000000_auth_helpers_require_active_status.sql`, `supabase/migrations/20260840000000_sec08_revoke_anon_table_privileges.sql`, and `supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql`.

#### Workforce: Attendance and Payroll
Attendance manages punches, rosters, approvals, attendance overrides, weekly offs, and real-time updates. Its UI and domain layer are centered on `src/pages/Attendance.tsx`, `src/lib/attendance.ts`, and `src/lib/useRealtimePunches.ts`; schema evolution begins in `supabase/migrations/20260707071648_initial_schema.sql` and includes roster/approval migrations.

Payroll is a separate routed workspace for employee compensation, incentives, advances/loans, repayments, reports, and payroll runs: `src/pages/payroll/PayrollLayout.tsx`, `src/lib/payroll.ts`, and `src/lib/advanceHistory.ts`. Financial state transitions and correctness are pushed into database constraints/RPCs, including `supabase/migrations/20260813000100_advance_loan_rpcs.sql`, `supabase/migrations/20260815000000_advance_approval_flow.sql`, and `supabase/migrations/20260850000000_cor01_server_side_finalize.sql`.

#### Commercial, Orders, Invoices, and Deliveries
Sales is a CRM-style workspace for leads, customers, executives, pipeline, analytics, imports/exports, and an AI screen: `src/pages/sales/SalesLayout.tsx`, `src/pages/sales/SalesPipeline.tsx`, and `src/lib/analytics.ts`.

Orders are the commercial transaction boundary, covering creation, branch filtering, detail, invoice views, and delivery creation: `src/pages/orders/OrdersLayout.tsx`, `src/pages/orders/OrderDetailPage.tsx`, and `src/lib/orders.ts`. Database RPCs and migrations model transactional writes, invoice/order schema, financial buckets, and list/dashboard aggregates: `supabase/migrations/20260715220000_order_transaction_rpcs.sql`, `supabase/migrations/20260802000000_orders_invoices_deliveries_schema.sql`, and `supabase/migrations/20260834000000_scale01_server_side_aggregates.sql`.

Delivery fulfillment is decoupled from invoices and includes drivers, vehicles, branches, assigned orders, workflow state, and receiving: `src/pages/orders/DeliveriesPage.tsx`, `src/lib/deliveryOrders.ts`, and `src/pages/ReceiveDeliveries.tsx`. Core evolution appears in `supabase/migrations/20260827000000_decouple_deliveries_from_invoices.sql` and `supabase/migrations/20260828000000_delivery_based_fulfilment.sql`.

#### Field Operations and Support
Tracking consumes driver trips, location pings, stop reviews, messages, and return trips: `src/pages/TrackingDashboard.tsx`, `src/lib/liveDrivers.ts`, and `src/lib/tripRoutes.ts`. The schema and ownership controls are in `supabase/migrations/20260720020000_driver_app_trips_and_versions.sql`, `supabase/migrations/20260720050000_driver_update_own_assigned_orders.sql`, and `supabase/migrations/20260720060000_trip_stop_reviews.sql`.

Tickets provide a support workflow with attachments and events through `src/pages/tickets/TicketsWorkspace.tsx`, `src/pages/tickets/NewTicket.tsx`, and `src/lib/tickets.ts`; persistence and storage limits are established by `supabase/migrations/20260718090000_tickets.sql` and `supabase/migrations/20260718120000_ticket_bucket_10mb.sql`.

#### Operations, AI, and External Services
Mission Control and developer screens surface database, storage, diagnostics, live operations, and security state: `src/pages/missioncontrol/MissionControlLayout.tsx`, `src/lib/missionControl.ts`, and `src/lib/diagnostics.ts`. Health data can cross an Edge Function boundary at `supabase/functions/vps-health/index.ts`.

AI requests are intentionally proxied through Supabase rather than called directly by the client: `src/lib/aiChat.ts`, `supabase/functions/groq-proxy/index.ts`, and `supabase/functions/_shared/auth.ts`. Consent and audit concerns are first-class cross-cutting features via `src/components/ConsentGate.tsx`, `src/lib/dpdpConsent.ts`, and `src/lib/activityLog.ts`.

Main entry points: [`supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql`](https://github.com/abeyakilesh/elgis-production/blob/main/supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql) (Postgres, RPCs and RLS), [`src/components/layout/AppLayout.tsx`](https://github.com/abeyakilesh/elgis-production/blob/main/src/components/layout/AppLayout.tsx) (Authenticated shell), [`src/lib/supabaseClient.ts`](https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/supabaseClient.ts) (Supabase client), [`src/pages/Attendance.tsx`](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/Attendance.tsx) (Attendance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_entry["Vite entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app["Route composition<br/>React application<br/>[App.tsx]"]
  node_shell["Authenticated shell<br/>layout &amp; launcher<br/>[AppLayout.tsx]"]
  node_access["Route and role guards<br/>client access boundary<br/>[ProtectedRoute.tsx]"]
  node_consent_audit["Consent and activity audit<br/>cross-cutting client services<br/>[ConsentGate.tsx]"]
end

subgraph group_workforce["Workforce"]
  node_attendance["Attendance<br/>punches, rosters &amp; approvals<br/>[Attendance.tsx]"]
  node_payroll["Payroll<br/>compensation workspace<br/>[PayrollLayout.tsx]"]
end

subgraph group_commerce["Commercial &amp; Fulfillment"]
  node_sales["Sales CRM<br/>leads, pipeline &amp; analytics<br/>[SalesLayout.tsx]"]
  node_orders["Orders and invoices<br/>commercial transactions<br/>[OrdersLayout.tsx]"]
  node_delivery["Delivery fulfillment<br/>assignment &amp; receiving<br/>[DeliveriesPage.tsx]"]
end

subgraph group_operations["Field Ops &amp; Support"]
  node_tracking["Live delivery tracking<br/>trips, pings &amp; stops"]
  node_tickets["Support tickets<br/>ticket workflow"]
  node_mission_control["Mission Control<br/>operations diagnostics"]
end

subgraph group_platform["Supabase Platform"]
  node_supabase_client{{"Supabase client<br/>browser platform adapter<br/>[supabaseClient.ts]"}}
  node_auth["Auth and employee roles<br/>identity mapping"]
  node_database[("Postgres, RPCs and RLS<br/>authoritative data boundary")]
  node_realtime["Realtime<br/>live data channel"]
  node_storage[("Storage")]
  node_ai_proxy{{"AI proxy function<br/>authenticated Edge Function<br/>[index.ts]"}}
  node_health_function{{"VPS health function<br/>Edge Function<br/>[index.ts]"}}
end

node_entry -->|"boots"| node_app
node_app -->|"composes"| node_shell
node_shell -->|"protects routes"| node_access
node_access -->|"resolves identity and roles"| node_auth
node_auth -->|"reads employee role data"| node_database
node_shell -->|"routes to"| node_attendance
node_shell -->|"routes to"| node_payroll
node_shell -->|"routes to"| node_sales
node_shell -->|"routes to"| node_orders
node_shell -->|"routes to"| node_delivery
node_shell -->|"routes to"| node_tracking
node_shell -->|"routes to"| node_tickets
node_shell -->|"routes to"| node_mission_control
node_attendance -->|"subscribes to punches"| node_realtime
node_attendance -->|"attendance data and approvals"| node_database
node_payroll -->|"payroll RPCs and constraints"| node_database
node_sales -->|"CRM and aggregates"| node_database
node_orders -->|"transaction RPCs"| node_database
node_orders -->|"creates delivery work"| node_delivery
node_delivery -->|"assignments and receiving"| node_database
node_tracking -->|"consumes live trips and pings"| node_realtime
node_tracking -->|"trip ownership and stop reviews"| node_database
node_tickets -->|"tickets and events"| node_database
node_tickets -->|"uploads attachments"| node_storage
node_mission_control -->|"checks VPS health"| node_health_function
node_mission_control -->|"inspects operations state"| node_database
node_consent_audit -->|"records consent and activity"| node_database
node_supabase_client -->|"queries and invokes RPCs"| node_database
node_supabase_client -->|"opens subscriptions"| node_realtime
node_supabase_client -->|"accesses objects"| node_storage
node_ai_proxy -->|"uses shared authorization"| node_database

click node_entry "https://github.com/abeyakilesh/elgis-production/blob/main/src/main.tsx"
click node_app "https://github.com/abeyakilesh/elgis-production/blob/main/src/App.tsx"
click node_shell "https://github.com/abeyakilesh/elgis-production/blob/main/src/components/layout/AppLayout.tsx"
click node_access "https://github.com/abeyakilesh/elgis-production/blob/main/src/components/ProtectedRoute.tsx"
click node_consent_audit "https://github.com/abeyakilesh/elgis-production/blob/main/src/components/ConsentGate.tsx"
click node_attendance "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/Attendance.tsx"
click node_payroll "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/payroll/PayrollLayout.tsx"
click node_sales "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/sales/SalesLayout.tsx"
click node_orders "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/orders/OrdersLayout.tsx"
click node_delivery "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/orders/DeliveriesPage.tsx"
click node_tracking "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/TrackingDashboard.tsx"
click node_tickets "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/tickets/TicketsWorkspace.tsx"
click node_mission_control "https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/missioncontrol/MissionControlLayout.tsx"
click node_supabase_client "https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/supabaseClient.ts"
click node_auth "https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/useCurrentEmployee.ts"
click node_database "https://github.com/abeyakilesh/elgis-production/blob/main/supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql"
click node_realtime "https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/useRealtimePunches.ts"
click node_storage "https://github.com/abeyakilesh/elgis-production/blob/main/supabase/migrations/20260718120000_ticket_bucket_10mb.sql"
click node_ai_proxy "https://github.com/abeyakilesh/elgis-production/blob/main/supabase/functions/groq-proxy/index.ts"
click node_health_function "https://github.com/abeyakilesh/elgis-production/blob/main/supabase/functions/vps-health/index.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_entry,node_app,node_shell,node_access,node_consent_audit toneBlue
class node_attendance,node_payroll toneAmber
class node_sales,node_orders,node_delivery toneMint
class node_tracking,node_tickets,node_mission_control toneRose
class node_supabase_client,node_auth,node_database,node_realtime,node_storage,node_ai_proxy,node_health_function toneIndigo
```

## Components

### React SPA

- [Vite entry](https://github.com/abeyakilesh/elgis-production/blob/main/src/main.tsx): React bootstrap · `src/main.tsx`
- [Route composition](https://github.com/abeyakilesh/elgis-production/blob/main/src/App.tsx): React application · `src/App.tsx`
- [Authenticated shell](https://github.com/abeyakilesh/elgis-production/blob/main/src/components/layout/AppLayout.tsx): layout & launcher · `src/components/layout/AppLayout.tsx`
- [Route and role guards](https://github.com/abeyakilesh/elgis-production/blob/main/src/components/ProtectedRoute.tsx): client access boundary · Maps authenticated identities to employee roles before workspace access. · `src/components/ProtectedRoute.tsx`
- [Consent and activity audit](https://github.com/abeyakilesh/elgis-production/blob/main/src/components/ConsentGate.tsx): cross-cutting client services · `src/components/ConsentGate.tsx`

### Workforce

- [Attendance](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/Attendance.tsx): punches, rosters & approvals · `src/pages/Attendance.tsx`
- [Payroll](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/payroll/PayrollLayout.tsx): compensation workspace · `src/pages/payroll/PayrollLayout.tsx`

### Commercial & Fulfillment

- [Sales CRM](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/sales/SalesLayout.tsx): leads, pipeline & analytics · `src/pages/sales/SalesLayout.tsx`
- [Orders and invoices](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/orders/OrdersLayout.tsx): commercial transactions · `src/pages/orders/OrdersLayout.tsx`
- [Delivery fulfillment](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/orders/DeliveriesPage.tsx): assignment & receiving · Delivery workflows are decoupled from invoices. · `src/pages/orders/DeliveriesPage.tsx`

### Field Ops & Support

- [Live delivery tracking](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/TrackingDashboard.tsx): trips, pings & stops · `src/pages/TrackingDashboard.tsx`
- [Support tickets](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/tickets/TicketsWorkspace.tsx): ticket workflow · Includes attachments and ticket events. · `src/pages/tickets/TicketsWorkspace.tsx`
- [Mission Control](https://github.com/abeyakilesh/elgis-production/blob/main/src/pages/missioncontrol/MissionControlLayout.tsx): operations diagnostics · `src/pages/missioncontrol/MissionControlLayout.tsx`

### Supabase Platform

- [Supabase client](https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/supabaseClient.ts): browser platform adapter · `src/lib/supabaseClient.ts`
- [Auth and employee roles](https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/useCurrentEmployee.ts): identity mapping · `src/lib/useCurrentEmployee.ts`
- [Postgres, RPCs and RLS](https://github.com/abeyakilesh/elgis-production/blob/main/supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql): authoritative data boundary · Migrations enforce scoped policies, active-status helpers, and revoked public privileges. · `supabase/migrations/20260846000000_sec11_narrow_remaining_policies.sql`
- [Realtime](https://github.com/abeyakilesh/elgis-production/blob/main/src/lib/useRealtimePunches.ts): live data channel · `src/lib/useRealtimePunches.ts`
- [Storage](https://github.com/abeyakilesh/elgis-production/blob/main/supabase/migrations/20260718120000_ticket_bucket_10mb.sql): attachment storage · Ticket attachment bucket has a 10 MB limit. · `supabase/migrations/20260718120000_ticket_bucket_10mb.sql`
- [AI proxy function](https://github.com/abeyakilesh/elgis-production/blob/main/supabase/functions/groq-proxy/index.ts): authenticated Edge Function · Keeps AI provider calls off browser clients. · `supabase/functions/groq-proxy/index.ts`
- [VPS health function](https://github.com/abeyakilesh/elgis-production/blob/main/supabase/functions/vps-health/index.ts): Edge Function · `supabase/functions/vps-health/index.ts`

## Connections

- Vite entry → Route composition: boots
- Route composition → Authenticated shell: composes
- Authenticated shell → Route and role guards: protects routes
- Route and role guards → Auth and employee roles: resolves identity and roles
- Auth and employee roles → Postgres, RPCs and RLS: reads employee role data
- Authenticated shell → Attendance: routes to
- Authenticated shell → Payroll: routes to
- Authenticated shell → Sales CRM: routes to
- Authenticated shell → Orders and invoices: routes to
- Authenticated shell → Delivery fulfillment: routes to
- Authenticated shell → Live delivery tracking: routes to
- Authenticated shell → Support tickets: routes to
- Authenticated shell → Mission Control: routes to
- Attendance → Realtime: subscribes to punches
- Attendance → Postgres, RPCs and RLS: attendance data and approvals
- Payroll → Postgres, RPCs and RLS: payroll RPCs and constraints
- Sales CRM → Postgres, RPCs and RLS: CRM and aggregates
- Orders and invoices → Postgres, RPCs and RLS: transaction RPCs
- Orders and invoices → Delivery fulfillment: creates delivery work
- Delivery fulfillment → Postgres, RPCs and RLS: assignments and receiving
- Live delivery tracking → Realtime: consumes live trips and pings
- Live delivery tracking → Postgres, RPCs and RLS: trip ownership and stop reviews
- Support tickets → Postgres, RPCs and RLS: tickets and events
- Support tickets → Storage: uploads attachments
- Mission Control → VPS health function: checks VPS health
- Mission Control → Postgres, RPCs and RLS: inspects operations state
- Consent and activity audit → Postgres, RPCs and RLS: records consent and activity
- Supabase client → Postgres, RPCs and RLS: queries and invokes RPCs
- Supabase client → Realtime: opens subscriptions
- Supabase client → Storage: accesses objects
- AI proxy function → Postgres, RPCs and RLS: uses shared authorization