A year ago my GitHub profile had 47 repositories. Some were experimental. Some were half-finished. Several were duplicates of ideas I'd explored twice without remembering the first attempt. A senior engineer looking at the profile would have seen volume and concluded scattered.
I restructured everything into five layers. Here's the architecture and the reasoning behind each decision.
The five layers
Layer 1 — Production platforms
These are the deployed applications. Live on Streamlit Cloud, accessible to real users with real problems. Twelve of them currently, each scoped to a specific question for a specific audience.
The constraint I imposed on myself: every platform must deliver a meaningful result in under 120 seconds. A drought coordinator should be able to arrive at Stahimili, enter a county name, and have a risk assessment in front of them before the next sentence of the meeting. An NGO finance officer should be able to open Hesabu and find the budget absorption figure they need for their report without training.
User-facing simplicity is an engineering constraint, not a design afterthought. The platforms look simple because significant complexity was pushed down into the layers below them.
Layer 2 — Service handlers
API integration logic lives here: the mpesa-mcp server, the Africa's Talking webhook handlers, the Daraja authentication flow. This layer knows how to talk to external services. The platforms above it don't need to.
The key decision: service handlers are versioned and tested independently. When Safaricom changed the Daraja base URL for sandbox environments, I changed it in one place and all twelve platforms that depend on payment functionality picked up the change automatically.
Layer 3 — SDKs
Clean Python wrappers around the external APIs. mpesa-python. The Africa's Talking wrapper. These are the packages I wish had existed when I started. They handle the non-obvious parts — phone number normalisation, timestamp-based password generation, delivery receipt parsing — so that the layers above them can think in business logic instead of protocol details.
Naming convention: simple, lowercase, domain-specific. mpesa-python not safaricom-daraja-api-wrapper-kenya. The name should tell you what it does in the time it takes to read it.
Layer 4 — Domain libraries
This is the most underrated layer. Domain libraries contain the knowledge specific to the problem space: Kenya's county boundary definitions, phone number format rules by carrier, administrative unit hierarchies, SASRA regulatory status codes.
kenya-counties is the clearest example: 47 counties, their codes, their sub-counties, their coordinates, their administrative relationships. Every platform in Layer 1 that needs to work with Kenyan geography imports from here. The data is authoritative, versioned, and tested. When Kenya National Bureau of Statistics updates constituency boundaries, the update happens in one package and propagates everywhere.
Layer 5 — Reference data
Static data that changes slowly and needs to be available everywhere: currency codes for African countries, GSMA network identifiers for 20+ carriers, IANA country codes with regional metadata. This layer rarely changes. When it does, the change is small and clearly bounded.
The governance layer
Every repository regardless of layer has the same baseline: CC BY-NC-ND 4.0 license, SECURITY.md with a single contact address, CONTRIBUTING.md that steers contributors to Issues rather than unsolicited PRs, a dependency manifest, and minimal CI (lint + test on push). This isn't bureaucracy — it's the difference between a portfolio that signals "I can build things" and one that signals "I can build things that other people can maintain."
What the restructure actually changed
The restructure didn't add a single line of business logic. Every platform did the same thing before and after. What changed was legibility — for collaborators, for institutional partners, and for myself.
The test counts got honest. The old profile had inflated numbers from passing trivially or from tests that tested the framework rather than the code. The current counts — 12 tests in daraja-mock, 19 in kenya-sms, 9 in pesa-cli — are lower and real.
The architecture became traceable. A new contributor can arrive at the GitHub profile, read the README, and understand in five minutes which layer to contribute to and why.
Coherence is an engineering deliverable. It takes deliberate work. It is worth doing.
Ecosystem source: github.com/gabrielmahia
Responses