DEV Community: Kirera paul murithi

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.

DEV Community: Kirera paul murithi

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

SokoFlow Build Log — Month 3 of 4

Goals for Month 3

Prerequisites: Two Mini-Projects Before the Real Work

1. Chat Simulator

2. Intent Resolver

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

The Core Problem: HTTP Has No Memory

The Session Schema: Pydantic vs. Dataclasses

Handling Edge Cases from the Start

The ConversationStore: Abstracting Redis Away

The Race Condition Problem: Why save_session Needed Special Treatment

The Solution: Redis Lua Scripting (Optimistic CAS)

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

The Architectural Strategy: State Pattern over if-else Chains

The ADD_PRODUCT State Blueprint

Input Validators: Handling the Messy Reality of Kenyan SME Text

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

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

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

What is Fuzzy Matching?

The Core Metric: Levenshtein Distance

The Performance Problem

The Solution: PostgreSQL pg_trgm and GIN Indexes

Confidence-Based Routing

The RECORD_SALE Flow

The CHECK_STOCK Flow

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

Understanding HMAC: Authentication and Integrity

Why the Raw Bytes Matter

Understanding the WhatsApp Webhook Payload

Redis Deduplication at the Webhook Layer

The Complete Webhook Pipeline

Progress Since Month 1

Final Thoughts and What's Next

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

SokoFlow Build Log — Month 2 of 4

Where We Left Off

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

Where Each Component Fits

The Mental Model That Cleared My Confusion

Biggest Takeaway

Week 6 — GitHub Actions: Setting Up the CI Pipeline

Why CI Exists: The Problem It Solved

Challenges

The Mental Model: GitHub Actions Runner = A Rented Computer

Biggest Takeaway

Week 7 — Docker Image Optimization

The Problem With Unoptimized Images

Solution 1: Multi-Stage Builds

Solution 2: Respecting the Layer Cache

Challenges

Biggest Takeaway

Week 8 — Deployment: Shipping to Staging

Connecting CI to CD

Challenges

The Full Deployment Journey

Biggest Takeaway

Month 1 → Month 2: What Changed

Looking Ahead to Month 3: Conversation Engine and Webhook Simulation

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

SokoFlow Build Log — Month 1 of 4

1. The Vision of a Headless ERP

2. The Power of TDD in Core Logic

3. The Technical Hurdles

A Wall of New Tooling

Fighting Async Testing and DB Drivers

Time and Timezones

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

5. Conclusion & Key Takeaway

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