System architecture

How the pieces connect.

The big picture

Customers (retail)           Resellers (B2B)
      │                             │
      ▼                             ▼
 Shopify / Amazon / eBay       eSIM Hub Portal (WIP)
      │                             │
      │ webhooks                    │
      ▼                             ▼
    ─────────── OMS (Next.js) ────────────
                   │         │
                   ▼         ▼
          Supabase       Supplier APIs
          (products,     (Redteago,
           orders,        eSIM Go, etc.)
           customers)         │
                              ▼
                       eSIM / SIM delivered
                          to customer

Data flow: retail order

1. Customer places order on Shopify / Amazon / eBay
2. Order webhook delivers to OMS
3. OMS looks up SKU in Supabase products table
4. OMS runs routing logic → picks an active variant
5. OMS calls that variant’s supplier API to provision
6. Supplier returns QR code / activation details
7. OMS stores fulfillment record and emails customer
8. Customer activates, traffic flows over carrier network

Data flow: B2B order (future, once eSIM Hub launches)

1. Reseller logs into eSIM Hub
2. Reseller browses catalog (reads Supabase products)
3. Reseller adds SKUs + quantity to cart
4. Portal looks up effective price (customer-specific → tier)
5. Reseller confirms order, payment confirmation TBD
6. Portal creates order in eSIM Hub DB, provisions via supplier
7. Reseller can track all orders in Portal dashboard

Shared state between OMS and eSIM Hub

The product catalog (products, product_variants, suppliers, product_price_tiers, customer_specific_prices) is shared between OMS and eSIM Hub. Both systems read from the same Supabase project.

Order tables are separate:

• OMS owns retail orders (from Shopify / Amazon / eBay)
• eSIM Hub owns wholesale orders

A reporting layer (TBD) will union both for unified financial views.

Chatbot integration

The Chatbot (Cloudflare Workers) reads from two places:

• Knowledge base chunks (Supabase kb_chunks) — for general Q&A, articles, policies
• products table — for live product info (price, coverage, data amount)

The chatbot never caches product data. Price is always a live query — stale prices in a chatbot are a customer-trust disaster.

Competitor monitoring

Runs as a scheduled Cloudflare Worker, writes results to Cloudflare D1. Separate from the main stack because it’s read-only and can fail without affecting operations.

Known architectural debt

• OMS and eSIM Hub are on separate Supabase projects as of now. Product catalog should be in one shared project or synced.
• No shared reporting / analytics layer yet
• Shopify → OMS sync is webhook-based (fragile); a reconciliation job should run hourly
• Supplier API calls have no retry / dead-letter queue
• No environment separation (staging vs prod) for OMS

These are all candidates for ADRs once we’re ready to tackle them.