codflow

# CodFlow  **The open-source, COD-first e-commerce platform for Algeria — built agentic-ready.** [](https://t.me/codflow_dz) 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: <table> <tr> <td width="50%" valign="top"> ### 🚀 **I want to run CodFlow** See it in action and deploy your own store. **[→ See It in Action](#-see-it-in-action)** **[→ What works today](#-whats-included)** **[→ Quick setup guide](#-quick-setup)** **[→ Production deployment](./docs/DEPLOYMENT.md)** </td> <td width="50%" valign="top"> ### 💻 **I want to contribute** Build features or customize CodFlow. **[→ Contributing guide](./CONTRIBUTING.md)** **[→ Architecture overview](./docs/ARCHITECTURE.md)** **[→ AI agent instructions](./AGENTS.md)** </td> </tr> </table> --- ## 🎥 See It in Action Watch the step-by-step setup guide: [](https://youtu.be/rJPCGQnDZ18) **[▶️ Watch: CodFlow Setup & Deployment Guide](https://youtu.be/rJPCGQnDZ18)** --- ## 🎯 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.** | The Reality | Western/Local Platforms | CodFlow | | :--- | :--- | :--- | | **Transaction fees eat margins** | 2–5% per order + monthly SaaS fees | **$0 transaction fees** — pay only Cloudflare hosting ($0–$5/mo) | | **Your data locked in their system** | Can't export, can't migrate, vendor lock-in | **You own everything** — D1 database, R2 images, full control | | **Expensive hosting** | VPS servers, maintenance, scaling costs | **Serverless Cloudflare** — auto-scales, zero maintenance | | **4+ carrier portals** | Juggle Yalidine, ZR, NOEST, EcoTrack separately | **Unified carrier API** — one integration for all carriers | | **In-house drivers ignored** | No native driver dispatch or per-wilaya pay | **Built-in driver management** with compensation and cash settlement | | **Ads optimize for form fills, not deliveries** | Meta Pixel fires on checkout submit (30–50% refuse at door) | **Meta CAPI fires at actual delivery** — optimize ads for real buyers | **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](https://dzverify.com), off by default) - ✅ Optional Cloudflare Turnstile bot protection on the checkout form ([Turnstile](https://www.cloudflare.com/products/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`](./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](./.agents/skills/codflow-setup/SKILL.md). **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](./.agents/skills/codflow-update/SKILL.md), 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 ```bash 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. ```bash 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 ```bash # 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 ```bash 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: ```bash # 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](./cod-server/src/endpoints/images/README.md) 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`](./docs/DEPLOYMENT.md) for production deployment. --- ## 🚢 Production Deployment Deploy all three apps to Cloudflare Workers: ```bash # 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](./cod-server/src/endpoints/images/README.md) for API tokens, CORS policy, and custom domain configuration. **Full deployment guide:** [`docs/DEPLOYMENT.md`](./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`](./docs/ARCHITECTURE.md) --- ## 🧪 Testing ```bash # 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 | Document | Purpose | | :--- | :--- | | **[docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)** | Cloudflare production deployment | | **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** | System map and data flows | | **[docs/CONFIGURATION.md](./docs/CONFIGURATION.md)** | All environment variables and configs | | **[docs/KNOWN_LIMITATIONS.md](./docs/KNOWN_LIMITATIONS.md)** | Incomplete features and platform constraints | | **[docs/SHOPPING-CART.md](./docs/SHOPPING-CART.md)** | Shopping cart, checkout page, free-delivery threshold | | **[docs/LEGAL-PAGES.md](./docs/LEGAL-PAGES.md)** | Terms, Privacy, Refund and Shipping pages — pre-seeded, merchant-editable | | **[docs/WHATSAPP-OTP-VERIFICATION.md](./docs/WHATSAPP-OTP-VERIFICATION.md)** | WhatsApp OTP verification feature | | **[docs/TURNSTILE.md](./docs/TURNSTILE.md)** | Cloudflare Turnstile checkout bot protection | | **[docs/CHECKOUT-FORM.md](./docs/CHECKOUT-FORM.md)** | Merchant-configurable storefront order form and custom questions | | **[docs/EMAIL-SENDING.md](./docs/EMAIL-SENDING.md)** | Transactional email feature (Sendili) | | **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Development standards and PR workflow | | **[AGENTS.md](./AGENTS.md)** | Repository instructions for AI coding assistants | ### 🎬 Video Tutorial **[▶️ Watch: How to edit your CodFlow theme](https://youtu.be/zZGWdEeUXVo)** --- ## 🗺️ 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](https://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](https://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](./CONTRIBUTING.md)** for detailed guidelines. --- ## 📄 License **Apache License 2.0** — 100% free and open-source. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE) for details. --- ## 🔗 Resources - **Repository:** [github.com/bighadj22/codflow](https://github.com/bighadj22/codflow) - **Video Setup Guide:** [Watch on YouTube](https://youtu.be/rJPCGQnDZ18) - **Changelog:** [CHANGELOG.md](./CHANGELOG.md) - **Security Policy:** [SECURITY.md](./SECURITY.md) --- **Version:** v1.1.0 — Self-hostable on Cloudflare. Built with ❤️ for Algerian e-commerce.