<div align="center"> <h1>🛍️ Fufuni</h1> <p><strong>The 100% free-tier, AI-native e-commerce framework.</strong><br/> Built on Cloudflare Workers · Auth0 · Stripe · Mailgun · GitHub Pages</p> <a href="https://sctg-development.github.io/fufuni/"> <img src="https://img.shields.io/badge/LIVE%20DEMO-brightgreen?style=for-the-badge&logo=cloudflare" alt="Live Demo" /> </a> <a href="https://github.com/sctg-development/fufuni/stargazers"> <img src="https://img.shields.io/github/stars/sctg-development/fufuni?style=for-the-badge" alt="Stars" /> </a> <a href="https://github.com/sctg-development/fufuni/blob/main/LICENSE"> <img src="https://img.shields.io/badge/License-AGPL%203.0-blue?style=for-the-badge" alt="License" /> </a> <a href="https://github.com/sctg-development/fufuni/actions/workflows/pages.yaml"> <img src="https://img.shields.io/github/actions/workflow/status/sctg-development/fufuni/pages.yaml?style=for-the-badge&label=DEPLOY" alt="Deploy" /> </a> <br/> <img src="https://tokeisrv.sctg.eu.org/b1/github.com/sctg-development/fufuni?type=TypeScript,TSX,html&category=code" alt="Code lines" /> <img src="https://tokeisrv.sctg.eu.org/b1/github.com/sctg-development/fufuni?type=TypeScript,TSX,html&category=comments" alt="Comment lines" /> <br/> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript" alt="TypeScript" /></a> <a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19-61DAFB?logo=react" alt="React" /></a> <a href="https://www.heroui.com/"><img src="https://img.shields.io/badge/HeroUI-v3-yellow" alt="HeroUI" /></a> <a href="https://auth0.com/"><img src="https://img.shields.io/badge/Auth0-Secured-EB5424?logo=auth0" alt="Auth0" /></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Available-6B46C1?logo=anthropic" alt="MCP Server" /></a> </div>

🚀 Deploy in 10 minutes, $0/month forever

| Service | Free Tier | Usage in Fufuni | |---|---|---| | Cloudflare Workers | 100k req/day | Backend API + Durable Objects SQLite | | Cloudflare R2 | 10 GB storage | Product images & assets | | Auth0 | 7,500 active users | Auth passwordless + social | | Mailgun | 1,000 emails/month | Order notifications | | Stripe | Pay-as-you-go | Payments (no monthly fee) | | GitHub Pages | Unlimited | SPA frontend hosting |

The entire stack can be self-hosted for €0 / month within these generous free tiers. GitHub Actions automates deployment — push to main and everything deploys automatically.

Star the project

If you appreciate my work, please consider giving it a star! 🤩

Live Demo

Click the screenshot below to try the public deployment. You can checkout with any Stripe test card for example 4242 4242 4242 4242 (any future expiry, CVC, and ZIP) — no real charges will be made.

Theme switcher in the top-right corner lets you toggle between classic and luxury themes, showcasing the dynamic theming capabilities of the platform.

Base Layout

Luxury Layout

Visitors see an attractive landing page with a Log in button and direct links to a sample API and autogenerated OpenAPI/Swagger docs — no auth required to view the interface.

Features
Architecture
KV Cache & CDN
Quick Start
Configuration Reference
- wrangler.jsonc — Variables
- Frontend .env
API Reference
Database Schema
- Migrations
Shipping System
Multi-Region & Multi-Currency
Authentication & Security
AI Features
Internationalisation
Admin Panel
Deployment
GitHub Actions Workflows
Contributing
License

Features

🤖 AI-Native: Universal Commerce Protocol (UCP)

Fufuni is one of the first open-source frameworks to implement UCP, allowing AI shopping agents (Claude, Gemini, ChatGPT) to interact with your store natively.

# Discover capabilities
curl https://your-worker.workers.dev/.well-known/ucp

# Browse catalog as an AI agent
curl "https://your-worker.workers.dev/ucp/v1/products?limit=5&q=golf"

# Create a checkout session (no UI needed)
curl -X POST https://your-worker.workers.dev/ucp/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -d '{"currency":"EUR","line_items":[{"item":{"id":"SKU-001"},"quantity":1}]}'

🛍 Products & Catalog

Product catalogue with variants, SKUs and per-variant multi-currency pricing
Multilingual product titles — plain text or JSON per locale, with AI translation
Multilingual product descriptions — rich HTML (Tiptap editor) or JSON per locale, with AI translation
RTL language support (Arabic, Hebrew)
Product image management via Cloudflare R2
Inventory management across multiple warehouses
Product shipping class assignment (per product or per variant override)
Per-variant weight (weightg) used for automatic cart weight calculation

📂 Categories

Hierarchical product categories with optional parent-child relationships
Multilingual category names — JSON per locale with fallback resolution
Multilingual descriptions — rich HTML or JSON per locale
One-click AI translation for names and descriptions across all locales
Category image URLs for storefront display
Position-based sorting for custom category ordering
Public read-only catalog endpoints, admin CRUD operations
Real-time permission checking for AI translation features

💳 Payments & Orders

Stripe Checkout integration with full webhook reconciliation
Multi-currency, multi-region pricing — explicit per-variant prices in variantprices
Dynamic shipping options in Stripe — rates come from your DB, not hardcoded values
Order lifecycle: pending → paid → processing → shipped → delivered → refunded → canceled
Tracking number and URL per order
Discount codes — fixed amount or percentage, with Stripe coupon sync
Order confirmation emails via Mailgun with signed 30-day view-token links
Secure order status page accessible via JWT token (no login required)
Public order lookup by Stripe session ID

🚚 Shipping

Shipping rates with weight limits and delivery day estimates
Shipping classes for product-specific transport constraints (exclusive or additive)
Cart weight calculation from variant weights — automatic, computed server-side
Multi-class cart filtering — exclusive classes hide incompatible rates; additive classes add theirs
Region-bound rates — rates are linked to regions, not shown globally
Address collection before checkout with automatic revalidation of the selected rate
Per-rate multi-currency pricing via shippingrateprices

👤 Customers & Auth

Auth0-based authentication for admin (JWT, RBAC, configurable permissions)
Customer accounts with address book
OAuth 2.0 / UCP (Universal Commerce Protocol) for customer-facing flows
Wishlist (favorites) — products stored in Auth0 user_metadata
Saved carts — full cart snapshots stored in Auth0 user_metadata for quick retrieval
Magic-link checkout

� Store Themes

Multi-theme architecture — built-in classic (light/dark) and luxury themes
Themes stored in store_themes table and served via GET /v1/theme/active
StoreThemeProvider applies data-theme on <html> at boot, preventing FOUC
Persistent user preference via localStorage (ui-theme key)
Floating ThemeSwitcher dropdown for instant preview/switch
Theme config overrides CSS variables (--accent, --radius, font stacks) without a redeploy

🛒 Storefront UX

CartDrawer — slide-in right panel for cart items with quantity controls, no separate cart page needed
WishlistButton — heart toggle on product cards; LoginModal shown to unauthenticated users with pending action preserved across Auth0 redirect via sessionStorage
HeroBanner — full-width hero section with configurable image, overlay, title and CTA
ProductCarousel — horizontal snap-scroll carousel of product cards
CategoryBentoGrid — asymmetric editorial grid (up to 5 categories, first spanning 2 columns)

�🌍 Internationalisation

6 built-in locales: English (US), French, Spanish, Chinese (Simplified), Arabic, Hebrew
availableLanguages registry with nativeName, isRTL, `isDefau

Fufuni

Install / Use

README