How saumyaadani05/dsr-manager works
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: localDB.js Local DB · App.jsx App Shell · shift Shift Entry · DashboardPage.jsx Dashboard
Components 24
UI Shell
Reusable layout and shared UI primitives
- App Shell · Bootstraps the SPA and route composition
src/App.jsx - Layout · Header, drawer, offline banner, sync indicator
src/components/layout - UI Primitives · Reusable buttons, inputs, modal and feedback components
src/components/ui
Pages
Route-level navigation screens
- Dashboard · Primary landing view and status overview
src/pages/DashboardPage.jsx
Core Workflow
Shift / DSR recording and adjacent operational flows
- Shift Entry · Daily record form, grid, totals and cash-party handling
src/components/shift - Shift Service · Shift persistence and business rules
src/services/shiftService.js - Daily Records · Daily sales register and summary logic
src/services/dailyRecordService.js - Bills · Daily bill views and party bill details
src/services/billService.js - Attendance · Attendance, advances, and salary operations
src/services/attendanceService.js - Party Mgmt · Credit-party data and billing support
src/services/partyService.js - Settings · Station configuration, nozzles, employees and security data
src/services/settingsService.js - Exports · DSR, monthly reports, Excel and PDF generation
src/services/exportService.js
State
App-wide context and hooks
- Shift State · Loads and presents shift data for the core workflow
src/context/ShiftContext.jsx - Shift Hooks · Derived shift data and carryover coordination
src/hooks/useShiftData.js - Settings State · Station configuration and employee-related state
src/context/SettingsContext.jsx - Auth State · Session and access control state
src/context/AuthContext.jsx - Sync State · Connectivity and synchronization status
src/context/SyncContext.jsx
Data & Sync
Local persistence, cloud integration, and sync
- Local DB · Offline-first local persistence entry point
src/db/localDB.js - Supabase · Auth, remote data, and row-level security boundary
src/db/supabaseClient.js - Sync Service · Queues, reconciles, and inspects offline changes
src/services/syncService.js - Auth Service · Wraps sign-in, reset, and protected access flows
src/services/authService.js
Docs & Deployment
Reference docs and hosting assets
- Design Docs · PRD, TRD, flow, schema and UX references
files - RLS Schema · Authoritative backend tables and security policies
supabase_schema.sql - Vercel · Browser deployment configuration
vercel.json
Connections 30
- 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