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

1.6 KiB

Target Architecture Specification

1. Modular Monolith Framework

The backend operates as a FastAPI Modular Monolith structured into 12 dedicated domain routers, backed by a strict 3-layer architecture (Routers -> Services -> Repositories).

Backend/app/
├── api/v1/routers/        # Dedicated Router Files
├── services/             # Domain Logic Layer
├── repositories/         # SQLAlchemy Data Access
├── models/               # Database Entities
├── schemas/              # Pydantic Schemas
├── workers/              # Celery Async Workers
└── infrastructure/       # Redis, OpenSearch, RabbitMQ

2. Source of Truth vs. Derived Projections

flowchart TD
    MySQL[("MySQL Database\n(Transactional Source of Truth)")]
    Outbox["Outbox Event Log"]
    RabbitMQ["RabbitMQ Broker"]
    Workers["Celery Workers"]
    
    OpenSearch[("OpenSearch Engine\n(Catalog Search Projection)")]
    Redis[("Redis Cache\n(Session/Cart Projection)")]
    Analytics[("Analytics Store")]

    MySQL --> Outbox
    Outbox --> RabbitMQ
    RabbitMQ --> Workers
    Workers --> OpenSearch
    Workers --> Redis
    Workers --> Analytics

Fallback & Resilience Rules

  1. OpenSearch Outage: Circuit breaker trips. Simple ID/SKU lookups fall back to MySQL; complex 15-filter searches are rate-limited/rejected gracefully.
  2. Redis Outage: System degrades to direct MySQL reads safely.
  3. Checkout Validation: Checkout ALWAYS revalidates product price and available stock against the MySQL transactional engine before order creation.