# Wocart (bighadj22/Wocart)

> CodFlow is an open-source, Cash-on-Delivery (COD) e-commerce and delivery platform built specifically for Algeria, deployable on your own Cloudflare account with zero transaction fees.

- GitHub: https://github.com/bighadj22/Wocart
- GitHub.Locker page: https://github.locker/bighadj22/Wocart
- Stars: 423
- Language: TypeScript
- License: Apache-2.0
- Last push: 2026-11-16

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is this a single app or a full stack of separate services?**

It is a self-hosted stack of three apps — a storefront (cod-astro), a merchant dashboard (cod-client-astro), and a backend (cod-server) — all running on Cloudflare Workers with D1, R2, and KV.

**How do I get it running?**

Clone the repo, create Cloudflare D1/R2/KV resources with Wrangler, configure the root .env, run the database/admin setup step, then start the storefront, dashboard, and backend dev servers in separate terminals.

**Do I need anything before I start?**

You need Node.js 22.12+ with npm, the Wrangler CLI, and a free Cloudflare account; no VPS or external database is required.

**Any gotchas when running it locally or in production?**

The storefront and dashboard both default to port 4321, so one must run on a different port locally; in production, Cloudflare blocks Worker-to-Worker fetch between .workers.dev domains, so at least the backend needs a custom domain.

**Who owns the store data?**

CodFlow is fully self-hosted on your own Cloudflare account, so you own the D1 database and R2 images with no vendor lock-in or data export restrictions.

**Which Algerian delivery carriers does it support?**

It integrates 4 Algerian carriers plus EcoTrack, giving access to 80+ couriers through one unified API, with real-time HMAC-verified webhook tracking for Yalidine and ZR Express.

**What can an AI agent do through the MCP integration?**

CodFlow exposes 15 RBAC-gated MCP tool sets (orders, products, stock, landing pages, customers, drivers, etc.) secured via OAuth, letting assistants like Claude, Cursor, ChatGPT, or LibreChat manage the store directly.

**Why does it fire ad conversion events at delivery instead of checkout?**

Meta Pixel normally fires on checkout submission even though 30–50% of COD orders get refused at the door, so CodFlow can fire the server-side Conversions API event only at confirmed delivery to optimize ad spend for real buyers.

**How much does hosting actually cost?**

Because everything runs serverless on Cloudflare Workers, D1, R2, and KV, hosting typically costs $0–$5/month with zero per-transaction fees.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/bighadj22/Wocart/blob/main/README.md

<p align="center">
  <img src="imgs/wocart_readme_banner.webp" alt="Wocart — open-source cash-on-delivery commerce for Algeria" width="100%">
</p>

# Wocart

**The open-source, cash-on-delivery commerce platform for Algeria.**

Wocart was formerly called CodFlow. The repository, packages, environment
variables and live domains still carry the old name where renaming would
break existing stores.

[![Telegram](https://img.shields.io/badge/Telegram-Join%20our%20group-2AABEE?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/codflow_dz)
[![Facebook](https://img.shields.io/badge/Facebook-Follow%20us-1877F2?style=for-the-badge&logo=facebook&logoColor=white)](https://www.facebook.com/wocartdz/)
[![Instagram](https://img.shields.io/badge/Instagram-Follow%20us-E4405F?style=for-the-badge&logo=instagram&logoColor=white)](https://www.instagram.com/wocart_dz/)

Run a whole store on your own Cloudflare account: storefront, merchant
dashboard and API on Workers, D1, R2 and KV, with no transaction fees. Ship to
Algeria's carriers or your own drivers, and send Meta the orders that were
really delivered.

**Documentation: [docs.wocart.store](https://docs.wocart.store)**

> [!TIP]
> **Rather not set it up yourself?** [Wocart Cloud](https://cloud.wocart.store)
> deploys the same stores to your own Cloudflare account in a few clicks, with a
> visual editor for their themes.
>
> [![Wocart Cloud](https://img.shields.io/badge/Wocart%20Cloud-Deploy%20a%20store-6D28D9?style=for-the-badge&logo=cloudflare&logoColor=white)](https://cloud.wocart.store)

---

## What is in the box

**Storefront** (`cod-astro/theme-00`, built on the published
[`@wocart/storefront`](https://www.npmjs.com/package/@wocart/storefront) and
[`@wocart/theme`](https://www.npmjs.com/package/@wocart/theme) SDKs)

- One-page cash-on-delivery order form, home delivery or carrier stop desk,
  with live shipping prices
- Arabic (right-to-left), French and English
- Landing pages, collections, offers (gifts, free shipping, quantity pricing)
  and coupons
- An optional shopping cart, off by default
- Reviews from verified orders, with photos and a voice note
- Legal pages (terms, privacy, refunds, shipping), pre-written and editable
- Optional WhatsApp phone verification ([DZVerify](https://dzverify.com)) and
  Cloudflare Turnstile bot protection

**Merchant dashboard** (`cod-client-astro`)

- Orders as work queues, from confirmation to delivery and returns
- Products with variants, stock and low-stock alerts
- Customers, groups and tags; abandoned checkouts
- Team roles with fine-grained permissions, and API keys
- Apps: Meta, DZVerify, Turnstile, Sendili email, WhatsApp button, Telegram
  and Reviews

**Delivery**

- Four carrier platforms behind one contract: Yalidine (and Guepex),
  ZR Express, NOEST and the EcoTrack platform
- Your own drivers, with per-wilaya pay and cash settlement
- Signed webhooks from Yalidine and ZR Express; the others are synced every
  five minutes

**Growth and integration**

- Meta Pixel and Conversions API, with the conversion you choose: `Lead` or
  `Purchase` at order, at confirmation or at delivery
- Signed, retried webhooks for every order and delivery event
- A documented REST API (OpenAPI) and an MCP server for AI agents

## Get started

| I want to… | Read |
| :--- | :--- |
| Run it on my machine | [Local setup](https://docs.wocart.store/self-hosting/local) |
| Put it in production | [Deploy](https://docs.wocart.store/self-hosting/deploy) |
| Set every variable and binding | [Configuration](https://docs.wocart.store/self-hosting/configuration) |
| Choose where images are stored | [Media](https://docs.wocart.store/self-hosting/media) |
| Upgrade a running store | [Upgrading](https://docs.wocart.store/self-hosting/upgrading) |
| Know what is not done yet | [Limitations](https://docs.wocart.store/self-hosting/limitations) |
| Understand how it fits together | [Architecture](https://docs.wocart.store/architecture) |
| Build a theme | [Theme SDK](https://docs.wocart.store/sdk/theme) |
| Build a storefront | [Storefront SDK](https://docs.wocart.store/sdk/storefront) |
| Call the API | [API reference](https://docs.wocart.store/api) |

Features, one page each:
[shopping cart](https://docs.wocart.store/features/cart) ·
[order form](https://docs.wocart.store/features/order-form) ·
[phone verification](https://docs.wocart.store/features/phone-verification) ·
[bot protection](https://docs.wocart.store/features/bot-protection) ·
[Meta](https://docs.wocart.store/features/meta) ·
[legal pages](https://docs.wocart.store/features/legal-pages) ·
[email](https://docs.wocart.store/features/email)

## npm packages

Build your own storefront or theme on the same SDKs Theme-00 uses.

| Package | What it is |
| :--- | :--- |
| [![@wocart/storefront](https://img.shields.io/npm/v/@wocart/storefront?label=%40wocart%2Fstorefront&color=6D28D9)](https://www.npmjs.com/package/@wocart/storefront) | The storefront SDK: typed catalog reads, basket, checkout, phone verification and order tracking, with Astro adapters |
| [![@wocart/theme](https://img.shields.io/npm/v/@wocart/theme?label=%40wocart%2Ftheme&color=6D28D9)](https://www.npmjs.com/package/@wocart/theme) | The theme contract: component definitions, JSON page documents, and a reference Astro renderer |
| [![create-wocart-theme](https://img.shields.io/npm/v/create-wocart-theme?label=create-wocart-theme&color=6D28D9)](https://www.npmjs.com/package/create-wocart-theme) | Starts a new theme on both SDKs |

```sh
npm create wocart-theme@latest my-theme
```

## Repository

| Folder | What it is |
| :--- | :--- |
| `cod-server/` | The API: Hono on Cloudflare Workers, D1 through Drizzle |
| `cod-client-astro/` | The merchant dashboard (Astro) |
| `cod-shared/` | Schema, queries, permissions and error codes shared by both |
| `cod-astro/theme-00/` | The reference storefront theme |
| `cod-docs/` | The documentation site, in English, French and Arabic |

```sh
npm ci                      # every workspace, from the repo root
npm run typecheck && npm test   # cod-server, then the dashboard
(cd cod-astro/theme-00 && npm ci && npm test)   # the theme, on the npm SDKs
```

## Contributing

Contributions are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) first;
[AGENTS.md](./AGENTS.md) holds the repository's rules for coding agents. Keep
credentials out of commits, and every claim in this README true to the code.

Security issues: see [SECURITY.md](./SECURITY.md). Release notes:
[CHANGELOG.md](./CHANGELOG.md).

## License

[Apache License 2.0](./LICENSE). See also [NOTICE](./NOTICE).

Repository: [github.com/bighadj22/Wocart](https://github.com/bighadj22/Wocart)

