Fixi

Fixi is a two-sided home-services marketplace for Sri Lanka. Customers create structured jobs with a Gemini-guided conversation, receive explainable matches from verified available professionals, coordinate the visit, and review completed work. Professionals apply for verification, manage availability, accept assigned work, and progress jobs through an enforced lifecycle.

main is the real Supabase-backed application. The original self-contained competition prototype is preserved on the demo branch.

Live architecture

• React 19 + Vite customer and professional application.
• Supabase Auth with email/password sessions.
• Supabase Postgres as the source of truth, with RLS on every exposed table.
• Authenticated Postgres RPCs for job creation, matching, selection, acceptance, transitions, worker applications, and reviews.
• FastAPI as the protected application/AI boundary. Normal database calls preserve the user's JWT and RLS; no master database key is required for runtime job operations.
• Gemini structured-output booking assistant with a deterministic outage fallback.
• Private Supabase Storage for issue and completion photos.
• Realtime job updates and participant-only messaging.
• Cash-after-service MVP payments. No card data is collected.
• Tauri 2 wrapper with native/browser geolocation fallback.

Requirements

• Node.js 20+
• Python 3.11+
• A Supabase project
• A Gemini API key
• Rust 1.77+ only for Tauri
• Docker-compatible runtime only for the optional local Supabase stack

Install

npm install

cd services/api
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
cd ../..

Create the ignored environment files:

cp .env.example .env
cp services/api/.env.example services/api/.env

Frontend configuration:

VITE_DEMO_MODE=false
VITE_API_URL=http://localhost:8000
VITE_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_YOUR_KEY

Backend configuration:

DEMO_MODE=false
FRONTEND_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_YOUR_KEY
SUPABASE_SECRET_KEY=
GEMINI_API_KEY=YOUR_GEMINI_KEY
GEMINI_MODEL=gemini-3.6-flash

The Supabase secret key is intentionally optional. Never place it or the Gemini key in frontend variables.

Deploy the database

The official CLI is a project dev dependency.

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push --dry-run
npx supabase db push

The production migrations include the required service categories. supabase/seed.sql remains for local reset compatibility. Do not use remote database reset commands on production.

For local Supabase development:

npx supabase start
npx supabase db reset

Run

Use two terminals:

npm run api:dev

npm run dev

Open http://localhost:5173. FastAPI documentation is at http://localhost:8000/docs.

First live workflow

1. Create and confirm a customer account in the app.
2. From Profile, submit a professional application using a second account.
3. In the Supabase SQL Editor, approve that professional after checking them:

update public.worker_profiles
set verification_status = 'verified'
where user_id = 'WORKER_AUTH_USER_UUID';

4. The professional signs in, goes online, and becomes eligible for matching.
5. The customer creates a guided job, selects the professional, and waits for acceptance.
6. The professional progresses the job through confirmed, en route, arrived, in progress, and awaiting release.
7. The customer confirms cash payment and submits a review, completing the job.

Verification

npm run check
npm audit --audit-level=high
cargo check --manifest-path src-tauri/Cargo.toml

Native wrapper

npm run tauri dev
npm run tauri android init
npm run tauri android dev
npm run tauri ios init
npm run tauri ios dev

Before a hosted native build, add the production FastAPI origin to connect-src in src-tauri/tauri.conf.json and configure the matching Supabase Auth mobile deep-link redirect.

Branch workflow

• main: real application and production migrations.
• demo: the frozen no-credential competition prototype.

After stabilizing a release on main, merge main into demo, resolve the app entry point in favor of demo mode, and run the competition walkthrough again. This lets the demo receive fixes without making its presentation dependent on network availability.

Production boundaries

• Worker verification is an owner-reviewed MVP process, not an automated identity or background check.
• Payment is cash after service. Integrate a licensed provider before accepting card or wallet payments.
• Postgres Changes is appropriate for the MVP; migrate high-volume realtime traffic to private Broadcast channels as usage grows.
• Add rate limiting, transactional email, monitoring, backups, support tooling, and account deletion before a broad public launch.