CodFlow

The open-source, COD-first e-commerce platform for Algeria — built agentic-ready.

Cash on Delivery meets serverless infrastructure. Self-host your entire commerce stack on Cloudflare with zero transaction fees, connect to Algeria's delivery carriers, and optimize Meta ads for real deliveries instead of door refusals.

Get Started

Choose your path:

🚀 I want to run CodFlow

See it in action and deploy your own store.

→ See It in Action
→ What works today
→ Quick setup guide
→ Production deployment

💻 I want to contribute

Build features or customize CodFlow.

→ Contributing guide
→ Architecture overview
→ AI agent instructions

🎥 See It in Action

Watch the step-by-step setup guide:

▶️ Watch: CodFlow Setup & Deployment Guide

🎯 The Problem CodFlow Solves

E-commerce in Algeria is 95%+ Cash on Delivery (الدفع عند الاستلام). Western platforms like Shopify and local tools charge per-transaction fees, require expensive VPS hosting, and lock your data in their databases.

CodFlow is the first and only open-source COD e-commerce platform built for Algeria.

Deploy CodFlow to your own Cloudflare account in minutes. No monthly fees. No transaction cuts. 100% open-source (Apache 2.0).

✅ What's Included

CodFlow v1.1.0 — here's what works today:

Storefront (cod-astro/theme01)

• ✅ Single-page COD checkout with live shipping calculation
• ✅ Home delivery or carrier stop-desk pickup selection
• ✅ Quantity-tier offers ("Buy 2 get 10% off", "Buy 3 free shipping")
• ✅ Order-verified product reviews (star ratings + Arabic/French text)
• ✅ Trilingual: Arabic (RTL), French, English
• ✅ Abandoned cart telemetry for recovery campaigns
• ✅ Optional WhatsApp phone verification at checkout (DZVerify, off by default)

Merchant Dashboard (cod-client-astro)

• ✅ Order management with full COD lifecycle tracking
• ✅ Product catalog with multi-attribute variants (size, color, SKU) and image uploads
• ✅ Inventory tracking with low-stock alerts and adjustment history
• ✅ Promotion engine (Buy X Get Y, free shipping rules)
• ✅ Review moderation (approve, reject, delete)
• ✅ Customer CRM with profiles, order history, groups, and tags
• ✅ Delivery: in-house drivers, per-wilaya compensation, cash settlement
• ✅ Carrier company management (credentials, stop-desk sync, reconciliation)
• ✅ Team RBAC with granular permission scopes and API keys
• ✅ Meta Pixel & CAPI configuration UI
• ✅ Abandoned order recovery
• ✅ MCP agent connection management
• ✅ Trilingual: Arabic (RTL), French, English

Delivery Engine

• ✅ 4 Algerian carriers + EcoTrack (80+ couriers behind one API)
• ✅ One-click shipment creation with printable labels
• ✅ Real-time webhook tracking (Yalidine, ZR Express with HMAC verification)
• ✅ Stop-desk catalog syncing across 58 wilayas
• ✅ In-house driver fleet management
• ✅ Per-wilaya driver compensation with cash settlement
• ✅ Partial returns with automatic inventory restock

Growth Engine

• ✅ Meta Conversions API (CAPI) fires Purchase only at confirmed delivery
• ✅ 7-day attribution window compliance
• ✅ Advanced data hashing (phone, city, IP, User-Agent)
• ✅ fbp and fbc attribution preservation
• ✅ Durable retry with Cloudflare Workflows

AI & Agentic (MCP)

• ✅ RFC 9728 OAuth Protected Resource Discovery with dynamic client registration
• ✅ OAuth login relay from the dashboard (login-ticket bridge)
• ✅ 14 RBAC-gated tool sets (orders, products, stock, offers, reviews, customers, drivers, etc.)
• ✅ Stateless elicitation with HMAC-sealed confirmation state
• ✅ Compatible with Claude, Cursor, ChatGPT, LibreChat

Backend (cod-server)

• ✅ Hono 4 on Cloudflare Workers (sub-5ms cold starts)
• ✅ Drizzle ORM + D1 (SQLite)
• ✅ D1 scale layer: indexed hot paths, atomic batched order writes, keyset pagination
• ✅ Auto-generated OpenAPI 3.1 spec at /api/docs
• ✅ Standardized error envelopes with semantic codes
• ✅ R2 image storage with edge caching
• ✅ KV-backed rate limiting

Known Limitations:
See docs/KNOWN_LIMITATIONS.md for honest coverage of incomplete features and platform constraints.

⚡ Quick Setup

Run CodFlow locally in 5 steps:

🤖 Using an AI Coding Assistant? CodFlow includes an autonomous setup skill. Tell your agent: "Set up CodFlow" and it will follow the codflow-setup runbook.

Prerequisites

• Node.js 22.12+ and npm
• Wrangler CLI: npm install -g wrangler
• Free Cloudflare account

1. Clone & Install

git clone https://github.com/bighadj22/codflow.git
cd codflow
npm ci

2. Create Cloudflare Resources

wrangler login
wrangler d1 create codflow-os-db
wrangler r2 bucket create codflow-images
wrangler kv namespace create RATE_LIMIT
wrangler kv namespace create OAUTH_KV

3. Configure Environment

# Backend
cd cod-server
cp .dev.vars.example .dev.vars
cp wrangler.toml.example wrangler.toml
# Update wrangler.toml with your D1 database_id, R2 bucket_name, KV ids

# Dashboard
cd ../cod-client-astro
cp wrangler.toml.example wrangler.toml   # same D1 database_id as cod-server + your KV id
cp .env.example .env
cp .dev.vars.example .dev.vars
# Set BETTER_AUTH_SECRET (same value as cod-server's, e.g. openssl rand -hex 32)

# Storefront
cd ../cod-astro/theme01
cp .dev.vars.example .dev.vars

4. Setup Database & Admin

cd cod-server
npm run db:setup:local

cd ../cod-client-astro
ADMIN_EMAIL=admin@example.com ADMIN_NAME=Admin npm run seed:admin
# ⚠️ Save the generated password and API key

5. Start Dev Servers

Open three terminals:

# Terminal 1: Backend (http://localhost:8787)
cd cod-server && npm run dev

# Terminal 2: Dashboard (http://localhost:4321)
cd cod-client-astro && npm run dev

# Terminal 3: Storefront (http://localhost:4321 → use a different port, see theme README)
cd cod-astro/theme01 && npm run dev

⚠️ The dashboard and storefront both default to port 4321 — run them on different ports (astro dev --port 4322 for one of them) or run only one at a time.

6. Enable Image Uploads

Product image uploads require R2 API tokens and CORS configuration. See the R2 setup guide for:

• Creating R2 API tokens
• Setting CORS policy on the bucket
• Adding a custom domain for serving images

Need more detail? See docs/DEPLOYMENT.md for production deployment.

🚢 Production Deployment

Deploy all three apps to Cloudflare Workers:

# 1. Backend
cd cod-server
npm run deploy -- --env production
wrangler secret put BETTER_AUTH_SECRET
wrangler secret put STORE_API_KEY

# 2. Dashboard
cd ../cod-client-astro
npm run build && npm run deploy
wrangler secret put BETTER_AUTH_SECRET         # same value as cod-server's
wrangler secret put MCP_LOGIN_TICKET_SECRET    # same value as cod-server's

# 3. Storefront
cd ../cod-astro/theme01
# Set COD_SERVER_URL in wrangler.jsonc to your deployed backend URL
npm run build && npm run deploy
wrangler secret put STORE_API_KEY

Important: Cloudflare blocks Worker-to-Worker fetch between *.workers.dev hosts. For production, put at least cod-server on a custom domain and point COD_SERVER_URL at it.

R2 Image Uploads: For production image uploads, see R2 setup guide for API tokens, CORS policy, and custom domain configuration.

Full deployment guide: docs/DEPLOYMENT.md

🏗️ Architecture

                          ┌──────────────────────────────────────────┐
                          │              cod-shared                  │
                          │   D1 schema • RBAC scopes • queries      │
                          └───────────────┬──────────────────────────┘
                                          │ relative imports
               ┌──────────────────────────┼──────────────────────────┐
               │                          │                          │
       ┌───────▼───────┐         ┌────────▼────────┐        ┌────────▼────────┐
       │  Storefront   │         │     Backend     │        │   Dashboard     │
       │  cod-astro    │──/store─▶  cod-server     │◀──/api─│ cod-client-astro│
       │  (Astro 7)    │  API    │ (Hono + Workflows) API   │  (Astro 7)      │
       └───────┬───────┘         └───┬─────┬───────┘        └─────────────────