DEV Community: Zack Grooms

CountIQ: A Systems Notebook on Real-World Backend Engineering

Zack Grooms — Sun, 15 Feb 2026 18:00:06 +0000

This is a developer notebook documenting what building a real backend is teaching me about invariants, state transitions, concurrency, and system design. No fluff — just real architecture lessons from building CountIQ.

I didn’t build CountIQ to ship a product.
I built it to understand what actually happens inside a backend.

Not in theory.
In reality — with state, invariants, race conditions, and deployment in mind.

This post isn’t a tutorial.
It’s a developer notebook.

I’m documenting what building a real system is teaching me about:

modeling state instead of writing endpoints
aligning database constraints with domain rules
preventing race conditions through transaction boundaries
why most backend bugs are invariant bugs, not syntax bugs
and how a simple service evolves into something deployable

CountIQ started as a small inventory backend.
But it quickly became a controlled environment for learning system design the hard way — by building, breaking, and fixing a real system.

If you’re learning backend engineering and want to see how a system evolves layer by layer — architecture, logging, concurrency, and deployment — this series is for you.

No frameworks magic.
No hand-wavy abstractions.

Just the mental models and design decisions that actually make a backend stable.

1. Core System Model

CountIQ is modeled as a state machine.


S = Map[id → item]
S' = f(S, input)

Translation

S → current system state
input → request
f → transition logic
S' → new system state

Every endpoint is a state transition.

If validation fails:


S' = S

State must remain unchanged.

State Visualization


Current State (S)
{
"1": milk,
"2": eggs
}

request
  ↓


Apply transition f(S, input)

↓


New State (S')
{
"1": milk,
"2": eggs,
"3": bread
}

2. Architecture


interface
↓
transport
↓
service
↓
domain
↓
database

Layer Responsibilities

Transport

parse request
no business logic

Service

orchestrate mutation
enforce boundaries

Domain

validate invariants
normalize input

Database

persistence
final authority

3. Mutation Pipeline

All mutations follow one path:


read → validate → commit

Diagram


Request
↓
Read state
↓
Validate invariants
↓
Commit transaction
↓
Return response

If validation fails:


no commit
state unchanged

4. Bug Refurbishment

Global vs Per-Owner Uniqueness

Original constraint


name UNIQUE

Observed behavior


User A → create milk → OK
User B → create milk → rejected

System enforced:

name globally unique

This was incorrect.

Correct invariant


(owner_id, name) must be unique

Meaning:

same user → duplicates forbidden
different users → duplicates allowed

Namespace Visualization


User A:
milk
eggs

User B:
milk   ← allowed
bread

Fix Alignment

Domain

Define invariant clearly.

Database


UNIQUE(owner_id, name)

Service

Attempt write → catch integrity error → translate.

Tests

Verify:

same owner duplicate fails
different owners succeed

5. Concurrency Model

Key truths:

processes don’t share memory
threads share heap
requests interleave
database enforces consistency

Concurrency Diagram


Request A ──────┐
├── Database
Request B ──────┘

Both requests may attempt mutation simultaneously.

Database constraint prevents corruption.

6. Request Lifecycle Graph


client
↓
OS
↓
kernel
↓
network
↓
process
↓
database
↓
response

Latency becomes:


path cost + contention

7. Testing Philosophy

Tests validate the mental model.

Rules:

assert state unchanged on failure
test transitions
separate transport vs service tests
integration tests verify layers

If tests are hard to write:

the model is wrong.

8. Logging System Direction

Logging is a system component.

Goals:

structured logs
lifecycle visibility
transition tracing
concurrency debugging

Logging = observability = understanding.

9. Why This Project Exists

CountIQ is a systems lab for learning:

invariants
mutation safety
concurrency
architecture
deployment

Built:

layer by layer
frozen interfaces
deployment-first mindset

10. Forward Roadmap


logging middleware
user model
Docker
AWS deployment
Python internals
concurrency deep dive

Each addition updates this notebook.

Developer Takeaway

Most backend bugs are not syntax bugs.

They are invariant bugs.

If the model is wrong:

code feels fragile
fixes are temporary

If the model is correct:

code simplifies
scaling becomes predictable

Rule:

Model the system first.

Then write the code.

Building an Atomic Quantity Update Endpoint in Django (and the Bugs That Taught Me More Than the Feature)

Zack Grooms — Tue, 10 Feb 2026 19:54:07 +0000

I’m building a backend-only inventory system to practice real systems engineering fundamentals:

state transitions
invariants
atomicity
correctness under concurrency

No UI.
Just HTTP + database.

This week I finished the service + transport layer for:

PATCH /items/<uuid>/qty

This endpoint applies a delta-based transition to item quantity.

Why use `delta` instead of setting quantity directly?

Instead of:

qty = 4

we send:

{ "delta": -1 }

The system performs:

qty' = qty + delta

This allows the database to apply the change atomically and avoids read-modify-write race conditions.

The Service-Layer Implementation

All state mutation lives in the service layer.

updated = (
    Item.objects
    .filter(id=item_id, qty__gte=-delta)
    .update(qty=F("qty") + delta)
)

What this does

1. Guard against invalid state

qty__gte=-delta

ensures:

current_qty + delta ≥ 0

If the result would be negative, the update never runs.

The database enforces this invariant.

2. Atomic update

qty = qty + delta

is executed entirely inside the database using F("qty").

No Python read-modify-write.
No race conditions.

3. Explicit outcome classification

If no row updated, we determine why:

if updated:
    return Item.objects.get(id=item_id)

if not Item.objects.filter(id=item_id).exists():
    return None

raise ValueError("qty cannot go below 0")

Service contract becomes:

Return	Meaning
Item	success
None	not found
ValueError	invariant violated

Transport maps to:

200 → success  
404 → not found  
400 → invalid transition

Bugs That Taught Me More Than the Feature

Bug 1 — Update succeeded but returned 404

Qty updated correctly but response returned “not found”.

Cause:

if updated:
    return

Bare return → None.
View interpreted None as 404.

Fix:

if updated:
    return Item.objects.get(id=item_id)

Lesson:
Return contracts must be explicit and deterministic.

Bug 2 — UUID routing mismatch

Model used UUID primary key.
URL used:

<int:item_id>

View never matched correctly.

Fix:

path("items/<uuid:item_id>/qty", ...)

Lesson:
URL converters define runtime identity types.

Bug 3 — Django HTML error pages

Invalid routes returned Django HTML debug pages.

Fix: custom JSON 404 handler.

def json_404(request, exception):
    return JsonResponse({"error": "not_found"}, status=404)

Lesson:
Transport layer should always return consistent API responses.

Bug 4 — The boolean delta bug (subtle but dangerous)

This one looks small but is actually critical.

Python behavior

In Python:

isinstance(True, int)  # True

bool is a subclass of int.

So if validation only checks:

if not isinstance(delta, int):

then this passes:

{ "delta": true }

What happens if you accept it?

True → behaves like 1  
False → behaves like 0

So:

{ "delta": true }

becomes:

qty = qty + 1

This creates a hidden mutation path where boolean values mutate state.

Even worse:

qty__gte=-delta

If delta=True:

-True == -1

The guard becomes:

qty >= -1

Almost always true.

So a boolean silently becomes an increment operation.

That violates the API contract and creates extremely hard-to-trace bugs.

The fix

Reject bool explicitly:

if isinstance(delta, bool) or not isinstance(delta, int):
    raise ValueError("delta must be an int")

Now the system only accepts real integers.

Lesson

Type validation must be explicit at the transport boundary.
Silent coercion creates invisible state transitions.

Bug 5 — Missing transaction boundary

If update succeeded but later code failed, state could commit partially.

Fix:

with transaction.atomic():

This guarantees:

all-or-nothing transition

Example Invariant Violation

Current state:

qty = 0

Request:

{ "delta": -2 }

Would produce:

qty = -2

Database blocks update.

Response:

400
{ "error": "qty cannot go below 0" }

State remains unchanged.

Architecture That Emerged

transport → service → model → database

Transport

parse JSON
validate shape
map service results → HTTP

Service

normalize input
enforce invariants
perform atomic transitions

Database

source of truth
guard state

Biggest Takeaway

Correctness comes from:

explicit transitions
database guards
deterministic return contracts
atomic updates

Not clever abstractions.

Today the system became predictable.

Next Steps

remove csrf_exempt
auth boundary
request logging
concurrency tests

If you’re learning backend systems, try implementing an atomic delta update yourself.

The bugs you hit will teach you more than the feature ever will.

What Building a Backend Taught Me About Statelessness and Idempotent APIs

Zack Grooms — Mon, 09 Feb 2026 00:58:04 +0000

This article was originally published on Medium: From Curiosity to Systems Thinking...
While building a backend system from scratch, I started to understand why Roy Fielding’s REST constraints exist...

Implementing an Idempotent Delete in Django

Zack Grooms — Sun, 08 Feb 2026 22:19:07 +0000

Today I worked on the delete mutation for my Django inventory system.
The goal was to make the endpoint idempotent:

DELETE /items/<id>/

If the item exists → remove it
If it doesn’t exist → no change
Always safe to retry

The bug

The delete wasn’t actually changing state.

I was calling:

python Item.objects.filter(item_id).delete()

instead of:

python Item.objects.filter(id=item_id).delete()

Because the query wasn’t filtering on the correct field, the state transition wasn’t happening. The endpoint looked like it worked, but the underlying state wasn’t being modified correctly.

The fix

Using:

python Item.objects.filter(id=item_id).delete()

inside a transaction made the delete naturally idempotent:

existing item → removed
missing item → no-op
safe under retries

No extra conditional logic needed.

System takeaway

Idempotence often comes from how you shape the query and state transition, not from adding more control flow.

Designing the delete this way keeps the service:

stateless
retry-safe
predictable

Next step

Next feature is atomic quantity updates:

invariant enforcement
transaction boundaries
avoiding lost updates

Building one feature per day and focusing on correctness first.

DEV Community: Zack Grooms

CountIQ: A Systems Notebook on Real-World Backend Engineering

1. Core System Model

Translation

State Visualization

2. Architecture

Layer Responsibilities

3. Mutation Pipeline

Diagram

4. Bug Refurbishment

Global vs Per-Owner Uniqueness

Original constraint

Observed behavior

Correct invariant

Namespace Visualization

Fix Alignment

Domain

Database

Service

Tests

5. Concurrency Model

Concurrency Diagram

6. Request Lifecycle Graph

7. Testing Philosophy

8. Logging System Direction

9. Why This Project Exists

10. Forward Roadmap

Developer Takeaway

Building an Atomic Quantity Update Endpoint in Django (and the Bugs That Taught Me More Than the Feature)

Why use delta instead of setting quantity directly?

The Service-Layer Implementation

What this does

1. Guard against invalid state

2. Atomic update

3. Explicit outcome classification

Bugs That Taught Me More Than the Feature

Bug 1 — Update succeeded but returned 404

Bug 2 — UUID routing mismatch

Bug 3 — Django HTML error pages

Bug 4 — The boolean delta bug (subtle but dangerous)

Python behavior

What happens if you accept it?

The fix

Lesson

Bug 5 — Missing transaction boundary

Example Invariant Violation

Architecture That Emerged

Transport

Service

Database

Biggest Takeaway

Next Steps

What Building a Backend Taught Me About Statelessness and Idempotent APIs

Implementing an Idempotent Delete in Django

The bug

The fix

System takeaway

Next step

Why use `delta` instead of setting quantity directly?