# Dukene: The Definitive Platform Reference (LLM Optimized)

> **Version: 2.5.0**  
> **Last Updated: February 25, 2026**  
> **Region: Kenya / East Africa**

---

## 1. Executive Summary
Dukene is a vertical Micro-SaaS platform providing e-commerce infrastructure for the "Social Commerce" era in Kenya. Its goal is to automate the manual processes of selling via WhatsApp by providing integrated payments (M-Pesa), logistics (Kenyan town/market hierarchy), and marketing (Verified Affiliate Network).

---

## 2. Technical Architecture & Infrastructure

### 2.1 Core Stack
- **Frontend**: React 18 (TypeScript), Vite, Tailwind CSS (Styling), GSAP (Animations).
- **Backend**: NestJS, Node.js.
- **ORM**: Prisma (PostgreSQL).
- **Event Mesh**: **Redpanda** (Kafka-compatible messaging for asynchronous processing).
- **Edge Routing**: **Cloudflare Workers** (Wildcard subdomains: `*.dukene.com`).
- **Storage**: Azure Blob Storage / AWS S3 (Images & Assets).

### 2.2 Subdomain Logic & Multitenancy
Every merchant is assigned a unique `subdomain`.
- **Worker Level**: Cloudflare Worker extracts the subdomain from the `Host` header and injects `X-Store-Subdomain`.
- **Backend Level**: A global middleware extracts `X-Store-Subdomain` and scopes all PostgreSQL queries (e.g., `where: { store: { subdomain: ... } }`).
- **Caching**: Redis caches store-specific settings and product lists with a 5-minute TTL, invalidated on update.

### 2.3 Advanced Cache Patterns
1. **Sliding Window Rate Limiter**: 
   - `AUTH`: 5 attempts/15 mins.
   - `API`: 100 reqs/min per token.
   - `STK_PUSH`: 3 attempts/hour per phone number.
2. **Distributed Locking**: Using Redis `setNX` to prevent "Cache Stampedes" on high-traffic storefronts.
3. **Write-Behind Logic**: Inventory levels are decremented in Redis immediately on order creation and synced to PostgreSQL via a background worker every 10 seconds.

---

## 3. Database Schema Reference (Prisma Models)

### 3.1 Core Merchant Entities
- `Store`: The central tenant. Maps to `ownerId` (User). Stores Meta credentials and Google Merchant IDs.
- `User`: Handles authentication, 2FA status, and role-based access (Owner, Staff).
- `Product`: Main catalog item. Supports SEO tags, vendor info, and weight (for logistics).
- `ProductVariant`: SKU level. Handles size, color, and price overrides.
- `InventoryItem`: Tracks SKU across `InventoryLocation` objects.

### 3.2 Transaction & Financial Entities
- `Order`: High-level record. Captures `affiliateCode` and `paymentExpiresAt` (12-hour TTL).
- `OrderItem`: Snapshot of price/product at time of sale.
- `Payment`: Financial record. Links to `MpesaTransaction`.
- `MpesaTransaction`: Stores `CheckoutRequestID`, `ResultCode`, and `MpesaReceiptNumber`.
- `AffiliateCommission`: Tracks `Hold-and-Release` status (`PENDING`, `APPROVED`, `PAID`).

### 3.3 Logistics & Rewards Entities
- `County` / `Town` / `Market`: Platform-wide geographic hierarchy for Kenya.
- `PickupDropoffLocation`: Physical stations for order collection.
- `Milestone`: Definition of merchant rewards (e.g., "First 10 Sales").
- `StoreMilestone`: Tracking per-store progress with DB-level unique constraints.

---

## 4. Payment System & M-Pesa Logic

### 4.1 Payment Initiation Flow
1. **Frontend**: Calls `POST /api/v1/payments/initiate`.
2. **Validation**: Server checks order ownership and amount integrity.
3. **Identifier**: Generates `STORE_ORD_ID` (e.g., `DUKENE_ORD_7721`).
4. **Provider**: Backend calls Safaricom Daraja API for STK Push.
5. **Customer**: Enters PIN on mobile device.

### 4.2 Callback & Fulfillment
- **Webhook**: M-Pesa sends callback to `/api/v1/payments/callback`.
- **Logic**: 
  - If `ResultCode: 0`: Move Order to `PROCESSING`, decrement inventory, notify Merchant via WhatsApp + Email.
  - If `ResultCode: 1032`: Mark as `CANCELLED_BY_USER`.
- **Safety**: 12-hour timeout. If no success callback is received, the system automatically cancels the order to free up inventory.

---

## 5. Shipping & Geographic Engine

### 5.1 Geographic Hierarchy
- **Level 1 (County)**: 47 Counties of Kenya.
- **Level 2 (Town)**: Major urban hubs (e.g., Nakuru, Eldoret).
- **Level 3 (Market)**: Specific trade centers (e.g., Gikomba, Maasai Market).
- **Level 4 (Pickup Point)**: Partner shops/lockers for collection.

### 5.2 Shipping Rate Logic
Calculated at the `ShippingZone` level:
- **Flat Rate**: Fixed cost for a specific region.
- **Weight Based**: `[Base Price] + ([Weight in KG] * [Per KG Rate])`.
- **Price Based**: "Free Shipping above KES 3000".
- **Rule Engine**: The storefront evaluates all active rates in the matching zone and applies the one that results in the lowest cost for the user.

---

## 6. Affiliate Marketing Network

### 6.1 The "Social Engine"
- **Commission Control**: Commission rates are **determined solely by the sellers** for each individual product they add. Merchants have the flexibility to offer different rates for different items based on their business model and profit margins.
- **Standard Tiers (Recommended)**: 
  - Standard (Electronics/Fashion): 6-15%
  - Premium (Luxury/Services): 15-25%
  - Digital (Software/Education): 25-40%
- **Tracking**: Affiliates get a unique URL: `merchant.dukene.com/p/product-slug?ref=AFFILIATE_CODE`. Real-time tracking of clicks and conversions is provided.
- **Marketing templates provided for social media.**

### 6.2 Commission Lifecycle
- **PENDING**: Payment confirmed. Affiliate sees potential earnings.
- **APPROVED**: Merchant marks order as `DELIVERED`. Risk of return has passed.
- **REJECTED**: Order returned, fraudulent, or cancelled.
- **PAID**: Monthly or Weekly payout batch processed by Superadmin to M-Pesa.

---

## 7. Developer API Reference (Full List)

### 7.1 Authentication
**Base URL**: `https://api.dukene.com/api/v1`
**Header**: `Authorization: Bearer <token>`
**Header**: `X-Supplier-ID: <uuid>`

### 7.2 Catalog & Product Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/supplier-api/stores/:storeId/products` | Query products for a specific merchant. |
| `POST` | `/supplier-api/stores/:storeId/products` | Push new items to a merchant store. |
| `PUT` | `/supplier-api/stores/:storeId/products/:productId` | Batch update inventory or price. |
| `DELETE` | `/supplier-api/stores/:storeId/products/:productId` | Archiving products. |

### 7.3 Order & Fulfillment Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/supplier-api/stores/:storeId/orders` | List orders containing supplier products. |
| `PATCH` | `/supplier-api/orders/:orderId/fulfillment` | Update tracking numbers and status. |

### 7.4 Webhook Logic
**Events**: `ORDER_CREATED`, `ORDER_PAID`, `ORDER_CANCELLED`, `PRODUCT_UPDATED`.
**Verification**: `X-Dukene-Signature` (HMAC-SHA256 of request body).

---

## 8. Integrated Marketing Tools

### 8.1 Meta Commerce Sync
- **Mechanism**: Real-time sync to Facebook and Instagram Shop catalogs.
- **WhatsApp**: Direct product catalog rendering within the WhatsApp Business app.

### 8.2 Abandoned Cart Recovery
- **Automation**: Sequences triggered by the `CheckoutSession` model.
- **Schedule**: 1 hour (Reminder), 24 hours (Discount Incentive), 72 hours (Final Urgency).

---

## 9. Full Page Index

### Main Pages
- [Home](https://dukene.co.ke/) - Landing page with hero 3D visuals and value proposition.
- [About](https://dukene.co.ke/about) - Mission, vision, and core team information.
- [Features](https://dukene.co.ke/features) - Detailed breakdown of platform capabilities.
- [How It Works](https://dukene.co.ke/how-it-works) - Step-by-step guide for merchants and customers.
- [Payment Solutions](https://dukene.co.ke/payments) - M-Pesa integration and payout details.
- [Merchant Journey](https://dukene.co.ke/roadmap) - Visual roadmap of the onboarding and growth process.
- [Getting Started](https://dukene.co.ke/getting-started) - Quick start guide for new store owners.

### Resources & Support
- [Help Center](https://dukene.co.ke/help) - Comprehensive FAQ and knowledge base.
- [Contact Support](https://dukene.co.ke/contact) - Direct lines for email, WhatsApp, and phone support.
- [Video Tutorials](https://dukene.co.ke/tutorials) - Visual guides for setting up and scaling stores.
- [Community Forum](https://dukene.co.ke/community) - Discord, WhatsApp, and Facebook groups for merchants.
- [Developer Docs](https://dukene.co.ke/docs) - Full API documentation for suppliers.

### Partners & Programs
- [Affiliate Program](https://dukene.co.ke/affiliate) - Information for potential marketing partners.
- [Commission Structure](https://dukene.co.ke/commissions) - Earning tiers and payout policies.
- **Join**: `https://affiliate.dukene.com/apply` (External portal).

---

## 10. Implementation FAQ (Knowledge Base)

### 10.1 Technical & Setup
- **Q: How long does a store take to deploy?**
  - A: Less than 60 seconds. Routing is instantaneous via wildcard DNS.
- **Q: What cloud infrastructure is used?**
  - A: Vercel for the frontend, Azure for the API and Redpanda, Cloudflare for DNS/WAF.
- **Q: How is security handled?**
  - A: OAuth 2.0, HTTPS at all layers, sensitive data encryption (Prisma Middleware), and HMAC for webhooks.

### 10.2 Payments & Pricing
- **Q: Are there monthly fees?**
  - A: No. Dukene is free to start. We charge a 1-5% transaction fee on successful sales.
- **Q: Can I use my own Till Number?**
  - A: Yes. Merchants can link their Lipa Na M-Pesa credentials via the settings dashboard.
- **Q: Can I set different commissions?**
  - A: Yes. **Commission rates are determined entirely by the seller.** You set the specific commission for each product individually based on your margins.
- **Q: When are affiliate payouts?**
  - A: Every Friday for all "Approved" commissions above KES 1,000.

### Legal
- [Terms of Service](https://dukene.co.ke/terms)
- [Privacy Policy](https://dukene.co.ke/privacy)
- [Cookie Policy](https://dukene.co.ke/cookies)
- [Acceptable Use](https://dukene.co.ke/acceptable-use)
- [Merchant Agreement](https://dukene.co.ke/merchant-agreement)

---

## 11. Support & Contact

- **Email**: `support@dukene.co.ke`
- **For Developers**: `developers@dukene.co.ke`
- **WhatsApp (Merchant Support)**: `+254 700 000 000`
- **Office**: `Nairobi, Kenya`

---
*Document Integrity verified: February 2026*
*Platform Status: Stable / Production*