ifixkart-admin/docs/architecture/iFixKart_Unified_Suite_Master_Plan.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- 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
2026-10-13 12:59:47 +05:30

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.