E-commerce Demo Shop + Event Tracker + Agentic Insights Platform

This repository contains a full-stack demo system that simulates a modern product analytics platform:

• Demo e-commerce shop (React)
• Embeddable tracking SDK (Mixpanel/GA-lite)
• Backend ingestion + raw event store (NestJS + Prisma + SQLite)
• CQRS-style analytics read models
• Agentic insights generation workflow
• Analytics dashboard (React)

This project is designed to demonstrate senior-level architectural judgment, decomposition, and vertical slice delivery.

---

Architecture Overview

Shop (React) 
   |
   | tracker.js (SDK)
   v
Backend (NestJS)
   - Raw Event Ingestion (CQRS write side)
   - RawEvent table (immutable log)
   - Analytics Read APIs
   - Agentic Insights Scheduler
   - Insights table
   |
   v
Dashboard (React)
   - Stats (aggregations)
   - Insights (human-readable)

Key concepts: - Immutable raw event log - Separate write and read paths (CQRS) - Background agentic workflow for insights - Frontend decoupled via SDK

---

Repo Structure

e-commerce-shop/
  backend/              # NestJS API + tracker.js + Prisma
  shop-frontend/        # React demo shop (Vite)
  dashboard-frontend/   # React analytics dashboard (Vite)

packages/
  shared/               # Shared TypeScript types

docs/
  agent-notes/          # Simulated multi-agent delegation notes

---

Prerequisites

• Node.js 18+
• npm
• SQLite (via Prisma, bundled)

---

Install Dependencies

From repo root:

npm install

---

Initialize Database

cd e-commerce-shop/backend
npx prisma migrate dev

Optional (recommended for demo/debug):

npx prisma studio

---

Start All Services

From repo root:

npm run dev

This starts:

• Backend API: http://localhost:3000
• Shop frontend: Vite dev server (usually http://localhost:5173)
• Dashboard frontend: Vite dev server (usually http://localhost:5174)

---

Health & Sanity Checks

Backend health

Open:

http://localhost:3000/health

Expected:

{ "status": "ok" }

Tracker SDK

Open:

http://localhost:3000/tracker.js

You should see JavaScript source.

---

End-to-End Test Flow

1. Use the Shop

Open the shop frontend.

Perform:

• View product
• Add to cart
• Remove from cart
• Checkout
• Complete purchase

2. Verify Network Events

In browser DevTools: - Look for POST requests to: - http://localhost:3000/events

Event types: - product_viewed - add_to_cart - remove_from_cart - checkout_started - purchase_completed

---

Verify Raw Events

Open Prisma Studio:

cd e-commerce-shop/backend
npx prisma studio

Check: - RawEvent table - Confirm events are persisted

---

Analytics API

Test aggregations:

http://localhost:3000/analytics/events/counts?shopId=shop_123

Expected response:

{
  "shopId": "shop_123",
  "counts": [
    { "eventName": "product_viewed", "count": 10 },
    { "eventName": "add_to_cart", "count": 5 }
  ]
}

---

Agentic Insights

Insights are generated by a background scheduler.

Default cadence: every 5 minutes.

Test endpoint:

http://localhost:3000/insights?shopId=shop_123

Example insight:

• Cart to purchase conversion opportunity
• Recent purchases detected
• High product interest but no purchases

These are generated automatically from heuristics.

---

Dashboard

Open the dashboard frontend.

Stats Page

• Displays event counts by type

Insights Page

• Displays human-readable insights
• Pulled from /insights API

---

Tracker SDK Embed Example

<script src="http://localhost:3000/tracker.js"></script>
<script>
  tracker.init({
    apiKey: "demo-shop",
    endpoint: "http://localhost:3000",
    shopId: "shop_123"
  });
</script>

---

Design Decisions

• Raw Event Log:
  • Immutable source of truth
  • Supports reprocessing and schema evolution
• CQRS:
  • Write path optimized for ingestion
  • Read path optimized for analytics
• Agentic Workflow:
  • Separates signal extraction from raw metrics
  • Prepares for LLM summarization
• SDK-based Tracking:
  • Decouples frontend from backend
  • Mirrors production analytics systems

---

Notes

This project intentionally prioritizes:

• Architectural clarity
• Thin vertical slices
• Production-shaped patterns
• Senior-level decomposition

Completeness over polish.