Commerce Platform Blueprint

This folder turns the high-level "how Zomato / Zepto / Flipkart-style systems work" idea into a buildable backend blueprint for AIERP.

The current repository is a frontend POS application, so the right implementation here is:

• target service architecture
• POS / ERP integration model
• event contracts
• API contracts for the UI
• phased rollout plan

If you later split backend services into their own repos, these docs can become the source of truth for those repos.

Repo-Specific Blueprint

For the current multi-repo workspace, use this alongside the higher-level docs:

• repo-refactor-blueprint.md for exact ownership, schema, events, and migration steps across catalog-service, store-hub, api-gateway, sync-service, and retail-agent

What We Are Building

We want a platform that can support:

• restaurant menu sync from POS systems
• dark-store inventory sync from ERP / warehouse systems
• fast catalog serving for the POS and commerce apps
• real-time price and stock updates
• search and recommendations
• LLM-powered enrichment on top of raw supplier / seller data

Core Principles

1. Source systems remain authoritative.
2. Updates should be push-first, not polling-first.
3. All writes should become events.
4. Serving APIs should read from optimized views, not transactional raw tables.
5. Search, pricing, inventory, and enrichment should be independently deployable.
6. The UI should never wait on slow source systems directly.

Logical Architecture

flowchart LR
  POS[Restaurant POS / Merchant POS]
  ERP[ERP / WMS / Dark Store Systems]
  SELLER[Seller APIs / Brand Feeds]

  WEBHOOK[Webhook Gateway]
  ADAPTERS[Connector Adapters]
  NORMALIZER[Normalization Service]
  CATALOG[(Catalog Core DB)]
  EVENTS[(Kafka / Event Bus)]
  INVENTORY[Inventory Service]
  PRICING[Pricing Service]
  SEARCH[Search Indexer]
  CACHE[(Redis Cache)]
  API[Serving API / BFF]
  LLM[LLM Enrichment Pipeline]
  INDEX[(OpenSearch / Elasticsearch)]

  POS --> WEBHOOK
  ERP --> WEBHOOK
  SELLER --> ADAPTERS
  WEBHOOK --> NORMALIZER
  ADAPTERS --> NORMALIZER
  NORMALIZER --> CATALOG
  NORMALIZER --> EVENTS
  EVENTS --> INVENTORY
  EVENTS --> PRICING
  EVENTS --> SEARCH
  EVENTS --> LLM
  SEARCH --> INDEX
  INVENTORY --> CACHE
  PRICING --> CACHE
  INDEX --> API
  CACHE --> API
  CATALOG --> API

Service Boundaries

1. Webhook Gateway

Responsibilities:

• receive POS / ERP / seller callbacks
• authenticate source systems
• validate signatures
• deduplicate inbound events
• write raw payloads for replay / audit

This service should be extremely small and stable.

2. Connector Adapters

Responsibilities:

• convert source-specific formats into canonical commands
• hide vendor differences like PetPooja vs UrbanPiper vs Unicommerce
• map location / merchant / SKU / item identifiers

Examples:

• petpooja-menu-adapter
• urbanpiper-store-adapter
• unicommerce-inventory-adapter
• seller-feed-bulk-importer

3. Catalog Normalization Service

Responsibilities:

• canonicalize product/menu/store structures
• validate required attributes
• version item payloads
• emit canonical catalog events

This is the heart of ingestion.

4. Catalog Core DB

Recommended storage:

• PostgreSQL for normalized canonical data and history

Store:

• merchants
• locations / stores / dark stores
• products
• variants
• addon groups
• price books
• assortment mappings
• source mappings
• version history

5. Inventory Service

Responsibilities:

• maintain per-location stock state
• compute orderability
• reserve / release stock
• publish availability changes

Recommended storage:

• PostgreSQL for durable state
• Redis for hot availability

6. Pricing Service

Responsibilities:

• store base price
• apply tax / promotion / store overrides
• publish effective price changes

7. Search Service

Responsibilities:

• maintain search documents
• power keyword, category, and filter queries
• expose ranking-ready attributes

Recommended storage:

• OpenSearch / Elasticsearch

8. Recommendation Service

Responsibilities:

• co-purchase signals
• substitutes / complements
• location-aware trending items
• business-rule recommendations

Start simple with rules and event aggregates before ML.

9. LLM Enrichment Pipeline

Responsibilities:

• clean titles
• normalize units
• infer missing attributes
• generate tags and synonyms
• deduplicate near-identical supplier items

This should be asynchronous and never block critical catalog serving.

Primary Data Flows

Restaurant Menu Sync

1. Merchant updates item in POS.
2. POS sends webhook to Webhook Gateway.
3. Adapter maps vendor payload into canonical commands.
4. Normalizer upserts menu / variant / addon entities.
5. Event emitted:
6. catalog.menu_item.updated
7. pricing.price.updated
8. inventory.item_availability.updated
9. Search index refreshes.
10. Redis cache invalidates.
11. App sees updated menu.

Dark Store Inventory Sync

1. ERP or store OMS publishes stock delta.
2. Webhook Gateway accepts update.
3. Adapter resolves source SKU to canonical SKU.
4. Inventory service applies delta to store-level stock ledger.
5. Event emitted:
6. inventory.stock.changed
7. inventory.orderability.changed
8. Serving cache refreshes.
9. App shows out-of-stock or available state.

Seller Feed / Bulk Catalog Sync

1. Seller uploads CSV / API feed.
2. Bulk importer stores raw payload in object storage.
3. Normalizer transforms and validates rows.
4. Good rows upsert canonical entities.
5. Bad rows go to review queue.
6. Search and enrichment pipelines run asynchronously.

Suggested Technology Choices

MVP

• Webhook/API: FastAPI or NestJS
• Catalog DB: PostgreSQL
• Event bus: Kafka or Redpanda
• Cache: Redis
• Search: OpenSearch
• Async workers: Celery / Dramatiq / BullMQ / Temporal

Scale-Up

• Inventory hot path: Redis + PostgreSQL
• Heavy search/reco workloads: dedicated search and feature stores
• Replay / lineage: S3 + compacted event topics

Serving API Shape

The frontend should not call many backend systems directly. Expose one API layer or BFF with fast read models:

• GET /v1/catalog
• GET /v1/catalog/:itemId
• GET /v1/stores/:storeId/inventory
• GET /v1/stores/:storeId/search?q=milk
• GET /v1/stores/:storeId/recommendations?itemId=...

SLO Targets

Reasonable starting targets:

• webhook ack: < 300 ms
• catalog read: < 150 ms p95
• inventory update propagation: < 5 sec p95
• price update propagation: < 5 sec p95
• store search: < 200 ms p95

What To Build First

If you want working business value quickly, build in this order:

1. Webhook Gateway
2. Connector Adapter pattern
3. Canonical catalog schema
4. Inventory service
5. Redis-backed serving API
6. Search indexing
7. Recommendation rules
8. LLM enrichment

Files In This Folder

• README.md: architecture overview
• pos-integration-microservice.md: ingestion and sync design
• contracts.md: canonical entities, events, and APIs
• roadmap.md: phased rollout plan