- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
18 KiB
Master Architectural Specification: iFixKart Unified Commerce, CRM & Repair ERP Suite
Executive Overview
This document represents the production-grade, finalized architectural specification for the iFixKart Unified Suite. It integrates E-Commerce, CRM, Repair ERP, Inventory, GST Billing, Review Moderation with Audit Trails, SLA Management, Multi-Dashboard Analytics, a Self-Hosted WhatsApp Web Notification Gateway (OpenWA), and a ZeptoMail / Zoho CPaaS Email Gateway (info@trionixsolution.com), built on a multi-tenant ready schema, Redis Streams event bus, dedicated worker architecture, Dead Letter Queue (DLQ), full observability, and enterprise disaster recovery.
Canonical Enterprise System Architecture
flowchart TD
subgraph Client_Layer ["Client Layer"]
REACT["React Admin Panel"]
STOREFRONT["Next.js Storefront & POS"]
end
REACT & STOREFRONT -->|HTTPS / WSS| FASTAPI["FastAPI API Gateway\n(JWT Auth + RBAC + Multi-Tenant Context)"]
subgraph Domain_Services ["Domain Micro-Services Layer"]
CRM["CRM Service\n(Customers, Contacts, Leads, Deals, Segments)"]
REPAIR["Repair ERP Service\n(Devices, IMEI Registry, Tickets, Technicians)"]
COMMERCE["Commerce & POS Service\n(Products, Inventory, Orders, POS)"]
FINANCE["Billing & Finance Service\n(GST Invoices, Payments, Warranty, Refunds)"]
end
FASTAPI --> CRM & REPAIR & COMMERCE & FINANCE
CRM & REPAIR & COMMERCE & FINANCE --> DB[(MySQL 8 Database Cluster)]
subgraph Event_Driven_Infrastructure ["Event Bus & Notification Infrastructure"]
EVENT_LAYER["Business Event Publisher"]
REDIS_STREAMS[("Redis Streams Event Bus")]
FINANCE & CRM & REPAIR & COMMERCE --> EVENT_LAYER --> REDIS_STREAMS
REDIS_STREAMS --> EMAIL_WORKER["Email Worker Process"]
REDIS_STREAMS --> WA_WORKER["WhatsApp Worker Process"]
REDIS_STREAMS --> PUSH_WORKER["Push Worker Process"]
EMAIL_WORKER --> ZEPTOMAIL["ZeptoMail / Zoho CPaaS Gateway\n(info@trionixsolution.com)"]
PUSH_WORKER --> WEBPUSH["Web Push Gateway"]
subgraph WA_Gateway_Architecture ["Self-Hosted WhatsApp Gateway"]
WA_WORKER --> SESS_REGISTRY["Session Registry Engine"]
SESS_REGISTRY --> OPENWA["OpenWA Instance(s)"]
OPENWA --> SESS_VOL[("Persistent Session Volume Storage")]
end
OPENWA --> WA_NET["WhatsApp Network"]
WA_WORKER & EMAIL_WORKER & PUSH_WORKER -->|Failed Max Retries| DLQ[("Dead Letter Queue (DLQ)")]
end
subgraph Observability_Layer ["Observability & System Health"]
MONITORING["Monitoring & Telemetry Hub\n(Metrics, Latency, Queue Depth, Connection State)"]
HEALTH["Health Endpoints (/health, /health/db, /health/redis, /health/whatsapp)"]
end
FASTAPI & REDIS_STREAMS & DB & OPENWA --> MONITORING & HEALTH
1. Multi-Tenant Foundation & Database Architecture
A. Multi-Tenancy Strategy (tenant_id)
To ensure future multi-business isolation without requiring schema refactoring later, every core table incorporates a tenant_id column from Phase 0.
B. Tenant-Scoped Unique Constraints
All natural key uniqueness constraints are explicitly scoped to tenant_id to prevent cross-tenant data collisions:
UNIQUE(tenant_id, phone)oncustomersUNIQUE(tenant_id, sku)onproductsUNIQUE(tenant_id, invoice_number)oninvoicesUNIQUE(tenant_id, imei)ondevices
C. Core MySQL 8 Database Entities
The database schema consists of 23 explicitly defined entities:
tenants: Multi-tenant organization records.users: System users, admins, technicians, and sales reps.roles: Role definitions (Super Admin,Admin,Technician,Sales Rep,Store Staff).permissions: Granular permission nodes (e.g.repairs.create,invoices.approve).customers: Master customer profiles (sales_tier,service_tier,LTV,is_dual_customer).contacts: Customer contact methods and address book entries.leads: Inbound lead inquiries, lead scores, and source tracking.deals: Sales pipeline deals (Kanban stages, estimated value, probability).products: E-Commerce and POS product catalog with SKU, brand, and category.inventory: Multi-warehouse stock tracking and low-stock threshold triggers.warehouses: Physical store locations and inventory storage hubs.devices: Customer device registry (Make, Model, Color, Serial/IMEI).repairs: Mobile repair tickets (Diagnostic notes, assigned technician, ticket stage).repair_items: Parts allocated and labor charges per repair job.invoices: GST-compliant Tax Invoices, Pro-Forma quotes, and Credit Notes.payments: Payment transaction ledger (Razorpay, PhonePe, UPI, Cash).reviews: Customer reviews and ratings (is_approved,moderated_by,moderation_reason).notifications: Outbound notification master records (event_id,channel,status).notification_attempts: Individual delivery attempt logs (attempt_number,provider,error).dead_letter_notifications: Failed notifications exceeding max retries for manual admin inspection.whatsapp_sessions: Session registry credentials and connection states.audit_logs: System-wide immutable action audit trail.business_events: Event log history published to Redis Streams.
D. Database Governance & Audit Policies
- Foreign Key Strategy: Explicit foreign key constraints enforced with
ON DELETE RESTRICTfor financial and inventory safety. - Indexing Strategy: Composite indexes on
(tenant_id, created_at),(tenant_id, customer_id), and(tenant_id, status). - Soft Delete Policy: Soft deletes enforced via
deleted_at DATETIME NULLon transactional tables. - Audit Fields Policy: All applicable business entities contain standard audit fields (
created_at,created_by,updated_at,updated_by,deleted_at); system-generated and technical entities (e.g.notification_attempts,business_events,audit_logs) use system/service/event identifiers where user attribution is not applicable. - Transaction Boundaries: Strict database transaction blocks (
db.begin(),db.commit(),db.rollback()) around all multi-table updates (e.g., Repair Completion + Inventory Deduction + Invoice Creation).
2. Database Backup & Disaster Recovery Strategy
A. MySQL 8 Database Backup & Recovery
- Automated Daily Full Backup: Daily physical/logical snapshots (
mysqldump/Percona XtraBackup) executed at off-peak hours (02:00 UTC). - Point-In-Time Recovery (PITR): Continuous binary logging (
binlog) enabling point-in-time restoration down to the exact second. - Backup Encryption: All backup files encrypted at rest using AES-256 before storage.
- Off-Server Remote Storage: Encrypted backups automatically synced to isolated remote cloud storage (AWS S3 / Google Cloud Storage) across separate geographic regions.
- Retention Policy: 30 days of daily backups, 12 months of monthly archive snapshots.
- Automated Restore Testing: Monthly automated restoration drills in an isolated staging environment to verify backup integrity and compute Recovery Time Objective (RTO < 1 hour) and Recovery Point Objective (RPO < 5 mins).
B. Redis Streams Persistence & Recovery
- Hybrid Persistence Strategy: Configured with combined RDB snapshots (every 15 mins) and AOF (Append-Only File) synced with
fsync everysec. - Disaster Recovery Restart: In the event of a container crash, Redis automatically reconstructs the stream queue state from AOF on startup without losing unacknowledged business events.
C. OpenWA Persistent Session Backup
- Session Storage Backup: Daily automated backup of
/var/lib/openwa/sessionspersistent volume archives. - Session Encryption: Session state files encrypted before remote storage to safeguard WhatsApp tokens.
- Fast Session Restore: Container recovery script mounts the session volume back into new OpenWA container instances, restoring WhatsApp connection state without requiring QR re-scanning.
3. Notification Infrastructure, Redis Streams & Worker Architecture
A. Async Worker Architecture (Decoupled & Scalable)
Notification triggers bypass synchronous request loops. FastAPI publishes events to Redis Streams, where decoupled dedicated worker processes consume and execute notifications asynchronously:
flowchart LR
FastAPI["FastAPI App"] -->|Publish Event| RedisStreams["Redis Streams"]
subgraph Workers ["Independent Worker Scale Set"]
RedisStreams --> EmailWorker["Email Worker (ZeptoMail API / SMTP)"]
RedisStreams --> WAWorker["WhatsApp Worker (OpenWA Gateway)"]
RedisStreams --> PushWorker["Push Worker (Web Push / FCM)"]
end
EmailWorker --> ZeptoMail["ZeptoMail / Zoho CPaaS (info@trionixsolution.com)"]
WAWorker --> OpenWA["OpenWA Notification Gateway"]
PushWorker --> WebPush["FCM / Web Push"]
B. Email Gateway Integration Details (ZeptoMail / Zoho CPaaS)
- Provider: ZeptoMail / Zoho CPaaS API & SMTP
- Host:
smtp.zeptomail.in/cpaas.zoho.in - Ports:
465 (SSL)/587 (TLS) - Sender Email:
info@trionixsolution.com - SMTP Username:
emailapikey - API REST Endpoint:
https://cpaas.zoho.in/v1.1/email - Auth Header:
Authorization: Zoho-enczapikey <password_token>
C. Delivery Safety, Circuit Breakers & Dead Letter Queue (DLQ)
- Rate Limiter: Strict message rate limits per recipient/channel (e.g. Max 5 msgs/min).
- Retry Policy: Exponential backoff retry policy (Attempts at 0s, 30s, 2m).
- Circuit Breaker: Automatically trips and pauses queue consumption if OpenWA or ZeptoMail reports service unavailability.
- Dead Letter Queue (DLQ): If a notification fails all 3 attempts, it is moved to
dead_letter_notificationsfor manual admin inspection and one-click resend.
D. Normalized Notification Log Schemas
1. notifications (Master Notification Record)
| Field | Type | Description |
|---|---|---|
id |
VARCHAR(36) |
Unique ULID (NOT-10292) |
tenant_id |
VARCHAR(36) |
Multi-tenant ID |
event_id |
VARCHAR(36) |
Source Business Event ID |
recipient |
VARCHAR(255) |
Target Phone / Email / User ID |
channel |
ENUM |
WHATSAPP, EMAIL, WEB_PUSH |
template_id |
VARCHAR(100) |
Template reference ID |
status |
ENUM |
PENDING, QUEUED, SENDING, SENT, DELIVERED, READ, FAILED, CANCELLED |
created_at |
DATETIME |
Event creation timestamp |
completed_at |
DATETIME |
Final resolution timestamp |
2. notification_attempts (Granular Delivery Attempts)
| Field | Type | Description |
|---|---|---|
id |
VARCHAR(36) |
Unique ULID (ATT-5011) |
notification_id |
VARCHAR(36) |
Foreign Key to notifications.id |
attempt_number |
INT |
1, 2, or 3 |
provider |
VARCHAR(50) |
OpenWA, ZeptoMail, FCM |
request_id |
VARCHAR(100) |
External Gateway Message ID |
status |
ENUM |
SUCCESS, FAILED |
error_log |
TEXT |
Diagnostic exception stack trace |
created_at |
DATETIME |
Execution timestamp |
4. OpenWA WhatsApp Gateway Architecture & Session Registry
A. Multi-Session Registry Architecture
To support single or multiple WhatsApp numbers per business tenant, FastAPI manages a Session Registry:
FastAPI Gateway
│
▼
WhatsApp Service Router
│
▼
Session Registry
│
├── Tenant A Session 1 (OpenWA Container Instance 1)
└── Tenant A Session 2 (OpenWA Container Instance 2)
│
├── Session Storage (/var/lib/openwa/sessions/tenant_a_1)
├── QR Manager (Base64 QR Stream to Admin Panel)
├── Connection Monitor (Ping health check every 30s)
└── Event Manager (Capture ACK, SENT, DELIVERED)
B. Secure Server-Side Proxy Isolation
The React Admin Panel never exposes OpenWA master API keys or direct container ports. The browser connects exclusively to FastAPI endpoints via JWT-authenticated HTTPS/WSS routes:
flowchart LR
ReactAdmin["React Admin Panel"] -->|HTTPS / WSS (User JWT)| FastAPIProxy["FastAPI Proxy Router"]
FastAPIProxy -->|Authenticated Internal REST (Master Key)| OpenWA["OpenWA Instance"]
OpenWA -->|WhatsApp Web Protocol| WANet["WhatsApp Network"]
5. Secrets Management & Production Configuration
All sensitive keys are strictly managed via environment variables and production secrets key vaults (Docker Secrets / HashiCorp Vault). Secrets are never committed to Git or exposed in client bundles.
Secrets Hierarchy
├── JWT_SECRET (User session signing)
├── OPENWA_MASTER_KEY (Internal gateway authorization)
├── DATABASE_PASSWORD (MySQL 8 credentials)
├── REDIS_CREDENTIALS (Redis Streams password)
├── EMAIL_SENDER_ADDRESS ("info@trionixsolution.com")
├── ZEPTOMAIL_HOST ("smtp.zeptomail.in" / "cpaas.zoho.in")
├── ZEPTOMAIL_API_KEY (Zoho enczapikey token)
└── ENCRYPTION_KEYS (Field-level customer PII encryption)
6. Configurable Capacity Ratios & Review Moderation Audit
A. Configurable VIP Capacity Ratio (booking_capacity_config)
Rather than hard-coding VIP capacity limits, ratios are stored in system configuration:
{
"general_capacity_percentage": 80,
"priority_capacity_percentage": 20
}
Admins can adjust capacity ratios dynamically (e.g. 70/30 or 90/10) from the Admin Settings dashboard without code redeployment.
B. Strict Review Moderation Audit Trail
Every review submission follows a strict moderation lifecycle with full auditing:
- Moderation States:
PENDING➔APPROVED(Visible on Storefront) ORREJECTED(Hidden). - Audit Fields:
moderated_by: User ID of approving/rejecting admin or sales manager.moderated_at: Timestamp of moderation action.moderation_reason: Mandatory notes field explaining why a review was rejected (e.g., "Spam", "Profanity", "Irrelevant").
7. System Observability & Health Monitoring
The system exposes structured telemetry and dedicated health check endpoints for uptime monitoring tools (Prometheus, Grafana, Datadog):
A. System Health Endpoints
/health: Overall system status./health/db: MySQL database connection pool health & latency./health/redis: Redis Streams connection and queue depth./health/email: ZeptoMail API / SMTP gateway status./health/whatsapp: OpenWA gateway session state (CONNECTED,DISCONNECTED,BATTERY_LEVEL).
B. Monitored Telemetry Metrics
- Application logs (JSON structured logging).
- Error rates & stack traces.
- API response latency (P95, P99).
- Redis queue depth & worker consumer lag.
- Email & WhatsApp message success / failure / delivery rates.
8. Master 8-Phase Implementation Roadmap
gantt
title iFixKart Master Implementation Roadmap
dateFormat YYYY-MM-DD
section Phase 0 & Core
Phase 0 — Foundation & Architecture :p0, 2026-10-01, 7d
Phase 1 — CRM Core Engine :p1, after p0, 10d
section Operations & ERP
Phase 2 — Repair ERP & IMEI Management :p2, after p1, 12d
Phase 3 — Inventory & E-Commerce POS :p3, after p2, 10d
Phase 4 — Billing & GST Finance :p4, after p3, 8d
section Gateways & Analytics
Phase 5 — WhatsApp (OpenWA) & ZeptoMail:p5, after p4, 8d
Phase 6 — Review Moderation System :p6, after p5, 6d
Phase 7 — Multi-Dashboard Suite :p7, after p6, 8d
Detailed Phase Breakdown:
- Phase 0 — Foundation Infrastructure:
- Multi-tenant JWT Authentication, Role-Based Access Control (RBAC), Audit Log framework, Business Event Publisher, Redis Streams setup, Notification Worker base, Secrets management (ZeptoMail / OpenWA), System
/healthendpoints, Backup scripts.
- Multi-tenant JWT Authentication, Role-Based Access Control (RBAC), Audit Log framework, Business Event Publisher, Redis Streams setup, Notification Worker base, Secrets management (ZeptoMail / OpenWA), System
- Phase 1 — CRM Core Engine:
- Customer profiles (
sales_tier,service_tier,LTV), Contact hierarchy, Leads engine, Deals Kanban pipeline, Customer 360 view.
- Customer profiles (
- Phase 2 — Repair ERP & IMEI Management:
- Device catalog, IMEI/Serial registry, Repair Tickets lifecycle, Diagnostic checklists, Technician dispatch, Status tracking, Repair Estimates, QC testing, Warranty records.
- Phase 3 — Inventory + E-Commerce POS:
- Products catalog, Spare parts stock management, Multi-warehouse inventory, Suppliers, Purchase orders, Order fulfillment, POS interface, Stock movement ledger.
- Phase 4 — Billing & GST Finance:
- GST Tax Invoices (Line item IMEI & SAC/HSN tax), Payment ledgers, Refunds, Credit Notes, Warranty vouchers, Bulk Quotation engine.
- Phase 5 — Self-Hosted WhatsApp Gateway (OpenWA) & Email Gateway (ZeptoMail):
- OpenWA container microservice, ZeptoMail API/SMTP Integration (
info@trionixsolution.com), FastAPI proxy router, QR Pairing UI (/admin/whatsapp-gateway), Session Storage volume backup, Session Registry, Worker consumers, Rate limiter, Circuit breaker, Dead Letter Queue (DLQ),notifications¬ification_attemptsaudit tables.
- OpenWA container microservice, ZeptoMail API/SMTP Integration (
- Phase 6 — Review & Reputation System:
- Submission endpoints, Moderation approval queue with audit fields (
moderated_by,moderation_reason), Public storefront sync, Rating analytics, Negative feedback rescue workflow.
- Submission endpoints, Moderation approval queue with audit fields (
- Phase 7 — Multi-Dashboard Analytics Suite:
- CRM Dashboard, Repair ERP Dashboard, Inventory Dashboard, Sales Dashboard, Finance Dashboard, Review Dashboard, Technician Dashboard.