Documentation
Everything to integrate Sua Pa AI
Architecture, environment variables, public APIs and security for engineers, schools and partners.
Architecture
- Next.js App Router + React server components for the web experience, React Native (Expo) for mobile.
- PostgreSQL queried directly via the `pg` driver — no ORM. Every query lives in typed repository helpers under `src/db`. Row-level access is enforced in the data layer and mirrored by Supabase RLS policies in production.
- Multi-agent AI layer (`src/lib/ai.ts`) with mode-specific system prompts, RAG grounding and a deterministic offline fallback engine.
- Feature-based folders: `src/app` (routes), `src/components` (UI), `src/lib` (domain logic), `src/db` (schema & client).
Environment variables
- DATABASE_URL — PostgreSQL connection string.
- OPENAI_API_KEY / OPENAI_MODEL — enables live GPT tutoring; without it the local curriculum engine is used.
- WHATSAPP_VERIFY_TOKEN — WhatsApp Cloud API webhook verification.
- PAYSTACK_SECRET_KEY, HUBTEL_CLIENT_ID, STRIPE_SECRET_KEY — payment providers.
- CLOUDINARY_URL, FCM_SERVER_KEY — media storage and push notifications.
Public API
- POST /api/ai/chat — { question, mode, conversationId?, agentId?, useKnowledge? } tutor response with citations.
- POST /api/whatsapp — inbound WhatsApp message; GET performs the webhook handshake.
- POST /api/ussd — { sessionId, phone, text } { message, continueSession }.
- GET /api/health — liveness and database connectivity probe.
Security
- Scrypt password hashing, HTTP-only session cookies, and optional 2FA.
- Role-based access control across student, teacher, parent, school admin and super admin.
- Audit logging of authentication, AI usage, uploads and billing events.
- Encryption in transit and at rest, secure upload scanning, rate limiting and daily backups.
Roadmap
- AI voice tutors, live virtual classrooms and AI exam invigilation.
- Curriculum builder, teacher assistant agents and scholarship recommender.
- Career guidance, internship matching and an educational marketplace.
- Government dashboards and expanded African language support.
Ready when you are
Have a technical question?
Our engineering team is happy to help. Reach out and we'll respond within one business day.