Ecomflow Technical Test

Production-grade ERP-WMS integration system showcasing clean architecture, event sourcing, and queue-based processing.

Architecture Overview

System Flow

Fulfil (ERP) → Ecomflow → Mabang (WMS)
     ↓            ↓            ↓
  Orders      Processing    Fulfillment

Tech Stack

Backend:

• Hono (Cloudflare Worker-compatible API)
• TypeScript (strict mode, zero comments)
• Drizzle ORM + PostgreSQL
• BullMQ + Redis (production-grade queues)
• Pino (structured logging)
• Prometheus metrics
• Zod validation

Frontend:

• React 18 + Vite
• TanStack Query (real-time updates)
• Tailwind CSS
• React Router

Architecture:

• Clean Architecture (entities, use cases, repositories, services)
• Event Sourcing (complete audit trail)
• SOLID principles
• Dependency Injection via interfaces

Project Structure

ecomflow-test/
├── backend/
│   ├── src/
│   │   ├── entities/           # Domain models
│   │   ├── repository/         # Data access (Drizzle)
│   │   ├── services/           # External integrations
│   │   ├── usecases/           # Business logic
│   │   ├── handlers/           # HTTP handlers
│   │   ├── router/             # Route registration
│   │   ├── queue/              # BullMQ processors
│   │   ├── middleware/         # Logging, metrics
│   │   ├── database/           # Drizzle schema + migrations
│   │   ├── types/              # TypeScript type definitions
│   │   └── validation/         # Zod schemas
│   ├── package.json
│   └── tsconfig.json
├── frontend/
│   ├── src/
│   │   ├── api/                # API client
│   │   ├── pages/              # React pages
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
├── docker-compose.yml          # PostgreSQL + Redis
└── dev-setup.sh                # Automated setup script

Quick Start

Prerequisites

• Node.js 20+
• pnpm 8+
• Docker Desktop (running)

Installation

Step 1: Install dependencies

pnpm install

Step 2: Start backend (databases + API)

pnpm dev:backend

This automatically:

• ✅ Checks Docker is running
• ✅ Starts PostgreSQL and Redis containers
• ✅ Waits for services to be ready
• ✅ Runs database migrations
• ✅ Starts the backend API

Step 3: Start frontend (in a new terminal)

pnpm dev:frontend

Access the app:

• Dashboard: http://localhost:5173
• API: http://localhost:3000
• API Docs: http://localhost:3000/doc

Health Checks

• API Health: http://localhost:3000/health
• Prometheus Metrics: http://localhost:3000/metrics

Features Implemented

Core Requirements ✅

• Order Flow: Fulfil → Ecomflow → Mabang with full state tracking
• Idempotency: Duplicate order detection via ERP Order ID
• Retry Strategy: BullMQ with exponential backoff (3 attempts: 1s, 2s, 4s)
• Reconciliation: Automated sync checks every 5 minutes
• Monitoring: Prometheus metrics + structured logs
• Dashboard: Real-time order status, reconciliation view

Bonus Features ✅

• Event Sourcing: Complete audit trail of all state transitions
• Clean Architecture: Entities, use cases, repositories, dependency injection
• Queue-Based Processing: BullMQ for reliable job execution
• Dead Letter Queue: Failed orders with manual retry capability
• API Documentation: Swagger UI at /doc with OpenAPI 3.0 spec
• Metrics & Health: Prometheus counters + deep health checks
• Type Safety: End-to-end TypeScript with Zod validation

Demo Features 🎯

• Dynamic Order Generation: Create test orders with configurable failure scenarios
• Visual Timeline: Interactive event timeline with circles and connecting lines
• Manual Retry: One-click retry for failed orders with full audit trail
• Database Reset: Quick reset button for clean demo runs
• Responsive Tables: Optimized for presentation mode
• Auto-Refresh: Real-time updates every 2-5 seconds

API Endpoints

Webhooks

• POST /api/v1/fulfil/orders - Receive orders from Fulfil ERP

Orders

• GET /api/v1/orders - List all orders with sync status
• GET /api/v1/orders/:id - Order details + event timeline

Failed Orders (Dead Letter Queue)

• GET /api/v1/failed-orders - List permanently failed orders
• GET /api/v1/failed-orders/stats - Get failed orders count
• POST /api/v1/failed-orders/:jobId/retry - Manually retry failed order

Reconciliation

• GET /api/v1/reconciliation - Latest reconciliation summary
• GET /api/v1/reconciliation/history - Historical reconciliation reports
• POST /api/v1/reconciliation/run - Trigger manual reconciliation

Testing & Demo

• POST /api/v1/seed/generate-orders - Generate test orders with failure scenarios
• POST /api/v1/system/reset - Clear all data (database + queues)

Monitoring

• GET /health - System health check (DB, Redis, queues)
• GET /metrics - Prometheus metrics (orders received/synced/failed)
• GET /doc - Interactive API documentation (Swagger UI)

Queue Architecture

BullMQ Queues

1. fulfil-sync-queue: Process incoming Fulfil orders

   • Validates order payload
   • Creates internal order entity
   • Stores events
   • Queues for WMS sync

2. mabang-push-queue: Sync orders to Mabang WMS

   • Transforms to Mabang format
   • Handles API failures
   • Implements retry logic
   • Updates sync state

3. reconciliation-queue: Automated reconciliation

   • Runs every 5 minutes
   • Compares ERP vs WMS state
   • Detects discrepancies
   • Stores results

Event Sourcing

All state changes are stored as immutable events:

• ORDER_RECEIVED_FROM_ERP
• ORDER_VALIDATED
• ORDER_QUEUED_FOR_WMS
• ORDER_SENT_TO_WMS
• ORDER_ACKNOWLEDGED_BY_WMS
• ORDER_FAILED_WMS_PUSH
• ORDER_MANUAL_RETRY
• SYNC_PERMANENTLY_FAILED
• SYNC_RETRY_SUCCESS
• WMS_STATUS_UPDATED
• RECONCILIATION_DISCREPANCY_DETECTED

Benefits:

• Complete audit trail
• Time-travel debugging
• Easy reconciliation
• Replay capabilities

Testing the Flow

1. Submit Test Order

Use the dashboard home page or curl:

curl -X POST http://localhost:3000/api/v1/fulfil/orders \
  -H "Content-Type: application/json" \
  -d '{
    "erpOrderId": "ORD-123",
    "organizationId": "org-456",
    "channelId": "shopify-store",
    "deliveryAddress": {
      "name": "John Doe",
      "address1": "123 Main St",
      "city": "Madrid",
      "zip": "28001",
      "countryCode": "ES",
      "subdivisionCode": "M",
      "phone": "+34612345678"
    },
    "lines": [{
      "id": 1,
      "product": {
        "id": 100,
        "name": "Test Product",
        "code": "SKU-001",
        "hsCode": "4202920000"
      },
      "quantity": 2,
      "currency": "EUR",
      "unitCustomsValue": 25.50
    }]
  }'

2. Monitor Progress

• Watch orders page for sync state updates
• Check order detail for event timeline
• View metrics endpoint for counters

3. Run Reconciliation

Click "Run Reconciliation" in the dashboard or:

curl -X POST http://localhost:3000/api/v1/reconciliation/run

Production Considerations

Monitoring & Alerts

Metrics to Track:

• ecomflow_orders_received_total - Order ingestion rate
• ecomflow_orders_failed_total - Failure rate by reason
• ecomflow_sync_duration_seconds - Sync performance
• ecomflow_reconciliation_discrepancies - Sync health

Alert Thresholds:

• Failure rate > 5%
• Sync duration > 10s
• Discrepancies > 10
• Queue depth > 1000

Scaling Strategy

1. Horizontal Scaling: Stateless API + worker pods
2. Queue Partitioning: Separate queues by organization
3. Database: Read replicas for queries
4. Caching: Redis for order status lookups
5. Rate Limiting: Per-organization limits

Security Enhancements

• API key authentication for ERP webhooks
• Webhook signature verification
• Rate limiting per organization
• Input sanitization (already using Zod)
• Secrets management (environment variables)

Observability Improvements

• OpenTelemetry tracing
• Distributed tracing across services
• Error tracking (Sentry)
• Log aggregation (DataDog/ELK)
• Custom dashboards (Grafana)

Development Commands

pnpm dev:backend      # Start backend (Docker + API)
pnpm dev:frontend     # Start frontend only
pnpm build            # Build all apps
pnpm typecheck        # Type check all packages
pnpm db:generate      # Generate Drizzle migrations
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Drizzle Studio
pnpm docker:up        # Start PostgreSQL + Redis
pnpm docker:down      # Stop containers

License

MIT