Recivo

Skill verification and escrow payments for Nigeria's informal workforce.

Recivo lets skilled workers (phone repairers, tailors, mechanics, electricians, welders) prove their expertise through a voice-based AI diagnostic interview. Employers post jobs, an algorithm matches them to the highest-scored workers, and every payment runs through a Squad Virtual Account so funds clear on confirmation — not on trust.

Built for GTCO Squad Hackathon 3.0.

---

What's inside

recivo/
├── backend/          FastAPI + SQLModel API
│   ├── app/
│   │   ├── api/      REST + WebSocket endpoints
│   │   ├── models/   SQLModel table definitions
│   │   ├── schemas/  Pydantic request/response shapes
│   │   ├── services/ Squad, Claude AI, TTS, scoring, Redis pub-sub
│   │   └── worker/   Async background scoring loop
│   ├── main.py       Entrypoint (reads PORT from env)
│   └── requirements.txt
└── frontend/         Next.js 15 App Router
    └── src/
        ├── app/      Pages (/, /auth, /apply, /app, /hire, /offers, /scene, /docs)
        ├── components/
        └── lib/      API client, auth store, session hooks

---

Architecture

Worker → Voice diagnostic (WebSocket + Claude AI + TTS)
       → Iṣẹ́ Score computed (Knowledge × Trust weighted blend)
       → Matched to employer jobs by trade + score

Employer → Posts job → escrow VA created (Squad)
         → Browses candidates by Iṣẹ́ Score
         → Sends offer → worker negotiates via real-time chat (Redis pub-sub)
         → Funds escrow → worker accepts → work done → employer confirms
         → Squad releases payout to worker's VA
         → Worker withdraws to any Nigerian bank

Iṣẹ́ Score = α · Knowledge + (1 − α) · Trust where α = max(0.3, 1 − completed_jobs / 20) — diagnostic matters most early; real jobs take over as history builds.

---

Stack

Layer	Tech
API	FastAPI 0.136, Python 3.12
DB	PostgreSQL (Neon) via SQLModel + SQLAlchemy
Auth	Phone OTP (Twilio) + JWT
Payments	Squad (GTCO) Virtual Accounts + Transfer API
AI	Claude (Anthropic) for diagnostic scoring + NLP job parse
TTS	ElevenLabs + Spitch (African languages)
Real-time	Redis pub-sub for offer chat WebSockets
Frontend	Next.js 15, TypeScript, Tailwind CSS, Framer Motion
Deployment	Render (backend) + Vercel (frontend)

---

Local setup

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in your keys
python main.py         # http://localhost:8000

Swagger UI: http://localhost:8000/docs

Frontend

cd frontend
npm install
# set NEXT_PUBLIC_API_URL in .env.local
npm run dev            # http://localhost:3000

Environment variables

See backend/.env.example for the full list. Minimum to run locally:

DATABASE_URL=          # Neon PostgreSQL connection string
SECRET_KEY=            # random 32-byte hex
SQUAD_PUBLIC_KEY=      # from Squad dashboard
SQUAD_SECRET_KEY=
SQUAD_MERCHANT_ID=
REDIS_URL=             # Redis Cloud or local
ANTHROPIC_API_KEY=

---

Deployment

The backend deploys to Render via render.yaml at the repo root.

git push origin main   # Render picks up render.yaml automatically

Set all secrets in the Render dashboard under Environment. SECRET_KEY and ADMIN_SECRET_KEY are auto-generated by the Blueprint.

For the frontend, connect the /frontend directory to a Vercel project and set:

NEXT_PUBLIC_API_URL=https://your-render-service.onrender.com/api/v1

---

API

Interactive docs at /docs (Swagger) or /redoc on the running backend.

Method	Path	Description
POST	/auth/send-otp	Send OTP to phone
POST	/auth/register	Create worker or employer account
POST	/auth/login	Get JWT via OTP
GET	/workers/me	Authenticated worker profile + Iṣẹ́ Score
POST	/jobs/	Employer: post a job
GET	/jobs/{id}/matches	Workers ranked by Iṣẹ́ Score for a job
POST	/offers/	Send offer to worker
WS	/offers/ws	Real-time offer negotiation chat
WS	/diagnostic/ws	AI voice diagnostic session
POST	/workers/me/transfer	Worker cash-out to any Nigerian bank

---

Testing

cd backend
sh test.sh              # full API suite (requires jq + running server)
sh test.sh --speech     # speech/WS only