ifixkart-admin/docs/architecture/overview.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

2.9 KiB

iFixKart Platform Architecture Overview

Executive Summary

iFixKart is an enterprise-grade Unified Commerce & Service Platform designed to serve both online digital customers and physical retail storefronts. The platform integrates high-concurrency e-commerce browsing, multi-tenant inventory control, automated GST invoicing, Razorpay payment processing, and an offline-first POS counter billing engine.


High-Level System Architecture

flowchart TD
    subgraph Client Layer
        WebStorefront["Next.js Storefront (Port 3021)"]
        AdminERP["Admin ERP/CRM Portal (Port 3022)"]
    end

    subgraph Backend Application ["FastAPI Modular Monolith (Port 8000)"]
        APIRouters["12 Separate Domain Routers\n(OrderRouter, CartRouter, InvoiceRouter...)"]
        ServicesLayer["3-Layer Business Services"]
        APIRouters --> ServicesLayer
    end

    subgraph Storage & Projections
        MySQLPrimary[("MySQL Primary DB\n(Transactional Source of Truth)")]
        RedisCache[("Redis Cache\n(Session / Price / Cart)")]
        OpenSearchProj[("OpenSearch Engine\n(Search / Facet Projection)")]
    end

    subgraph Outbox & Worker Pipeline
        OutboxTable["MySQL Outbox Table"]
        RabbitMQBroker["RabbitMQ Message Broker"]
        CeleryWorkers["Celery Workers"]
        
        SearchWorker["Search Index Worker"]
        InvoiceWorker["Invoice Generation Worker"]
        PaymentWorker["Payment Reconciliation Worker"]
        POSWorker["POS Sync Worker"]

        CeleryWorkers --> SearchWorker
        CeleryWorkers --> InvoiceWorker
        CeleryWorkers --> PaymentWorker
        CeleryWorkers --> POSWorker
    end

    subgraph Offline POS Store Environment
        TauriPOSApp["Tauri Desktop POS App"]
        SQLiteLocalDB[("SQLite Local DB")]
        TauriPOSApp <--> SQLiteLocalDB
    end

    Client Layer --> Backend Application
    ServicesLayer --> MySQLPrimary
    ServicesLayer --> RedisCache
    ServicesLayer --> OpenSearchProj
    
    MySQLPrimary --> OutboxTable
    OutboxTable --> RabbitMQBroker
    RabbitMQBroker --> CeleryWorkers
    
    SearchWorker --> OpenSearchProj
    PaymentWorker --> RazorpayAPI["Razorpay Payment Gateway"]
    
    TauriPOSApp <-->|Sync Protocol| APIRouters

Core System Characteristics

  1. Transactional Source of Truth: MySQL database via SQLAlchemy, operating with ULID primary keys.
  2. Derived Projections: OpenSearch for catalog search/faceting and Redis for high-frequency caching.
  3. Transactional Outbox Pattern: Decouples MySQL database mutations from async background workers to prevent state drift.
  4. Offline POS Capability: Desktop Tauri application backed by a local SQLite engine with automatic synchronization queues and idempotency guards.
  5. Decoupled 3-Layer Architecture: Routers \rightarrow Business Services \rightarrow Repositories across 12 separate domain router files.