- 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
328 lines
18 KiB
Markdown
328 lines
18 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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)` on `customers`
|
|
* `UNIQUE(tenant_id, sku)` on `products`
|
|
* `UNIQUE(tenant_id, invoice_number)` on `invoices`
|
|
* `UNIQUE(tenant_id, imei)` on `devices`
|
|
|
|
### C. Core MySQL 8 Database Entities
|
|
The database schema consists of 23 explicitly defined entities:
|
|
|
|
1. `tenants`: Multi-tenant organization records.
|
|
2. `users`: System users, admins, technicians, and sales reps.
|
|
3. `roles`: Role definitions (`Super Admin`, `Admin`, `Technician`, `Sales Rep`, `Store Staff`).
|
|
4. `permissions`: Granular permission nodes (e.g. `repairs.create`, `invoices.approve`).
|
|
5. `customers`: Master customer profiles (`sales_tier`, `service_tier`, `LTV`, `is_dual_customer`).
|
|
6. `contacts`: Customer contact methods and address book entries.
|
|
7. `leads`: Inbound lead inquiries, lead scores, and source tracking.
|
|
8. `deals`: Sales pipeline deals (Kanban stages, estimated value, probability).
|
|
9. `products`: E-Commerce and POS product catalog with SKU, brand, and category.
|
|
10. `inventory`: Multi-warehouse stock tracking and low-stock threshold triggers.
|
|
11. `warehouses`: Physical store locations and inventory storage hubs.
|
|
12. `devices`: Customer device registry (Make, Model, Color, Serial/IMEI).
|
|
13. `repairs`: Mobile repair tickets (Diagnostic notes, assigned technician, ticket stage).
|
|
14. `repair_items`: Parts allocated and labor charges per repair job.
|
|
15. `invoices`: GST-compliant Tax Invoices, Pro-Forma quotes, and Credit Notes.
|
|
16. `payments`: Payment transaction ledger (Razorpay, PhonePe, UPI, Cash).
|
|
17. `reviews`: Customer reviews and ratings (`is_approved`, `moderated_by`, `moderation_reason`).
|
|
18. `notifications`: Outbound notification master records (`event_id`, `channel`, `status`).
|
|
19. `notification_attempts`: Individual delivery attempt logs (`attempt_number`, `provider`, `error`).
|
|
20. `dead_letter_notifications`: Failed notifications exceeding max retries for manual admin inspection.
|
|
21. `whatsapp_sessions`: Session registry credentials and connection states.
|
|
22. `audit_logs`: System-wide immutable action audit trail.
|
|
23. `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 RESTRICT` for 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 NULL` on 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/sessions` persistent 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:
|
|
|
|
```mermaid
|
|
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_notifications` for 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:
|
|
|
|
```mermaid
|
|
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:
|
|
```json
|
|
{
|
|
"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) OR `REJECTED` (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
|
|
|
|
```mermaid
|
|
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 `/health` endpoints, Backup scripts.
|
|
* **Phase 1 — CRM Core Engine**:
|
|
- Customer profiles (`sales_tier`, `service_tier`, `LTV`), Contact hierarchy, Leads engine, Deals Kanban pipeline, Customer 360 view.
|
|
* **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` & `notification_attempts` audit tables.
|
|
* **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.
|
|
* **Phase 7 — Multi-Dashboard Analytics Suite**:
|
|
- CRM Dashboard, Repair ERP Dashboard, Inventory Dashboard, Sales Dashboard, Finance Dashboard, Review Dashboard, Technician Dashboard.
|