Board Report · Architecture Plan

DUKA Software Architecture: Instagram Order to Delivered Product

DUKA should be built as a parallel event-driven operations app that tracks every state from customer DM to successful delivery.

Instagram DM→AI Order Capture→M-Pesa Payment→Rider Dispatch→Delivery + Reporting
Architecture Thesis

Build a Parallel Operations App

  • Instagram/WhatsApp stay as acquisition and conversation channels.
  • DUKA becomes the source of truth for orders, payments, dispatch, and delivery.
  • This enables reliable reconciliation, analytics, and automation.
Feasibility Verdict

Implementable in Stages

  • Required rails exist today: Meta APIs, Daraja, and rider ecosystems.
  • Main challenge is robust edge-case handling and reliability engineering.
  • Phased rollout is the safest route.
Operating Principle

Human-Assisted First, Full Automation Later

  • Launch with fallback controls and operator takeover.
  • Automate stable workflows first, then expand.
  • Use real pilot data to tune AI and dispatch rules.

Reference Workflow (Instagram DM to Product Delivery)

  1. Customer sends DM; Channel Gateway receives webhook.
  2. Conversation Service extracts intent, items, address, and contact.
  3. Order Service creates order as PENDING_PAYMENT and reserves inventory.
  4. Payment Service initiates M-Pesa STK push.
  5. M-Pesa callback is reconciled; order marked PAID.
  6. Dispatch Service assigns rider and sends pickup/dropoff details.
  7. Rider updates status (PICKED_UP, IN_TRANSIT, DELIVERED).
  8. Dashboard, alerts, and end-of-day reports update automatically.

End-to-End Journey Diagram

Customer Journey and System Flow
External Actors DUKA Core Platform Outputs Customer (Instagram DM) M-Pesa (STK + Callback) Rider / Logistics Partner 1) Channel Gateway (Webhook Intake) 2) Conversation + AI Parsing 3) Order Service (PENDING_PAYMENT) 4) Payment + Reconciliation 5) Dispatch Service (Assign Rider) 6) Event Log + Analytics + Alerts Merchant Dashboard (Order/Payment/Delivery) Customer Notifications (Paid, Dispatched, Delivered) End-of-Day Reports (Revenue, SLA, Exceptions)
Presentation note: DUKA runs as the system-of-record parallel app while Instagram and M-Pesa act as external channels/rails.

Implementation Option A - Fastest to Market (Recommended)

What to Build First
  • WhatsApp/Instagram intake + structured order extraction.
  • M-Pesa STK push + callback confirmation pipeline.
  • Operations dashboard for paid/unpaid and delivery status.
  • Manual-assisted rider assignment.
Why This Works
  • Lowest integration friction while proving willingness to pay.
  • Reduces engineering risk from day one.
  • Creates real transaction data for future automation.

Implementation Option B - Full Automation from Day One

Approach
  • Omnichannel orchestration immediately.
  • Automated rider allocation and ETA logic.
  • Real-time inventory, reconciliation, and analytics stack.
Trade-Off
  • High upfront complexity and slower time-to-revenue.
  • Harder debugging due to tightly coupled failures.
  • Best only with larger team and funding runway.

Build Decision: Parallel App vs Channel-Only

Recommended

Parallel DUKA App

  • Single source of truth across channels and providers.
  • Supports reconciliation, exception queues, and SLA control.
  • Scales into analytics and automation cleanly.
Not Recommended

Channel-Only Operations

  • No durable state history and weak operational visibility.
  • Manual reconciliation burden remains high.
  • Poor scalability and difficult debugging.

Phased Rollout Plan

  • Phase 1 (Weeks 1-8): intake + payment + dashboard + manual-assisted dispatch for pilot merchants.
  • Phase 2 (Weeks 9-16): auto reconciliation, inventory automation, dispatch rules, exception queue.
  • Phase 3 (Weeks 17-28): AI tuning, SLA alerts, multi-merchant hardening, advanced reporting.
30 min

Target merchant onboarding time.

<2%

Target payment-order mismatch after tuning.

95%+

Target order acknowledgement within 1 minute.

Execution Risks and Mitigation

Key Risks
  • API policy/rate limit changes.
  • AI errors in multilingual conversations.
  • Payment edge cases and delayed callbacks.
  • Rider quality inconsistency.
Mitigation Plan
  • Channel abstraction + fallback paths.
  • Confidence thresholds + human takeover.
  • Idempotent webhooks + exception queue.
  • SLA timers, proof-of-delivery, rider scorecards.
Final recommendation: build DUKA as a parallel event-driven operations app, start with Option A, and expand toward full automation after reliability and retention targets are met.