# sofiyancms/bill-nexa architecture

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

- Interactive diagram: https://gitdiagram.com/sofiyancms/bill-nexa
- Repository: https://github.com/sofiyancms/bill-nexa

## Overview

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: [`src/components/ProtectedRoute.tsx`](https://github.com/sofiyancms/bill-nexa/blob/main/src/components/ProtectedRoute.tsx) (ProtectedRoute), [`src/integrations/supabase/client.ts`](https://github.com/sofiyancms/bill-nexa/blob/main/src/integrations/supabase/client.ts) (Supabase client), [`src/components/ui`](https://github.com/sofiyancms/bill-nexa/tree/main/src/components/ui) (UI kit), [`src/App.tsx`](https://github.com/sofiyancms/bill-nexa/blob/main/src/App.tsx) (App.tsx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_index_html["index.html<br/>entry shell<br/>[index.html]"]
  node_main_tsx["main.tsx<br/>bootstrap<br/>[main.tsx]"]
  node_app_tsx["App.tsx<br/>router root<br/>[App.tsx]"]
  node_app_layout["AppLayout<br/>shell layout<br/>[AppLayout.tsx]"]
  node_protected_route["ProtectedRoute<br/>auth gate<br/>[ProtectedRoute.tsx]"]
  node_login_page["LoginPage<br/>public screen<br/>[LoginPage.tsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[DashboardPage.tsx]"]
  node_customers_page["Customers<br/>page<br/>[CustomersPage.tsx]"]
  node_villages_page["Villages<br/>page<br/>[VillagesPage.tsx]"]
  node_income_expense_page["Income/Expense<br/>page"]
  node_reports_page["Reports<br/>page<br/>[ReportsPage.tsx]"]
  node_admin_page["Admin<br/>page<br/>[AdminPage.tsx]"]
  node_ui_components["UI kit<br/>shared components"]
  node_app_services["Auth + i18n<br/>client services"]
  node_supabase_client["Supabase client<br/>data client<br/>[client.ts]"]
  node_supabase_types["DB types<br/>generated types<br/>[types.ts]"]
  node_receipt_lib["Receipt<br/>formatting util<br/>[receipt.ts]"]
end

subgraph group_backend["Supabase backend"]
  node_supabase_migrations[("Migrations<br/>sql schema")]
  node_reset_password_fn["Reset password<br/>edge function<br/>[index.ts]"]
  node_supabase_backend[("Supabase platform<br/>backend platform")]
end

subgraph group_tooling["Tooling"]
  node_build_test_tooling["Build & test<br/>tooling"]
end

node_index_html -->|"loads"| node_main_tsx
node_main_tsx -->|"mounts"| node_app_tsx
node_app_tsx -->|"wraps"| node_app_layout
node_app_tsx -->|"guards"| node_protected_route
node_protected_route -->|"redirects to"| node_login_page
node_protected_route -->|"allows"| node_dashboard_page
node_protected_route -->|"allows"| node_customers_page
node_protected_route -->|"allows"| node_villages_page
node_protected_route -->|"allows"| node_income_expense_page
node_protected_route -->|"allows"| node_reports_page
node_protected_route -->|"allows"| node_admin_page
node_app_layout -->|"uses"| node_ui_components
node_dashboard_page -->|"uses"| node_ui_components
node_customers_page -->|"uses"| node_ui_components
node_villages_page -->|"uses"| node_ui_components
node_income_expense_page -->|"uses"| node_ui_components
node_reports_page -->|"uses"| node_ui_components
node_admin_page -->|"uses"| node_ui_components
node_login_page -->|"uses"| node_app_services
node_app_services -->|"authenticates via"| node_supabase_client
node_app_services -->|"types"| node_supabase_types
node_dashboard_page -->|"fetches"| node_supabase_client
node_customers_page -->|"fetches"| node_supabase_client
node_villages_page -->|"fetches"| node_supabase_client
node_income_expense_page -->|"writes/reads"| node_supabase_client
node_reports_page -->|"aggregates"| node_supabase_client
node_admin_page -->|"administers"| node_supabase_client
node_supabase_client -->|"connects to"| node_supabase_backend
node_supabase_backend -->|"schema managed by"| node_supabase_migrations
node_supabase_backend -->|"executes"| node_reset_password_fn
node_supabase_migrations -.->|"supports auth flow"| node_reset_password_fn
node_build_test_tooling -.->|"builds/tests"| node_app_tsx
node_build_test_tooling -.->|"checks"| node_supabase_migrations

click node_index_html "https://github.com/sofiyancms/bill-nexa/blob/main/index.html"
click node_main_tsx "https://github.com/sofiyancms/bill-nexa/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/sofiyancms/bill-nexa/blob/main/src/App.tsx"
click node_app_layout "https://github.com/sofiyancms/bill-nexa/blob/main/src/components/AppLayout.tsx"
click node_protected_route "https://github.com/sofiyancms/bill-nexa/blob/main/src/components/ProtectedRoute.tsx"
click node_login_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/LoginPage.tsx"
click node_dashboard_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/DashboardPage.tsx"
click node_customers_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/CustomersPage.tsx"
click node_villages_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/VillagesPage.tsx"
click node_income_expense_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/IncomeExpensePage.tsx"
click node_reports_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/ReportsPage.tsx"
click node_admin_page "https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/AdminPage.tsx"
click node_ui_components "https://github.com/sofiyancms/bill-nexa/tree/main/src/components/ui"
click node_app_services "https://github.com/sofiyancms/bill-nexa/tree/main/src/lib"
click node_supabase_client "https://github.com/sofiyancms/bill-nexa/blob/main/src/integrations/supabase/client.ts"
click node_supabase_types "https://github.com/sofiyancms/bill-nexa/blob/main/src/integrations/supabase/types.ts"
click node_receipt_lib "https://github.com/sofiyancms/bill-nexa/blob/main/src/lib/receipt.ts"
click node_supabase_migrations "https://github.com/sofiyancms/bill-nexa/tree/main/supabase/migrations"
click node_reset_password_fn "https://github.com/sofiyancms/bill-nexa/blob/main/supabase/functions/reset-password/index.ts"
click node_supabase_backend "https://github.com/sofiyancms/bill-nexa/tree/main/supabase"

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_index_html,node_main_tsx,node_app_tsx,node_app_layout,node_protected_route,node_login_page,node_dashboard_page,node_customers_page,node_villages_page,node_income_expense_page,node_reports_page,node_admin_page,node_ui_components,node_app_services,node_supabase_client,node_supabase_types,node_receipt_lib toneBlue
class node_supabase_migrations,node_reset_password_fn,node_supabase_backend toneAmber
class node_build_test_tooling toneMint
```

## Components

### Frontend app

Vite React SPA and shared client-side architecture

- [index.html](https://github.com/sofiyancms/bill-nexa/blob/main/index.html): entry shell · HTML entry loaded by the browser · `index.html`
- [main.tsx](https://github.com/sofiyancms/bill-nexa/blob/main/src/main.tsx): bootstrap · Mounts the React app · `src/main.tsx`
- [App.tsx](https://github.com/sofiyancms/bill-nexa/blob/main/src/App.tsx): router root · Top-level application composition and routing · `src/App.tsx`
- [AppLayout](https://github.com/sofiyancms/bill-nexa/blob/main/src/components/AppLayout.tsx): shell layout · Global navigation frame and content shell · `src/components/AppLayout.tsx`
- [ProtectedRoute](https://github.com/sofiyancms/bill-nexa/blob/main/src/components/ProtectedRoute.tsx): auth gate · Blocks protected screens until authenticated · `src/components/ProtectedRoute.tsx`
- [LoginPage](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/LoginPage.tsx): public screen · Authentication entry screen · `src/pages/LoginPage.tsx`
- [Dashboard](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/DashboardPage.tsx): page · Overview and key metrics screen · `src/pages/DashboardPage.tsx`
- [Customers](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/CustomersPage.tsx): page · Customer records and related workflows · `src/pages/CustomersPage.tsx`
- [Villages](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/VillagesPage.tsx): page · Geography and organization data screen · `src/pages/VillagesPage.tsx`
- [Income/Expense](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/IncomeExpensePage.tsx): page · Financial entry and transaction screen · `src/pages/IncomeExpensePage.tsx`
- [Reports](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/ReportsPage.tsx): page · Reporting and analytics screen · `src/pages/ReportsPage.tsx`
- [Admin](https://github.com/sofiyancms/bill-nexa/blob/main/src/pages/AdminPage.tsx): page · Administration and management screen · `src/pages/AdminPage.tsx`
- [UI kit](https://github.com/sofiyancms/bill-nexa/tree/main/src/components/ui): shared components · Reusable shadcn/radix-style component library · `src/components/ui`
- [Auth + i18n](https://github.com/sofiyancms/bill-nexa/tree/main/src/lib): client services · Shared client-side auth, language, and formatting helpers · `src/lib`
- [Supabase client](https://github.com/sofiyancms/bill-nexa/blob/main/src/integrations/supabase/client.ts): data client · Frontend entry point to Supabase · `src/integrations/supabase/client.ts`
- [DB types](https://github.com/sofiyancms/bill-nexa/blob/main/src/integrations/supabase/types.ts): generated types · Typed Supabase database schema bindings · `src/integrations/supabase/types.ts`
- [Receipt](https://github.com/sofiyancms/bill-nexa/blob/main/src/lib/receipt.ts): formatting util · Receipt and billing document helpers · `src/lib/receipt.ts`

### Supabase backend

Database, auth, migrations, and edge functions managed in Supabase

- [Migrations](https://github.com/sofiyancms/bill-nexa/tree/main/supabase/migrations): sql schema · Database schema, RLS, trigger, and performance migrations · `supabase/migrations`
- [Reset password](https://github.com/sofiyancms/bill-nexa/blob/main/supabase/functions/reset-password/index.ts): edge function · Serverless password-reset logic · `supabase/functions/reset-password/index.ts`
- [Supabase platform](https://github.com/sofiyancms/bill-nexa/tree/main/supabase): backend platform · Hosted Postgres, auth, RLS, and edge execution · `supabase`

### Tooling

Build, test, and repository-level scripts

- **Build & test**: tooling · Vite, Vitest, ESLint, and repo scripts

## Connections

- 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
