Closing the Loop, Saving Every Meal.
Cirquo is a Circular Food Recovery Platform that connects food businesses, consumers, and organic processors into a single circular ecosystem. It is not a food delivery app — the marketplace is only the entry point. The product is Material Flow Orchestration: knowing where every kilogram of surplus food goes.
Built for DSDC ANFORCOM 2026.
Indonesia generates an estimated 23–48 million tonnes of food loss and waste per year, worth Rp213–551 trillion annually (Bappenas). At street level the failure is not technological but organisational:
- Bakeries, restaurants, and caterers have predictable daily surplus with no recovery path
- Consumers would buy discounted surplus but cannot discover it in time
- Organic processors (BSF/maggot, composting, biogas) want feedstock but receive it inconsistently
- Nobody can measure what actually happened to any of it
In Semarang the infrastructure already exists — TPA Jatibarang operates BSF processing, TPST Gemah receives organic waste from restaurants and shops and routes it to maggot farmers. Cirquo digitises an ecosystem that is already there but fragmented.
Every unit of surplus food gets a next best use, and every outcome is recorded.
MERCHANT
surplus food
│
▼
┌─────────────────┐
│ CIRQUO │
│ Rescue Engine │
│ Pricing Engine │
│ Material Ledger │
└────────┬────────┘
│
┌─────────┴─────────┐
▼ ▼
STILL EDIBLE NOT RESCUED
│ │
▼ ▼
CONSUMER ORGANIC PROCESSOR
RESCUED BSF / COMPOST
│ │
│ RECOVERED
└─────────┬─────────┘
▼
IMPACT TRACKING
rescued · recovered · residual
Three terminal outcomes, always measured:
| Outcome | Meaning |
|---|---|
| Rescued | A Consumer collected and ate it |
| Recovered | An Organic Processor turned it into compost, BSF larvae, feed, or biogas |
| Residual | Neither happened — reported honestly, never hidden |
circularity rate = (rescued + recovered) / total surplus
We do not claim zero waste. We claim we know where every kilogram went.
| Feature | Description |
|---|---|
| Material Flow Ledger | Append-only, immutable event log of every Rescue Item lifecycle event. The single source of truth for all impact metrics |
| Circular Routing | Automatically matches unclaimed or unsellable surplus to a verified Organic Processor by material type, distance, and capacity |
| Dynamic Rescue Pricing | Transparent rule-based discount curve that escalates as the pickup window closes, always respecting the merchant's floor price |
| Map Discovery | Mapbox-powered nearby Rescue Item discovery, ranked by proximity, discount, and urgency |
| Impact Tracking | Role-scoped dashboards showing kg rescued, kg recovered, kg residual, circularity rate, and estimated CO2e — all derived from the ledger |
| Pickup Verification | Code/QR handover confirmation that makes physical fulfilment auditable |
| Role | What they do |
|---|---|
| Consumer | Discovers Rescue Items on a map, reserves, pays, collects, sees personal impact |
| Merchant | Lists surplus, receives a suggested price, confirms pickup, tracks recovered revenue and impact |
| Organic Processor | Receives routed material, logs measured intake and processing outcome |
| Admin | Verifies businesses, moderates listings, resolves disputes, audits the ledger, monitors platform impact |
| Layer | Technology |
|---|---|
| Frontend | React 19 · Vite 8 · TypeScript · React Router v7 |
| Styling | Tailwind CSS v4 (OKLCH tokens) · shadcn/ui · Lucide |
| Backend | Convex (database, serverless functions, realtime, scheduler) |
| Maps | Mapbox |
| Payments | Midtrans Sandbox (QRIS) |
| Mobile | Capacitor 8 (Android) |
| Forms | React Hook Form + Zod |
| Tooling | Bun · oxlint |
Rationale and rejected alternatives for every choice: docs/architecture/ARCHITECTURE.md.
Prerequisites: Bun, Node.js (Vite-compatible), Git. Android Studio + SDK only if building the APK.
git clone <repository-url>
cd cirquo
bun install
cp .env.example .env.localRun with a Convex backend (two terminals):
# Terminal 1 — backend
bunx convex dev
# Terminal 2 — frontend
bun run devbunx convex dev prompts for login, creates or selects a deployment, generates convex/_generated, and writes VITE_CONVEX_URL into your local env.
Without VITE_CONVEX_URL the app still runs in a placeholder mode with no backend — useful for UI work.
Full setup, troubleshooting, and the Android workflow: docs/engineering/DEVELOPMENT.md.
| Command | Purpose |
|---|---|
bun run dev |
Start the Vite dev server |
bunx convex dev |
Start the Convex backend and watch functions |
bun run build |
Typecheck and build to dist/ |
bun run lint |
Run oxlint |
bun run preview |
Preview the production build |
bun run android:sync |
Build web and sync into the Android project |
bun run android:open |
Open the project in Android Studio |
bun run android:run |
Run on a connected device or emulator |
| Variable | Scope | Public? | Purpose |
|---|---|---|---|
VITE_CONVEX_URL |
Client | Convex deployment URL. Unset ⇒ placeholder mode | |
VITE_MAPBOX_ACCESS_TOKEN |
Client | Mapbox access token (scope and URL-restrict it) | |
MIDTRANS_SERVER_KEY |
Convex | 🔒 No | Set via bunx convex env set — never in .env |
VITE_MIDTRANS_CLIENT_KEY |
Client | Midtrans Snap client key; public by design |
Anything prefixed VITE_ is embedded in the client bundle and is therefore public. Secrets belong in Convex environment variables only. See docs/security/SECURITY.md.
src/
app/ router and providers
components/
ui/ shadcn/ui primitives
common/ cross-role composites
consumer/ role-specific components
merchant/
processor/
admin/
constants/ placeholder data (to be removed)
features/ feature-scoped modules
hooks/ shared React hooks
layouts/ per-role navigation shells
lib/ framework-agnostic logic (pricing, routing, impact, geo)
pages/ route components by role
types/ domain and navigation types
convex/ schema and backend functions
public/ PWA manifest, service worker, icons
android/ Capacitor Android project
docs/ complete documentation system
Architectural discipline: business algorithms live in src/lib/*.ts with no Convex imports. Convex functions load data, call the pure function, and persist the result. This keeps the logic unit-testable, portable, and explainable.
| Actor | Routes |
|---|---|
| Guest | /welcome · /login · /register |
| Consumer | / · /discover · /explore · /orders · /item/:id · /checkout/:orderId |
| Merchant | /merchant · /merchant/surplus · /merchant/surplus/new |
| Processor | /processor · /processor/recovery |
| Admin | /admin · /admin/ledger |
| Fallback | * |
Route access is restored from the persisted session and checked by role. See src/app/router.tsx for the current route table and docs/architecture/FRONTEND.md for the architecture.
Implementation snapshot — 2026-08-27. Source code is the release-status authority; roadmap and API documents distinguish implemented functions from target contracts.
✅ In place
- Vite + Bun + TypeScript toolchain, oxlint
- React Router with four role-scoped layouts
- 17 shadcn/ui primitives plus
PageHeader,SummaryCard,RoleShell - Convex schema with 10 tables, including sessions, auth events, Material Flow Ledger, and payments
- Session authentication, role onboarding, persisted token restoration, and role-specific route guards
- Merchant Rescue Item draft, publish, edit, cancellation, and reactive list flows with ledger writes
- Consumer Mapbox discovery, reservation, order views, and Midtrans Sandbox transaction/webhook integration
- Capacitor Android configured (
com.cirquo.app), PWA manifest and service worker - Tailwind v4 OKLCH design tokens, Geist Variable font
- Documentation system; implementation notes are being kept in sync with source
📋 Not yet built
- Processor intake and outcome logging
- Full Circular Routing and lifecycle scheduling
- Pickup confirmation and complete Merchant fulfilment flow
- Ledger-derived impact aggregation, notifications, and complete Admin operations
Some dashboards and role surfaces remain placeholders. Verify the relevant Convex function and UAT before presenting any dashboard figure as real. Delivery plan: docs/business/ROADMAP.md.
The full documentation system lives in docs/. Start with docs/README.md as the index.
| Area | Documents |
|---|---|
| Product | PRD · PRODUCT · VISION |
| Business | BUSINESS · ROADMAP · RISKS |
| Specification | FEATURES · USER_STORIES · USER_FLOW · ROLES |
| Domain | DOMAIN · STATE_MACHINE · DATA_MODEL · DATABASE |
| API | API · AUTH · CONSUMER · MERCHANT · PROCESSOR · ADMIN |
| Architecture | ARCHITECTURE · FRONTEND · BACKEND · REALTIME · SCHEDULER |
| Impact | ALGORITHM · IMPACT · MATERIAL_LEDGER |
| Security | SECURITY · AUTH · PERMISSIONS |
| Design | DESIGN · UI_GUIDE · COMPONENTS · FIGMA |
| Engineering | STYLE_GUIDE · DEVELOPMENT · TESTING · DEPLOYMENT |
| Project | AGENTS · CONTRIBUTING · CHANGELOG |
AI agents working on this repository: read AGENTS.md first.
Placeholder — to be added once the core flows are implemented.
| Screen | Preview |
|---|---|
| Consumer map discovery | docs/assets/screens/consumer-explore.png |
| Reservation and pickup code | docs/assets/screens/consumer-pickup.png |
| Merchant listing creation | docs/assets/screens/merchant-create.png |
| Circular routing to processor | docs/assets/screens/processor-queue.png |
| Material Flow Ledger audit trail | docs/assets/screens/admin-ledger.png |
| Impact dashboard | docs/assets/screens/impact-dashboard.png |
Branch model: main ← dev ← feat/*
main
└── dev
├── feat/consumer-marketplace
├── feat/merchant-dashboard
├── feat/recovery-flow
└── feat/impact-dashboard
Conventional commits (feat:, fix:, chore:, docs:, refactor:). Feature branches merge into dev; dev promotes to main after review.
Two rules that are never negotiable:
- Every state-changing mutation writes a Material Flow Ledger event in the same transaction.
- Every mutation enforces authorization server-side. The frontend may hide a button; the server must reject the call regardless.
Full workflow and PR checklist: docs/project/CONTRIBUTING.md.
In scope for the competition MVP: four-role authentication, merchant listing with Dynamic Rescue Pricing, consumer map discovery with reservation and Midtrans Sandbox payment, pickup code verification, automatic Circular Routing of unclaimed surplus, processor intake and outcome logging, Material Flow Ledger, role-scoped impact dashboards, admin verification and moderation, Capacitor Android build.
Explicitly out of scope: logistics dispatch and route optimisation, peer-to-peer food swap, allergy-safety guarantees (only dietary preference filtering on merchant-declared attributes), AI demand forecasting, multiple payment gateways, multi-currency, native Flutter/React Native apps, loyalty and gamification, computer-vision quality verification.
Rationale for each exclusion: docs/business/ROADMAP.md §9.
To be determined before public release.
Built for DSDC ANFORCOM 2026
Cirquo — Closing the Loop, Saving Every Meal