boda

Imported from Qaphael/boda (AGENTS.md). Install upstream with npx skills add Qaphael/boda. Copyright stays with the author.

AGENTS.md — Boda Project

Read this entire file before writing any code. Every rule here comes from a real production bug. Violating them breaks the live app used by real people in Gulu, Uganda.

1. What Is Boda

Ride-hailing and parcel delivery platform for Gulu, Uganda. Customers book boda boda (motorcycle) riders for rides or deliveries. Payments via MTN/Airtel Mobile Money escrow.

Target users: Android phone users in Gulu. Budget devices, varying screen sizes, gesture and button navigation bars, inconsistent font scaling.

2. Architecture

Customer App (React Native/Expo)  ─┐
Rider App    (React Native/Expo)  ─┼── HTTPS + WebSocket ──→ Fastify API ──→ PostgreSQL (Docker)
Admin Dashboard (React/Vite)      ─┘                                   └──→ Redis (Docker)

3. Directory Structure

D:\code\
├── backend/src/           # Fastify API (server.js = entry, routes/ = handlers)
├── admin/src/             # React + Vite admin dashboard
├── customer-app/src/      # React Native customer app
├── rider-app/src/         # React Native rider app
├── deploy/                # Deploy scripts + SECURITY_AUDIT.md
└── docker-compose.yml     # PostgreSQL 15 + Redis 7

4. Tech Stack

5. Key Files

6. API Endpoints

Base URLs

• Production: https://boda.ocaya.space
• Local: http://localhost:3000
• Never use localhost in any mobile app code — always production URL.

Auth: POST /auth/send-otp /auth/verify-otp /auth/refresh /auth/logout

Riders: POST /riders/register · GET /riders/nearby · PATCH /riders/:id/location · /riders/:id/online · GET /riders/:id/profile · GET /riders/:id/earnings

Bookings: POST /bookings · GET /bookings/:id · GET /bookings/my/customer · GET /bookings/my/rider · PATCH /bookings/:id/accept · POST /bookings/:id/request-rider · PATCH /bookings/:id/start · PATCH /bookings/:id/complete · PATCH /bookings/:id/cancel · POST /bookings/:id/rate · POST /deliveries/:id/confirm

Profile: GET|PUT /profile/customer · GET|POST|PUT|DELETE /profile/saved-places · GET|POST|DELETE /profile/payment-methods · PATCH /profile/payment-methods/:id/default · GET /profile/referral · POST /profile/referral/apply · GET|POST|DELETE /profile/emergency-contacts · GET|PUT /profile/settings · GET /profile/notifications · PATCH /profile/notifications/:id/read · PATCH /profile/notifications/read-all

Admin: /admin/* (dashboard, riders, bookings, payments, support, settings, profile, notifications)

7. Database Tables

All user-generated data uses soft delete (is_deleted column). Filter it in every query.

8. UI & Layout Patterns

These are mandatory. Read the full pattern files before building any screen.

Non-negotiable UI rules

• @gorhom/bottom-sheet for all draggable sheets — not plain View with absolute positioning.
• BottomSheetTextInput for every input inside a sheet — never plain TextInput.
• keyboardBehavior="interactive" and android_keyboardInputMode="adjustResize" on every BottomSheet.
• useSafeAreaInsets() for all top/bottom positioning — never hardcoded pixel offsets like top: 56 or bottom: 230.
• expo-status-bar only — never StatusBar from react-native.
• Map screens: StatusBar translucent + absoluteFill WebView, overlays positioned with insets.top.
• softwareKeyboardLayoutMode: "resize" in app.json.
• Snap points as percentages — never pixels.
• Touch targets ≥ 44×44 with hitSlop where needed.
• maxFontSizeMultiplier set on all typography tokens in theme.js.
• Responsive sizing via wp(), hp(), scale(), rs() from src/utils/responsive.js — never hardcoded layout pixels.
• GestureHandlerRootView wraps the entire app root.
• SafeAreaProvider wraps inside GestureHandlerRootView.
• Every injectJavaScript call must end with ; true;
• Keep WebView source={{ html }} stable — use injectJavaScript for all dynamic updates. Never put changing state in the HTML source.
• map.invalidateSize() must be called whenever the sheet changes snap point.
• Separate ride and delivery flows — NewBookingScreen (rides only) → DeliveryDetailsScreen (deliveries only). Never mix them.

9. Critical Rules by Layer

9.1 Backend

9.2 Mobile Apps (React Native — applies to both customer-app and rider-app)

9.3 Admin Dashboard (React/Vite)

10. Common Commands

Backend deploy (from PC, PowerShell)

scp -i "$env:USERPROFILE\.ssh\id_rsa" <file> root@212.47.72.186:/root/boda/backend/src/<path>
ssh -i "$env:USERPROFILE\.ssh\id_rsa" root@212.47.72.186 "systemctl restart boda-api"

Admin deploy

cd D:\code\admin && cmd /c "npx vite build"
scp -i "$env:USERPROFILE\.ssh\id_rsa" -r "D:\code\admin\dist\*" root@212.47.72.186:/var/www/boda-admin/

Backend change workflow

1. Edit D:\code\backend\src\<file>
2. scp changed file to VPS
3. ssh → systemctl restart boda-api
4. Verify: curl https://boda.ocaya.space/health or Invoke-WebRequest -Uri "https://boda.ocaya.space/health"

Mobile — dev / build

# Dev
cd D:\code\customer-app; npx expo start

# Production build
$env:EXPO_TOKEN = (Get-Content "D:\code\expo-token.txt")
$env:EAS_NO_VCS = "1"
cd D:\code\customer-app; cmd /c eas.cmd build -p android --profile preview --non-interactive

Database access

ssh -i ~/.ssh/id_rsa root@212.47.72.186
docker exec -it boda-postgres psql -U boda -d boda

Run a migration

docker exec -i boda-postgres psql -U boda -d boda < /root/boda/backend/src/migrations/<file>.sql

Make a user admin

INSERT INTO admins (user_id, is_active) VALUES ('<user-uuid>', true);
-- User must log out and back in for JWT to pick up the admin role

Live logs

ssh -i ~/.ssh/id_rsa root@212.47.72.186 "journalctl -u boda-api -f"

OTP in dev mode

OTPs are logged to the server console (SMS not active in dev). Get them from live logs above.

Tests

cd D:\code\backend  && npm test          # Jest
cd D:\code\admin    && npm test          # Vitest
cd D:\code\rider-app && npm test         # Vitest
# customer-app: no test script — use npx expo start

11. Infrastructure

12. EAS / Expo Build

13. Known Environment Quirks

Node version mismatch: VPS runs Node.js 20. Local PC runs Node.js 24 (npm 11). If npm install fails with Invalid Version: caniuse-lite, regenerate package-lock.json on the VPS and copy it to PC.

Expo SDK 56: Removed the splash field from app.json. Run npx expo-doctor after any app.json change.

Phone numbers: All stored and validated as 256XXXXXXXXX (12 digits, Ugandan format).

Security audit: Completed June 2026. 17 vulnerabilities fixed. See deploy/SECURITY_AUDIT.md.