# saumyaadani05/dsr-manager architecture

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

- Interactive diagram: https://gitdiagram.com/saumyaadani05/dsr-manager
- Repository: https://github.com/saumyaadani05/dsr-manager

## Overview

1. **Overall shape**
   - DSR Manager is a single-page React application, built with Vite and styled with Tailwind CSS.
   - It is designed as an **offline-first PWA** for gas station daily sales register workflows, not as a traditional server-rendered app.

2. **Primary runtime boundary**
   - All user interaction happens in the browser.
   - The app stores operational data locally in **IndexedDB via Dexie** first, so the UI can continue working without a network connection.
   - Supabase is used as the cloud backend for authentication and synchronization, but not as the immediate runtime dependency for normal usage.

3. **Main data flow**
   - User actions in feature screens go through feature services in `src/services`.
   - Those services write to local storage (`src/db/localDB.js`) and calculate domain values with utilities in `src/utils`.
   - A sync layer then pushes queued changes to Supabase when connectivity returns, and the UI reflects both online status and sync state.

4. **Core domain area: shift / DSR recording**
   - The central business object is the daily shift record: nozzle readings, sales quantities, cash/online/credit totals, and shift-based summaries.
   - The `src/components/shift` area holds the main data-entry and summary UI, while `src/services/shiftService.js` and `src/services/dailyRecordService.js` handle persistence and business logic.
   - `src/hooks/useShiftData.js` and `src/context/ShiftContext.jsx` are the coordination layer for loading and presenting shift data.

5. **Operational modules around the core register**
   - **Bills**: daily bill views and party bill details live under `src/components/bills` and are backed by `billService.js`.
   - **Attendance**: employee attendance, advances, and salary payments are handled in `src/components/attendance` with `attendanceService.js` and `advanceService.js`.
   - **Party management**: credit-party data and billing are isolated in `src/pages/PartyManagementPage.jsx` and `partyService.js`.
   - **Settings/admin**: station configuration, nozzles, employees, security questions, and password changes are handled in `src/components/settings` and `settingsService.js`.

6. **Screen structure**
   - Route-level pages in `src/pages` are the app’s primary navigation boundaries: dashboard, attendance, bills, calendar, history, employee profile, login/reset, settings, and party management.
   - These pages assemble feature components and rarely contain domain logic themselves; they mainly connect routing to the underlying contexts and services.

7. **State and cross-cutting concerns**
   - `AuthContext`, `SettingsContext`, `ShiftContext`, and `SyncContext` are the app-wide state layers.
   - `useOnlineStatus` provides connectivity awareness, and the layout components show status with banners/indicators so the user can see offline and sync conditions.
   - This makes auth, configuration, shift data, and synchronization separate concerns rather than a single monolithic store.

8. **Authentication and access control**
   - Supabase authentication is wrapped by `authService.js`, `LoginPage`, `LoginForm`, `ForgotPassword`, and `ProtectedRoute`.
   - The frontend enforces route protection, while the backend database uses **Row Level Security** so cloud data is isolated per user.
   - `supabase_schema.sql` is the key backend artifact defining that security model and the required tables/policies.

9. **Export and reporting pipeline**
   - Reporting is handled on the client side, not by a dedicated server.
   - `src/components/export` and `exportService.js` generate DSR exports, monthly reports, and bill outputs using **SheetJS** for Excel and **jsPDF** for PDF.
   - This means report generation depends on the locally available dataset, which is important for offline operation.

10. **Sync and resilience**
   - `syncService.js`, `read_sync_queue.js`, and `check_db.js` indicate an explicit offline queue/inspection layer around synchronization and local database health.
   - The app is built to tolerate intermittent connectivity: users keep working locally, then queued changes are reconciled later with Supabase.
   - `src/services/cleanupService.js` suggests maintenance of local or sync-related artifacts to keep the offline store manageable.

11. **UI composition**
   - The app uses reusable UI primitives in `src/components/ui` and shared layout shell components in `src/components/layout`.
   - Feature components are grouped by domain rather than by generic widget type, which supports a diagram where each business area hangs off a common shell.

12. **Deployment and platform**
   - The app is intended for browser deployment, with `vercel.json` included for Vercel hosting.
   - `public/` contains PWA icons and static assets, and the README references Vite PWA/Workbox support for installability and offline behavior.

13. **Documentation as architecture source**
   - The `files/` directory contains PRD, TRD, flow, schema, and UX documents, which act as the system’s design reference set.
   - `supabase_schema.sql` is the authoritative cloud schema artifact, while `src/db/localDB.js` is the authoritative local persistence entry point.

14. **Key architectural takeaway**
   - The system is best diagrammed as a **browser-first domain app** with four main layers: UI pages/components, app state/context, service/business logic, and persistence/sync.
   - The critical boundary is between **local offline persistence** and **Supabase cloud sync/auth**, with all operational workflows centered on the local database and only secondarily replicated to the backend.

Main entry points: [`src/db/localDB.js`](https://github.com/saumyaadani05/dsr-manager/blob/main/src/db/localDB.js) (Local DB), [`src/App.jsx`](https://github.com/saumyaadani05/dsr-manager/blob/main/src/App.jsx) (App Shell), [`src/components/shift`](https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/shift) (Shift Entry), [`src/pages/DashboardPage.jsx`](https://github.com/saumyaadani05/dsr-manager/blob/main/src/pages/DashboardPage.jsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI Shell"]
  node_node_app["App Shell<br/>react entry<br/>[App.jsx]"]
  node_node_layout["Layout<br/>shell"]
  node_node_ui["UI Primitives<br/>shared controls"]
end

subgraph group_group_pages["Pages"]
  node_node_dashboard["Dashboard<br/>page<br/>[DashboardPage.jsx]"]
end

subgraph group_group_core["Core Workflow"]
  node_node_shift["Shift Entry<br/>feature UI"]
  node_node_shift_service["Shift Service<br/>domain service<br/>[shiftService.js]"]
  node_node_daily_record["Daily Records<br/>domain service"]
  node_node_bill["Bills<br/>feature service<br/>[billService.js]"]
  node_node_attendance["Attendance<br/>feature service"]
  node_node_party["Party Mgmt<br/>feature service<br/>[partyService.js]"]
  node_node_settings["Settings<br/>admin service<br/>[settingsService.js]"]
  node_node_export["Exports<br/>reporting<br/>[exportService.js]"]
end

subgraph group_group_state["State"]
  node_node_shift_ctx(("Shift State<br/>context+hook<br/>[ShiftContext.jsx]"))
  node_node_shift_hooks(("Shift Hooks<br/>[useShiftData.js]"))
  node_node_settings_ctx(("Settings State<br/>context"))
  node_node_auth_ctx(("Auth State<br/>context<br/>[AuthContext.jsx]"))
  node_node_sync_ctx(("Sync State<br/>context<br/>[SyncContext.jsx]"))
end

subgraph group_group_data["Data & Sync"]
  node_node_localdb[("Local DB<br/>IndexedDB<br/>[localDB.js]")]
  node_node_supabase[("Supabase<br/>cloud backend<br/>[supabaseClient.js]")]
  node_node_sync["Sync Service<br/>sync pipeline<br/>[syncService.js]"]
  node_node_auth["Auth Service<br/>[authService.js]"]
end

subgraph group_group_docs["Docs & Deployment"]
  node_node_docs["Design Docs"]
  node_node_schema["RLS Schema<br/>sql schema"]
  node_node_deploy["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_node_app -->|"renders"| node_node_layout
node_node_app -->|"routes to"| node_node_dashboard
node_node_app -->|"mounts"| node_node_shift
node_node_app -->|"wraps"| node_node_auth_ctx
node_node_app -->|"wraps"| node_node_sync_ctx
node_node_layout -->|"uses"| node_node_ui
node_node_dashboard -->|"reads"| node_node_shift_ctx
node_node_dashboard -->|"shows"| node_node_sync_ctx
node_node_shift -->|"consumes"| node_node_shift_ctx
node_node_shift -->|"derives"| node_node_shift_hooks
node_node_shift -->|"uses"| node_node_ui
node_node_shift_ctx -->|"loads/saves"| node_node_shift_service
node_node_shift_hooks -->|"computes"| node_node_daily_record
node_node_shift_service -->|"persists"| node_node_localdb
node_node_daily_record -->|"reads/writes"| node_node_localdb
node_node_sync -->|"drains queue"| node_node_localdb
node_node_sync -->|"pushes/pulls"| node_node_supabase
node_node_auth -->|"authenticates"| node_node_supabase
node_node_auth_ctx -->|"wraps"| node_node_auth
node_node_sync_ctx -->|"drives"| node_node_sync
node_node_settings_ctx -->|"coordinates"| node_node_settings
node_node_bill -->|"reads"| node_node_localdb
node_node_attendance -->|"reads/writes"| node_node_localdb
node_node_party -->|"reads/writes"| node_node_localdb
node_node_settings -->|"persists"| node_node_localdb
node_node_export -->|"exports from"| node_node_localdb
node_node_export -->|"summarizes"| node_node_shift_service
node_node_schema -->|"defines"| node_node_supabase
node_node_docs -.->|"describes"| node_node_export
node_node_deploy -->|"hosts"| node_node_app

click node_node_app "https://github.com/saumyaadani05/dsr-manager/blob/main/src/App.jsx"
click node_node_layout "https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/layout"
click node_node_ui "https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/ui"
click node_node_dashboard "https://github.com/saumyaadani05/dsr-manager/blob/main/src/pages/DashboardPage.jsx"
click node_node_shift "https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/shift"
click node_node_shift_ctx "https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/ShiftContext.jsx"
click node_node_shift_hooks "https://github.com/saumyaadani05/dsr-manager/blob/main/src/hooks/useShiftData.js"
click node_node_settings_ctx "https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/SettingsContext.jsx"
click node_node_auth_ctx "https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/AuthContext.jsx"
click node_node_sync_ctx "https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/SyncContext.jsx"
click node_node_localdb "https://github.com/saumyaadani05/dsr-manager/blob/main/src/db/localDB.js"
click node_node_supabase "https://github.com/saumyaadani05/dsr-manager/blob/main/src/db/supabaseClient.js"
click node_node_sync "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/syncService.js"
click node_node_auth "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/authService.js"
click node_node_shift_service "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/shiftService.js"
click node_node_daily_record "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/dailyRecordService.js"
click node_node_bill "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/billService.js"
click node_node_attendance "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/attendanceService.js"
click node_node_party "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/partyService.js"
click node_node_settings "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/settingsService.js"
click node_node_export "https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/exportService.js"
click node_node_docs "https://github.com/saumyaadani05/dsr-manager/tree/main/files"
click node_node_schema "https://github.com/saumyaadani05/dsr-manager/blob/main/supabase_schema.sql"
click node_node_deploy "https://github.com/saumyaadani05/dsr-manager/blob/main/vercel.json"

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_app,node_node_layout,node_node_ui toneBlue
class node_node_dashboard toneAmber
class node_node_shift,node_node_shift_service,node_node_daily_record,node_node_bill,node_node_attendance,node_node_party,node_node_settings,node_node_export toneMint
class node_node_shift_ctx,node_node_shift_hooks,node_node_settings_ctx,node_node_auth_ctx,node_node_sync_ctx toneRose
class node_node_localdb,node_node_supabase,node_node_sync,node_node_auth toneIndigo
class node_node_docs,node_node_schema,node_node_deploy toneTeal
```

## Components

### UI Shell

Reusable layout and shared UI primitives

- [App Shell](https://github.com/saumyaadani05/dsr-manager/blob/main/src/App.jsx): react entry · Bootstraps the SPA and route composition · `src/App.jsx`
- [Layout](https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/layout): shell · Header, drawer, offline banner, sync indicator · `src/components/layout`
- [UI Primitives](https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/ui): shared controls · Reusable buttons, inputs, modal and feedback components · `src/components/ui`

### Pages

Route-level navigation screens

- [Dashboard](https://github.com/saumyaadani05/dsr-manager/blob/main/src/pages/DashboardPage.jsx): page · Primary landing view and status overview · `src/pages/DashboardPage.jsx`

### Core Workflow

Shift / DSR recording and adjacent operational flows

- [Shift Entry](https://github.com/saumyaadani05/dsr-manager/tree/main/src/components/shift): feature UI · Daily record form, grid, totals and cash-party handling · `src/components/shift`
- [Shift Service](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/shiftService.js): domain service · Shift persistence and business rules · `src/services/shiftService.js`
- [Daily Records](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/dailyRecordService.js): domain service · Daily sales register and summary logic · `src/services/dailyRecordService.js`
- [Bills](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/billService.js): feature service · Daily bill views and party bill details · `src/services/billService.js`
- [Attendance](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/attendanceService.js): feature service · Attendance, advances, and salary operations · `src/services/attendanceService.js`
- [Party Mgmt](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/partyService.js): feature service · Credit-party data and billing support · `src/services/partyService.js`
- [Settings](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/settingsService.js): admin service · Station configuration, nozzles, employees and security data · `src/services/settingsService.js`
- [Exports](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/exportService.js): reporting · DSR, monthly reports, Excel and PDF generation · `src/services/exportService.js`

### State

App-wide context and hooks

- [Shift State](https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/ShiftContext.jsx): context+hook · Loads and presents shift data for the core workflow · `src/context/ShiftContext.jsx`
- [Shift Hooks](https://github.com/saumyaadani05/dsr-manager/blob/main/src/hooks/useShiftData.js): hook · Derived shift data and carryover coordination · `src/hooks/useShiftData.js`
- [Settings State](https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/SettingsContext.jsx): context · Station configuration and employee-related state · `src/context/SettingsContext.jsx`
- [Auth State](https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/AuthContext.jsx): context · Session and access control state · `src/context/AuthContext.jsx`
- [Sync State](https://github.com/saumyaadani05/dsr-manager/blob/main/src/context/SyncContext.jsx): context · Connectivity and synchronization status · `src/context/SyncContext.jsx`

### Data & Sync

Local persistence, cloud integration, and sync

- [Local DB](https://github.com/saumyaadani05/dsr-manager/blob/main/src/db/localDB.js): IndexedDB · Offline-first local persistence entry point · `src/db/localDB.js`
- [Supabase](https://github.com/saumyaadani05/dsr-manager/blob/main/src/db/supabaseClient.js): cloud backend · Auth, remote data, and row-level security boundary · `src/db/supabaseClient.js`
- [Sync Service](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/syncService.js): sync pipeline · Queues, reconciles, and inspects offline changes · `src/services/syncService.js`
- [Auth Service](https://github.com/saumyaadani05/dsr-manager/blob/main/src/services/authService.js): auth service · Wraps sign-in, reset, and protected access flows · `src/services/authService.js`

### Docs & Deployment

Reference docs and hosting assets

- [Design Docs](https://github.com/saumyaadani05/dsr-manager/tree/main/files): docs · PRD, TRD, flow, schema and UX references · `files`
- [RLS Schema](https://github.com/saumyaadani05/dsr-manager/blob/main/supabase_schema.sql): sql schema · Authoritative backend tables and security policies · `supabase_schema.sql`
- [Vercel](https://github.com/saumyaadani05/dsr-manager/blob/main/vercel.json): deployment · Browser deployment configuration · `vercel.json`

## Connections

- App Shell → Layout: renders · The app shell composes the shared layout
- App Shell → Dashboard: routes to · Primary navigation begins at route-level pages
- App Shell → Shift Entry: mounts · Core workflow screens are composed into the SPA
- App Shell → Auth State: wraps · Authentication state gates the application
- App Shell → Sync State: wraps · Sync status is available app-wide
- Layout → UI Primitives: uses · Layout is built from shared UI primitives
- Dashboard → Shift State: reads · Dashboard reflects current shift state
- Dashboard → Sync State: shows · Dashboard can surface sync/offline status
- Shift Entry → Shift State: consumes · Shift entry UI is driven by coordinated shift state
- Shift Entry → Shift Hooks: derives · Derived values and carryover logic feed the form
- Shift Entry → UI Primitives: uses · Feature UI is assembled from reusable controls
- Shift State → Shift Service: loads/saves · Context coordinates persistence through shift services
- Shift Hooks → Daily Records: computes · Hook layer relies on daily record domain logic
- Shift Service → Local DB: persists · Shift data is stored locally first
- Daily Records → Local DB: reads/writes · Daily register data is maintained in IndexedDB
- Sync Service → Local DB: drains queue · Sync reconciles queued local changes
- Sync Service → Supabase: pushes/pulls · Cloud sync happens through Supabase
- Auth Service → Supabase: authenticates · Authentication is delegated to Supabase
- Auth State → Auth Service: wraps · Auth context exposes the auth service to the app
- Sync State → Sync Service: drives · Context exposes sync state and actions
- Settings State → Settings: coordinates · Settings state feeds admin configuration flows
- Bills → Local DB: reads · Bills are generated from locally available data
- Attendance → Local DB: reads/writes · Attendance and payroll data are stored locally
- Party Mgmt → Local DB: reads/writes · Party data and billing records are persisted locally
- Settings → Local DB: persists · Station configuration is saved in local storage first
- Exports → Local DB: exports from · Reports are generated from the offline dataset
- Exports → Shift Service: summarizes · Exports depend on shift and register data
- RLS Schema → Supabase: defines · Backend schema and policies define the cloud boundary
- Design Docs → Exports: describes · Design docs document operational reporting flows
- Vercel → App Shell: hosts · Deployment config targets the browser SPA
