Feastly documentation

A resellable, multi-restaurant on-demand food-delivery platform shipped as complete source code: three Flutter apps (Customer, Rider, Restaurant) and a Next.js admin panel on one shared backend, monetized by per-order commission, with an optional AI search & recommendations layer.

Feastly is a complete, self-hostable food-delivery platform you can rebrand and launch in your own market — an UberEats / Grab / Foodpanda-style operation. It is a four-surface bundle on a single shared backend:

The wedge. The food-delivery category is saturated with PHP/Laravel incumbents. Feastly competes on a full 4-app ecosystem, a modern Next.js + Flutter stack, an optional dual-provider AI layer, and zero paid-service lock-in for the buyer: the realtime layer is self-hosted, transactional email is plain SMTP, and AI is fully optional.

Portable. The backend is one Next.js app you can deploy to Vercel or any Node host / VPS / container. The database is standard PostgreSQL (the docs use Neon’s free serverless tier; any Postgres works). No secret ever ships inside a mobile binary.

What’s included

• Full source for all four surfaces — three Flutter apps + the Next.js admin/API/AI/realtime backend.
• Shared Drizzle schema (24 tables) with 3 generated SQL migrations, runnable on a fresh Postgres.
• A shared Dart package (packages/shared-dart) — theme, typed API client, and models used by all three apps.
• An idempotent demo seed: 12 restaurants, 71 menu items, 11 users, 11 orders (5 completed + 6 in-flight), commission & payout ledgers, ratings, cuisines, banners and a delivery zone — so no surface ever loads empty.
• The design system (design tokens, Inter typography, the “AI Spark” gradient marker) mirrored across web and mobile.
• A branding pipeline: brand SVG/PNG masters + one-command launcher-icon regeneration.
• Optional, gracefully-degrading integrations: Stripe, Cloudflare R2, SMTP, Google Maps, OpenAI/Gemini.
• This documentation, a quick-start guide, per-surface widget tests, and a dependency license audit.
• 6 months of item support (see Support and licensing).

Customer app

• Email/password onboarding (JWT-backed mobile sessions); manual address book with delivery-zone gating.
• Discovery: restaurant list, categories, cuisines, filters & sort, and AI-assisted search (degrades to full-text).
• Restaurant page with categorised menu, item detail, modifiers/add-ons, and veg/allergen tags.
• Cart & checkout: modifiers, order notes, tip, delivery vs pickup, address & payment-method select.
• Payments: Cash on Delivery (first-class) and card via Stripe (webhook-confirmed).
• Live order tracking: status timeline + rider location over the self-hosted realtime stream.
• Post-order: rate restaurant + rider, reorder, order history.
• Recommendations: “Recommended for you” / “Popular near you” (degrades to popularity).

Rider app

• Rider auth & profile; online/offline availability toggle.
• Order intake: auto-assign or accept-from-pool (admin-configurable mode).
• Full status flow: accepted → arrived → picked up → en route → delivered, with a location ping.
• Earnings: per-order breakdown plus daily/weekly totals and payout status.

Restaurant app

• Restaurant auth & profile (hours, min order).
• Menu management: categories, items, modifiers, availability toggles, images.
• Order board: incoming → accept/reject → preparing → ready-for-pickup.
• Earnings dashboard: gross, commission deducted, net owed.
• Basic analytics: orders, revenue, top items.

Admin panel (Next.js)

• Dashboard: GMV, orders, commission earned, top items.
• Restaurant management: onboard/approve, per-restaurant or global commission %, suspend.
• Rider management: onboard/approve, assignment mode, suspend.
• Order oversight: search, live status, manual reassign, refund/cancel.
• Commission engine: global default + per-restaurant override, automatic per-order calculation into an immutable ledger.
• Payout ledger: per-restaurant and per-rider amounts owed, with mark-as-paid (manual settlement in V1).
• Content: banners, categories, cuisines, delivery zones (geofence editor) at /admin/content.
• Configuration: payment / AI / maps / SMTP / push keys — all stored server-side.
• Users, roles, disputes, and ratings moderation.

Backend API (all surfaces run against it)

42 route handlers under apps/web/src/app/api, including /api/mobile/* (bootstrap config, JWT auth, addresses, zone-check), /api/restaurants, /api/search, /api/recommendations, /api/orders, /api/payments/webhook/[gateway], /api/uploads/presign, /api/realtime/* (SSE), and /api/inngest (background jobs).

How the four surfaces connect

The three Flutter apps and the browser-based admin UI all talk to one shared Next.js backend (apps/web). Mobile apps use HTTPS REST with a JWT bearer and receive live updates over SSE; the admin UI is served by the same app using session cookies. Every third-party key stays server-side.

Flows. Mobile → backend over HTTPS REST (JWT bearer); backend → mobile live updates over SSE (order status + rider location); the admin browser ↔ backend over session cookies; backend ↔ PostgreSQL via Drizzle ORM. Payment confirmation arrives as a signature-verified webhook before an order advances past payment. All optional third-party keys are read server-side and never ship inside a mobile binary.

Monorepo layout

feastly/
├── apps/
│   ├── web/            # Next.js — admin UI + API + AI + realtime (SSE) backend
│   ├── customer/       # Flutter
│   ├── rider/          # Flutter
│   └── restaurant/     # Flutter
├── packages/
│   ├── config/         # shared TS config + Tailwind design-token preset
│   ├── db/             # Drizzle schema + migrations (PostgreSQL / Neon)
│   └── shared-dart/    # shared Dart: theme, API client, models
├── brand/              # logo SVG/PNG masters → launcher icons
├── scripts/            # set-maps-key.sh
└── .env.example        # every environment variable, grouped

The JS side (apps/web, packages/config, packages/db) is a Turborepo + pnpm workspace. The three Flutter apps and packages/shared-dart are a Dart pub workspace (Melos optional).

Tech stack

Design invariants

• All third-party keys are server-side only and admin-configurable — no secret ships in an APK/IPA.
• AI is fully optional: the app is 100% functional with AI disabled. Model IDs are env / admin-config toggled, never hardcoded.
• Money math is fail-safe (reserve → commit → refund); an order only advances past payment after a webhook-confirmed charge. COD is first-class.
• The order lifecycle is a canonical state machine; every transition emits a notification + a background event; the commission ledger entry written on completion is immutable.
• Graceful empty/offline states everywhere; single-currency config and an i18n scaffold in V1.

No paid third-party service is required. Payments, AI, Maps, Push and SMTP are all optional (Optional integrations).

Deploy the backend — Vercel

1. 01
   Push the repo to GitHub, then New Project → Import in Vercel.
2. 02
   Set Root Directory to apps/web (the one critical setting). Framework (Next.js), build (next build) and install (pnpm install) auto-detect. Node 24.x is pinned via engines.
3. 03
   Add environment variables (Production): required DATABASE_URL, AUTH_SECRET, AUTH_TRUST_HOST=true, AUTH_URL=https://your-domain; plus any optional keys you use (Optional integrations).
4. 04
   Add your custom domain and keep AUTH_URL in sync with it.
5. 05

   Run migrations once from your machine against the production DB (Vercel does not run them):

   terminalCopy

   DATABASE_URL="<prod-url>" pnpm db:migrate

Deploy the backend — any Node host / VPS / container

pnpm install
pnpm --filter @feastly/web build
DATABASE_URL="…" AUTH_SECRET="…" pnpm --filter @feastly/web start   # serves on :3000

Set DATABASE_URL and AUTH_SECRET in the host’s environment. Run pnpm db:migrate once against the production database.

Build the mobile apps

flutter build apk    --dart-define=FEASTLY_API_URL=https://your-domain   # Android
flutter build appbundle --dart-define=FEASTLY_API_URL=https://your-domain
flutter build ios    --dart-define=FEASTLY_API_URL=https://your-domain   # iOS (from macOS)

1. 01

   Provision Postgres

   Create a free project at neon.tech (or use any Postgres) and copy the connection string.
2. 02

   Set env

   Put it in .env as DATABASE_URL (a single root .env feeds both the web app and the DB tooling).
3. 03

   Migrate

   pnpm db:migrate applies the 3 committed SQL migrations. (Changed the schema? pnpm db:generate regenerates SQL first.)
4. 04

   Seed

   pnpm db:seed loads the demo data. The seed is idempotent — if customer@feastly.dev already exists it logs and exits cleanly, so it is safe to re-run and will not duplicate.

The schema is split into auth, catalog, orders, ledger and system groups under packages/db/src/schema:

Your whole platform — restaurants, menus, orders, ledgers, users — lives in one PostgreSQL database (whatever DATABASE_URL points at). You don’t need to know PostgreSQL internals to keep it safe: a backup is a single command. The two tools below, pg_dump and pg_restore/psql, ship with PostgreSQL — install them with brew install libpq on macOS or apt install postgresql-client on Linux.

Back up the entire database to one file

pg_dump writes a complete, restorable snapshot. The compressed custom format is the safest default:

# everything → one compressed file
pg_dump "$DATABASE_URL" --format=custom --file=feastly-backup.dump

# …or a plain-text .sql file you can open and read
pg_dump "$DATABASE_URL" --format=plain --file=feastly-backup.sql

Keep that file somewhere safe (your computer, an R2/S3 bucket, a private repo). That one file is your full backup.

Restore into a fresh database

Point at an empty database ($TARGET_DATABASE_URL) and load the dump back in:

# from a custom-format .dump
pg_restore --clean --if-exists --no-owner --dbname "$TARGET_DATABASE_URL" feastly-backup.dump

# from a plain .sql file
psql "$TARGET_DATABASE_URL" --file=feastly-backup.sql

Export a single table to CSV (e.g. for a spreadsheet)

psql "$DATABASE_URL" --command "\copy (SELECT * FROM orders) TO 'orders.csv' WITH CSV HEADER"

Every integration is optional and gracefully no-ops when its keys are blank — the app stays fully functional. Keys live in .env or, at runtime, in the admin Configuration page; the code resolves env first, then the admin store.

Every variable the platform reads, in one place. These tables mirror .env.example line-for-line — that file is the canonical template, so cp .env.example .env always gives you a complete, current file. The same key list also drives the admin Configuration page (apps/web/src/lib/config.ts), so template, docs and admin UI stay in step; when a release adds a variable it lands in all three.

Only the first two are required. Every other row can stay blank — the “If left blank” column tells you exactly what happens.

Required

Core URLs (set these in production)

Payments and currency

Media — Cloudflare R2

Push — Firebase Cloud Messaging

AI (fully optional)

Transactional email — SMTP

Maps

Realtime at scale

Set at build time, not in .env

Two values belong to the mobile build rather than the server environment:

The AI layer (apps/web/src/lib/ai/provider.ts) is a server-side provider abstraction over OpenAI and Gemini embeddings. It powers two surfaces, both badged with the “AI Spark” marker:

• AI-assisted search (/api/search) — embedding-based semantic ranking with a keyword fallback.
• Recommendations (/api/recommendations) — “Recommended for you” / “Popular near you” from order history, falling back to popularity/proximity on cold start.

Enable it

AI_PROVIDER="openai"                 # or "gemini", or "" to disable
OPENAI_API_KEY="sk-…"
OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
# Gemini instead:
# AI_PROVIDER="gemini"
# GEMINI_API_KEY="…"
# GEMINI_EMBEDDING_MODEL="…"

• Server-only. Keys are read from env or the admin config store and are never returned to a client or embedded in a mobile binary.
• Never hardcoded. Model IDs are configuration values, so you can swap models without a code change.
• Fully optional. Leave AI_PROVIDER blank and every AI surface degrades gracefully — the app is 100% functional with AI off.

Payments

A CardGateway interface (apps/web/src/lib/payments.ts) has two shipping implementations: a manual gateway (the default; COD is first-class, and card flows confirm via a local webhook) and a Stripe gateway (payment intents, refunds, and signature-verified webhooks). The order state machine only advances past payment on a webhook-confirmed charge. Webhooks land at /api/payments/webhook/[gateway]. The mobile apps fetch only publishable config from /api/mobile/config — the Stripe secret and webhook secret are never sent to a client.

Media (Cloudflare R2)

Image uploads use short-lived presigned PUT URLs minted at /api/uploads/presign — the client uploads directly to R2 and only ever receives the presigned URL plus the resulting public URL. With R2 unconfigured, presigning returns null and uploads are simply disabled; existing/seeded imagery is unaffected. Set the five R2_* vars to enable.

Push notifications

Order transitions write a notifications row and publish a realtime event, so every surface reflects status changes in-app immediately. Native FCM delivery is scaffolded (env slots present) but not yet wired server-side — enabling true push is a documented roadmap step, not required for the flow to work.

Background jobs (Inngest)

Inngest handles order-state jobs, notification fan-out and ledger events at /api/inngest. It runs against Inngest’s dev server locally and their cloud (or a self-hosted relay) in production.

Realtime

The self-hosted SSE layer streams order status and rider location to the customer tracking screen and the restaurant/rider/admin boards (/api/realtime/*). Out of the box it is an in-process pub/sub (apps/web/src/lib/realtime.ts) — perfect for dev and a single Node instance. On a horizontally-scaled or serverless deploy, an event published on one instance won’t reach SSE clients connected to another.

Scaling out: a Redis pub/sub adapter

Back the bus with Redis and every instance shares one channel — the publish() / subscribe() surface the rest of the app calls stays identical, so no route, job or component changes. Install the client and point REDIS_URL at any Redis (Upstash, Redis Cloud, or your own):

pnpm --filter @feastly/web add ioredis
# .env  →  REDIS_URL=redis://default:••••@your-host:6379

Then swap the body of apps/web/src/lib/realtime.ts for this drop-in replacement — same exports, Redis-backed fan-out:

import 'server-only';
import Redis from 'ioredis';

export type RealtimeEvent = { type: 'status' | 'location' | 'hello' | 'order' | 'pool'; data: unknown };
type Listener = (event: RealtimeEvent) => void;

export const CHANNELS = {
  restaurant: (id: string) => `restaurant:${id}`,
  adminOrders: 'admin:orders',
  riderPool: 'rider:pool',
} as const;

const BUS = 'feastly:realtime';                    // one shared Redis channel
const local = new Map<string, Set<Listener>>();     // channel → this node's SSE listeners

// A connection in subscribe mode can't run other commands, so publishing needs its own.
const pub = new Redis(process.env.REDIS_URL!);
const sub = new Redis(process.env.REDIS_URL!);

// Fan every bus message out to the listeners living on THIS node.
sub.subscribe(BUS);
sub.on('message', (_channel, payload) => {
  const { channel, event } = JSON.parse(payload) as { channel: string; event: RealtimeEvent };
  const set = local.get(channel);
  if (!set) return;
  for (const listener of set) {
    try { listener(event); } catch { /* a dead listener must not break the fan-out */ }
  }
});

export function subscribe(channel: string, listener: Listener): () => void {
  let set = local.get(channel);
  if (!set) local.set(channel, (set = new Set()));
  set.add(listener);
  return () => {
    set!.delete(listener);
    if (set!.size === 0) local.delete(channel);
  };
}

export function publish(channel: string, event: RealtimeEvent): void {
  // Publish to Redis only; the message loops back through sub.on('message')
  // above, so this node's listeners fire exactly once — same path as every other node.
  pub.publish(BUS, JSON.stringify({ channel, event }));
}

Why publish only to Redis? Every node — including the one that called publish() — receives the event back through the shared subscriber, so each listener fires exactly once with no special-casing of the origin. For a managed option, Upstash exposes a Redis-compatible endpoint that works from serverless functions.

Five edits turn Feastly into your brand — roughly half an hour, no screen-by-screen work. Each step names the exact file to change, and the paths below are copy-paste ready. Steps 1–4 are the visual identity; step 5 points the apps at your backend and legal pages. Finish with the verification checklist to confirm nothing was missed.

1. 01

   Swap the logo and app icon

   Replace the two 1024×1024 master PNGs with your own square icon art — keep the same file names and dimensions and everything downstream regenerates from them: brand/icon-1024.png, brand/foreground-1024.png.

   Optional vector sources: brand/feastly-icon.svg, brand/feastly-mark.svg. Web favicon & admin browser icon: apps/web/src/app/favicon.ico, apps/web/src/app/icon.svg, apps/web/src/app/apple-icon.png.

2. 02

   Update the color scheme

   The palette is defined once per platform from a single primary color — change it and every screen, button and badge follows. Current tokens:

   TokenValue

   primary

   #ae3200

   primary-container

   #ff5a1f

   tertiary

   #006d37

   error

   #ba1a1a

   surface

   #f8f9fa

   Web / admin: packages/config/tailwind-preset.ts (the shared Tailwind design-token preset). Mobile (all three apps at once): packages/shared-dart/lib/src/theme/app_colors.dart and packages/shared-dart/lib/src/theme/app_theme.dart (the shared Material 3 seed color). Edit the primary in these places and the whole system re-themes.

3. 03

   Rename the apps and set your bundle IDs

   Display name — each app’s android/app/src/main/AndroidManifest.xml (android:label) and iOS ios/Runner/Info.plist (CFBundleDisplayName). Identifiers — android/app/build.gradle.kts (applicationId + namespace) and the iOS PRODUCT_BUNDLE_IDENTIFIER. The current names/IDs are in the App identity table below.
4. 04

   Regenerate the launcher icons

   Run once inside each app folder (apps/customer, apps/rider, apps/restaurant) after swapping the masters in step 1:

   terminalCopy

   dart run flutter_launcher_icons

5. 05

   Point everything at your own backend and legal pages

   Three text edits, all outside the visual layer — do these before you ship a build:

   • Backend URL. The apps ship pointing at our demo backend. Set your own default in packages/shared-dart/lib/src/api/api_config.dart (ApiConfig.productionBaseUrl), or override per build with --dart-define=FEASTLY_API_URL=https://your-domain.
   • Terms & privacy links shown in every app’s Settings → About: _termsUrl / _privacyUrl in packages/shared-dart/lib/src/widgets/settings_about_section.dart. Point them at your own pages — the app stores require both.
   • Admin browser title. metadata.title / metadata.description in apps/web/src/app/layout.tsx (currently “Feastly Admin”) — this is the browser-tab name of your admin panel.

Run through this once; if every row passes, no “Feastly” branding is left anywhere a user can see.

Design tokens

The palette centers on primary orange #ae3200 (vibrant #ff5a1f) with a leaf-green accent #006d37, Inter throughout, 12px-radius buttons, 16px-radius cards, and the “AI Spark” gradient marker on AI surfaces. Web tokens live in the Tailwind preset (packages/config); mobile tokens live in packages/shared-dart.

Launcher icons

All three apps regenerate icons from shared masters in brand/ via flutter_launcher_icons:

# masters: brand/icon-1024.png (full), brand/foreground-1024.png (adaptive foreground)
# vector sources: brand/feastly-icon.svg, brand/feastly-mark.svg
dart run flutter_launcher_icons     # run inside apps/customer, apps/rider, apps/restaurant

To rebrand: replace the two 1024×1024 PNGs (optionally update the SVG masters), optionally change adaptive_icon_background in each app’s pubspec.yaml, then re-run the command. The web favicon is apps/web/src/app/favicon.ico.

App identity

Change the display name in each android/app/src/main/AndroidManifest.xml (android:label) and iOS Info.plist (CFBundleDisplayName); change ids in each android/app/build.gradle.kts (applicationId + namespace) and the iOS project’s PRODUCT_BUNDLE_IDENTIFIER. Min iOS is 17.0; Android inherits the Flutter default minSdk (raise it explicitly if your Flutter toolchain’s default is below what flutter_stripe requires). If you self-host, also update the production URL and the terms/privacy links in packages/shared-dart.

Short answers to the questions new operators ask most — first the platform itself, then the deployment and day-two questions that come up once you go live. Full detail lives in Deployment, Database setup, Backups and exports, Optional integrations, Environment reference and Rebrand step by step.

Using the platform

Deployment and operations

1. 01
   Set DATABASE_URL and a stable AUTH_SECRET (openssl rand -base64 32) in the host environment.
2. 02
   Set AUTH_URL to your production domain and AUTH_TRUST_HOST=true.
3. 03
   Run pnpm db:migrate against the production database (do not seed it).
4. 04
   Add only the optional keys you use — Stripe, R2, SMTP, Maps, AI — all server-side. Every variable and its blank-value behavior is in the complete environment reference.
5. 05
   If enabling AI on a public deployment, add a rate limiter in front of /api/search and /api/recommendations (AI setup).
6. 06
   For horizontally-scaled/serverless realtime, set REDIS_URL and back apps/web/src/lib/realtime.ts with Redis pub/sub — drop-in adapter in Payments, media, push and realtime.
7. 07
   Schedule a backup: one pg_dump command as a nightly cron job or GitHub Action (Backups and exports).
8. 08
   Build each mobile app with --dart-define=FEASTLY_API_URL=https://your-domain and your own signing config.
9. 09
   Rebrand: swap brand/ masters, re-run flutter_launcher_icons, set app names/ids, update terms/privacy links.
10. 10
    Set CURRENCY to your market’s ISO 4217 code.

Every version published so far. Updates are free for the life of the item.

Version 1.1.0 · 2026-08-03

Order details across all four apps.

• Rider order detail screen (new). Pickup and drop-off cards with one-tap Navigate and Call on each leg, the full item list with modifiers, delivery notes, and the cash-to-collect amount called out on COD orders.
• Richer rider job cards. Before accepting, a rider sees the restaurant, its address, the delivery area with distance, item count, payment method and their payout — instead of just an order number and a total.
• Restaurant order board + detail screen. Customer name, itemised order with modifiers, and the assigned rider with a Call button once one is allocated.
• Admin order oversight. Expandable pickup / drop-off / assigned-rider contact block on every order row, so support can answer “where is this going, and to whom?”.
• Customer tracking. Now shows which restaurant the order is coming from, with its address, Navigate and Call.
• Customer privacy model. A customer’s street address and phone number are visible only to the rider actually assigned to their delivery, and to the platform admin. Riders browsing the unclaimed order pool see the delivery area and distance, never the customer’s identity or exact address. Enforced in the database queries, not just hidden in the UI.
• Fixes. Delivery coordinates are now saved when a customer checks out with a saved address (previously the rider’s drop-off Navigate button had no destination); two riders can no longer accept the same order; pickup-only orders no longer appear in the rider delivery queue; and the restaurant’s address and phone now reach the customer’s tracking screen.
• Demo data. Customer phone numbers, delivery coordinates, item modifiers, and a card-paid order so both the “collect cash” and “already paid” states are visible in the seed.
• Upgrading. No database migration. Existing installations should run the one-off coordinate backfill below.

UPDATE orders o SET delivery_lat = a.lat, delivery_lng = a.lng
FROM addresses a
WHERE o.address_id = a.id AND o.delivery_lat IS NULL;

Version 1.0.0 · 2026-07-10

• Initial release. Four surfaces on a shared backend; order lifecycle state machine; commission & payout ledgers; COD + Stripe payments; self-hosted realtime tracking; optional AI search + recommendations; idempotent demo seed; full documentation.

DevSnack — 6 months of item support is bundled per CodeCanyon standard (setup guidance, bug fixes, and answering usage questions). You supply your own hosting, domains and third-party accounts; we provide the walkthroughs.

• Support requests: post on the Comments tab of this item’s CodeCanyon page — the fastest way to reach us.
• Support tickets: open one from the Support tab on our CodeCanyon author profile.

License. Sold under the standard Envato Regular and Extended licenses. All dependencies are permissive (MIT / Apache-2.0 / BSD / ISC); no copyleft or per-seat obligation is passed to you.

What support covers

• Six months of support from purchase, extendable at checkout
• Support covers bugs in the template and questions about how it is put together
• It does not cover custom feature work, third-party API changes or store review outcomes
• The Regular licence covers one free end product. Charging users for the app itself needs the Extended licence