# musaibbashir/mercanta architecture

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

- Interactive diagram: https://gitdiagram.com/musaibbashir/mercanta
- Repository: https://github.com/musaibbashir/mercanta

## Overview

1. **Overall shape**
   - This repo is a **multi-tier information system** with a React frontend, a Python backend, and Supabase-based data/storage services.
   - It also includes **automation workflows** for WhatsApp and payment/order events, so the system is not just a UI + API; it has event-driven operational flows.

2. **Primary user-facing application**
   - The main app is a **Vite + React + TypeScript SPA** under `src/`.
   - `src/main.tsx` and `src/App.tsx` are the app entry points; `src/pages/` contains the route-level screens.
   - Deployment appears to be on **Netlify** (`netlify.toml`, `public/_redirects`, README link).

3. **Role- and domain-based screens**
   - The page structure suggests several business roles:
     - **General sales/inventory operations**: `SalesPage`, `InventoryPage`, `CustomersPage`, `SalesHistoryPage`, `ForecastPage`, `BusinessSettingsPage`, `RestaurantMenuPage`
     - **Admin operations**: `src/pages/admin/*`
     - **Franchise operations**: `src/pages/franchise/*`
   - That split is important for architecture: the UI is organized around **permissioned business functions**, not just generic navigation.

4. **State, auth, and shared business context**
   - `src/context/AuthContext.tsx` likely owns authentication/session state.
   - `src/context/InventoryContext.tsx` likely centralizes inventory-related shared state.
   - `src/components/ProtectedRoute.tsx` indicates route guarding and access control in the frontend.

5. **Frontend data access layer**
   - `src/lib/supabaseClient.ts` is the key client boundary to the backend data layer.
   - Feature services such as `src/services/forecastService.ts`, `menuService.ts`, and `tokenService.ts` suggest a thin service layer between UI components and data APIs.
   - This means data fetching is not embedded directly in pages; it is split into reusable domain services.

6. **Operational UI components**
   - Reusable components like `KitchenDisplaySystem`, `InvoiceModal`, `CameraScanner`, `TokenTracker`, and charts/cards indicate the app supports:
     - order fulfillment
     - invoice generation
     - barcode/scan-assisted workflows
     - queue/token handling
     - analytics dashboards
   - `src/components/ui/*` is a broad design-system layer used across the app.

7. **Backend application**
   - `backend/app.py` is the main server-side application, with `requirements.txt`, `runtime.txt`, `Procfile`, `railway.toml`, and `render.yaml` showing it is deployed as a Python service.
   - The backend likely handles domain logic that should not live in the browser: transactional rules, database mutations, and integration endpoints.
   - The presence of migration and seed SQL files suggests the backend is closely coupled to the database schema rather than acting as a standalone microservice layer.

8. **Database and schema management**
   - The `backend/` SQL files (`migration.sql`, `sales_enhancements_migration.sql`, `stock_orders_migration.sql`, `fix_rls_policies.sql`, etc.) indicate **Supabase/Postgres schema evolution** and policy management.
   - `seed_data.sql`, `seed_franchises.sql`, and `seed_supabase.py` show repeatable environment bootstrap for sample/demo data.
   - `fix_rls_policies.sql` is especially important: access control is enforced at the database layer via **RLS policies**.

9. **External integrations and automation**
   - `supabase/functions/razorpay-webhook/index.ts` is a serverless webhook handler for **Razorpay payment events**.
   - The `n8n/` workflows and `mercanta_whatsapp_n8n_workflow.json` indicate **WhatsApp automation** and event-based orchestration, likely for order confirmations and “order ready” notifications.
   - This creates an async path separate from the main UI: external events trigger automation, which then updates the system or messages users.

10. **Deployment boundaries**
   - The app is split across multiple deployable surfaces:
     - **Frontend** on Netlify
     - **Python backend** on Railway/Render-compatible hosting
     - **Supabase** for database and edge functions
     - **n8n** for workflow automation
   - That means an architecture diagram should show clear boundaries between browser, application server, database, and automation/webhook services.

11. **Business intelligence and reporting**
   - Chart components such as `RevenueBreakdownChart`, `SalesTrendChart`, `RegionSalesChart`, `YoYGrowthChart`, and `PerformanceMetricsChart` show that reporting is a first-class part of the system.
   - `src/pages/admin/FinancialReportsPage.tsx` and related admin pages suggest aggregated metrics are consumed by managers/admins, not just operational staff.

12. **Supporting assets and knowledge**
   - `docs/Mercanta-Knowledge-Base.html` and `src/guidelines/Guidelines.md` imply there is internal product/process documentation alongside the codebase.
   - `src/data/sampleData.ts` and `Liquid-Gradient/` look like supporting/demo UI assets rather than core production logic.

13. **What the data flow likely looks like**
   - User actions in the React app go through **contexts/services** to **Supabase/backend APIs**.
   - Database changes propagate to **dashboards, reports, and operational screens**.
   - Payment or order status events can also flow through **Razorpay webhook → Supabase function/backend → database updates → n8n/WhatsApp notifications**.

14. **Diagram takeaway**
   - The cleanest architecture view is: **React SPA at the edge**, **Python application + Supabase/Postgres in the middle**, and **event-driven integrations (Razorpay, WhatsApp/n8n)** on the side.
   - The most important boundary is between **browser-facing UI logic** and **server-side transactional/business logic + database policy enforcement**.

Main entry points: [`backend/app.py`](https://github.com/musaibbashir/mercanta/blob/main/backend/app.py) (API server), [`src/App.tsx`](https://github.com/musaibbashir/mercanta/blob/main/src/App.tsx) (Shell), [`src/pages`](https://github.com/musaibbashir/mercanta/tree/main/src/pages) (Business screens), [`n8n`](https://github.com/musaibbashir/mercanta/tree/main/n8n) (n8n workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend App"]
  node_src_main["App entry<br/>vite-react entry<br/>[main.tsx]"]
  node_src_app["Shell<br/>[App.tsx]"]
  node_src_pages["Business screens<br/>route pages"]
  node_src_contexts["Shared state<br/>auth/inventory context"]
  node_src_services["Domain services<br/>frontend service layer"]
  node_src_components["UI components<br/>shared components"]
  node_src_ui["Design system<br/>ui primitives"]
  node_src_layout["Layout layer<br/>app layout"]
  node_src_supabase_client["Supabase client<br/>browser db client<br/>[supabaseClient.ts]"]
  node_src_protected_route["Route guard<br/>access control<br/>[ProtectedRoute.tsx]"]
end

subgraph group_backend["Backend & Data"]
  node_backend_app["API server<br/>python app<br/>[app.py]"]
  node_backend_schema[("Schema SQL<br/>postgres migrations<br/>[migration.sql]")]
  node_backend_seed["Seed data<br/>bootstrap data<br/>[seed_data.sql]"]
  node_supabase_edge["Webhook edge<br/>supabase function<br/>[index.ts]"]
end

subgraph group_automation["Automation"]
  node_n8n_flows["n8n workflows<br/>automation flows"]
  node_whatsapp_bot["WA bot<br/>messaging workflow<br/>[wa_bot.json]"]
  node_payment_flow["Payment flow<br/>event workflow"]
  node_order_ready_flow["Order-ready flow<br/>event workflow<br/>[order_ready.json]"]
end

subgraph group_support["Docs & Assets"]
  node_docs_kb["Knowledge base<br/>product docs"]
  node_liquid_demo["Liquid demo<br/>demo asset"]
end

node_src_main -->|"renders"| node_src_app
node_src_app -->|"routes to"| node_src_pages
node_src_app -->|"uses"| node_src_layout
node_src_app -->|"guards"| node_src_protected_route
node_src_pages -->|"consumes"| node_src_contexts
node_src_pages -->|"calls"| node_src_services
node_src_pages -->|"composes"| node_src_components
node_src_components -->|"built on"| node_src_ui
node_src_contexts -->|"syncs"| node_src_supabase_client
node_src_services -->|"queries"| node_src_supabase_client
node_src_services -.->|"may call"| node_backend_app
node_src_supabase_client -->|"data/API"| node_backend_app
node_backend_app -->|"governed by"| node_backend_schema
node_backend_app -.->|"bootstrapped by"| node_backend_seed
node_backend_app -->|"integrates with"| node_supabase_edge
node_supabase_edge -->|"updates"| node_backend_schema
node_supabase_edge -->|"triggers"| node_n8n_flows
node_n8n_flows -->|"contains"| node_whatsapp_bot
node_n8n_flows -->|"contains"| node_payment_flow
node_n8n_flows -->|"contains"| node_order_ready_flow
node_backend_schema -.->|"documented by"| node_docs_kb
node_src_components -.->|"references"| node_liquid_demo

click node_src_main "https://github.com/musaibbashir/mercanta/blob/main/src/main.tsx"
click node_src_app "https://github.com/musaibbashir/mercanta/blob/main/src/App.tsx"
click node_src_pages "https://github.com/musaibbashir/mercanta/tree/main/src/pages"
click node_src_contexts "https://github.com/musaibbashir/mercanta/tree/main/src/context"
click node_src_services "https://github.com/musaibbashir/mercanta/tree/main/src/services"
click node_src_components "https://github.com/musaibbashir/mercanta/tree/main/src/components"
click node_src_ui "https://github.com/musaibbashir/mercanta/tree/main/src/components/ui"
click node_src_layout "https://github.com/musaibbashir/mercanta/tree/main/src/components/layout"
click node_src_supabase_client "https://github.com/musaibbashir/mercanta/blob/main/src/lib/supabaseClient.ts"
click node_src_protected_route "https://github.com/musaibbashir/mercanta/blob/main/src/components/ProtectedRoute.tsx"
click node_backend_app "https://github.com/musaibbashir/mercanta/blob/main/backend/app.py"
click node_backend_schema "https://github.com/musaibbashir/mercanta/blob/main/backend/migration.sql"
click node_backend_seed "https://github.com/musaibbashir/mercanta/blob/main/backend/seed_data.sql"
click node_supabase_edge "https://github.com/musaibbashir/mercanta/blob/main/supabase/functions/razorpay-webhook/index.ts"
click node_n8n_flows "https://github.com/musaibbashir/mercanta/tree/main/n8n"
click node_whatsapp_bot "https://github.com/musaibbashir/mercanta/blob/main/n8n/wa_bot.json"
click node_payment_flow "https://github.com/musaibbashir/mercanta/blob/main/n8n/payment_confirmed.json"
click node_order_ready_flow "https://github.com/musaibbashir/mercanta/blob/main/n8n/order_ready.json"
click node_docs_kb "https://github.com/musaibbashir/mercanta/blob/main/docs/Mercanta-Knowledge-Base.html"
click node_liquid_demo "https://github.com/musaibbashir/mercanta/tree/main/Liquid-Gradient"

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_src_main,node_src_app,node_src_pages,node_src_contexts,node_src_services,node_src_components,node_src_ui,node_src_layout,node_src_supabase_client,node_src_protected_route toneBlue
class node_backend_app,node_backend_schema,node_backend_seed,node_supabase_edge toneAmber
class node_n8n_flows,node_whatsapp_bot,node_payment_flow,node_order_ready_flow toneMint
class node_docs_kb,node_liquid_demo toneRose
```

## Components

### Frontend App

React SPA, shared UI, and browser-side business state.

- [App entry](https://github.com/musaibbashir/mercanta/blob/main/src/main.tsx): vite-react entry · Bootstraps the browser application. · `src/main.tsx`
- [Shell](https://github.com/musaibbashir/mercanta/blob/main/src/App.tsx): route shell · Top-level app composition and routing. · `src/App.tsx`
- [Business screens](https://github.com/musaibbashir/mercanta/tree/main/src/pages): route pages · Role-based operational, admin, and franchise screens. · `src/pages`
- [Shared state](https://github.com/musaibbashir/mercanta/tree/main/src/context): auth/inventory context · Cross-cutting session and inventory state. · `src/context`
- [Domain services](https://github.com/musaibbashir/mercanta/tree/main/src/services): frontend service layer · Reusable data access and business helpers. · `src/services`
- [UI components](https://github.com/musaibbashir/mercanta/tree/main/src/components): shared components · Operational widgets and reusable presentation components. · `src/components`
- [Design system](https://github.com/musaibbashir/mercanta/tree/main/src/components/ui): ui primitives · Generic component library used across the SPA. · `src/components/ui`
- [Layout layer](https://github.com/musaibbashir/mercanta/tree/main/src/components/layout): app layout · Shared page framing and navigation structure. · `src/components/layout`
- [Supabase client](https://github.com/musaibbashir/mercanta/blob/main/src/lib/supabaseClient.ts): browser db client · Frontend boundary to the hosted data platform. · `src/lib/supabaseClient.ts`
- [Route guard](https://github.com/musaibbashir/mercanta/blob/main/src/components/ProtectedRoute.tsx): access control · Protects restricted pages in the SPA. · `src/components/ProtectedRoute.tsx`

### Backend & Data

Python service, Supabase/Postgres schema, and serverless data integrations.

- [API server](https://github.com/musaibbashir/mercanta/blob/main/backend/app.py): python app · Main backend application for transactional logic and integrations. · `backend/app.py`
- [Schema SQL](https://github.com/musaibbashir/mercanta/blob/main/backend/migration.sql): postgres migrations · Database migrations, constraints, and RLS policy fixes. · `backend/migration.sql`
- [Seed data](https://github.com/musaibbashir/mercanta/blob/main/backend/seed_data.sql): bootstrap data · Sample and franchise seeding for repeatable environments. · `backend/seed_data.sql`
- [Webhook edge](https://github.com/musaibbashir/mercanta/blob/main/supabase/functions/razorpay-webhook/index.ts): supabase function · Serverless Razorpay webhook handler in the Supabase runtime. · `supabase/functions/razorpay-webhook/index.ts`

### Automation

Event-driven workflows and messaging integrations.

- [n8n workflows](https://github.com/musaibbashir/mercanta/tree/main/n8n): automation flows · WhatsApp and order/payment orchestration workflows. · `n8n`
- [WA bot](https://github.com/musaibbashir/mercanta/blob/main/n8n/wa_bot.json): messaging workflow · WhatsApp bot and notification automation. · `n8n/wa_bot.json`
- [Payment flow](https://github.com/musaibbashir/mercanta/blob/main/n8n/payment_confirmed.json): event workflow · Payment-confirmed automation path. · `n8n/payment_confirmed.json`
- [Order-ready flow](https://github.com/musaibbashir/mercanta/blob/main/n8n/order_ready.json): event workflow · Order completion and ready notification workflow. · `n8n/order_ready.json`

### Docs & Assets

Supporting documentation and demo assets.

- [Knowledge base](https://github.com/musaibbashir/mercanta/blob/main/docs/Mercanta-Knowledge-Base.html): product docs · Internal documentation and operational reference. · `docs/Mercanta-Knowledge-Base.html`
- [Liquid demo](https://github.com/musaibbashir/mercanta/tree/main/Liquid-Gradient): demo asset · Standalone visual demo asset outside the core app. · `Liquid-Gradient`

## Connections

- App entry → Shell: renders · Application entry mounts the main shell.
- Shell → Business screens: routes to · Shell dispatches users into role-based screens.
- Shell → Layout layer: uses · Shared layout frames pages and navigation.
- Shell → Route guard: guards · Restricted routes are protected by auth checks.
- Business screens → Shared state: consumes · Screens read shared auth and inventory state.
- Business screens → Domain services: calls · Pages delegate data access and business actions to services.
- Business screens → UI components: composes · Operational UI is assembled from reusable components.
- UI components → Design system: built on · Feature components rely on the design system primitives.
- Shared state → Supabase client: syncs · Contexts use the client boundary for session and data state.
- Domain services → Supabase client: queries · Services fetch and mutate through the Supabase client.
- Domain services → API server: may call · Domain services can reach server-side application endpoints.
- Supabase client → API server: data/API · Browser-side data access ultimately depends on server-side logic and APIs.
- API server → Schema SQL: governed by · Server logic relies on the Postgres schema and RLS policies.
- API server → Seed data: bootstrapped by · Environments are initialized with sample and franchise data.
- API server → Webhook edge: integrates with · Webhook events enter through Supabase edge functions.
- Webhook edge → Schema SQL: updates · Webhook handling writes into the shared database schema.
- Webhook edge → n8n workflows: triggers · Payment or order events can fan out into automation workflows.
- n8n workflows → WA bot: contains · WhatsApp bot logic is one of the workflow paths.
- n8n workflows → Payment flow: contains · Payment-confirmation automation is modeled as a workflow.
- n8n workflows → Order-ready flow: contains · Order-ready notifications are modeled as a workflow.
- Schema SQL → Knowledge base: documented by · Operational knowledge supports schema and business-process understanding.
- UI components → Liquid demo: references · The repository includes a standalone visual demo asset alongside the app.
