How sofiyancms/bill-nexa works
1. Overall shape
- BILL NEXA is a single-page React application built with Vite + TypeScript, with Supabase serving as the backend platform.
- The repo is primarily a frontend app plus Supabase schema/functions; there is no custom Node/Express server in this codebase.
2. Client application boundary
- The browser loads index.html, src/main.tsx, and src/App.tsx, which boot the SPA.
- Routing is page-based: the app is organized into route-level screens under src/pages, with shared layout and guards applied around them.
3. Primary user-facing domains
- The main screens are:
- DashboardPage
- CustomersPage
- VillagesPage
- IncomeExpensePage
- ReportsPage
- AdminPage
- LoginPage
- This suggests the product centers on billing/accounting operations, with separate workflows for customer records, geography/organization data, financial entries, reporting, and admin access.
4. Shell, navigation, and route protection
- src/components/AppLayout.tsx likely provides the global frame: navigation, content area, and app-wide UI chrome.
- ProtectedRoute.tsx gates authenticated sections, while NavLink.tsx supports app navigation.
- LoginPage is the public entry point; everything else appears to be behind auth.
5. Shared UI system
- The app uses a large reusable component layer under src/components/ui, consistent with shadcn/ui + Radix UI primitives.
- Higher-level shared pieces like StatCard, LanguageSelector, InstallPrompt, LazyLoad, and toast wrappers indicate a polished dashboard-style UI with reusable cards, notifications, and mobile/install support.
6. State, data fetching, and app services
- The repo README says React Query is part of the stack, so server state is likely fetched/cached through that layer rather than stored globally.
- src/lib/utils.ts holds common helpers; src/lib/auth.tsx centralizes auth behavior; src/lib/receipt.ts suggests receipt generation/formatting is a dedicated utility boundary.
- Hooks in src/hooks provide cross-cutting UI behavior such as mobile detection and toast state.
7. Authentication and session flow
- Auth is handled through Supabase Auth and wrapped by frontend auth utilities.
- The presence of ProtectedRoute, LoginPage, and a Supabase reset-password function indicates the key auth flow is:
- user signs in through Supabase
- session state is used to allow/deny protected routes
- password reset is delegated to a serverless Supabase function
8. Backend and persistence boundary
- src/integrations/supabase/client.ts is the frontend entry point to Supabase.
- src/integrations/supabase/types.ts suggests generated database typings are used to keep frontend data access type-safe.
- The actual business data lives in Supabase Postgres, not in local storage or a custom API layer.
9. Database lifecycle and operational fixes
- The supabase/migrations folder shows the schema is managed through SQL migrations with multiple production fixes.
- Migration names indicate work on:
- schema stabilization for production
- performance indexes
- auth-trigger fixes
- RLS changes
- allowing nullable user IDs in some tables/paths
- This implies the backend architecture depends heavily on row-level security and database triggers.
10. Serverless backend logic
- supabase/functions/reset-password/index.ts is the notable edge/serverless function in the repo.
- That function likely handles password reset email or token-related logic outside the browser, keeping sensitive auth flow on the backend side of Supabase.
11. Internationalization and user experience
- src/lib/i18n.tsx plus LanguageSelector show the app is multilingual, specifically English, Kannada, and Hindi per the README.
- The architecture therefore includes a language/state layer that affects UI text across pages rather than isolated per-screen strings.
12. Presentation and reporting
- The UI stack includes charting support (recharts in README, plus src/components/ui/chart.tsx), which is relevant to ReportsPage and dashboard metrics.
- src/lib/receipt.ts implies document/receipt rendering is part of the presentation layer, likely tied to billing outputs or exports.
13. Cross-cutting quality and tooling
- The repo is set up with Vite, Tailwind, PostCSS, ESLint, and Vitest.
- Test files under src/test and repo-level Supabase test scripts suggest both frontend behavior and backend/auth integration are verified separately.
- The supabase CLI config and migration scripts indicate local/CI database synchronization is part of the delivery pipeline.
14. Important architectural takeaway
- The clean separation is: React SPA UI → shared components/hooks/lib → Supabase client/auth/db → Supabase Postgres, RLS, and edge functions.
- For an architecture diagram, the major boundaries to draw are the browser app, the Supabase backend platform, and the migration/function layer that manages backend behavior.
Main entry points: ProtectedRoute.tsx ProtectedRoute · client.ts Supabase client · ui UI kit · App.tsx App.tsx
Components 21
Frontend app
Vite React SPA and shared client-side architecture
- index.html · HTML entry loaded by the browser
index.html - main.tsx · Mounts the React app
src/main.tsx - App.tsx · Top-level application composition and routing
src/App.tsx - AppLayout · Global navigation frame and content shell
src/components/AppLayout.tsx - ProtectedRoute · Blocks protected screens until authenticated
src/components/ProtectedRoute.tsx - LoginPage · Authentication entry screen
src/pages/LoginPage.tsx - Dashboard · Overview and key metrics screen
src/pages/DashboardPage.tsx - Customers · Customer records and related workflows
src/pages/CustomersPage.tsx - Villages · Geography and organization data screen
src/pages/VillagesPage.tsx - Income/Expense · Financial entry and transaction screen
src/pages/IncomeExpensePage.tsx - Reports · Reporting and analytics screen
src/pages/ReportsPage.tsx - Admin · Administration and management screen
src/pages/AdminPage.tsx - UI kit · Reusable shadcn/radix-style component library
src/components/ui - Auth + i18n · Shared client-side auth, language, and formatting helpers
src/lib - Supabase client · Frontend entry point to Supabase
src/integrations/supabase/client.ts - DB types · Typed Supabase database schema bindings
src/integrations/supabase/types.ts - Receipt · Receipt and billing document helpers
src/lib/receipt.ts
Supabase backend
Database, auth, migrations, and edge functions managed in Supabase
- Migrations · Database schema, RLS, trigger, and performance migrations
supabase/migrations - Reset password · Serverless password-reset logic
supabase/functions/reset-password/index.ts - Supabase platform · Hosted Postgres, auth, RLS, and edge execution
supabase
Tooling
Build, test, and repository-level scripts
- Build & test · Vite, Vitest, ESLint, and repo scripts
Connections 33
- index.html → main.tsx: loads · Browser entry loads the SPA bootstrap
- main.tsx → App.tsx: mounts · React entry renders the application root
- App.tsx → AppLayout: wraps · Routes are rendered within the global app shell
- App.tsx → ProtectedRoute: guards · Authenticated screens are protected at the routing layer
- ProtectedRoute → LoginPage: redirects to · Unauthenticated users are sent to sign in
- ProtectedRoute → Dashboard: allows · Protected dashboard entry
- ProtectedRoute → Customers: allows · Protected customer management screen
- ProtectedRoute → Villages: allows · Protected village/organization screen
- ProtectedRoute → Income/Expense: allows · Protected financial entry screen
- ProtectedRoute → Reports: allows · Protected reporting screen
- ProtectedRoute → Admin: allows · Protected administration screen
- AppLayout → UI kit: uses · Shell uses shared UI primitives and reusable widgets
- Dashboard → UI kit: uses · Dashboard is built from shared cards, charts, and UI primitives
- Customers → UI kit: uses · Customer workflows rely on shared forms and tables
- Villages → UI kit: uses · Village management uses reusable UI controls
- Income/Expense → UI kit: uses · Financial entry uses shared inputs and dialogs
- Reports → UI kit: uses · Reporting uses chart and table components
- Admin → UI kit: uses · Admin screen uses shared controls and layout widgets
- LoginPage → Auth + i18n: uses · Authentication screen relies on shared auth utilities
- Auth + i18n → Supabase client: authenticates via · Client-side auth helpers talk to Supabase
- Auth + i18n → DB types: types · Shared services use generated database typings
- Dashboard → Supabase client: fetches · Dashboard reads application data from Supabase
- Customers → Supabase client: fetches · Customer data comes from Supabase
- Villages → Supabase client: fetches · Village data comes from Supabase
- Income/Expense → Supabase client: writes/reads · Financial entries are persisted in Supabase
- Reports → Supabase client: aggregates · Reports query backend data for summaries
- Admin → Supabase client: administers · Admin actions operate on backend data and settings
- Supabase client → Supabase platform: connects to · Frontend data access terminates at Supabase
- Supabase platform → Migrations: schema managed by · Database structure and policies are maintained by migrations
- Supabase platform → Reset password: executes · Supabase runs the password-reset edge function
- Migrations → Reset password: supports auth flow · Backend auth behavior depends on database and function setup
- Build & test → App.tsx: builds/tests · Repository tooling validates the frontend application
- Build & test → Migrations: checks · Tooling and scripts support database migration workflows