ifixkart-admin/Documentation/enterprise_system_architecture.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

188 lines
6.8 KiB
Markdown

# iFixKart Platform: Enterprise System Architecture & Business Capabilities Blueprint
This high-level blueprint provides a conceptual, ecosystem-wide view of the **iFixKart Unified Platform**. It highlights the business capabilities, system architecture blocks, cloud infrastructure topology, and end-to-end user journeys.
---
## 1. Business Capability Map
This diagram maps out the core business capabilities enabled by the platform, organized by operational area.
```mermaid
mindmap
root((iFixKart Platform))
Demand Generation
Website SEO & AEO
Google Merchant Center Sync
Meta Ads Lead Capture
Social Media Content Calendar
Channel & Sales Management
Customer Storefront (Next.js)
Walk-In In-Store POS (Billing)
Order Management (OMS)
Inventory Allocation Ledger
Service Delivery
Device Lookup wizard
Slot Booking Calendar
Advance Deposit Collection
Technician Job Portal
Finance & Operations
Sequential GST Invoicing
Automated Payout Reconciliation
RMA & Product Returns
Warranty Tracker
Security & Reliability
Role-Based Access (RBAC)
Audit Logs
Redis Lock Concurrency
Bailey Whatsapp Alerts
```
---
## 2. Platform Ecosystem Diagram
A high-level view showing how data flows across storefront applications, backends, databases, and third-party SaaS integrations.
```mermaid
graph TD
%% Users
customer((Customers))
admin_staff((Staff & Admins))
tech_staff((Technicians))
%% Channels
subgraph Channels ["Channels (Front-Ends)"]
storefront[Customer Storefront & Repair Portal]
admin_dashboard[Admin & Management CRM Dashboard]
tech_portal[Mobile-Friendly Technician Portal]
end
%% Core Services
subgraph Core ["Platform Services (Modular Monoliths)"]
ecomm_api[E-commerce API Service]
admin_api[Admin Operations API Service]
bailey_bot[Bailey WhatsApp Dispatcher]
end
%% Data Store
subgraph Storage ["Storage Layer"]
ecomm_db[(E-commerce DB)]
admin_db[(Admin DB)]
cache[(Redis Session & Cache)]
end
%% External Systems
subgraph External ["External Services"]
razorpay[Razorpay Payment Gateway]
shipping_rocket[ShippingRocket Logistics]
meta[Meta Marketing API]
gmc[Google Merchant Center]
end
%% Interconnections
customer -->|Accesses| storefront
admin_staff -->|Accesses| admin_dashboard
tech_staff -->|Accesses| tech_portal
storefront -->|REST APIs| ecomm_api
admin_dashboard -->|REST APIs| admin_api
tech_portal -->|REST APIs| admin_api
ecomm_api <-->|Sync Engine| admin_api
ecomm_api -->|Cache & Locks| cache
ecomm_api -->|Write/Read| ecomm_db
admin_api -->|Write/Read| admin_db
ecomm_api -.->|Triggers Alerts| bailey_bot
admin_api -.->|Triggers Alerts| bailey_bot
ecomm_api <-->|Collect Payments| razorpay
admin_api <-->|Generate Labels| shipping_rocket
admin_api <-->|Sync Feeds| gmc
admin_api <-->|Sync Leads| meta
classDef channel fill:#eff6ff,stroke:#2563eb,stroke-width:2px;
classDef core fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px;
classDef storage fill:#ecfdf5,stroke:#059669,stroke-width:2px;
classDef ext fill:#fffbeb,stroke:#d97706,stroke-width:1px;
class storefront,admin_dashboard,tech_portal channel;
class ecomm_api,admin_api,bailey_bot core;
class ecomm_db,admin_db,cache storage;
class razorpay,shipping_rocket,meta,gmc ext;
```
---
## 3. High-Level Cloud Infrastructure Topology
A typical Docker/AWS deployment structure running containerized micro-applications behind a reverse proxy.
```mermaid
graph TD
user_traffic[Storefront Users & API Requests] --> DNS[Route 53 DNS]
DNS --> LB[Nginx Load Balancer / Reverse Proxy]
subgraph Containers ["Container Cluster (Docker Swarm or ECS)"]
LB -->|Route: / | container_sf[Next.js Customer Storefront]
LB -->|Route: /admin | container_admin[Next.js Admin Dashboard]
LB -->|Route: /api/v1/storefront | container_api_ecomm[FastAPI E-commerce Service]
LB -->|Route: /api/v1/admin | container_api_admin[FastAPI Admin Service]
end
subgraph DataServices ["Managed Data Services"]
container_api_ecomm & container_api_admin --> db_rds[(Amazon RDS MySQL Master)]
container_api_ecomm --> cache_redis[(Amazon ElastiCache Redis)]
end
subgraph VPC ["Private Network Subnet"]
container_api_ecomm
container_api_admin
db_rds
cache_redis
end
```
---
## 4. Conceptual End-to-End User Journeys
### 4.1 The Customer Purchase Journey
```mermaid
stateDiagram-v2
[*] --> Discovery : Google Shopping/Organic Search
Discovery --> BrowseCatalog : Browse parts & devices
BrowseCatalog --> CartInteraction : Add item (System holds Soft-Lock)
CartInteraction --> Checkout : Provide address details
Checkout --> PaymentGateway : Trigger Razorpay portal
PaymentGateway --> ConfirmPurchase : Payment succeeds
ConfirmPurchase --> ShippingRocket : Automated order sync
ShippingRocket --> [*] : Delivery update sent to customer
```
### 4.2 The Device Repair Booking & Repair Journey
```mermaid
stateDiagram-v2
[*] --> DeviceSelection : Select Model (e.g., iPhone 15 Pro)
DeviceSelection --> IssueSelection : Pick issue (Screen replacement)
IssueSelection --> SlotBooking : Choose Date & Time slot
SlotBooking --> PayDeposit : Pay 30% advance on Razorpay
PayDeposit --> BookingConfirmed : Notification sent to team via Bailey
BookingConfirmed --> TechAssigned : Admin assigns job to Technician
TechAssigned --> RepairStart : Device received & repair begins
RepairStart --> BalancePaid : Job complete; customer pays remaining 70%
BalancePaid --> InvoiceIssued : GST invoice generated & logged
InvoiceIssued --> [*] : Device returned with active warranty
```
---
## 5. Transition Plan & Business Value Progression
The deployment of these capabilities is mapped out across logical implementation milestones:
| Phase | Capability Focus | Business Value | Operational Impact |
| :--- | :--- | :--- | :--- |
| **Phase 1: Foundation** | Online Checkout, Slot Booking, Basic Invoicing | Open digital storefront channel | Customers can book & buy 24/7 without calling |
| **Phase 2: Sync** | CRM Pipeline, Shipping Integration, POS | Single Customer Profile | Sales/Service database consolidated; labels printed automatically |
| **Phase 3: Automation** | Stock Locks, Reconciliation, Bailey WhatsApp | Close revenue leakages | No double-booking; payment errors flagged instantly; zero stalled bookings |
| **Phase 4: Loyalty** | Warranties, RMA workflows, Loyalty credits | Maximize customer Lifetime Value (LTV) | Automated warranty verification; repeat purchases incentivized |