DEV Community

Cover image for How I Built a Free KCSE Course Checker for Kenyan Students Using React, Supabase and M-Pesa
gitau254-m
gitau254-m

Posted on

How I Built a Free KCSE Course Checker for Kenyan Students Using React, Supabase and M-Pesa

#kenya #webdev #react #supabase

How I Built a Free KCSE Course Checker for Kenyan Students Using React, Supabase and M-Pesa

Every year, thousands of Kenyan Form 4 leavers wait anxiously for KUCCPS placement — not knowing which university courses they actually qualify for. I built a tool to solve that.

Try it here: course-compass-guide.vercel.app

The Problem

After KCSE results are released, students struggle with two things:

  1. They don't know how to calculate their cluster scores — the scores KUCCPS uses to determine eligibility for specific courses
  2. Even if they know their grades, they have no easy way to see which of the 393 degree and diploma courses they qualify for

The official KUCCPS website shows cutoff points but doesn't help students check their own eligibility automatically.

What I Built

KCSE Course Checker — a web app where a student enters their KCSE subject grades and instantly sees:

  • Their calculated cluster scores for all 6 KUCCPS clusters
  • Every degree programme they qualify for (based on 2024 KUCCPS cutoff points)
  • Every diploma programme they qualify for
  • Courses filtered by their interest areas (Engineering, Medicine, Business, Law, etc.)
  • The official 2024 KUCCPS cutoff points PDF for verification

Tech Stack

Layer Technology
Frontend React 18 + TypeScript
Styling Tailwind CSS + shadcn/ui
Database Supabase (PostgreSQL)
Auth Supabase Google OAuth
Payments IntaSend M-Pesa STK Push
Serverless Supabase Edge Functions (Deno)
PWA vite-plugin-pwa
Hosting Vercel

The Cluster Score Formula

KUCCPS uses a cluster scoring system. Each university course belongs to one of 6 clusters, and each cluster uses specific KCSE subjects.

After studying the 2024 placement data, I calibrated this formula:

C = √((r/48) × (t/84)) × 48 × 0.957
Enter fullscreen mode Exit fullscreen mode

Where:

  • r = raw cluster subject score (max 48 points across 4 subjects)
  • t = KCSE aggregate score (max 84 points across 7 subjects)
  • 0.957 = calibration factor matched to actual 2024 KUCCPS placements

This produces cluster scores that match real 2024 KUCCPS placement data closely enough to give students accurate guidance.

The Payment Flow (Secure M-Pesa Integration)

One challenge was building a secure payment system. Here's how it works:

1. User enters phone number
2. Frontend calls intasend-stk Edge Function
3. Edge Function sends STK Push via IntaSend API
4. IntaSend prompts user's phone with M-Pesa PIN request
5. User enters PIN on their phone
6. IntaSend calls our mpesa-callback Edge Function (webhook)
7. Edge Function verifies transaction and updates payments table to 'confirmed'
8. Frontend polls the payments table every 3 seconds
9. When status = 'confirmed', results are unlocked
Enter fullscreen mode Exit fullscreen mode

The key security principle: the frontend never grants itself access. It only reads what the database says. The database is only updated by the server-side Edge Function after IntaSend's webhook confirms the payment. This means even if a user tried to skip the payment, they'd still be blocked.

Database Structure 

users              -- student profiles
user_results       -- KCSE subject grades
user_cluster_results -- calculated cluster scores  
payments           -- M-Pesa payment records
courses            -- 393 courses with cutoff points
degree_programme_cutoffs_exact_2024 -- 703 exact 2024 KUCCPS cutoffs
reviews            -- student reviews (admin approved)
Enter fullscreen mode Exit fullscreen mode

All tables have Row Level Security (RLS) enabled so users can only access their own data.

Key Features

Returning user flow — students who paid before can retrieve their results by name and phone number without paying again. Google OAuth users get this automatically.

Diploma-only mode — if a student's aggregate is below C+ (46/84 points), the app automatically switches to diploma-only mode, hides degree results, and shows an explanation.

Interest filtering — students can filter results by field of interest so they don't scroll through 291 degrees looking for relevant courses.

PWA — the app is installable on Android and iPhone without going through the Play Store or App Store.

What I Learned

1. IntaSend + Supabase Edge Functions work great together for M-Pesa

There's very little documentation on building M-Pesa integrations with modern JavaScript frameworks in Kenya. IntaSend abstracts the Safaricom Daraja API well and their STK Push is straightforward once you understand the webhook flow.

2. React SPAs need extra work for Google indexing

Since all the content is loaded via JavaScript, Google struggles to read it. I had to add structured data (JSON-LD), proper meta tags, a sitemap, and submit to Google Search Console manually.

3. Calibrating the cluster formula took the most time

I spent hours comparing my formula output against known 2024 KUCCPS placements to get the calibration factor right. The official formula isn't published anywhere publicly.

What's Next

  • Custom .co.ke domain when the app gets more users
  • Admin dashboard to view payments and user stats
  • Push notifications for KUCCPS placement results
  • More courses including TVET programmes

Try It

👉 Live app: course-compass-guide.vercel.app

👨‍💻 GitHub: github.com/gitau254-m/course-compass

If you know any Kenyan Form 4 leavers or their parents — please share this with them. And if you're a developer interested in Kenyan EdTech or M-Pesa integrations, feel free to explore the code.

Built by Wallace Gitau — Front-End Developer based in Kenya. Open to internships and freelance work.

Tags: kenya, react, supabase, mpesa, edtech, webdev, typescript, pwa

Top comments (0)