Codflow

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)

• ✅ Landing pages (/lp/[slug]) — one-product marketing pages: stacked image story + COD form, no nav chrome
• ✅ 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)
• ✅ Optional Cloudflare Turnstile bot protection on the checkout form (Turnstile, off by default)
• ✅ Legal pages (/pages/[slug]) — Terms, Privacy, Refund/Return, Shipping (pre-seeded, merchant-editable) and any custom page, with a checkout consent line linking to them
• ✅ Merchant-configurable order form — require or hide the address, notes and email, turn a delivery option off, and add up to 5 questions of your own (enforced server-side, not just hidden)

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)
• ✅ Landing page studio — two-sidebar builder (image stack + spacing), product-picker-first creation, publish flow, live link copy
• ✅ Landing page comparison — per-product A/B table (views, orders, CVR, revenue) to pick winning creatives
• ✅ 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
• ✅ Legal pages editor — TipTap rich-text, per-locale (store's own language first), one-click reset to the current CodFlow template, and the business-details form templates render from
• ✅ 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)
• ✅ Carrier delivery-zone name sync — dispatches carry the carrier's exact wilaya/commune spellings (Yalidine)
• ✅ Dispatch-time delivery-type switching (home ⇄ stop desk) with wilaya-scoped desk picking
• ✅ Webhook event log with per-event outcomes (applied / ignored / unmapped / error) per carrier
• ✅ 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 Pixel (browser) + Conversions API (server) dual setup with event deduplication
• ✅ Merchant-chosen conversion event: Lead at order placement or Purchase at confirmed delivery
• ✅ Test Mode toggle routes CAPI events to Meta's test stream (test_event_code)
• ✅ Graph API v26.0 with 7-day attribution window compliance
• ✅ PII hashed per Meta spec (phone, names, city, zip, country, external_id); IP, User-Agent, fbp, fbc sent unhashed as required
• ✅ fbp and fbc attribution preservation
• ✅ Durable retry with Cloudflare Workflows (network + Meta 5xx, exponential backoff)
• ✅ CAPI event audit log (capi_event_log) for every send attempt

AI & Agentic (MCP)

• ✅ RFC 9728 OAuth Protected Resource Discovery with dynamic client registration
• ✅ OAuth login relay from the dashboard (login-ticket bridge)
• ✅ 15 RBAC-gated tool sets (orders, products, stock, offers, landing pages, 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.

Already set up and want the latest version? Don't redo the setup. Tell your agent: "Update CodFlow" — it will follow the codflow-update runbook, which pulls the latest code from this repository's main branch, applies new database migrations, keeps your resources, secrets, and store data intact, rebuilds and redeploys your workers, and reports each step in plain language.

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

Names are yours to choose — scripts read them from the root .env (see step 3), so nothing is hardcoded.

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

3. Configure Environment

# Repo root — resource names for the seeders, the D1 wrapper, the R2 CORS
# setup and the storefront deploy helper. Precedence: process.env > .env > default.
cp .env.example .env
# Set COD_ACCOUNT_ID, COD_DB_NAME, COD_R2_BUCKET_NAME, COD_SERVER_URL, COD_MEDIA_DOMAIN

# 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
[email protected] 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
# Production PUBLIC_API_URL comes from wrangler.toml [vars]; deploy builds with it
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
# COD_SERVER_URL comes from the repo-root .env — deploy injects it, never wrangler.jsonc
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)      │
       └───────┬───────┘         └───┬─────┬───────┘        └─────────────────┘
               │                     │     │
               │               /webhooks   │ CodCapiWorkflow
               │              carrier calls│
               │                     │     └─────────▶ Meta Conversions API
               │                     │                 (Purchase @ delivered)
               │                     │
               │              ┌──────▼─────┐
               │              │ Carriers    │   Yalidine • ZR Express  (webhooks)
               │              │  APIs       │   NOEST • EcoTrack       (tracking pull)
               │              └─────────────┘
               │
               │        /images (R2)      /mcp (AI agents, OAuth-scoped)
               └──────────────────────────────────────────────────────▶

Tech Stack:

• Storefront: Astro 7, Tailwind CSS v4 → Cloudflare Workers + Static Assets
• Backend: Hono 4, Drizzle ORM, Better Auth, Workflows → Cloudflare Workers + D1 + R2 + KV
• Dashboard: Astro 7 (prerendered static + auth worker) → Cloudflare Workers + D1 + KV
• Shared: Drizzle schema, RBAC scopes, error codes

More detail: docs/ARCHITECTURE.md

🧪 Testing

# Backend tests (handlers, workflows, OpenAPI, MCP)
cd cod-server && npm test

# Dashboard tests (feature models, i18n guards, API seam)
cd cod-client-astro && npm test

# Storefront tests (property-based, cart calculations)
cd cod-astro/theme01 && npm test

# TypeScript verification
cd cod-server && npm run typecheck
cd cod-client-astro && npm run typecheck

CI runs typecheck + tests for cod-server and cod-client-astro, plus astro check + tests for theme01.

📚 Documentation

🎬 Video Tutorial

▶️ Watch: How to edit your CodFlow theme

🗺️ Roadmap

Planned

• 📈 Deeper dashboard analytics — revenue, delivery-rate, and return-rate trends
• 📦 More Themes — Additional storefront themes beyond theme01
• 📘 Theme Editing Guides — Comprehensive guides for customizing and creating themes
• ☁️ CodFlow Cloud — One-click deployment from dashboard for agencies to resell CodFlow
• 📧 Email order notifications & admin alerts — extend the Sendili integration beyond transactional mail

Recently Shipped

• ✅ Legal Pages — Terms, Privacy, Refund/Return, Shipping pre-seeded per store from Algeria-COD-grounded templates, merchant-editable with the dashboard's TipTap editor, and any custom page on the same rails
• ✅ Yalidine Hardening — full 36-status webhook mapping (live-verified return flows), HMAC-SHA256 signature verification, per-carrier delivery-zone name sync, dispatch-time delivery-type switching, and a webhook events log for every webhook-capable carrier
• ✅ Landing Pages — one-product marketing pages (image stack + COD order form) with the Studio builder, per-link stats, A/B comparison, order attribution, and 7 MCP tools
• ✅ Astro Dashboard — the merchant dashboard now runs on Astro (was Next.js)
• ✅ WhatsApp OTP Verification — DZVerify.com phone verification at checkout
• ✅ Cloudflare Turnstile — optional per-store bot protection on the checkout form (off by default)
• ✅ EcoTrack Integration — 80+ Algerian couriers behind one API
• ✅ Transactional Email (Sendili) — Sendili.com powers team-invite emails and password-reset emails; merchants configure their API key and verified sending domain in Settings → Email Sending

🤝 Contributing

We welcome contributions from developers across Algeria and the global open-source community.

1. Fork the repo and create a feature branch (feat/amazing-feature)
2. Maintain code-verified claims and test coverage
3. Keep credentials and live API keys out of commits
4. Submit a PR referencing the related issue

See CONTRIBUTING.md for detailed guidelines.

📄 License

Apache License 2.0 — 100% free and open-source.
See LICENSE and NOTICE for details.

🔗 Resources

• Repository: github.com/bighadj22/codflow
• Video Setup Guide: Watch on YouTube
• Changelog: CHANGELOG.md
• Security Policy: SECURITY.md

Version: v1.1.0 — Self-hostable on Cloudflare.
Built with ❤️ for Algerian e-commerce.