Shifting Left: How TDD Became the Foundation of SokoFlow's Core Engine

Kirera paul murithi — Tue, 30 Jun 2026 12:35:46 +0000

SokoFlow Build Log — Month 1 of 4

Last semester I set out on a new strategic plan to level up my software development skills through deliberate, project-based learning. That work produced one of the most ambitious things I've built so far: Sim-Pesa, a local-first transactional appliance that lets developers working in the M-Pesa ecosystem test and simulate STK Push workflows entirely on their own machines, without depending on the Daraja sandbox. I documented that build in 16 weekly posts, which you can find here.

This semester, the focus shifts — from fintech foundations to cloud-native integration and real-world systems. The flagship project is SokoFlow, a conversational ERP for small Kenyan shopkeepers to track inventory and record sales entirely through WhatsApp chat. No app to download, no training session required — just natural language.

Where Sim-Pesa lived in a controlled, predictable transactional world, SokoFlow steps into the mess of cloud-native reality: third-party API failures, webhook signature verification, the statelessness of HTTP, and container orchestration. The target audience shifts too — Kenyan SMEs operating on infrastructure that is often unreliable by design, not by exception.

It's an ambitious project, but the goal was always to learn as much as possible from it. With the plan in place, I got to work.

1. The Vision of a Headless ERP

The first real question I had to answer before writing a line of code: what does "headless" actually mean?

Headless architecture decouples the frontend — the "head," or user interface — from the backend, the "body" that holds the data and business logic. A conventional ERP bundles both: backend plus a dashboard or UI on top. A headless ERP, by contrast, is just the engine. The brain. There's no built-in screen.

So how do users interact with a system that has no interface of its own? SokoFlow doesn't actually care. It could be:

WhatsApp
SMS
A web app
A mobile app
A voice assistant

In this case, the "frontend" happens to be a WhatsApp conversation. Instead of clicking "Add Product," the shopkeeper just texts:

"Added 5 packets of milk"

And the backend processes that message the way an ERP would process a structured command.

In a sense, most modern systems are already headless-ish. Any architecture where the backend exposes an API and the frontend simply consumes JSON over HTTP is practically headless by default — if you've built something like that before, you were already doing this without naming it.

SokoFlow just makes the principle explicit. The backend is built on the assumption that it may never have a traditional UI:

Normal web app	SokoFlow
Backend exists mainly to serve a website or app	Backend is the product
Frontend is the product	WhatsApp is just one client talking to it

That framing matters because it means tomorrow I could plug in Telegram, SMS, a voice bot, a React dashboard, or USSD — without touching the core business logic.

Month 1's task wasn't the exciting part on the surface: four weeks spent entirely on core business logic, with no async layers and no WhatsApp integration in sight. That was deliberate. The core is everything — if it's wrong, the conversation engine built on top of it will be wrong too. That focus is also what pulled me into one of the most talked-about (and most misunderstood) practices in software engineering: Test-Driven Development.

2. The Power of TDD in Core Logic

TDD is a development style where you write a failing automated test first, write just enough code to make it pass, then refactor both the test and the implementation — and repeat for the next piece of behavior. This was my first real experience working this way, and it initially felt backwards. Most of us default to Design → Write Code → Write Tests. TDD inverts that order entirely.

Once it clicked, though, it was genuinely simple — the cycle is known as Red-Green-Refactor:

Red — write a failing test. Define exactly what a piece of code should do before it exists. Since only the test exists, it fails by definition.
Green — write just enough code. The minimum implementation required to make that test pass. Nothing more.
Refactor — clean it up. Revisit both the test and the implementation, tighten them up, and confirm the tests still pass.

That's the entire playbook, repeated feature by feature. After working in this loop for a few weeks, I came around to it completely — it forces you to think through edge cases and the shape of a request-response cycle before you write the implementation, not after.

With that approach set, here's how the four weeks broke down:

Week 1 — Project scaffold: PostgreSQL schema, Alembic migrations, FastAPI skeleton.
Week 2 — Product core: 20+ unit tests covering product CRUD operations (add, update, delete, and friends).
Week 3 — Inventory management: Inventory deduction logic tested against boundary cases.
Week 4 — Sales recording & daily aggregation: A sales service backed by report queries that return accurate totals against test data.

By the end of the month: 40+ tests, 92% coverage.

3. The Technical Hurdles

Everything moved smoothly on the surface, but the real lessons — as always — came from what went wrong along the way.

A Wall of New Tooling

This was my first extended stretch writing Python, which meant getting fluent in what I've started calling the "modern Python stack."

Type hints. In old-style Python, def greet(name): tells you nothing about what name actually is — a string, a list, a database object — until the code crashes at runtime. Adding type hints like name: str makes the expectation explicit, both for other developers and for tooling.

MyPy — the quality inspector. Python itself ignores type hints at runtime; they're purely documentation unless something enforces them. MyPy is a static analysis tool that reads code without executing it, catching type errors that would otherwise slip through and surface only in production.

Pydantic — the bouncer. FastAPI is built on Pydantic, a data validation library. If type hints are documentation, Pydantic is enforcement: it uses those same type hints to validate that data entering the application — from users, APIs, or the database — is exactly what it claims to be.

Fighting Async Testing and DB Drivers

Going all-in on TDD meant spending a lot of time inside the test suite, which meant the environment had to be low-friction enough to iterate quickly. The center of that effort was a single file: conftest.py.

Understanding conftest.py and fixtures. Before pytest's fixture system existed, test setup was a maintenance headache — every test file needed the same boilerplate (database connections, authenticated users, HTTP clients), duplicated across the suite. Any change meant updating dozens of files, and forgotten cleanup could quietly break unrelated tests. conftest.py exists to centralize that shared setup in one place. Pytest discovers it automatically and makes everything inside available to every test in the directory tree, with no explicit imports required.

A fixture is just a function that builds whatever a test needs, hands it over with yield, and guarantees cleanup afterward — even if the test fails. That lets each test focus purely on its assertions. Pytest also lets fixtures live at different scopes, from a fresh instance per test (function) to a single shared instance for the whole run (session); the goal is to use the broadest scope that still keeps tests properly isolated.

Moving from sync to async changed more than a few keywords. Swapping SQLite and standard SQLAlchemy sessions for asyncpg, AsyncSession, and async route handlers introduces an event loop — and every async resource is tied to the loop that created it. By default, pytest-asyncio spins up a fresh event loop per test, which can leave long-lived objects like the database engine bound to a loop that no longer exists. The fix was a session-scoped event_loop fixture so the entire suite shares one consistent loop.

That wasn't the only wrinkle. SQLAlchemy's default connection pooling — great in production — can leak state between tests and cause loop-ownership conflicts, so switching to NullPool ensures every connection is opened, used, and immediately discarded. FastAPI's synchronous TestClient also has to bridge sync and async code, which made loop issues more likely; switching to httpx.AsyncClient kept the tests, the client, and the application running on the same event loop, resulting in a far more reliable setup.

Time and Timezones

This trips up even experienced developers, and it caught up with me too — starting with not fully internalizing the difference between naive and aware datetimes.

A naive datetime — datetime(2026, 6, 25, 15, 0) — just says "3 PM." But 3 PM where? London? Nairobi? There's no way to know. An aware datetime — datetime(2026, 6, 25, 15, tzinfo=UTC) — says "3 PM UTC," which is complete information.

Picture two servers, one in Kenya and one in New York, both calling datetime.now(). The Kenya server returns 15:00; the New York server returns 08:00. Same moment, different values — which is exactly the kind of inconsistency that makes naive datetimes unsafe in production. The fix is datetime.now(UTC), so every server agrees on a single source of truth.

The sharpest version of this problem showed up in the daily report logic. To answer "what did this shop sell today," the database needs the start and end of that specific day — but in which timezone?

The shop operates in Kenya, on EAT (UTC+3) year-round. If an owner asks for the report for June 20, they mean everything between midnight and 11:59:59 PM on June 20, Kenya time. In UTC, those boundaries are:

Local (EAT)	UTC
Jun 20 00:00	Jun 19 21:00
Jun 21 00:00	Jun 20 21:00

So the correct query is created_at >= 2025-06-19T21:00:00Z AND created_at < 2025-06-20T21:00:00Z — notice that a single "June 20" local day actually spans two different UTC calendar dates.

My initial implementation got this wrong by treating the date naively:

UTC	Kenya (UTC+3)
Jun 20 00:00	Jun 20 03:00
Jun 21 00:00	Jun 21 03:00

That version was effectively collecting sales from 3 AM June 20 to 3 AM June 21 Kenya time, instead of midnight to midnight. The result: sales between midnight and 3 AM disappeared from the correct day's report, and late-night sales from the next day bled into it.

If a shop closes at 8 PM, this bug is invisible — almost nothing happens between midnight and 3 AM, so the totals come out right by coincidence. But the moment that assumption breaks — late opening hours, an online order at 1 AM, an overnight automated payment, an inventory sync that runs after midnight — the cracks show immediately: June 20's report comes up short, June 21's report has mysterious extra sales, and the daily totals stop matching the receipts.

The rule of thumb that came out of this: when a user requests a report for a calendar day, interpret that date in the shop's local timezone, compute the local start and end of that day, convert those instants to UTC, and only then query the database (which stores everything in UTC). The underlying principle is that dates are a local concept; timestamps are absolute instants — a "day" has to be defined in local time first, then translated to UTC for storage and querying.

4. Looking Ahead to Month 2: Docker, CI/CD, and Infrastructure Automation

With Month 1 behind me and the core business logic locked down under a solid test suite, Month 2 shifts focus from a local code project to production-ready, cloud-native infrastructure. Three things are top of mind for the next four weeks:

Production-grade containerization. Orchestrating SokoFlow's full topology with Docker — a multi-stage docker-compose.yml that cleanly networks the FastAPI gateway, PostgreSQL 15, Redis 7, and a split Celery worker pool (conversation_tasks and report_tasks).

Automated CI/CD quality gates. A strict GitHub Actions pipeline that runs the full test suite on every push and blocks pull requests if coverage drops below 85% or MyPy flags any strict type violations.

Environment-aware configuration. Hardening configuration management so that switching between development, staging, and production happens cleanly through environment variables, with no changes to application logic required.

5. Conclusion & Key Takeaway

Finishing Month 1 confirmed one thing for me: build the business core before letting any external infrastructure distract you.

Forcing myself into strict TDD from day one surfaced complex boundary cases early — inventory hitting exactly zero, low-stock threshold triggers — without the noise of webhooks, servers, or third-party APIs in the way. Fighting through async test fixtures and timezone mismatches wasn't fun in the moment, but resolving those foundational issues now means Month 2 starts on an airtight, predictable core that's actually ready to scale.

SokoFlow has its engine. Now it's time to build the container that runs it. Stay locked in for the next build log.

DEV Community: Kirera paul murithi