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

Source: Dev.to

Overview

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 free web app that lets students enter their KCSE grades and instantly see the courses they’re eligible for.

Live demo:
Source code:

Problem Statement

After KCSE results are released, students face two major hurdles:

1. Calculating cluster scores – the scores KUCCPS uses to determine eligibility for specific courses.
2. Finding eligible programmes – there are 393 degree and diploma courses, and the official KUCCPS site only lists cutoff points without an automatic eligibility checker.

Solution: KCSE Course Checker

A single‑page web app where a student:

• Enters their KCSE subject grades.
• Instantly sees calculated cluster scores for all six KUCCPS clusters.
• Views every degree and diploma programme they qualify for (based on the 2024 KUCCPS cutoff points).
• Can filter results by interest areas (Engineering, Medicine, Business, Law, etc.).
• Downloads the official 2024 KUCCPS cutoff PDF for verification.

Tech Stack

Cluster Scoring Formula

KUCCPS groups courses into six clusters, each using a specific set of KCSE subjects. After analysing the 2024 placement data, I derived the following calibrated formula:

C = \sqrt{\frac{r}{48} \times \frac{t}{84}} \times 48 \times 0.957

• 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 that aligns the computed scores with the actual 2024 KUCCPS placements.

The resulting cluster scores match the official data closely enough to give students reliable guidance.

Secure M‑Pesa Payment Flow

1. User enters their phone number.
2. Frontend calls the intasend-stk Edge Function.
3. The Edge Function triggers an STK Push via the IntaSend API.
4. IntaSend prompts the user’s phone for the M‑Pesa PIN.
5. User enters the PIN on their device.
6. IntaSend invokes the mpesa-callback Edge Function (webhook).
7. The webhook verifies the transaction and updates the payments table to confirmed.
8. Frontend polls the payments table every 3 seconds.
9. When status = 'confirmed', the results are unlocked.

Security principle: The frontend never writes data directly; it only reads what the database says. All updates are performed by server‑side Edge Functions after the webhook confirms the payment, preventing any attempt to bypass the payment step.

Database Schema (RLS‑protected)

• 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)

All tables have Row Level Security enabled so each user can only access their own data.

User Flows

Returning Users

Students who have paid before can retrieve their results by providing their name and phone number; 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 displays an explanatory message.

Interest Filtering

Students can filter results by field of interest, avoiding the need to scroll through hundreds of programmes.

Progressive Web App

The app is installable on Android and iOS devices without going through the Play Store or App Store.

Lessons Learned

1. IntaSend + Supabase Edge Functions – a smooth combination for M‑Pesa integrations, despite scarce documentation in Kenya.
2. SEO for React SPAs – required adding JSON‑LD structured data, proper meta tags, a sitemap, and manual submission to Google Search Console.
3. Calibrating the cluster formula – the most time‑consuming part; the official formula isn’t publicly disclosed, so extensive testing against 2024 placement data was necessary.

Future Enhancements

• Custom .co.ke domain for broader adoption.
• Admin dashboard for monitoring payments and user statistics.
• Push notifications for KUCCPS placement results.
• Inclusion of TVET programmes and additional courses.

Get Involved

• Live app:
• GitHub repository:

If you know any Kenyan Form 4 leavers or their parents, please share this tool with them. Developers interested in Kenyan EdTech or M‑Pesa integrations are welcome to explore the code.

Tags: kenya react supabase mpesa edtech webdev typescript pwa