Quiko
Peer-to-peer package delivery for India — Quiko matches senders who need a
package delivered with travellers already going that way, holds the payment
in escrow, and releases it on delivery. Quiko keeps a 2% commission.
This is a monorepo containing the web app (which is also the backend/API), the
mobile app, and shared code.
Repository layout
| Path | What it is |
|---|
quiko-app/ | The main app — Next.js 16 web frontend and the backend/API and database. This is where you'll spend most of your time. |
quiko-app/core/ | Framework-agnostic shared logic (pricing, geo/detour, formatting, moderation). Imported by both web and mobile — keep it free of React/Next/RN. |
quiko-mobile/ | The Expo / React Native mobile app. Talks to quiko-app's API. Currently behind the web app (see plan.md). |
docs/ | Product, design, and business docs (incl. the vendor-onboarding checklist). |
WALKTHROUGH.md | Guided tour of every feature with demo logins — do this after setup to learn the app. |
plan.md | Living plan/journal: every feature built, decisions made, and what's pending. Read this first for context. |
quiko-prototype/ | The original static HTML prototype. Historical reference only — not the live app. |
Stack: Next.js 16 (App Router, React 19) · TypeScript · Drizzle ORM · PostgreSQL (Docker) · custom JWT auth (jose) · Tailwind · Expo/React Native.
⚠️ quiko-app runs a modified Next.js 16. Read quiko-app/AGENTS.md — some APIs differ from the docs you know.
Prerequisites
- Node.js 20 or newer (tested on 26). Check with
node -v.
- Docker Desktop (runs the local Postgres). Make sure it's started.
- npm (ships with Node).
- For mobile only: the Expo Go app or Xcode / Android Studio simulators.
Quick start — web app + API
cd quiko-app
# 1. Install dependencies
npm install
# 2. Create your local env file, then generate a session secret
cp .env.example .env.local
# edit .env.local → set SESSION_SECRET (run: openssl rand -base64 32)
# 3. Start Postgres (Docker) — runs on host port 5433
npm run db:up
# 4. Create the schema and load demo data
npm run db:migrate
npm run db:fixtures # full walkthrough dataset (recommended — see "Seeding")
# 5. Run the app
npm run dev
Open http://localhost:3000.
Logging in (dev)
There's no real SMS in dev — OTP is mocked.
- Enter any Indian phone number, then the OTP
345678.
- The code is also printed in the server console:
[dev-otp] code for <phone> = 345678.
Seeded accounts
| Role | Phone | Notes |
|---|
| Admin | 919999900001 | Full admin console (Profile → Open admin panel). |
| Admin | 919000000002 | — |
| Support | 91939313463 | Assist-only ops console (Profile → Open ops console). |
Seeding the database
Two seed scripts (both idempotent — safe to re-run):
| Command | What it loads |
|---|
npm run db:fixtures | Recommended. A full walkthrough dataset — demo sender/traveller, staff roles, and matches in every state (paid, delivered+review, disputed, cancelled), plus a support thread and a moderation flag. Creates the logins below. |
npm run db:seed | Minimal — just a few traveller profiles + trips so the "find travellers" list isn't empty. |
npm run db:reset | Re-applies migrations, then runs db:seed. |
db:fixtures adds these demo logins (OTP 345678): Sam Sender 918888800001, Tara Traveller 918888800002 (plus the admin/support accounts above). Then follow WALKTHROUGH.md to tour every flow.
The seeds upsert and never delete login profiles — only their own fixture rows — so re-running won't wipe accounts you've created.
Quick start — mobile app
The web app (API) must be running first.
cd quiko-mobile
npm install
cp .env.example .env # already points at http://127.0.0.1:3000
npx expo start # press "i" for iOS simulator, "a" for Android
Use 127.0.0.1, not localhost, for the API URL — the iOS simulator
resolves localhost to IPv6 where the dev server isn't listening.
Common commands (quiko-app)
| Command | Does |
|---|
npm run dev | Start web + API (hot reload). |
npm run db:up / db:down | Start / stop the Postgres container. |
npm run db:generate | Generate a new migration after editing db/schema.ts. |
npm run db:migrate | Apply pending migrations. |
npm run db:seed | Minimal seed (travellers + trips). |
npm run db:fixtures | Full walkthrough dataset (see Seeding). |
npm run db:reset | Migrate + reseed. |
npm run db:studio | Open Drizzle Studio (browse the DB). |
npm run lint | ESLint. |
npx tsc --noEmit | Type-check the whole app. |
Database: Postgres runs in Docker on host port 5433 (not the default 5432, to avoid clashes). Credentials are quiko / quiko / quiko (see docker-compose.yml).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
