DEV Community: Kirera paul murithi

The Gateway, the Registry and the Executor: Keeping Groq at the Edge of My Backend

Kirera paul murithi — Sun, 11 Oct 2026 10:29:51 +0000

SokoFlow AI Build Log, Week 2 of 6: the LLMClient, the ToolExecutor, and one component that almost became a god object

The Week 2 goal said "wire three tools end-to-end."

By the end of the week, all three tools executed against PostgreSQL and came back as structured results. I still wouldn't call it end-to-end, and the reason is the most useful thing I learned this week.

TL;DR

Week 2 built the provider boundary (LLMClient) and the execution boundary (ToolExecutor), then ran three tools through them: get_sales_summary, get_stock_level and get_top_products.

LLMClient is a translator and gateway. It keeps Groq's concepts at the edge so the rest of SokoFlow speaks SokoFlow's language. It does not know what a tool means.

I got two things wrong first: I let LLMClient become a "god" object, and I let ToolExecutor own domain logic. A simple "Milk" query showed me why that's wrong.

I verified the execution layer, not the full LLM round trip. I'm not going to claim a loop works when I only tested half of it.

Where we are

SokoFlow is a headless WhatsApp ERP for Kenyan SMEs. There's no app and no UI to learn; for a shopkeeper, the conversation is the interface. Phase 3 adds one AI feature: natural-language shop analytics. A shopkeeper asks "which products are running low?" or "how does this week compare to last week?", and an LLM, using function calling against SokoFlow's existing services, figures out which query to run.

Last week I designed seven read-only tools and benchmarked three models across two providers on the same 10 shopkeeper queries. Groq's openai/gpt-oss-20b won. But right now those tools sit in isolation, and on their own they aren't worth much. This week's goal was to connect at least three of them.

That takes three components: an LLMClient, a ToolRegistry and a ToolExecutor. Each has its own task and its own boundary. So why do we need all three?

The problem: provider coupling

The first thing I had to understand was the provider boundary. Last week I picked one provider for this phase, and my first instinct was the obvious one: call the Groq SDK directly wherever SokoFlow needs the model.

SokoFlow component
        ↓
    Groq SDK
        ↓
       Groq

I quickly saw the flaws in that design. The biggest was provider coupling: Groq's concepts would leak into the whole application. The second was cross-cutting duplication: logging, latency tracking, retries, error mapping and metrics would get scattered everywhere.

And switching providers isn't a hypothetical for me. Llama 3.3 70B on OpenRouter also scored 10/10 in last week's benchmark, so a swap is a realistic future decision.

LLMClient: one gateway to the provider

There had to be a better way, and that's where I learned the idea of an LLM client. What if there were exactly one gateway to the provider? The rest of the application talks to that client and doesn't care who's behind it.

SokoFlow
    │
    ▼
LLMClient
    │
    ▼
Provider SDK / API
    │
    ▼
Groq

The deeper purpose isn't just making providers replaceable. It's keeping provider-specific concerns at the edge of the system, so the rest of SokoFlow can reason in SokoFlow's own language. The LLMClient plays two roles:

Translator: SokoFlow input becomes a provider request, and the provider response becomes SokoFlow output.
Gateway: it's the one controlled point through which SokoFlow talks to the external LLM.

If Groq exposes response.choices[0].message.tool_calls..., nothing outside LLMClient should ever need to know that structure exists.

The "god object" I almost built

I was treating LLMClient as the silver bullet. It was the right answer, but I kept giving it more to do. At first I figured it would also handle tool semantics, tool existence checks, and the retry policy for semantically bad model responses. It was turning into a "god" object that knows far too much.

So I defined three contracts for the provider boundary.

Input contract. What SokoFlow sends to the LLM: the conversation messages, the available tool definitions, and the model configuration. The rule: SokoFlow expresses the request in a SokoFlow-owned representation, never a provider SDK request object. The client translates it into the provider's format.

Output contract. What SokoFlow actually needs back. The first time I saw a raw response, there was a lot in it (abbreviated here):

{
    "choices": [...],
    "usage": {...},
    "system_fingerprint": "...",
    "id": "...",
    "created": 123456,
    ...
}

Should the client hand back the entire Groq response object, or a small SokoFlow-owned result? Returning the whole object would recreate the exact coupling I was avoiding, with Groq details spread through the app. So the client normalizes the response into a small result with only what the application needs.

Error contract. Groq's SDK exposes its own exceptions, like groq.APIConnectionError and groq.APITimeoutError. If application code catches those, error handling is coupled to Groq too. Instead, provider-specific failures are translated at the LLMClient boundary into provider-agnostic application errors, wherever SokoFlow needs to react to them.

The responsibility split: who handles a bad tool call?

Should LLMClient validate tool names and arguments? To answer that, I ran a thought experiment. Suppose the provider returns:

tool = "delete_everything"
arguments = {"random invalid": true}

Who handles it? My answer: not the LLMClient. As far as the client is concerned, it got a response from the provider. No infrastructure or provider error happened, so it did its job as gateway and translator. It shouldn't know what get_sales_summary or delete_everything means, which periods are valid, or what the business rules are. So the design decision was to normalize the request and let downstream components deal with it.

(One more piece I'll keep mentioning: the Orchestrator. It will sit above these components, take the model's response, run the tool, and decide what happens next. It wasn't finished this week. More on that below.)

Why the ToolRegistry exists

Continuing the same thought experiment: the model asked for delete_everything. Who detects that no such tool exists?

From Week 1, the ToolRegistry is the single source of truth for every tool SokoFlow exposes and the backend handler behind each one. So if any component should detect a missing tool, it's the registry. Its job is to answer one question:

"What capabilities does SokoFlow expose to the model, and how does a proposed capability map into the backend?"

But that left a gap. We now know the tool exists. What about running it?

The ToolExecutor: the execution boundary

That's the third component. LLMClient talks to the provider, the registry confirms a supported tool was requested, and the ToolExecutor owns the execution boundary:

Are the arguments structurally valid?
Convert them into the typed input the handler expects.
Call the handler.
Normalize the outcome.

What I got wrong first: I started by designing the executor to handle all domain logic. Then I considered this:

get_stock_level(product_name="Milk")

Suppose "Milk" matches three products: Milk 500ml, Milk 1L and Milk 2L. The model supplied a perfectly valid string according to the schema. But the domain operation knows the product is ambiguous and needs clarification. A ToolExecutor containing product-resolution rules would be doing the domain's job.

So the split became clear: schema and contract validation belong to the executor. Business and domain validation stay with the existing domain services. This revises what I described last week, when I put domain validation in the same gate as schema validation.

The final failure taxonomy

With that boundary, there are three distinct failure scenarios:

Unknown tool, like tool_name = "delete_inventory". The registry lookup fails and the executor rejects it.
Structurally invalid arguments, like get_top_products(limit=10, dimension="profit"). Schema validation fails and the executor rejects it.
Structurally valid, domain-invalid request, like get_stock_level(product_name="Milk"). The schema says it's fine, but the backend can't uniquely resolve the product. That's not a schema failure. The executor validated the request and reached the handler, and the domain operation answers with AmbiguousProduct. The Orchestrator then decides whether to ask the shopkeeper to clarify.

The result envelope

One more decision. Once the executor finds the tool, validates the arguments and calls the handler, what does it return?

The raw handler result, a Pydantic model such as a revenue summary (for example, {"total_revenue": 4250, "transaction_count": 17}).
An executor-owned result that wraps the handler's output:

{
    "status": "success",
    "tool": "get_sales_summary",
    "data": {
        ...
    }
}

I chose the second. It separates execution metadata (did this run succeed?) from domain data (what the handler returned), so the Orchestrator doesn't need to understand every domain result just to know whether execution worked.

The key limit: the executor owns the envelope, but it must not reshape the domain data inside it. Otherwise it grows a universal "mega-schema" and gets coupled to every tool:

ToolExecutionResult
├── revenue
├── products
├── stock
├── transaction_count
├── ...

Instead, the envelope looks like this:

ToolExecutionResult
├── execution metadata
└── data → domain result

The first three tools

With the boundaries set, I wired three analytics tools through the deterministic backend path: get_sales_summary, get_stock_level and get_top_products. Each one executes through the existing ToolRegistry and ToolExecutor, reuses SokoFlow's services, reaches PostgreSQL, and returns a structured result. I covered the tools themselves in the Week 1 blog.

I didn't wire in the full WhatsApp conversation (the next section explains why). Instead I leaned on the principle that guided the MVP: tests. Each tool got multiple unit tests, and there's at least one integration test touching all the related components.

Tool	What the contract covers	Verified by
`get_sales_summary`	An explicit reporting period, backend-owned date calculations, shop-timezone-aware relative periods, half-open boundaries, valid zero-sales results, and `total_revenue` and `transaction_count` in the output	Unit tests (mocks and patches) for validation and execution; integration test reaching PostgreSQL through the existing repository; result wrapped in `ToolExecutionResult`
`get_stock_level`	Backend-owned product resolution; existing stock and product services; ambiguous matches handled by the domain	Unit tests; integration test reaching PostgreSQL; result wrapped in `ToolExecutionResult`
`get_top_products`	Units and revenue rankings, an optional ranking dimension, both rankings when none is given, and a limit applied to both. Structural validation rejects invalid dimensions like `profit` and invalid limits like zero before the handler runs	Unit tests; integration test reaching PostgreSQL; result wrapped in `ToolExecutionResult`

The part where I changed the plan

The Week 2 objective was to wire these three tools end-to-end outside the WhatsApp flow, using a standalone script or REPL harness that also measured p95 latency.

Partway through, I hit a distinction I hadn't thought about: testing tool execution is not the same as testing the complete LLM-to-tool interaction.

The three tools had registered handlers connected to the service and repository layers, with unit tests and PostgreSQL-backed integration tests. But exercising the full LLM-driven path is harder. A genuine flow needs the model's tool call to pass through the Orchestrator, which coordinates model responses, tool execution and what happens next. At this stage, the Orchestrator and its conversation-level integration weren't complete.

I considered making a real model call with temporary workarounds. But that would have meant writing a half-baked orchestration layer ahead of schedule, and it would have made it harder to tell a tool-execution bug from an orchestration bug.

So I made a deliberate scope decision. I kept Week 2 on the provider boundary, the registry, the executor and the three tool handlers. The standalone harness feeds normalized, model-shaped tool calls straight into the ToolExecutor, so I can test successful execution and failure cases without building the WhatsApp path early.

There's an important qualification. That harness verifies the backend execution path. It does not prove that a real LLM can pick a tool, have the Orchestrator run it, and get the result back in a full round trip with latency measured and recorded. That work moves to Week 3, where analytics connects to the conversation flow and gets verified through the WhatsApp simulator.

The lesson: an end-to-end test is only meaningful when its boundaries are clear. I didn't want to claim the whole function-calling loop worked when I'd only verified its execution layer. I'd rather move the unfinished integration to the week where it belongs than force it early and trust a result I can't interpret.

What I'd do differently

I wrote the goal "end-to-end" before checking what an end-to-end run actually depends on. It depends on the Orchestrator, and that didn't exist yet. Next time I would list the dependencies of an end-to-end goal before I commit to the word.

Where Week 2 landed

Here's how responsibility is divided now:

Component	Owns
LLMClient	Provider interaction and the normalized tool call
ToolRegistry	Exposed tools, schemas and handler mappings
ToolExecutor	Lookup, structural validation, safe invocation, and the execution result envelope
Domain Service	Business rules and the actual operation
Orchestrator	What happens next, including retries and recovery

And against the Week 2 target of three tools wired end-to-end from a harness, with p95 latency recorded:

Done: the provider boundary, the executor and three tools running through the execution layer, tested against PostgreSQL.
Carried to Week 3: a real LLM tool call going through the Orchestrator and executor in a full round trip, with p95 latency measured.

What's next

Week 3 is the fun part: the WhatsApp and conversation integration. That means adding a new ANALYTICS_QUERY intent to the existing resolver, so complex free-text messages are routed to the LLM. It also means handling session context, so a follow-up like "and yesterday?" can reuse what came before.

Stay locked in as SokoFlow slowly gains intelligence.

Check out the source code on Github.
Read more from the 4-Month MVP Blogs.

The LLM Interprets, the Backend Owns the Truth: Week 1 of Adding AI to a WhatsApp ERP

Kirera paul murithi — Mon, 05 Oct 2026 20:53:49 +0000

I Spent Week 1 of Adding AI to My ERP Deciding What the AI Is Not Allowed to Do

SokoFlow AI Build Log, Week 1 of 6: tool boundaries, a timezone detour, and a bug with two correct answers

Two correct answers. One question: "Compare this month with the previous period."

My code picked one of them, silently, and never told me it had a choice.

That bug is why Week 1 of adding AI to SokoFlow had almost nothing to do with AI.

TL;DR

Week 1 wasn't about wiring an LLM into SokoFlow. It was about deciding what the LLM gets to own, and what it doesn't.

The rule I locked in: the LLM interprets language, the backend owns the truth. The model picks a tool and proposes arguments. It never executes anything, never supplies shop_id, and never decides what "today" means.

"Previous period" has two valid meanings. My code was choosing one without telling me. Some bugs aren't implementation failures, they're failures to define what the thing means.

I treat LLM output like an untrusted client request: validate the shape, then the business rules, then allow one bounded retry for cheap model slips.

Provider: I benchmarked three models across Groq and OpenRouter and chose Groq's openai/gpt-oss-20b: 10/10 queries routed correctly, 1309 ms average latency, about $0.00005 per call.

Where SokoFlow was

Welcome to the new series. SokoFlow is a headless WhatsApp ERP and conversational commerce engine for Kenyan SMEs. There's no app to download and no UI to learn. For a shopkeeper, the conversation is the interface. The 16-week MVP is shipped, and I wrote about it along the way. You can read the series here.

The MVP is deterministic and rule-based on purpose, and that isn't changing. But it only understands specific commands that trigger specific flows. For an ERP aimed at small shops, that's enough. I've also always wanted to explore AI systems, and extending something I already understand felt like the best way to do it.

So Phase 3 adds exactly one AI feature: natural-language shop analytics. A shopkeeper asks "which products are running low?" or "how does this week compare to last week?", and an LLM, using function calling against SokoFlow's existing internal services, figures out which query to run.

The guardrails I set up front:

No vector DB, no RAG, no fine-tuning.
No new data store, no dashboard, no multi-shop analytics.
No writes through the LLM. "Record a sale" stays FSM-only.

Week 1 was the Tool Surface & Provider Decision: finalize 5–8 tool schemas, benchmark LLM providers on function-calling reliability, and decide fallback policy and guardrails. The goal was not to connect an LLM to SokoFlow. It was to understand where an LLM should fit without handing it responsibilities that belong to the backend.

The problem: two messages that look alike but aren't

Imagine a shopkeeper sends one of these.

Message B: sell 2 bread

The existing system handles this well:

Intent:   RECORD_SALE
Product:  bread
Quantity: 2

It's constrained. The intent resolver recognizes the pattern and the FSM walks the user through whatever's missing.

Message A: How much did I sell today?

There's no fixed conversational flow to enter. Something has to infer at least two things: what operation does the user want? (a sales summary) and what time period? (today).

Here's the key move. I'm not asking the LLM to answer the question. I'm asking it to interpret the question and pick an operation that can.

User's natural language
        ↓
"What does this person want?"
        ↓
"Sales summary for today"
        ↓
Which SokoFlow operation can provide that?
        ↓
get_sales_summary(...)
        ↓
Actual database/service logic

This is tool calling: instead of replying with prose, the model replies with a structured request, usually JSON, naming a tool and its arguments. It doesn't run anything. Your code does.

When the model outputs get_sales_summary(period="today"), that isn't an answer. It's a request to SokoFlow to perform an operation. The LLM sits at the interpretation boundary between messy human language and SokoFlow's structured world, and it never becomes the source of truth.

One difference from the textbook loop: in the generic version, the tool result goes back to the model so it can write the final reply. I'm deliberately not doing that. SokoFlow's ResponseFormatter turns the structured result into a reply using templates and i18n. My reasoning: a shopkeeper's revenue figure shouldn't pass through a text generator that might rephrase a number. Predictable beats eloquent.

The architecture barely changes:

WhatsApp → Webhook → FSM / Intent Resolver → ANALYTICS_QUERY
   → LLM → tool selection + structured arguments
   → validation / executor → existing SokoFlow services
   → PostgreSQL / Redis → structured result
   → Response Formatter → WhatsApp reply → Interaction Logger

The intent resolver flags free text as ANALYTICS_QUERY only when it doesn't match an existing structured intent. And every LLM decision gets logged before it executes, so failures can be diagnosed afterwards.

Hallucination, and why the boundary matters

An LLM isn't a database of answers. It learns statistical relationships, so it's good at recognizing that "How much did I sell…" lives near concepts like sales, amounts and time periods. That's why it can handle many phrasings of one question.

It's also why it can invent things. Suppose a shopkeeper asks "How much did I sell today?" and the model replies with get_monthly_profit. That tool doesn't exist (this is a made-up example), but the model would have invented a capability.

The model doesn't know how to operate SokoFlow. It only knows the operations we show it: names, descriptions, required arguments. So every rule below comes from one stance: the model's output is a suggestion, never an instruction.

The seven tools, and the decisions hiding inside them

I kept the surface small and read-only. Seven tools, each with a strict typed schema and bounded output.

Tool	The decision that mattered
`get_sales_summary`	`shop_id` is injected by the backend, never supplied by the LLM. Zero sales is a valid result, not an error.
`get_top_products`	Optional ranking dimension (units, revenue, or both when the question is broad). A `limit` defaults to 10 so WhatsApp doesn't get 500 rows.
`get_stock_level`	Users say "sugar", not `product_id=42`. A product-resolution step must turn names into trusted IDs.
`get_low_stock_items`	Defaults to each product's own `low_stock_threshold`. Explicit thresholds like "fewer than 3 units" don't exist yet in this phase.
`get_product_price`	Same name-to-ID problem as stock. Current price comes from `Product.price`, not the historical `Sale.unit_price` snapshot.
`get_slow_moving_items`	Products whose total units sold over the period are at or below `max_sales_count`, which defaults to 2 unless overridden.
`get_sales_trend`	The LLM interprets "this week vs last week"; the backend computes the exact boundaries. The metric (revenue, units, transaction count, or all) depends on the question.

Three of these decisions are worth explaining.

The LLM never supplies shop_id. For a shopkeeper in Nairobi, the worst-case bug is seeing someone else's sales numbers. Scope comes from the authenticated session, injected server-side. The model can't ask for another shop because the argument doesn't exist in its schema.

"Sugar" must become a trusted ID before any tool runs. I already had fuzzy matching with pg_trgm and candidate handling from the MVP, so I reused it. And the system doesn't guess: if several products match, or the best match scores low, it asks the shopkeeper to clarify. A missing product is a domain error, and I created a custom error for it.

The LLM interprets the meaning of "today", but it doesn't decide what date it is. That belongs to the application, using the shop's timezone.

Explicit over ambiguous: the schema that argued with itself

Consider "How much did I sell this week?" The LLM can tell the user means a weekly period. But should it calculate timestamps? I first sketched a schema like this:

relative_period: day | week | month | year
exact_start_date: string | optional
exact_end_date: string | optional

Now the schema allows contradictory input:

relative_period = "week"
start_date = "2026-09-01"
end_date = "2026-09-30"

Who wins? Nobody can say, because those fields aren't different parameters. They're two ways of expressing one concept: the requested reporting period. So the schema should force the model to answer one question first: am I expressing this period relatively, or as an explicit range?

period_type
├── relative
│   └── relative_period: day | week | month | year
│
└── date_range
    ├── start_date
    └── end_date

That gives each layer a clean job:

LLM: chooses the strategy and supplies the semantic values.
Schema validation: ensures the chosen strategy has the required fields.
Backend: derives actual boundaries using the shop timezone, calendar rules, ZoneInfo and half-open intervals.
Database: receives deterministic boundaries and just queries.

period_type is the discriminator, and the application enforces it with explicit checks:

if self.period_type == PeriodType.RELATIVE:
    if self.relative_period is None:
        raise ValueError("relative_period is required when period_type is 'relative'.")
    if self.date_range is not None:
        raise ValueError("date_range must be null when period_type is 'relative'.")
elif self.period_type == PeriodType.DATE_RANGE:
    if self.date_range is None:
        raise ValueError("date_range is required when period_type is 'date_range'.")
    if self.relative_period is not None:
        raise ValueError("relative_period must be null when period_type is 'date_range'.")

A small detour: what does "today" even mean?

Time keeps coming back in this project, and in backend work in general. "Show me today's sales" sounds trivial. But a backend doesn't live inside the user's wall clock. It deals with instants on a global timeline. Nairobi is UTC+3, so a sale rung up at 1 a.m. on the 5th is still the 4th in UTC. A shop owner closing late and a server clock can disagree about which day that sale belongs to.

So the shop's timezone defines "today". The backend converts the reference instant into that timezone, derives the calendar date, and turns relative periods into calendar boundaries, not durations. "This month" isn't "the last 30 days". It's:

[start of this month, start of next month)

That's a half-open interval: the start is included, the end isn't. It beats inventing an endpoint like 23:59:59.999999, because the next period's start is exactly this one's end, with no gaps and no overlap.

I used ZoneInfo, astimezone(), datetime.combine() and timedelta, but the APIs weren't the lesson. The lesson was the model: an instant, a timezone, a local calendar and boundaries are four different concepts. In SokoFlow, the week starts on Monday, and "today" is always evaluated in the shop's timezone.

The bug with two right answers

Back to the hook. A user asks: "Compare this month with the previous period." What does "previous period" mean?

I caught this while manually reviewing one of the reports. The previous month's range started on August 2 instead of August 1.

Here's how get_sales_trend worked when I found it. If the caller gives an explicit comparison period, the handler resolves it directly:

if input_data.comparison_period:
    prev_start, prev_end = resolve_period_boundaries(
        input_data.comparison_period
    )

If not, it derived one automatically:

else:
    prev_start, prev_end = resolve_previous_period_boundaries(
        input_data.period
    )

And that helper did it by subtracting the current period's length:

duration = curr_end - curr_start
prev_end = curr_start
prev_start = prev_end - duration

For September, that gives:

Current:   Sep 1 ──────── Oct 1   (30 days)
Previous:  Aug 2 ──────── Sep 1   (30 days)   ← equal duration

But a shopkeeper asking about "last month" means all of August:

Current:   Sep 1 ──────── Oct 1   (30 days)
Previous:  Aug 1 ──────── Sep 1   (31 days)   ← previous calendar period

Both are mathematically valid. Only the domain tells you which is correct. SokoFlow already thinks in calendar units (day, week, month, year), and months have different lengths (30, 31, 28 or 29 days), so "same number of days" isn't a reliable meaning of "equivalent period."

What I chose: by default, "previous period" means the previous equivalent calendar period. The duration-based version isn't wrong, it's a different question: "the last 30 days vs the 30 days before that." That should be asked for explicitly, not inherited by accident:

Previous calendar period → "previous month", "previous week"
Previous duration window → "the 30 days immediately before this 30-day window"

An explicitly provided comparison_period still resolves through resolve_period_boundaries(). I went with the calendar option and recorded the decision in an ADR (architecture decision record), so the meaning is written down instead of living in one helper function.

The lesson: some backend bugs aren't failures of implementation. They're failures to define what the implementation is supposed to mean. And it matters more with an LLM in front, because the model will happily translate a vague phrase into a vague argument.

Never trust the client, even when the client is an LLM

When the model produces a tool call, is that a request or a response? Both, depending on where you stand. In HTTP terms I sent the user's message and the model responded. In application terms it's a request that my backend executes. And how do we treat requests? We don't blindly trust them. That was my turning point.

The tempting shortcut is passing the model's arguments straight to the handler:

await tool.handler(shop_id, raw_args, db)

That's dangerous. The model can hallucinate arguments, add parameters that don't exist, or omit required ones, and any of those can crash application code. So the arguments go through a gate, in two stages:

LLM → raw_args → VALIDATION (Pydantic schema)
                    ├── ❌ invalid → stop
                    └── ✅ valid → handler

Stage 1, schema validation: does this data have the right shape and types? A missing required date, or a date that isn't a date, fails here.
Stage 2, domain validation: is it valid but nonsensical? A start date after the end date has the right types and still makes no business sense.

The JSON Schema the model sees is generated from the same Pydantic models that validate its output, so there's one definition instead of two that can drift apart. Unexpected extra arguments aren't silently stripped. They cause a validation error and the call is rejected.

The failure cases I designed for

Missing tool: the model emits a name like get_sales_summery. Caught at registry lookup. (An illustrative example, not one I've observed yet.)
Malformed or missing arguments: caught by stage 1.
Domain validation failure: caught by stage 2.
Product ambiguity: "How much is milk?" matches several products. We don't guess, we ask.
Infrastructure failure: the database or Redis is down. The shopkeeper did nothing wrong.

Who is at fault?

Not all errors are the same, and the awkward part is that a missing tool isn't the user's fault. Returning a generic "invalid request" would be bogus. The user's contract with SokoFlow is "I ask a question in natural language." The LLM's contract with my tool layer is "produce a valid tool call from the tools exposed." An invented tool name is a model failure, not a user failure.

That left two options:

Retry once with the LLM, with a constrained message: "Invalid tool name. Select one of the available tools."
Fail the AI operation with a generic fallback like "I couldn't process that request right now," with no raw model error, no stack trace, and no internals exposed.

I chose option 1. "How much did I make this week?" is a perfectly valid question, and failing it over a one-character generation slip punishes the shopkeeper for the model's typo. I worried this would balloon into a retry system. It doesn't need to:

attempt = 1
LLM → tool call
      ↓
ToolRegistry
      ↓
ToolNotFound
      ↓
if attempt == 1:
    retry once
else:
    fail + log

The principle I locked in: recover from cheap, model-local errors when recovery is deterministic and bounded. Don't build elaborate machinery for failures that belong to the application or infrastructure.

The registry: deliberately boring

The ToolRegistry is the single source of truth. It owns the schemas the model sees, the routing map from tool name to the code that implements it, and the validation definitions.

registry.register_tool(
    name="get_sales_summary",
    description=(
        "Calculates total revenue and transaction count for a shop over a requested "
        "reporting period."
    ),
    input_model=GetSalesSummaryInput,
    output_model=GetSalesSummaryOutput,
    handler=handle_get_sales_summary,
)

It doesn't run queries. A string like "get_sales_summary" maps to one handler, which calls the service method that does the work (here, SalesService.fetch_sales()). Anything not in the map doesn't exist as far as the executor is concerned.

The provider decision

I wanted to stay on free or cheap models, like with the MVP. My early runs were noisy (OpenRouter returned 404s), so I tightened the benchmark script: it runs the same 10 sample shopkeeper queries against each model and scores function-calling reliability, latency and cost.

Provider / model	Requests	Generated calls	2xx	Routed (tool + schema)	Avg latency	Avg cost / call	Statuses
Groq (`openai/gpt-oss-20b`)	10	10	10	100% (10/10)	1309 ms	$0.00005	200: 10
OpenRouter Free (`openrouter/free`)	10	8	10	20% (2/10)	4590 ms	$0.0000	200: 10
OpenRouter (`meta-llama/llama-3.3-70b-instruct`)	10	10	10	100% (10/10)	1905 ms	$0.00042	200: 10

A query only counted as correctly routed if the model picked the exact expected tool and its arguments passed my strict local Pydantic validation (schema and domain checks).

Decision: Groq with openai/gpt-oss-20b. It tied with Llama 3.3 70B at 10/10, so latency and cost broke the tie: 1309 ms vs 1905 ms, and about 8x cheaper per call. That clears the Week 1 bar of 8/10 correctly routed.

One honest caveat: 10 queries is a small sample, and the two top models tied. The real test comes in Week 5, with a 25–40 query eval set.

What I'd do differently

I found the "previous period" bug by eyeballing a report, not because something told me the definition was missing. Next time, the meaning of a business phrase gets written down before the first resolver is written, not after.

What's next

Week 1 was less about writing code and more about deciding what the AI layer should be responsible for. The architecture has a shape, the boundaries are clearer, and I have something concrete to build against.

Week 1 KPIs:

Finalized and froze the schemas for all 7 read-only tools (sales summary, top products, stock level, low stock, price, sales trend, slow moving).
Built a benchmark script with 10 real shopkeeper-style queries.
Benchmarked 3 models across 2 providers on function-calling accuracy, latency and cost per call. The chosen model routed 10/10 queries correctly (target: 8/10).

Next week the question changes from "what should this system look like?" to "can I actually make it work?" The plan is the core function-calling loop: LLMClient, ToolExecutor, and three tools (sales summary, stock level, top products) wired end-to-end from a manual harness, with p95 latency measured.

The LLM interprets language. The backend owns the truth. See you next week.

Shipping the Capstone: PDF Reports, Chaos Testing, and the Architecture of a System That Fails Gracefully

Kirera paul murithi — Tue, 22 Sep 2026 09:23:13 +0000

SokoFlow Build Log , Month 4 of 4

Sixteen weeks ago, I opened an empty directory, ran git init, and started building something I wasn't entirely sure I could finish.

This is the final build log for SokoFlow a conversational ERP for small Kenyan shopkeepers that lets them manage inventory and record sales entirely through WhatsApp chat. No app, no training, just natural language.

If you've been following along: Month 1 was the business core, built with TDD. Month 2 was infrastructure: Docker, CI/CD, and a live staging deployment. Month 3 was the conversational engine: FSMs, Redis sessions, fuzzy matching, and a secured webhook.

Month 4 was the capstone: async report delivery, a chaos testing suite, internationalization, and final integration. Everything built over the previous 12 weeks came down to these four weeks.

Goals for Month 4

Report PDF generated within 5 seconds and delivered as a document message via the mock sender.
The system handles all chaos scenarios without crashing or corrupting state.
A shop registered with locale='sw' receives Swahili responses.
Repository clone-to-running in under 5 minutes following the README.

Week 13 Async Report Delivery: ReportLab, PDF Bytes, and the report_tasks Queue

Two Worlds, One Translator

In Month 1, Week 4, I built the sales recording, aggregation, and report data generation. Month 4 built the final layer on top: turning that data into something a human can actually use.

Imagine a shopkeeper asking SokoFlow for an end-of-day summary. The system can calculate this:

Today's Sales:     KSh 45,000
Number of Sales:   37
Top Product:       Blue T-Shirt
Profit:            KSh 12,000

But data is not documentation. The shopkeeper might want to download it, print it, email it to their accountant, or archive it for the month. A Python dictionary serves none of those needs.

This is where a PDF comes in; and the PDF service's job is conceptually simple: translate between the computer's world and the human's world.

Computer World	Human World
`{"sales": 45000, "orders": 37, "profit": 12000}`	SOKOFLOW DAILY REPORT , Sales: KSh 45,000, Orders: 37, Profit: KSh 12,000

ReportLab

For PDF generation, the options range from manual word processors to print-to-PDF workarounds; both of which have no place in an automated pipeline. ReportLab is a Python library built precisely for this: generating complex, data-driven documents programmatically from any data source.

Since SokoFlow is already a Python system, the integration is natural. ReportLab lets us express document structure directly in code , no external processes, no format conversions, no third-party API round trips.

Where Does the PDF Live? A Three-Way Architecture Decision

Once ReportLab builds the PDF, there's an immediate question: where does the resulting data live while it waits to be sent to WhatsApp?

This is a real infrastructure decision. I evaluated three options:

Option A , In-memory (BytesIO)

The PDF exists purely as bytes in the Python process's memory. No files written to disk, no cleanup required.

Advantages: Simplest implementation. No Disk I/O. No orphaned temporary files.

Drawbacks: Memory is finite and volatile. Under concurrent load, large PDFs could create memory pressure. A worker crash before delivery means the PDF is gone permanently.

Option B , Temporary file on the server

Write a /tmp/daily-summary-[job-id].pdf file, send it, then delete it.

Advantages: Doesn't consume application memory for stored documents. More manageable for very large files.

Drawbacks: Disk I/O costs. Temporary files accumulate if a crash prevents cleanup. Multiple application instances don't share the same filesystem.

Option C , Object storage (e.g., S3)

Generate the PDF, upload it to a storage bucket, retrieve the URL for delivery.

Advantages: Durable, scalable, shared across all application instances. Enables report history and audit trails.

Drawbacks: Network round-trip latency. Storage costs. Additional infrastructure and credential management.

The choice: Option A , in-memory delivery for the MVP.

The spec's requirement is to generate a shop's daily summary (typically under 200KB) and immediately deliver it. That's a precise, time-bounded operation. Introducing S3 at this stage would add network latency, infrastructure cost, and credential complexity for a problem that in-memory delivery already solves cleanly. If report sizes grow or delivery patterns change, moving to Option C is a clear migration path , the PDFService abstraction makes that swap a localized change, not a systemic one.

Database → Aggregate data → ReportLab → BytesIO → WhatsApp API

Extending the MessageSender

Until Week 13, the MessageSender protocol only knew how to send text. Adding document delivery meant extending the protocol with a send_document method:

send_document(
    recipient,
    document_bytes,
    filename,
    caption
)

The sender constructs an HTTP multipart request, posts the raw PDF bytes to the WhatsApp API, receives a media ID in return, and attaches that ID to an outbound message. WhatsApp's infrastructure handles the rest.

The Async Pipeline: Why Report Generation Is Architecturally Different

Every other flow built in Month 3 , ADD_PRODUCT, RECORD_SALE, CHECK_STOCK , followed the same pattern: message arrives, FSM transitions through states across multiple turns, business logic executes at CONFIRM, session resets to IDLE.

The report flow broke that pattern in an important way: it's genuinely one-turn, but the task is heavy.

Sales aggregation, PDF generation, and document delivery are not operations that belong inside a synchronous Celery task serving the conversation_tasks queue. That queue is optimized for fast, lightweight FSM transitions. Tying it up with a potentially long-running report job would degrade response times for every other active conversation.

My first instinct was to handle this like any other flow , hook it into the handler map and route by state. But that doesn't work. A standard flow looks like:

Incoming message → FSM engine → dispatch by state → handler → transition → FSMResult

For the report, by the time the next message arrives, the job is already running in the background. There's no follow-up state to route to.

The design I landed on:

When the Intent Resolver detects Intent.GENERATE_REPORT in the IDLE handler, log the transient REPORT_PENDING state to session history for observability purposes.
Immediately delegate to GenerateReportFlow.handle_daily_report(...) , a dispatcher that does exactly one thing: enqueue the job into report_tasks and return.
Return an immediate acknowledgement to the user: "Your report is being generated and will arrive shortly."
The session resets to IDLE. The user can continue interacting.
The report_tasks worker picks up the job independently, generates the PDF, and delivers it asynchronously.

The REPORT_PENDING state is never used for routing. It exists purely as a breadcrumb in the session history , useful for debugging and observability, not for FSM logic.

The result: the conversation worker is never blocked, the user isn't waiting, and the report arrives when it's ready.

Week 14 , Chaos Testing: Proving That SokoFlow Fails Gracefully

"But I Already Have Tests. Why Do I Need a Chaos Runner?"

Going into Week 14, SokoFlow had over 100 tests spanning unit and integration suites. State transitions, invalid inputs, cancellation flows, normal paths , all covered. The question that genuinely confused me was: what gap is a chaos runner filling that those tests aren't?

The answer required stepping back and looking at what SokoFlow actually is.

It's a system where every message arrives through a stateless HTTP webhook, gets validated, deduplicated, pushed into Celery, processed by an FSM, persisted across Redis and PostgreSQL, and sometimes triggers asynchronous background work. The components are distributed. The state is shared across processes. The inputs come from an unreliable external network.

That changes the question from "does this piece of code behave correctly?" to something harder:

"Does SokoFlow remain correct when reality starts being annoying?"

The individual components can all be correct while the system as a whole can still behave badly when things happen in the wrong order, happen twice, fail halfway through, or disappear temporarily. That's the gap existing tests don't cover , and it's exactly the gap the chaos runner was designed for.

I implemented tools/chaos_runner.py as a dedicated script that runs against the actual local stack , not mocked functions, not isolated units. It injects specific failure scenarios and checks whether the system preserves its important invariants.

The Scenarios

DUPLICATE_MESSAGE

WhatsApp can deliver the same message more than once under normal network conditions. The chaos runner sends the exact same message_id twice and checks what doesn't happen afterward.

The duplicate must not create a second FSM transition, execute the business operation twice, or send another response. SokoFlow should acknowledge the second delivery and silently drop it. This tests the Redis deduplication layer end-to-end , not just the dedup function in isolation, but the entire path from webhook to worker to FSM to response gate.

DELAYED_DELIVERY

A message arrives after the user's session TTL has expired in Redis:

User:    "add product"
System:  "What's the product name?"
         ... session expires (Redis TTL) ...
User:    "Milk 500ml"

The dangerous failure mode here is the system resurrecting the old state and treating "Milk 500ml" as an ADD_PRODUCT_NAME response. Instead, an expired session should produce a clean IDLE initialisation: "Your previous session timed out. Let's start fresh."

This matters because Redis TTLs are silent. There's no expiry event, no callback, no notification , the key simply disappears. The system has to handle that disappearance gracefully on the next incoming message.

MALFORMED_JSON

Send intentionally broken JSON to the webhook. The important check isn't just that FastAPI returns 422 , it's that no Celery task is enqueued. Invalid input should die at the front door. Business logic should never see it.

This aligns directly with the architectural rule from Month 3: the webhook is responsible for validation and dispatch. The worker is responsible for business logic. Malformed input is the webhook's problem to reject, not the worker's problem to handle.

INVALID_HMAC

Take a valid request payload and tamper with the HMAC signature. The expected path is strict:

Tampered request → HMAC verification → 401 → no task → no FSM transition → no database work

A normal FSM unit test doesn't prove this. The FSM can be perfectly implemented while the security boundary is completely absent. The chaos runner validates both at once.

WORKER_CRASH

Inject an exception after the session has been written to Redis but before the outbound response is sent. When Celery retries the task, two invariants must hold: the FSM state must not roll backwards to its pre-transition position, and the retry must not execute the operation a second time.

This directly tests the CAS (compare-and-swap) architecture from Month 3's Week 9. The Lua script's expected_old_state check means a retry encountering an already-advanced state either continues safely or surfaces a StateMismatchError , never silently re-applies a transition.

CONCURRENT_MESSAGES

Submit five messages for the same phone number simultaneously. One phone number maps to one active FSM instance. If multiple Celery workers race to read and write the same session key without coordination, the conversation state becomes incoherent. The invariant being tested: exactly one valid state exists in Redis at the end of all five operations.

DATABASE_FAILURE

Pause PostgreSQL in the middle of a task. The worker should fail, retry with exponential backoff, and succeed once Postgres recovers , without leaving corrupted application state. Structured Celery retry configuration looks correct in code; the chaos runner verifies it works against the actual running database.

INVALID_FSM_LOOP

Send invalid input repeatedly while the FSM holds a state awaiting a specific input type , for example, feeding non-numeric strings to ADD_PRODUCT_PRICE. After three consecutive failures in the same state, the FSM should force-reset to IDLE and apologise. This scenario verifies that guard, end-to-end, with real messages through the full stack.

Without this, a shopkeeper who accidentally types the wrong thing three times in a row is trapped in an infinite re-prompt loop , one of the most frustrating experiences possible in a conversational interface.

REDIS_UNAVAILABILITY

Pause Redis while a conversation is active. Redis isn't just a cache in SokoFlow , it's session memory, Celery's message broker, and the deduplication store. Losing Redis means losing the FSM's ability to remember anything. The test verifies graceful degradation and correct recovery once Redis comes back online.

REPORT_TIMEOUT

Inject a timeout into document delivery during the async report path:

Report task → generate PDF → delivery fails → retry → idempotency check → safe continuation

The retry check isn't just "does it try again?" It's "does trying again produce a duplicate report?" Each mutating Celery task carries an idempotency key. The chaos runner validates both sides: that the retry fires correctly, and that idempotency prevents duplicate delivery.

The Results

❯ uv run -m tools.chaos_runner

SokoFlow Chaos Testing Suite v1.0
============================================================
Environment: local
Started: 2026-09-09T10:59:33.613254+00:00

Running scenario: DUPLICATE_MESSAGE (1/10)       PASSED (0.23s)
Running scenario: DELAYED_DELIVERY (2/10)        PASSED (3.03s)
Running scenario: MALFORMED_JSON (3/10)          PASSED (0.04s)
Running scenario: INVALID_HMAC (4/10)            PASSED (0.03s)
Running scenario: WORKER_CRASH (5/10)            PASSED (0.03s)
Running scenario: CONCURRENT_MESSAGES (6/10)     PASSED (1.12s)
Running scenario: DATABASE_FAILURE (7/10)        PASSED (8.34s)
Running scenario: INVALID_FSM_LOOP (8/10)        PASSED (0.67s)
Running scenario: REDIS_UNAVAILABILITY (9/10)    PASSED (12.44s)
Running scenario: REPORT_TIMEOUT (10/10)         PASSED (14.03s)

Summary: 10/10 passed | Duration: 40.0s | Coverage: 100.0%
Report saved: chaos_reports/chaos_2026-09-09T11-00-13.html

The Reframe That Changed Everything

My original question going into this week , "why do I need chaos testing when I already have unit tests?" , had the wrong premise. The better question was:

"What kinds of failures can my existing tests structurally not see?"

Unit tests answer: "does this piece of code behave correctly in isolation?"

Chaos tests answer: "does the system remain correct when a Celery task retries, Redis temporarily disappears, and another message arrives for the same phone number , all at the same time?"

Those are completely different questions. Both matter. Neither replaces the other.

Week 15 , Internationalization and Low-Stock Alerts

Internationalization (i18n)

The spec required that a shop registered with locale='sw' receives Swahili responses, while locale='en' receives English. Straightforward requirement. The interesting engineering challenge was figuring out where in the architecture this belongs.

Scoping the Problem First

Before touching any code, I had to decide: inbound Swahili parsing, or outbound Swahili responses only?

Inbound internationalization , understanding incoming Swahili messages like "uzia maziwa 3" , would require redesigning the entire Intent Resolver. That's a separate, significant project. It would also expand the intent-resolution problem rather than implement the i18n requirement.

The scope for Week 15 was outbound messages only: whatever the shop's locale, the FSM responses go out in the correct language. No changes to incoming message parsing.

Finding the Right Architectural Boundary

With scope defined, the next question: where does localization live?

The most obvious place was inside the FSM handlers themselves. Each handler already returns an FSMResult with a reply_text field. Why not just make that text language-aware?

The problem: hardcoding localized strings across 20+ FSM flows means that adding a new locale in the future requires editing every handler. More critically, it means the FSM is doing two jobs at once , determining state transitions and producing presentation text. Those are different responsibilities, and mixing them creates the coupling that makes systems brittle.

The right answer kept pointing to the same place: the edge. Specifically, the MessageSender , the one layer every outbound message passes through before it leaves the system.

This keeps the FSM entirely unaware of language. The FSM produces meaning. The localization layer translates meaning into the correct language. The MessageSender delivers it.

The FSMResult Refactor

This is where things got architecturally interesting. The existing FSMResult looked like:

FSMResult(
    previous_state=...,
    new_state=...,
    context=...,
    reply_text="Sale recorded successfully"   # ← English hardcoded in business logic
)

The problem: reply_text is a presentation decision baked into a domain object. The FSM is saying how to say something instead of what happened.

The refactored version:

FSMResult(
    previous_state=...,
    new_state=...,
    context=...,
    message_key=MessageKey.SALE_RECORDED,             # ← what happened
    message_params={                          # ← the data to render it with
        "product": "Milk 500ml",
        "quantity": 5,
        "remaining_stock": 12
    }
)

At the outbound boundary, message_key + message_params + shop.locale renders the final text:

en: "Sale of 5 Milk 500ml recorded. Remaining stock: 12 units."
sw: "Mauzo ya Milk 500ml 5 yamehifadhiwa. Stoke iliyobaki: vitengo 12."

This is the principle i18n exposed that was always latent in the design:

Application code should declare what happened. Not how to say it.

One key decision I was careful about: the localization logic lives in a dedicated localization.py service, not directly inside MessageSender. Transport responsibility and localization responsibility are different things, and conflating them would just move the coupling problem from one place to another.

What i18n Actually Taught Me

Features like internationalization are worth building not just for the user-facing value , they expose architectural boundaries that were previously invisible. The original FSMResult design wasn't wrong. It was correct and efficient for one language and fast iteration. But it had a hidden assumption: that presentation and domain logic were the same thing. i18n made that assumption impossible to ignore.

Low-Stock Alerts

The spec promised shop owners an alert when a product crosses its defined low-stock threshold. The interesting design question was deceptively simple: what exactly is the event that triggers the alert?

The naive approach , send an alert after every sale if stock is currently below threshold , sends multiple alerts for a product that stays low across several consecutive sales. If a threshold is 10 and stock goes 12 → 8 → 6 → 4, the naive approach fires three times. That's spam.

The correct approach is threshold crossing detection , the alert fires only when a sale transitions a product from above to below the threshold. Not when it's already below and goes lower.

old_is_low = inventory.quantity <= inventory.low_stock_threshold

# Deduct inventory for the sale

new_is_low = inventory.quantity <= inventory.low_stock_threshold

low_stock_triggered = (not old_is_low) and new_is_low

The logic:

Stock Before	Stock After	Result
Above threshold	Above threshold	❌ No alert
Above threshold	Below threshold	✅ Alert fires
Below threshold	Below threshold	❌ No alert (already alerted)
Below threshold	Above threshold	❌ No alert

Only the False → True transition fires the alert. It's detecting a state change event, not a condition being true. The alert enqueues as a Celery task into report_tasks, which handles delivery through the same localized MessageSender pipeline built for i18n.

Week 16 , Final Integration: GUI Simulator, Demo, and Shipping

The final week was deliberately narrow. The project was functionally complete. Week 16 was about integration, documentation, and one addition I hadn't anticipated: a visual demo interface.

The GUI Chat Simulator

For 15 weeks, I'd been testing conversations through a CLI REPL , a terminal process that mimicked a WhatsApp session. It worked perfectly for development. For a demo, it looked like a developer tool, not a product.

The decision: build a lightweight web-based chat simulator that looks like a WhatsApp conversation, wired to the actual SokoFlow backend. The constraints were strict , final week means shipping, not feature-adding. No new backend endpoints, no new dependencies.

The stack: pure HTML, CSS, and vanilla JavaScript. Python's built-in http.server to serve static files and handle API requests. No FastAPI changes.

How a message flows from the browser to SokoFlow and back:

Inbound (user → SokoFlow):

User types a message in the browser UI.
UI posts { phone, message } to the simulator's POST /api/send endpoint.
The simulator constructs a valid WhatsAppWebhook payload, signs it with HMAC-SHA256 (X-Hub-Signature-256), and forwards it to http://localhost:8000/webhook/whatsapp.
FastAPI validates the payload, verifies the signature, deduplicates via Redis, and dispatches to the appropriate Celery queue.

Outbound (SokoFlow → browser):

When the Celery worker completes processing, MockMessageSender.send_text() or send_document() POSTs the response to the simulator's receiver endpoint.
The simulator appends the message to an in-memory store keyed by phone number.
The browser polls GET /api/messages?phone=... every second and renders new messages as chat bubbles.

The backend never knew the difference. Every message went through the real webhook, the real HMAC verification, the real FSM, the real database. The simulator was a cosmetic wrapper around the same production-shaped infrastructure that Month 2 built.

The Demo

I recorded an 11-minute walkthrough using Loom covering the full system , adding products, recording sales, generating a PDF report, and demonstrating FSM edge cases including invalid input recovery and session cancellation. You can watch it here.

Docker and README

The Docker work was largely done in Month 2 , multi-stage builds, an optimised image under 200MB, and a docker-compose.yml orchestrating FastAPI, PostgreSQL 15, Redis 7, and the Celery worker pools. Week 16 ensured everything was documented clearly enough that a fresh clone reached a running system in under 5 minutes.

The Complete Journey: All Four Months

	Month 1	Month 2	Month 3	Month 4
Focus	Business core	Infrastructure	Conversational engine	Integration + polish
Environment	Local development	Containerized + cloud	Stateful conversations	Fully integrated
Testing	TDD, 40+ unit tests	CI pipeline, 85% gate	FSM unit + integration	100+ tests + chaos suite
Key technology	FastAPI, PostgreSQL, Alembic	Docker, GitHub Actions, Railway	Redis FSM, Lua CAS, pg_trgm, HMAC	ReportLab, i18n, chaos runner
State of system	Runs locally	Runs in the cloud	Holds a conversation	Deployed, tested, documented

Final Thoughts: What 16 Weeks Actually Taught Me

The Answer to the LLM Question

In Month 1, I said SokoFlow wouldn't use an LLM for intent parsing. In Month 3, I said the explanation would come in Month 4.

Here it is.

An LLM would have resolved "uzia maziwa 3" into RECORD_SALE, product=milk, qty=3 in milliseconds. It would have handled typos, ambiguity, and Swahili code-switching out of the box. It would have been faster to build.

The reason I didn't: SokoFlow deals with real inventory and real sales for real shop owners. When a system records that 5 units of milk were sold, that number needs to be reliable. An LLM's output is probabilistic , it produces the most likely answer, not a guaranteed one. Debugging a hallucination in production at a shop owner's expense is not an acceptable failure mode.

The FSM approach gives me something the LLM approach cannot: every decision is traceable. If a sale is recorded incorrectly, I can read the state transition log and find exactly where the interpretation went wrong. There's no probability distribution to interrogate, no temperature to tune. The system is deterministic by design, and for a system that moves inventory and revenue, that's not a constraint , it's a feature.

That said, "no LLMs" was a design choice for SokoFlow's MVP, not a position. The right tool depends on the problem. Which is exactly why Month 5 will add one carefully scoped AI-powered feature , and why that distinction matters.

The Bigger Lesson

Before this project, I knew the names of these tools. FastAPI, Celery, Redis, Docker, PostgreSQL , I could have listed them in a sentence. What I didn't have was any intuition for why a system is designed the way it is. Why the webhook is dumb and the worker is smart. Why naive datetimes are a silent landmine. Why localization belongs at the edge and not inside business logic. Why chaos testing asks different questions than unit testing.

Those aren't things you learn from documentation. They show up when you build something real and the wrong design creates a problem you have to solve.

What's Next

SokoFlow is complete as an MVP. But it doesn't end here.

For the next month, I'll be adding one AI-powered feature on top of the existing FSM foundation: natural-language shop analytics. A shopkeeper will be able to ask free-form questions like "which products are running low?" or "how does this week compare to last week?" , and an LLM, using function calling against SokoFlow's existing internal APIs, will resolve the question into a real query and a grounded answer.

No new data store. No separate product. The AI layer is additive , it works with the deterministic FSM, not instead of it.

That's the right way to introduce AI into a system: find a specific problem it solves better than rules-based logic, add it at the edge, and keep the core predictable.

Keep following for when that episode drops.

SokoFlow is open source. The full codebase, architecture diagrams, and documentation are available on GitHub.

Teaching SokoFlow to Remember: Building a Conversational Engine with FSMs, Redis, and WhatsApp Webhooks

Kirera paul murithi — Sun, 23 Aug 2026 09:20:52 +0000

SokoFlow Build Log — Month 3 of 4

Welcome back. If you're new here — I'm an IT student running a structured, project-based learning plan toward becoming a production-grade backend engineer. Last semester I built SimPesa, a local-first M-Pesa STK Push simulator. This semester, the theme is from controlled environments to the messy real world.

SokoFlow is my flagship project: a conversational ERP for small Kenyan shopkeepers that lets them track inventory and record sales entirely through WhatsApp chat — no app, no training, just natural language.

Month 1 was the business core, built with strict TDD. Month 2 was infrastructure — Docker, CI/CD, and a live staging deployment on Railway. If you haven't read those, I covered them in the previous build logs.

Month 3 was the part I'd been building toward since the beginning: the Conversation Engine.

At the end of the Month 1 blog, I left off with a question:

How do you turn messy human language into deterministic system actions without the whole thing becoming cursed spaghetti?

The answer I committed to: Finite State Machines (FSMs) + controlled intent parsing + conversational context.

And then you might be wondering — why not just throw an LLM at this? That answer is coming. Keep reading.

Goals for Month 3

The acceptance criteria going into this month were specific and measurable:

Session survives a worker restart. An expired session resets to IDLE correctly.
Full add-product flow completes via chat simulator in fewer than 5 messages.
A sale is recorded correctly for an ambiguous product name (e.g., "milk" → "Milk 500ml").
Simulator payload accepted. Invalid signature returns 401. Duplicate dropped silently.

Prerequisites: Two Mini-Projects Before the Real Work

Before starting any FSM implementation, there were two self-contained tools I had to build first. These weren't part of the weekly milestones — they were infrastructure the rest of the month depended on. Both were interesting enough that I'll dedicate a separate post to each. For now, here's the short version.

1. Chat Simulator

Relying on a real WhatsApp API during local development would have been painful. So I built a CLI tool that mimics a WhatsApp conversation directly from the terminal.

After exploring a few options, I settled on an interactive REPL with a local webhook server:

The CLI step turns the simulator into a long-running process and spins up a lightweight background HTTP server using Python's built-in http.server.
The worker step: when Celery finishes processing a state transition, it fires a standard HTTP POST request back to that background server.
The loop closes: the running CLI thread captures the inbound payload and prints it to the terminal instantly.

The result is a single terminal screen that behaves exactly like an active WhatsApp conversation — without needing a phone, a verified business account, or any real API calls.

2. Intent Resolver

When a user's message hits the system, it's raw natural language. "sold milk", "check stock", "Hi" — the system needs to decide what the user wants before deciding what to do.

The Intent Resolver sits in front of the FSM and classifies incoming text into a discrete intent the system can act on. Think of it as a receptionist at a building entrance. The receptionist doesn't solve your problem — they just say "You're here for Finance" or "You're here for HR" and point you to the right floor.

The resolver maps something like "Sale" into Intent.RECORD_SALE. The FSM takes it from there.

Crucially, the Intent Resolver is only active when the FSM is in the IDLE state. Once a user is inside a flow like:

ADD_PRODUCT_NAME → ADD_PRODUCT_PRICE → ADD_PRODUCT_QTY

...the current state provides all the context needed. There's no ambiguity to resolve.

Week 9 — Redis Session Layer: FSM State Serialization, TTL Handling, and Dedup Keys

The Core Problem: HTTP Has No Memory

The key mental model to start with: HTTP is stateless by design. If a user sends a message to SokoFlow, the system processes it and responds. When the next message arrives seconds later, the system has no idea who this person is or what they were doing.

For a back-and-forth conversation to work, the system needs persistent memory between requests. That points to a database — but not just any database. It needs to be fast and lightweight. Everything pointed to Redis, an in-memory data store already in SokoFlow's stack as the Celery broker. No new dependencies, just a Redis client and a clear schema.

The Session Schema: Pydantic vs. Dataclasses

The first implementation decision was how to model the session structure. In Python, this immediately surfaces the Pydantic vs. dataclasses debate. They look similar on the surface — both package typed fields — but they serve fundamentally different purposes.

Dataclasses are for clean internal data structures. Pydantic is for enforcing schema integrity across untrusted boundaries.

Redis stores raw strings. Celery workers read raw messages off a queue. These are untrusted boundaries. Pydantic wins here for four concrete reasons:

Reason	Detail
Automatic type coercion	Converts raw string timestamps from Redis directly into `datetime` objects — no manual parsing
Nested deserialization	Rebuilds complex nested JSON into deep Python objects automatically
Runtime validation	Guarantees Celery workers never process corrupted or malformed session state — raises `ValidationError` before business logic touches bad data
Native JSON compatibility	Serializes complex Python types directly into JSON strings Redis can store

Handling Edge Cases from the Start

Before writing the first handler, I defined how the system behaves when things go sideways. These aren't afterthoughts — they're first-class design decisions.

User Interruptions. If a user sends cancel or menu from any non-IDLE state, the FSM transitions unconditionally to IDLE, clears the working context, and confirms cancellation. This override works from any state, no exceptions.

Session Expiry. When a session's TTL expires in Redis, the next message from that phone number finds nothing. The FSM initialises fresh from IDLE with: "Your previous session timed out. Let's start fresh." Partial operations are never committed to PostgreSQL until the CONFIRM state is explicitly reached.

Invalid Inputs. Each state defines its own acceptance criteria. If a user enters a non-numeric value when a price is expected, the FSM holds the current state and re-prompts with a helpful message, incrementing an error counter. After 3 consecutive invalid inputs in the same state, the FSM transitions to IDLE with an apology — preventing infinite loops.

Duplicate Messages. WhatsApp can deliver the same message multiple times under poor network conditions. Each incoming message is checked against a Redis set of recently processed message IDs (TTL: 60 seconds). If the message_id already exists in the set, the request is acknowledged with 200 OK and silently dropped:

redis.set(f"dedup:{message_id}", "1", nx=True, ex=ttl)

The NX flag makes this atomic — the key is set only if it doesn't already exist, which is exactly the check we need.

The ConversationStore: Abstracting Redis Away

The ConversationStore is the Data Access Object (DAO) for session management. Its job is to completely hide Redis implementation details from the rest of the application. The FSM engine and Celery tasks don't care how sessions are saved — they just call the store.

Method	Responsibility
`get_session(phone)`	Fetches raw string from Redis, parses JSON into a Pydantic model, returns `None` on cache miss
`save_session(...)`	Updates session state using atomic compare-and-swap to prevent race conditions
`delete_session(phone)`	Removes the key explicitly when a user completes a flow or cancels

The save_session method is where things get interesting — and where the most important architectural decision of the week lives.

The Race Condition Problem: Why `save_session` Needed Special Treatment

Anywhere a system reads state, modifies it in memory, and writes it back is dangerous. The pattern looks innocent:

Read state → modify in memory → write state back

But the state you read may no longer be the state that exists when you write. The classic failure mode is a lost update: two workers read the same state simultaneously, both modify it independently, and the second write overwrites the first — producing a state that was never a valid transition.

Imagine two requests arriving near-simultaneously from the same phone number:

Worker A reads state: IDLE
Worker B reads state: IDLE
Worker A transitions to ADD_PRODUCT_NAME in memory
Worker B transitions to ADD_PRODUCT_NAME in memory
Worker A writes ADD_PRODUCT_NAME → correct
Worker B writes ADD_PRODUCT_NAME → overwrites A's work

According to the FSM, the next valid state was ADD_PRODUCT_PRICE, not a second ADD_PRODUCT_NAME. The conversation is now corrupt.

The Solution: Redis Lua Scripting (Optimistic CAS)

I had two genuine options:

Option 1 — Optimistic CAS via Lua Script: At write time, atomically verify that the state in Redis still matches what the worker expected. If another worker has already advanced the state, the write fails and the error is handled explicitly.

Option 2 — Pessimistic Distributed Locking: Acquire a Redis lock on the user's phone number at the beginning of task processing, preventing any concurrent access.

I chose Option 1. Here's why Option 2 was the wrong pick for this architecture:

SokoFlow is built on the principle of a dumb webhook receiver and a smart async worker pool (Principle 4 in the Developer Manifesto: "Failure Is a First-Class Input"). Pessimistic locking introduces a hard coordination problem between the lock TTL, the Celery task timeout, and the 30-minute Redis session TTL. If a worker crashes while holding a lock, that user's entire chat session is frozen until the lock expires — a terrible experience for an SME user who's in the middle of recording a sale.

Optimistic CAS aligns with the architecture naturally. Concurrent messages from the same phone number are rare (the deduplication layer already handles retransmissions). When a CAS failure does occur, the recovery path is explicit: fetch the new state, log the conflict with a correlation_id, and re-prompt the user — no blocked threads, no frozen sessions.

The implementation uses a Lua script registered at startup that executes atomically inside Redis:

save_session(phone, expected_old_state, new_payload, ttl=1800) → bool

The Lua script receives three arguments: the expected old state, the new serialized session JSON, and the TTL. It compares the current state in Redis against the expected state before writing. The return codes map directly to typed domain exceptions:

1 → Success
0 → StateMismatchError (stale state — another worker advanced it first)
-1 → CorruptedSessionError (invalid JSON in Redis)

Week 10 — FSM Core: The ADD_PRODUCT Flow End-to-End

With the session layer solid, Week 10 was about wiring up the actual state machine.

The Architectural Strategy: State Pattern over if-else Chains

The naive approach to routing a message to its handler looks like this:

if state == IDLE:
    ...
elif state == ADD_PRODUCT_NAME:
    ...
elif state == ADD_PRODUCT_PRICE:
    ...

This works until the FSM has 20 states. Then process_message() becomes a 300-line method that knows everything. Adding, removing, or renaming a state means surgically editing one giant block.

The better approach is a dispatch table — a dictionary that maps each state directly to its handler function:

handlers = {
    IDLE: handle_idle,
    ADD_PRODUCT_NAME: handle_product_name,
    ADD_PRODUCT_PRICE: handle_product_price,
    ADD_PRODUCT_QTY: handle_product_qty,
    CONFIRM_ADD_PRODUCT: handle_confirm_add_product,
}

handler = handlers.get(state)
if handler:
    return handler(message)

The engine now answers exactly one question: which handler belongs to this state? Adding a new state means adding one line to the map and writing the handler independently. Each handler can evolve, be tested, and be reasoned about in complete isolation.

The dispatch table keeps the engine generic and the state-specific logic where it belongs: in the handler.

Every message turn through the engine follows a strict pipeline:

Pre-processing (Universal Guards): Check for global commands — cancel, menu, exit, stop.
State Evaluation: Look up the current SessionState in the dispatch table.
Input Validation: Validate the message according to that state's rules.
State Transition & Context Mutation: On valid input, update UserSession.context and advance UserSession.state.
Error Counter Management: On invalid input, increment context.error_count. At 3 consecutive failures, force reset to IDLE.
Atomic Persistence: Save the updated session back to Redis via ConversationStore.save_session().

The ADD_PRODUCT State Blueprint

Current State	Input Accepted	Target State	System Response
`IDLE`	Intent trigger (`"add product"`, `"add"`, `"new product"`)	`ADD_PRODUCT_NAME`	"What is the product name? (e.g., Milk 500ml)"
`ADD_PRODUCT_NAME`	Non-empty string (2–100 chars)	`ADD_PRODUCT_PRICE`	Stores name. "What is the selling price in KES?"
`ADD_PRODUCT_PRICE`	Positive float/decimal (> 0)	`ADD_PRODUCT_QTY`	Stores price. "How many units in stock?"
`ADD_PRODUCT_QTY`	Positive integer (≥ 0)	`CONFIRM_ADD`	Stores qty. "Confirm add: {name} at KES {price}, {qty} units? (yes/no)"
`CONFIRM_ADD`	`"yes"` / `"y"`	`IDLE`	Commits product to Postgres, clears context, returns success
`CONFIRM_ADD`	`"no"` / `"n"`	`ADD_PRODUCT_NAME`	Clears context, restarts from name prompt
`ANY NON-IDLE`	`"cancel"` / `"menu"`	`IDLE`	Resets state, clears context, confirms cancellation
`ANY NON-IDLE`	3 consecutive invalid inputs	`IDLE`	Resets state, apologises, sends guidance message

Input Validators: Handling the Messy Reality of Kenyan SME Text

Before wiring up the engine, I wrote pure, stateless helper functions to clean up the real-world text a shopkeeper would type:

parse_product_name(raw_text) — trims whitespace, validates 2–100 character length.
parse_price(raw_text) — handles Kenyan currency formats like "KES 150", "150/=", and plain "150". Parses to Decimal and validates greater than zero.
parse_quantity(raw_text) — parses positive integers, validates ≥ 0.
parse_confirmation(raw_text) — accepts positive triggers ("yes", "y", "ndio", "1") and negative triggers ("no", "n", "zii", "2").

These are the entry points to every state transition. They raise typed InvalidInputError with user-facing messages, so the FSM engine never has to write error messages itself — the validators do it.

A 5-Message Execution Flow, End-to-End

User:  "add product"
FSM:   IDLE → ADD_PRODUCT_NAME       | "Great, let's add a product. What is the product name?"

User:  "Uji Flour 2kg"
FSM:   ADD_PRODUCT_NAME → ADD_PRODUCT_PRICE  | "Nice. What is the price in KES?"

User:  "150/="
FSM:   ADD_PRODUCT_PRICE → ADD_PRODUCT_QTY  | "Got it. How many units are in stock?"

User:  "20"
FSM:   ADD_PRODUCT_QTY → CONFIRM_ADD | "Confirm: Uji Flour 2kg at KES 150.00, 20 units. Reply yes or no."

User:  "yes"
FSM:   CONFIRM_ADD → IDLE            | "Product added: Uji Flour 2kg at KES 150.00, opening qty 20."

The Biggest Lesson of Week 10: Process Separation and Database Sessions

After completing the flow, I ran into a design question that tripped me up. When a user confirms a product, the data needs to move from Redis into PostgreSQL permanently. But here's the problem: Celery workers and the FastAPI web app are completely separate operating system processes — often separate Docker containers in production. They cannot share memory, engines, or connection pools.

In the FastAPI app, database sessions are managed through dependency injection — Depends(get_db) yields a request-scoped session tied to the HTTP request lifecycle. Celery tasks are triggered by messages off the Redis queue, not HTTP requests. You can't use Depends(get_db) inside a worker.

The solution was a dedicated async context manager for background tasks:

async_session_factory = async_sessionmaker(
    bind=engine,
    expire_on_commit=False,
    class_=AsyncSession
)

@asynccontextmanager
async def get_worker_db() -> AsyncGenerator[AsyncSession, None]:
    async with async_session_factory() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

Inside any Celery task, wrapping execution in async with get_worker_db() as db: gives a task-scoped transactional session. This wins on three fronts:

No idle DB locks: State transitions that don't persist (like NAME → PRICE) open and close the session instantly.
Atomic commits: The context manager automatically commits on clean exit, making product creation atomic at the CONFIRM_ADD step.
Automatic rollback: If PostgreSQL raises a constraint error or connection error mid-task, the rollback is guaranteed — no corrupted state.

Week 11 — RECORD_SALE and CHECK_STOCK Flows: Fuzzy Product Name Matching

With ADD_PRODUCT working end-to-end, Week 11 expanded the FSM to cover the two flows shopkeepers would use daily: recording a sale and checking stock.

The wrinkle that made this interesting: users don't type exact product names. They type "milk", "mllk", "Fresh Milk". The system needs to figure out what they actually meant.

What is Fuzzy Matching?

Fuzzy matching is a technique for finding strings that are approximately equal rather than exactly equal. A standard database index treats a one-letter typo as a completely different word. Fuzzy matching provides a mathematical way to say: "These two strings aren't identical, but they're a 90% match."

It's the same technology behind Google's "Did you mean...?" feature and autocorrect.

The Core Metric: Levenshtein Distance

The most common distance measure is Levenshtein Distance — the minimum number of single-character operations (insertion, deletion, substitution) needed to transform one word into another.

cat → cats: distance 1 (one insertion)
bread → bred: distance 1 (one deletion)
bred → brad: distance 1 (one substitution)

Lower distance = closer match.

The Performance Problem

Calculating Levenshtein distance against a full product table is expensive. On a table with 1,000 products, a naive query calculates the distance for every single row. A standard B-Tree index can't help here — it only understands exact alphabetical ordering. At scale, this would spike the database CPU immediately.

The Solution: PostgreSQL pg_trgm and GIN Indexes

Rather than introducing a separate fuzzy search library, I used what was already in the stack: PostgreSQL's pg_trgm extension.

Instead of full-string comparison, pg_trgm breaks strings into overlapping trigrams — groups of three consecutive characters:

"bread" → b, br, bre, rea, ead, ad
"bred" → b, br, bre, red, ed

The database measures similarity by counting shared trigrams. A GIN (Generalized Inverted Index) indexes these chunks, so PostgreSQL can skip 99% of the table and surface the closest matches in milliseconds.

Why not a dedicated search library or service? Because the product catalogue for a small shop is not a Google-scale problem. Everything already lives in PostgreSQL. Adding pg_trgm means zero new infrastructure, and the queries are fast enough for the domain.

Confidence-Based Routing

When a user types a product name, the system returns similarity-scored matches and routes them based on confidence:

Score	Action
≥ 0.8	Auto-select product, proceed
0.3 – 0.8	Disambiguation: list up to 3 options — "Did you mean: 1. Fresh Milk 500ml 2. Mala Milk 1L? Reply 1 or 2"
< 0.3	Re-prompt user, no match found

This required one addition I hadn't planned for in the original FSM spec: a new RECORD_SALE_PRODUCT_SELECTION state. When multiple candidates are returned, the FSM needs to pause and wait for the user's selection — it can't just advance to quantity collection. The candidates are stored in the session context, and the user's numeric response ("1", "2") is mapped to the correct product.

The RECORD_SALE Flow

IDLE → RECORD_SALE_PRODUCT → [RECORD_SALE_PRODUCT_SELECTION] → RECORD_SALE_QTY → CONFIRM_SALE → IDLE

Key business rules built into the flow:

Stock validation guard. Before transitioning to CONFIRM_SALE, the system verifies requested_qty <= available_stock. If insufficient stock exists, the FSM holds at RECORD_SALE_QTY and warns the user — it never lets the sale proceed into confirmation with stock it doesn't have.

Atomic transaction execution. On "yes" at CONFIRM_SALE:

Insert into the sales table.
Atomically decrement inventory.quantity.
Check if remaining stock hits the low-stock threshold and queue a notification task if so.

The CHECK_STOCK Flow

A lightweight 1–2 turn flow:

IDLE → CHECK_STOCK_QUERY → IDLE

Fuzzy lookup → return current quantity and unit price → reset to IDLE. Simple, but uses the same trigram matching infrastructure as the sale flow.

Week 12 — WhatsApp Webhook: HMAC Verification, Payload Schema, and Deduplication

The final week of Month 3 was about building the front door — the point where the outside world starts talking to SokoFlow.

Until now, messages entered through the internal chat simulator. Week 12 replaced the simulator with a production-shaped webhook that processes requests the way the real WhatsApp Business Platform would send them.

The core architectural principle for this week, pulled directly from the Developer Manifesto:

"The Webhook Endpoint Is Dumb. The Worker Is Smart."

The endpoint validates, deduplicates, enqueues, and responds. It does not touch the database. It does not make business decisions. That's the entire architectural thesis of Week 12.

Understanding HMAC: Authentication and Integrity

A message arriving at the server doesn't prove it came from a trusted sender. A webhook endpoint is a publicly reachable URL — anyone who knows it can send requests.

HMAC (Hash-based Message Authentication Code) solves this with a shared secret known only to the sender and receiver:

The sender combines the raw message body and the secret to produce a signature, which travels with the request.
The receiver independently computes the expected signature from the same raw body and the same secret, then compares the two.

If the signatures match, two things are proven:

Authentication — the request was created by someone who possesses the shared secret.
Integrity — the message body was not modified after it was signed.

HMAC does not prove freshness. Replay protection requires additional mechanisms — timestamps and event IDs — layered on top.

The mental model: HMAC is a mathematical secret handshake between two systems. The secret stays private. Only the resulting signature travels over the wire.

Why the Raw Bytes Matter

One implementation detail with real consequences: signature verification must happen against the raw request body bytes — before any JSON parsing.

Parsing the JSON and then re-serializing it can silently alter whitespace, key ordering, or escape sequences. The re-serialized body produces a different HMAC digest even though the data appears identical. Signature mismatch → 401 → dropped message.

The verification step uses hmac.compare_digest() rather than a plain string comparison. This provides constant-time comparison, which eliminates timing-based side-channel attacks.

No valid signature → no entry. No exceptions.

Understanding the WhatsApp Webhook Payload

The WhatsApp Business Platform sends a specific JSON envelope for inbound messages. The key components SokoFlow cares about:

messaging_product: Always "whatsapp".
metadata: Business identification — display_phone_number and phone_number_id.
contacts: Sender profile — profile.name and wa_id (the sender's phone number).
messages: The actual inbound message content — id, type, text.body.
statuses: Delivery receipt tracking (sent, delivered, read, failed) — ignored by SokoFlow's webhook since it only processes inbound messages.

The Pydantic contract models only what SokoFlow actually needs — not the entire WhatsApp universe. The goal was clean: feed the simulator payload through Pydantic and reliably extract phone, message_id, message_text, and message_type without the webhook knowing anything about FSM logic.

Redis Deduplication at the Webhook Layer

External networks are unreliable. The same webhook can arrive twice under normal operating conditions — retransmissions, network jitter, WhatsApp's own retry logic. The system must not record a sale twice because the same event showed up twice.

The same is_duplicate mechanism from Week 9 handles this at the webhook layer:

# SET key "1" only if it does NOT already exist (NX), with a 60-second TTL (EX)
redis.set(f"dedup:{message_id}", "1", nx=True, ex=ttl)

Duplicate message_id → return 200 OK with status: ignored — no FSM processing, no Celery task dispatch.

The 200 OK matters: returning an error code would signal to WhatsApp that the delivery failed, causing it to retry — which is exactly the cycle we're trying to prevent.

The Complete Webhook Pipeline

By the end of Week 12, a valid inbound message travels through this sequence:

FastAPI receives the HTTP POST.
Pydantic validates the payload shape. Malformed → 422.
HMAC-SHA256 signature is verified against the raw body. Invalid → 401.
Redis checks the message_id for duplicates. Duplicate → 200 OK, dropped.
The message is enqueued into Celery's conversation_tasks queue.
FastAPI returns 200 OK immediately.
The Celery worker picks up the task, fetches or initialises the Redis session, runs the FSM, persists to PostgreSQL if needed, and sends the response back through the chat simulator loop.

Progress Since Month 1

Month 1	Month 2	Month 3
Core business logic	Automated workflows	Conversational engine
Local development	Containerized development	Stateful conversations
Manual test runs	CI pipeline	Redis-backed sessions
Single synchronous process	Background workers via Celery	Finite state machine
Runs on my machine	Runs in the cloud	Simulated WhatsApp integration

Final Thoughts and What's Next

Month 3 is done. That's 12 weeks of building and shipping SokoFlow, and for the first time it actually feels like a conversational system rather than just a backend with ambitions.

The interesting engineering challenge this month wasn't the code — it was the design. How do you impose deterministic structure on something as unpredictable as a human conversation? The answer turned out to be: you don't fight the unpredictability. You contain it. State machines give each message exactly one valid set of responses depending on where the conversation is. Redis gives the conversation memory. Lua scripting makes that memory safe under concurrency. Pydantic keeps every input honest before it touches business logic.

And the reason I didn't use an LLM? That's a full answer worth its own section, and it's coming in the Month 4 wrap-up. The short version: an LLM would have been easier to build, but harder to operate, debug, and trust for a system that moves real money and inventory for real shop owners.

Month 4 moves into async report generation, chaos testing, Swahili language support, and final integration.

The system can now have a conversation. Next month, I want to see how well it holds up when things go wrong.

Stay locked in.

Thinking Like a Platform Engineer: Celery, Docker, CI/CD, and Getting SokoFlow Into the Cloud

Kirera paul murithi — Wed, 22 Jul 2026 13:50:18 +0000

SokoFlow Build Log — Month 2 of 4

Welcome back to another SokoFlow build log. If you're new here — I'm an IT student running a structured, project-based learning plan to grow into a production-grade backend engineer. Last semester I built SimPesa, a local-first STK Push simulator for testing M-Pesa Daraja payment workflows without touching a live sandbox. This semester, the theme is from controlled environments to the messy real world.

SokoFlow is my flagship project for this semester: a conversational ERP for small Kenyan shopkeepers that lets them track inventory and record sales entirely through chat — no app to download, no onboarding session, just natural language over WhatsApp. I covered the architecture and core business logic in the Month 1 build log.

Month 2 wasn't about adding features. It was about making everything built in Month 1 deployable, scalable, and production-ready — so that every subsequent feature ships into an environment that actually mirrors the real world. That meant Celery, Docker, CI/CD, and a live staging deployment. Let's get into it.

Where We Left Off

Month 1 ended with a solid core: CRUD operations for the key models, business rules enforced through a strict TDD cycle, and a combined test suite of 40+ tests at 92% coverage. The foundation was sound — but it only ran on my machine.

Month 2's goals were concrete and measurable:

Celery processes a test job, with worker logs confirming execution.
A green badge on the main branch; pull requests blocked if coverage drops below 85%.
A production Dockerfile with build logs showing cache hits on unchanged layers.
A CD pipeline that deploys to staging on merge to main, with both the Swagger UI and /health endpoint publicly accessible.

Week 5 — Celery Integration: Broker Config, Task Definition, Worker Startup

Before writing a single line of code, I had to build the right mental model. This week revolved entirely around one idea: background jobs.

In Month 1, I built CRUD for sales. Now imagine a shopkeeper sends the system a message at the end of the day: "Generate a daily sales report."

The naive approach is to handle that inside the normal HTTP request-response cycle:

The problems are immediate:

The API is blocked for the entire duration.
The request is likely to time out.
The server can't handle any other users while it waits.

The better pattern is to offload the heavy work to a background task:

The user gets an immediate response. The hard work happens asynchronously. The API stays free to serve other requests.

Where Each Component Fits

Component	Responsibility
Producer (the API)	Receives the job, adds it to the queue, responds immediately. It does not execute the work.
Broker (Redis / RabbitMQ)	The mailroom. Stores tasks until a worker picks them up.
Queue	The ordered line of waiting jobs inside the broker. First-in, first-out (with optional priority support).
Worker	The process that actually executes jobs. You can scale workers independently to handle more load.

Celery is not the broker — it's the framework that ties everything together. It gives you a client (inside the API) to publish jobs, and a worker process to consume and execute them. The broker — Redis in SokoFlow's case — is the transport layer that carries messages between the two.

The Mental Model That Cleared My Confusion

Coming from SimPesa, I had worked extensively with BullMQ. The name similarity between BullMQ and RabbitMQ made me mentally group them as peers — which led to real confusion when setting Celery up.

The hierarchy that finally cleared it up:

Application Layer      → Your business logic (generate_report)
Task Framework Layer   → BullMQ (Node.js) | Celery (Python)      ← peers
Messaging/Storage      → RabbitMQ | Redis | Amazon SQS           ← peers
Infrastructure         → TCP | Disk | Memory | Network

BullMQ and Celery sit at the same layer. RabbitMQ and Redis sit at the same layer. They are not interchangeable across layers.

Biggest Takeaway

Offloading slow operations to background workers keeps the API fast and improves scalability — but it's not free. It introduces real complexity in error handling, state management, and debugging, because execution now happens entirely outside the main request flow. Design for that from the start.

Week 6 — GitHub Actions: Setting Up the CI Pipeline

With Celery integrated, Week 6 was about automation. Specifically, making sure the test suite runs on every push and that a failing test physically blocks deployment.

Why CI Exists: The Problem It Solved

To understand why CI pipelines matter, it helps to understand what software development looked like before them.

Imagine a team of ten developers, each working on an isolated feature branch for several weeks. When everyone finally tries to merge their work at once — different assumptions, different dependencies, overlapping changes — the result is what engineers call Integration Hell: a codebase that can barely compile, let alone pass tests.

The breakthrough insight was deceptively simple: merge frequently. If you merge three months of work at once, you inherit a thousand conflicts. Finding the root cause is nearly impossible. If you merge three hours of work, you get one or two conflicts. Root cause analysis takes minutes.

But merging daily created a new bottleneck — human fatigue. Every merge meant someone had to manually compile the code, install dependencies, and run thousands of tests. Steps got skipped. Mistakes got missed.

The solution was to automate the checklist entirely: CI pipelines. Every push triggers an isolated server to compile the code, run the tests, and return a clear pass or fail signal. Jenkins, GitHub Actions, GitLab CI — they all do this, just with different configuration syntax.

Challenges

Database dependencies in CI. Locally, the test suite runs against a Postgres and Redis instance I already have configured. The CI runner starts with a completely clean machine. How does it get those?

The modern answer is service containers. When the CI job starts, the runner spins up lightweight Docker containers for Postgres and Redis alongside the main test container, connects them on a private local network, and exposes them via hostnames like localhost or postgres. The test code connects to them exactly the same way it does locally.

Credentials and security. Having database credentials hardcoded in a YAML file sounds alarming, but test database credentials carry essentially zero risk. The containers live on a private, ephemeral network that's unreachable from the public internet, and the database is permanently destroyed the moment the tests finish.

Sensitive credentials — production deployment keys, third-party API keys — are a different matter entirely. Those go into the platform's encrypted secrets store (GitHub's "Secrets" settings panel), and the pipeline injects them into the runner's memory as environment variables at runtime.

The Mental Model: GitHub Actions Runner = A Rented Computer

The most useful reframe for understanding GitHub Actions:

Step	On Your Laptop	On the GitHub Runner
Setup	You open your laptop	GitHub spins up a clean virtual machine
Code	You write code in VS Code	`actions/checkout` downloads your repo
Tools	You install Python and uv	`setup-python` and `setup-uv` install them
Infrastructure	You start a database container	The `services` block starts one
Execution	You type `uv run pytest`	The runner runs `uv run pytest`
Cleanup	You shut your laptop	GitHub wipes the disk and destroys the VM

The only real difference: your laptop persists its state. The runner is ephemeral — it starts completely clean, does exactly what you scripted, and is destroyed the moment it finishes.

Biggest Takeaway

A GitHub Actions runner is not abstract magic. It is a regular computer in a data center, running the same commands you would run manually in a terminal. Once that clicked, everything about configuring CI became far more intuitive.

Week 7 — Docker Image Optimization

With CI in place, Week 7 was about containerization. My targets: build time under 90 seconds and a final image size under 200MB. Given the number of services in SokoFlow's stack, I was skeptical.

The Problem With Unoptimized Images

The typical first Dockerfile — pull a full OS, install every tool, copy all the code, run it — produces images that are 1–2 GB. That creates real operational problems:

High infrastructure costs. A team deploying 20 times a day and pushing a 2 GB image each time wastes enormous bandwidth and storage.
Slow deployments. Auto-scaling events that require pulling a 2 GB image are measurably slower than pulling a 100 MB one.
Expanded attack surface. Bundling compilers, package managers, and text editors into a production image gives an attacker more tools to work with if they ever get in.

Solution 1: Multi-Stage Builds

A multi-stage build is like a professional kitchen. You use the full counter space — heavy tools, cutting boards, prep mess — to build the dish. But when it's time to serve, only the final plate goes out. The kitchen stays in the kitchen.

In Dockerfile terms:

Build stage: Start with a heavy base image that includes compilers and package managers. Install all dependencies, compile what needs compiling.
Production stage: Start fresh with a minimal base image (Alpine Linux is around 5 MB). Copy only the compiled application artifacts from the build stage. Discard everything else.

The result: a final image that might be 50–80 MB instead of 1 GB.

Solution 2: Respecting the Layer Cache

Every instruction in a Dockerfile creates a new immutable layer. Docker caches these layers and reuses them if their inputs haven't changed. The key implication: layer order determines cache efficiency.

# Layer 1 — Base image (rarely changes)
FROM python:3.12-alpine

# Layer 2 — Dependencies (changes when requirements.txt changes)
COPY requirements.txt .
RUN pip install -r requirements.txt

# Layer 3 — Application code (changes constantly)
COPY . .

If you only change application code, Docker rebuilds only Layer 3. Layers 1 and 2 are pulled straight from cache. Copy your code before your dependencies and you forfeit that optimization entirely — every code change forces a full dependency reinstall.

Challenges

Chaining RUN commands. I noticed the recommended pattern for apt-get installs chains everything into a single command:

# Three separate layers — the cleanup layer doesn't actually remove the cached package index
RUN apt-get update
RUN apt-get install -y build-essential
RUN rm -rf /var/lib/apt/lists/*

# One layer — download, install, and cleanup happen before Docker takes the snapshot
RUN apt-get update && \
    apt-get install -y --no-install-recommends build-essential libpq-dev && \
    rm -rf /var/lib/apt/lists/*

The subtlety: deleting files in a later layer doesn't remove them from earlier layers — it just hides them. The data is still baked into the image history. Chaining with && ensures everything happens inside a single container state before Docker freezes it into a layer.

Why does a Python app need C build tools? Adding build-essential and libpq-dev to a Python Dockerfile initially confused me. I was writing Python — why did I need a C compiler?

The answer is in how psycopg2 works. Python is a high-level, dynamically typed language — fast to write, but comparatively slow to execute. PostgreSQL is written in C and expects high-speed communication. psycopg2 bridges that gap by wrapping a C extension that handles network sockets, memory management, and binary data streams directly. When Python calls psycopg2.connect(), it hands the heavy lifting to that underlying C layer.

build-essential provides gcc, the C compiler needed to build that extension.
libpq-dev provides the PostgreSQL header files — the "dictionary" the C compiler needs to understand how to communicate with Postgres.

Python Wheels. Historically, pip install psycopg2 downloaded raw C source and compiled it locally — slow builds and cryptic errors if the build tools weren't present. Python's solution is Wheels (.whl files): pre-compiled binary packages built by library maintainers for common operating systems and uploaded to PyPI. When a matching Wheel exists, pip install just downloads and unpacks it. No C compilation required.

Biggest Takeaway

Docker is not magic. It is mostly Linux. The Dockerfile is a sequence of Linux commands executed inside a container environment:

RUN apt-get update

is literally running apt-get update inside the image. Once I stopped thinking of Docker as a separate abstraction and started reading it as a shell script with layers, the mental overhead dropped significantly.

Week 8 — Deployment: Shipping to Staging

Week 8 was the capstone. The goal: a CD pipeline that deploys to staging automatically on every successful merge to main, with the Swagger UI and /health endpoint publicly accessible.

Connecting CI to CD

The interesting design question here wasn't the deployment itself — it was the sequencing. You only want to deploy when CI passes. A failing test suite means questionable code, and questionable code should never deploy automatically.

The simplest pattern is a single workflow file using the needs keyword to create a strict job dependency — Job B won't start until Job A finishes with a green checkmark.

I opted for two separate files (ci.yml and deploy.yml) because separate files communicate intent more clearly and are easier to manage independently. The tradeoff is that the needs keyword doesn't work across files — they don't share context. The solution is workflow_run, which lets the deployment workflow listen for the CI workflow to complete:

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}

This means the deployment job only wakes up when the CI workflow finishes, and only proceeds if it finished successfully.

Challenges

Database driver mismatch. Railway provided a standard PostgreSQL connection URL, but SokoFlow's SQLAlchemy engine is configured for async operation using asyncpg. A plain postgresql:// URL defaults to the synchronous psycopg2 driver, which fails immediately in an async context. The fix is to normalize the driver on startup:

if url.drivername in ("postgresql", "postgres", "postgresql+psycopg2"):
    url = url.set(drivername="postgresql+asyncpg")

The Full Deployment Journey

Here's how a single git push to main travels from a local machine to a live staging environment:

CI pipeline — GitHub Actions spins up an isolated runner, installs dependencies, and runs the full test suite. If anything fails, the pipeline stops here.
CD pipeline — On CI success, the deployment workflow triggers and connects to Railway.
Build phase — Railway reads the Dockerfile and builds the production image.
Pre-deploy phase — Railway runs alembic upgrade head in a temporary container, applying any pending database migrations before the new application code goes live.
Live deploy — Railway starts the new FastAPI containers and performs a health check. Once they respond successfully, traffic is switched from the old containers to the new ones with minimal downtime.

Biggest Takeaway

The cloud is not magic either. Before Week 8, SokoFlow looked like this:

FastAPI → localhost → Postgres, Redis

After Week 8:

FastAPI → Environment Variables → Railway PostgreSQL, Railway Redis

The application code is identical. It only knows connection strings. Environment variables replace .env in production — same variable names, different values, and the application has no idea where they came from.

And staging is not "production lite." It is a production-identical environment used to validate deployment mechanics, infrastructure configuration, and integration behavior before anything touches real users.

Month 1 → Month 2: What Changed

Month 1	Month 2
Core business logic	Automated deployment workflows
Local development only	Containerized and reproducible
Manual test runs	CI pipeline with enforced coverage gate
Single synchronous process	Background workers via Celery
Runs on my machine	Runs in the cloud

Looking Ahead to Month 3: Conversation Engine and Webhook Simulation

Month 3 is the feature I've been looking forward to most since this project started — and probably the hardest one.

A WhatsApp message looks like this:

"sold 3 milks"
"Add uji 24 pcs @ 85"
"How much stock for soda?"
"Today's report"

But the system needs structured actions like this:

{
  "intent": "RECORD_SALE",
  "product": "Milk 500ml",
  "quantity": 3
}

The core challenge: how do you turn unpredictable human language into deterministic system commands — without the whole thing collapsing into spaghetti at scale?

SokoFlow's answer is Finite State Machines (FSMs) + controlled intent parsing + conversational context. The easy path would be to drop an LLM into the middle of this and let it handle everything. I didn't take that path — and Month 3's build log explains exactly why.

Stay tuned.

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.