How musaibbashir/mercanta works
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: app.py API server · App.tsx Shell · pages Business screens · n8n n8n workflows
Components 20
Frontend App
React SPA, shared UI, and browser-side business state.
- App entry · Bootstraps the browser application.
src/main.tsx - Shell · Top-level app composition and routing.
src/App.tsx - Business screens · Role-based operational, admin, and franchise screens.
src/pages - Shared state · Cross-cutting session and inventory state.
src/context - Domain services · Reusable data access and business helpers.
src/services - UI components · Operational widgets and reusable presentation components.
src/components - Design system · Generic component library used across the SPA.
src/components/ui - Layout layer · Shared page framing and navigation structure.
src/components/layout - Supabase client · Frontend boundary to the hosted data platform.
src/lib/supabaseClient.ts - Route guard · Protects restricted pages in the SPA.
src/components/ProtectedRoute.tsx
Backend & Data
Python service, Supabase/Postgres schema, and serverless data integrations.
- API server · Main backend application for transactional logic and integrations.
backend/app.py - Schema SQL · Database migrations, constraints, and RLS policy fixes.
backend/migration.sql - Seed data · Sample and franchise seeding for repeatable environments.
backend/seed_data.sql - Webhook edge · Serverless Razorpay webhook handler in the Supabase runtime.
supabase/functions/razorpay-webhook/index.ts
Automation
Event-driven workflows and messaging integrations.
- n8n workflows · WhatsApp and order/payment orchestration workflows.
n8n - WA bot · WhatsApp bot and notification automation.
n8n/wa_bot.json - Payment flow · Payment-confirmed automation path.
n8n/payment_confirmed.json - Order-ready flow · Order completion and ready notification workflow.
n8n/order_ready.json
Docs & Assets
Supporting documentation and demo assets.
- Knowledge base · Internal documentation and operational reference.
docs/Mercanta-Knowledge-Base.html - Liquid demo · Standalone visual demo asset outside the core app.
Liquid-Gradient
Connections 22
- 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.