Awade
A parent opens their child's homework and freezes: a topic they last saw fifteen years ago, taught a different way. Awade began as a lesson-planning tool for teachers — until user discovery kept surfacing the same person doing unsupported teaching every night: the parent at the kitchen table.
An AI platform that gives African parents curriculum-matched guides to support their child's learning at home — repositioned from a teacher-facing lesson planner after discovery reshaped the product.
Problem
Parents want to help with homework, but curricula have moved on since they studied, and generic AI tools answer questions without matching what the child is actually being taught. The teacher-facing original solved resource creation — but the sharper unmet need sat at home, where parents do unsupported teaching every night with no tools built for them.
Solution
Curriculum-matched, step-by-step learning guides from a human-in-the-loop generation pipeline grounded in a structured curriculum database, so a parent can follow them without teaching experience. The generation core built for teachers carried over; the product around it was redesigned for the home.
Architecture
Comprehensive System Architecture: Hybrid Cloud Deployment with Async Processing & Multi-Model AI
Multi-Model AI Strategy
Engineered a flexible AI core with OpenAI and Google Gemini providers behind a single interface, selected by configuration with per-call model tiers. This monorepo package handles prompt caching, input sanitisation, content-safety checks, and response normalization to maintain curriculum alignment.
Async Processing Pipeline
Implemented a background worker system using Redis and Arq. This offloads heavy AI generation and document exporting (PDF/DOCX) to independent processes, ensuring 100ms API response times for users.
Hybrid Cloud Deployment
Architected a distributed system across Vercel (Frontend) and Railway (Backend/Workers/DB). This provides high availability and independent scalability for compute-heavy background tasks.
Administrative RBAC
Developed a multi-tenant Role-Based Access Control system. Admins have dedicated routers for moderation, audit logs, and system health monitoring, separated from user-facing workflows.
class AwadeGPTService:
def _make_api_call(self, prompt, config, temperature=None):
if not self.provider:
# mock keeps tests and local dev off the network
return self._generate_mock_response(prompt, ...)
cached = self._get_cached_response(
config["prompt_metadata"], config["model_tier"]
)
if cached:
return cached
return self._call_provider_with_cache(prompt, config, temp)Data Integrity & Migrations
Managed a normalized relational schema in PostgreSQL via SQLAlchemy. Complexity across Users, Plans, and Resources is governed by Alembic-driven migrations, ensuring safe updates to the production system.
Published security review
Identity, child data, and AI boundaries
I traced Awade’s security boundaries from the React client through FastAPI, PostgreSQL, Redis, and its OpenAI/Gemini provider layer. The review covers JWT and HttpOnly-cookie sessions, role and child-record ownership checks, token revocation, abuse controls, prompt-injection defences, structured model-output validation, and secure PDF generation.
Key Decisions
01Reposition from teachers to parents
ConsideredStaying the course with the teacher-facing lesson planner the product was originally specced as.
ChoseFollowing discovery to the sharper need: parents supporting homework at home. The generation core stayed; the packaging, tone, and workflows were rebuilt around the parent.
Trade-offTeacher-facing UX work set aside. The win: an audience with nightly demand and no procurement cycle — and proof the architecture never assumed its audience.
02Human-in-the-loop, not full automation
ConsideredA fully automated generator that hands finished answers straight to the child.
ChoseAI drafts the structured, curriculum-matched guide; the adult reviews and leads the session. Trust and judgment stay with the person who knows the child.
Trade-offAn extra step in every session. The win: adoption — families use a tool that keeps the parent in charge of the learning.
03A multi-model AI core instead of one provider
ConsideredBinding the platform to a single model API and keeping the integration simple.
ChoseA provider abstraction with OpenAI and Gemini implementations behind one interface, plus per-call model tiers, prompt caching, and a mock provider that keeps tests and local dev off the network.
Trade-offAn abstraction layer to maintain. The win: switching providers is configuration, not a rewrite — no single vendor owns the product.
04Background workers for everything heavy
ConsideredCalling the model and generating PDF/DOCX exports inline in the request path.
ChoseA Redis + Arq worker pipeline that offloads AI generation and document export to independent processes.
Trade-offJob-state plumbing and a second deployment surface. The win: 100ms API responses regardless of how long the model takes.
Technology
Outcome
Before
Parents guessing at homework help — or generic AI answers aligned to no curriculum.
After
A step-by-step, curriculum-matched guide a parent can follow, with the adult — not the AI — leading the child.
Repositioning from teachers to parents kept the entire generation core — provider abstraction, validation layers, RBAC — while opening a far larger, higher-frequency audience. The product changed audience without a rebuild because the architecture never assumed one.
Interested in the code?
View Repository