# yukesh4349/finora-ai architecture

> Architecture diagram of the GitHub repository yukesh4349/finora-ai, 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/yukesh4349/finora-ai
- Repository: https://github.com/yukesh4349/finora-ai

## Overview

#### Purpose and entry points
Finora AI is a retail-finance platform combining POS checkout, inventory, vendor invoice processing, fraud checks, reporting, and role-specific operations. The React/Vite client starts at `frontend/src/main.jsx` and routes through `frontend/src/App.jsx`. The Express REST API starts at `backend/index.js`; root scripts orchestrate both runtimes via `package.json`.

#### Client application and user workflows
The frontend provides public/authentication views plus focused operational screens for owners and staff. Dashboard composition is centered on business-owner analytics, invoice upload, invoice creation/POS, and specialized embedded modules.
- `frontend/src/pages/BusinessOwnerDashboard.jsx`
- `frontend/src/pages/UploadInvoiceFullPage.jsx`
- `frontend/src/pages/CreateInvoiceFullPage.jsx`
- `frontend/src/components/dashboard/PosBillingModule.jsx`
- `frontend/src/components/dashboard/AiAssistantModule.jsx`

Client-side service boundaries separate REST calls and direct Supabase access/configuration:
- `frontend/src/services/api.js`
- `frontend/src/services/supabaseClient.js`
- `frontend/src/services/postgresDb.js`

#### API composition and authorization
`backend/index.js` is the API composition root, mounting domain route modules. Authentication and role enforcement form the security boundary before protected financial, inventory, and employee operations.
- `backend/routes/auth.js`
- `backend/middleware/rbac.js`
- `backend/routes/dashboard.js`
- `backend/routes/settings.js`

Primary route domains split responsibilities across vendors, expenses, payments, transactions, employee/payroll, analytics, and reporting:
- `backend/routes/vendors.js`
- `backend/routes/expenses.js`
- `backend/routes/payments.js`
- `backend/routes/reports.js`

#### Invoice intelligence and fraud-control pipeline
Vendor invoice ingestion is a core write path: uploaded document data is scanned through NVIDIA Nemotron Vision with Tesseract fallback, converted into structured invoice/items data, then evaluated for duplicate/anomalous bills before downstream storage and inventory updates. AI assistant requests are exposed separately from document OCR.
- `backend/routes/invoices.js`
- `backend/routes/ai.js`
- `frontend/src/pages/UploadInvoiceFullPage.jsx`

This boundary depends on file upload handling, NVIDIA AI credentials, and potentially outbound webhook processing; document extraction should remain server-side because it uses privileged external AI credentials.

#### POS, sales, and inventory synchronization
Checkout flows originate in the POS UI, submit customer bills/sales through the API, and deduct stock. Vendor-invoice saves move in the opposite direction by increasing or updating inventory, supplier pricing, MRP, and low-stock state.
- `frontend/src/components/dashboard/PosBillingModule.jsx`
- `backend/routes/customer_bills.js`
- `backend/routes/inventory.js`
- `backend/routes/invoices.js`

Financial effects are represented through dedicated transaction and payment interfaces rather than being confined to UI state:
- `backend/routes/transactions.js`
- `backend/routes/payments.js`

#### Persistence, runtimes, and external services
Node.js/Express is the backend runtime; React 18/Vite is the browser runtime. PostgreSQL is the system of record through Supabase, with a dual database adapter and SQL schemas defining relational persistence. Supabase credentials include an elevated service-role path, so backend-only usage is a material trust boundary.
- `backend/db.js`
- `backend/supabase_schema.sql`
- `backend/schema.sql`

External dependencies include Supabase PostgreSQL, NVIDIA Nemotron Vision, Tesseract OCR, and configured webhook endpoints. A local fallback dataset exists at `backend/data.json`, likely supporting development or degraded persistence.

Main entry points: [`backend/db.js`](https://github.com/yukesh4349/finora-ai/blob/main/backend/db.js) (Database adapter), [`backend/middleware/rbac.js`](https://github.com/yukesh4349/finora-ai/blob/main/backend/middleware/rbac.js) (Authentication & RBAC), [`backend/routes/invoices.js`](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js) (Invoice routes), [`frontend/src/services/api.js`](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/services/api.js) (REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React/Vite Client"]
  node_client_entry["Client entry &amp; routes<br/>React application<br/>[main.jsx]"]
  node_owner_dashboard["Owner dashboard<br/>analytics workspace"]
  node_invoice_upload["Invoice upload<br/>operations screen"]
  node_pos_ui["POS billing<br/>checkout module"]
  node_client_api["REST client<br/>API service<br/>[api.js]"]
  node_client_supabase["Client Supabase access<br/>database adapter<br/>[supabaseClient.js]"]
end

subgraph group_api["Express API"]
  node_api_root["API composition root<br/>Express server<br/>[index.js]"]
  node_auth_rbac{{"Authentication &amp; RBAC<br/>security boundary<br/>[rbac.js]"}}
  node_dashboard_settings["Dashboard &amp; settings<br/>API routes<br/>[dashboard.js]"]
  node_invoice_routes["Invoice routes<br/>ingestion API<br/>[invoices.js]"]
  node_ai_routes["AI assistant API<br/>AI API routes<br/>[ai.js]"]
  node_sales_inventory["Sales &amp; inventory routes<br/>operational APIs<br/>[customer_bills.js]"]
  node_financial_routes["Financial routes<br/>payments &amp; reporting APIs<br/>[payments.js]"]
end

subgraph group_pipeline["Invoice Intelligence"]
  node_invoice_extraction["Invoice extraction<br/>OCR orchestration<br/>[invoices.js]"]
  node_fraud_checks{{"Duplicate &amp; anomaly checks<br/>fraud control<br/>[invoices.js]"}}
end

subgraph group_data["Data &amp; External Services"]
  node_postgres_adapter["Database adapter<br/>Supabase/Postgres access<br/>[db.js]"]
  node_postgres[("Supabase PostgreSQL<br/>system of record")]
  node_vision_ocr["Vision OCR providers<br/>external AI/OCR"]
  node_webhooks["Webhook endpoints<br/>outbound integration"]
  node_local_data["Local fallback data<br/>degraded persistence<br/>[data.json]"]
end

node_client_entry -->|"renders"| node_owner_dashboard
node_client_entry -->|"routes to"| node_invoice_upload
node_client_entry -->|"hosts"| node_pos_ui
node_owner_dashboard -->|"loads operations data"| node_client_api
node_invoice_upload -->|"uploads invoices"| node_client_api
node_pos_ui -->|"submits checkout"| node_client_api
node_client_api -->|"REST requests"| node_api_root
node_client_supabase -->|"direct client access"| node_postgres
node_api_root -->|"enforces protected access"| node_auth_rbac
node_auth_rbac -->|"authorizes"| node_dashboard_settings
node_auth_rbac -->|"authorizes"| node_invoice_routes
node_auth_rbac -->|"authorizes"| node_sales_inventory
node_auth_rbac -->|"authorizes"| node_financial_routes
node_invoice_routes -->|"processes uploads"| node_invoice_extraction
node_invoice_extraction -->|"extracts document data"| node_vision_ocr
node_invoice_extraction -->|"structures invoices"| node_fraud_checks
node_fraud_checks -->|"persists approved data"| node_postgres_adapter
node_invoice_routes -->|"updates received stock"| node_sales_inventory
node_sales_inventory -->|"records sales and stock"| node_postgres_adapter
node_financial_routes -->|"records payments and reports"| node_postgres_adapter
node_dashboard_settings -->|"reads business data"| node_postgres_adapter
node_ai_routes -->|"assistant AI requests"| node_vision_ocr
node_postgres_adapter -->|"service-role database access"| node_postgres
node_invoice_routes -.->|"optional outbound events"| node_webhooks
node_postgres_adapter -.->|"fallback"| node_local_data

click node_client_entry "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/main.jsx"
click node_owner_dashboard "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/pages/BusinessOwnerDashboard.jsx"
click node_invoice_upload "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/pages/UploadInvoiceFullPage.jsx"
click node_pos_ui "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/components/dashboard/PosBillingModule.jsx"
click node_client_api "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/services/api.js"
click node_client_supabase "https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/services/supabaseClient.js"
click node_api_root "https://github.com/yukesh4349/finora-ai/blob/main/backend/index.js"
click node_auth_rbac "https://github.com/yukesh4349/finora-ai/blob/main/backend/middleware/rbac.js"
click node_dashboard_settings "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/dashboard.js"
click node_invoice_routes "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js"
click node_ai_routes "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/ai.js"
click node_sales_inventory "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/customer_bills.js"
click node_financial_routes "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/payments.js"
click node_invoice_extraction "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js"
click node_fraud_checks "https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js"
click node_postgres_adapter "https://github.com/yukesh4349/finora-ai/blob/main/backend/db.js"
click node_postgres "https://github.com/yukesh4349/finora-ai/blob/main/backend/supabase_schema.sql"
click node_local_data "https://github.com/yukesh4349/finora-ai/blob/main/backend/data.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_client_entry,node_owner_dashboard,node_invoice_upload,node_pos_ui,node_client_api,node_client_supabase toneBlue
class node_api_root,node_auth_rbac,node_dashboard_settings,node_invoice_routes,node_ai_routes,node_sales_inventory,node_financial_routes toneAmber
class node_invoice_extraction,node_fraud_checks toneMint
class node_postgres_adapter,node_postgres,node_vision_ocr,node_webhooks,node_local_data toneRose
```

## Components

### React/Vite Client

- [Client entry & routes](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/main.jsx): React application · Bootstraps the browser app and route composition. · `frontend/src/main.jsx`
- [Owner dashboard](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/pages/BusinessOwnerDashboard.jsx): analytics workspace · `frontend/src/pages/BusinessOwnerDashboard.jsx`
- [Invoice upload](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/pages/UploadInvoiceFullPage.jsx): operations screen · `frontend/src/pages/UploadInvoiceFullPage.jsx`
- [POS billing](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/components/dashboard/PosBillingModule.jsx): checkout module · `frontend/src/components/dashboard/PosBillingModule.jsx`
- [REST client](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/services/api.js): API service · `frontend/src/services/api.js`
- [Client Supabase access](https://github.com/yukesh4349/finora-ai/blob/main/frontend/src/services/supabaseClient.js): database adapter · Direct browser-side Supabase access and configuration. · `frontend/src/services/supabaseClient.js`

### Express API

- [API composition root](https://github.com/yukesh4349/finora-ai/blob/main/backend/index.js): Express server · Mounts domain routes and API middleware. · `backend/index.js`
- [Authentication & RBAC](https://github.com/yukesh4349/finora-ai/blob/main/backend/middleware/rbac.js): security boundary · Protects role-scoped financial, inventory, and employee operations. · `backend/middleware/rbac.js`
- [Dashboard & settings](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/dashboard.js): API routes · `backend/routes/dashboard.js`
- [Invoice routes](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js): ingestion API · Accepts vendor invoices and coordinates stock-affecting saves. · `backend/routes/invoices.js`
- [AI assistant API](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/ai.js): AI API routes · Separates assistant requests from document extraction. · `backend/routes/ai.js`
- [Sales & inventory routes](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/customer_bills.js): operational APIs · Records checkout bills and maintains stock. · `backend/routes/customer_bills.js`
- [Financial routes](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/payments.js): payments & reporting APIs · `backend/routes/payments.js`

### Invoice Intelligence

- [Invoice extraction](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js): OCR orchestration · Uses server-side vision extraction with OCR fallback. · `backend/routes/invoices.js`
- [Duplicate & anomaly checks](https://github.com/yukesh4349/finora-ai/blob/main/backend/routes/invoices.js): fraud control · Evaluates extracted bills before storage and inventory updates. · `backend/routes/invoices.js`

### Data & External Services

- [Database adapter](https://github.com/yukesh4349/finora-ai/blob/main/backend/db.js): Supabase/Postgres access · Backend access includes an elevated service-role trust boundary. · `backend/db.js`
- [Supabase PostgreSQL](https://github.com/yukesh4349/finora-ai/blob/main/backend/supabase_schema.sql): system of record · Relational persistence defined by SQL schemas. · `backend/supabase_schema.sql`
- **Vision OCR providers**: external AI/OCR · NVIDIA Nemotron Vision with Tesseract fallback.
- **Webhook endpoints**: outbound integration
- [Local fallback data](https://github.com/yukesh4349/finora-ai/blob/main/backend/data.json): degraded persistence · Supports local development or degraded persistence. · `backend/data.json`

## Connections

- Client entry & routes → Owner dashboard: renders
- Client entry & routes → Invoice upload: routes to
- Client entry & routes → POS billing: hosts
- Owner dashboard → REST client: loads operations data
- Invoice upload → REST client: uploads invoices
- POS billing → REST client: submits checkout
- REST client → API composition root: REST requests
- Client Supabase access → Supabase PostgreSQL: direct client access
- API composition root → Authentication & RBAC: enforces protected access
- Authentication & RBAC → Dashboard & settings: authorizes
- Authentication & RBAC → Invoice routes: authorizes
- Authentication & RBAC → Sales & inventory routes: authorizes
- Authentication & RBAC → Financial routes: authorizes
- Invoice routes → Invoice extraction: processes uploads
- Invoice extraction → Vision OCR providers: extracts document data
- Invoice extraction → Duplicate & anomaly checks: structures invoices
- Duplicate & anomaly checks → Database adapter: persists approved data
- Invoice routes → Sales & inventory routes: updates received stock
- Sales & inventory routes → Database adapter: records sales and stock
- Financial routes → Database adapter: records payments and reports
- Dashboard & settings → Database adapter: reads business data
- AI assistant API → Vision OCR providers: assistant AI requests
- Database adapter → Supabase PostgreSQL: service-role database access
- Invoice routes → Webhook endpoints: optional outbound events
- Database adapter → Local fallback data: fallback