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

6.8 KiB

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.

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.

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.

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

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

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