System Design on Shane's Personal Blog

Where Stateless APIs Meet Stateful Databases

Sat, 22 Nov 2025 00:00:00 GMT

I used to treat databases like magic.

The tutorials always showed the same pattern: create an engine, make a session factory, write a dependency that yields sessions. It worked. I copied it everywhere. But I never really understood why.

Then I started building background workers and suddenly those copy-paste patterns stopped working. I’d stare at my code, confused:

Why do we keep the database engine around forever?
Why do we recreate sessions for every request?
If APIs should be “stateless,” why are we persisting anything?
Is S3 stateless or stateful? What about Redis?

Something wasn’t adding up.

The Tension That Wouldn’t Go Away

Everyone says: “Build stateless APIs.”

But in practice, every backend I’ve built keeps things around:

Database engines that live for the entire process
Session factories stored in app state
S3 clients tucked into context objects
Redis connections shared across requests

So which is it? Are we stateless or not?

For a long time, my brain filed this under: “This is just what you do.” Which was really code for: “I don’t understand this, but it seems to work, so let’s move on.”

The Mental Model That Changed Everything

Here’s the picture that finally made sense.

Imagine a horizontal line cutting through your entire system:

Above the line: Your request handlers and background tasks.

They behave like they’re stateless
Each request is its own clean unit of work
No hidden state carried between requests

Below the line: The persistence world.

Postgres with its tables and rows
S3 with its buckets and objects
Redis with its keys and values
This is where real state lives across everything

On the line: Client objects that connect the two worlds.

Database engines with their connection pools
S3 clients with their configuration
Redis clients with their connection management
These are the bridges between your stateless code and the stateful world

Once I saw it this way, everything started making sense.

Your code isn’t cheating when it keeps an engine around. You’re not breaking the “stateless” rule. You’re just maintaining the infrastructure to access the stateful world cleanly.

Why Databases Feel So Special

Let’s be honest: databases get way more ceremony than S3 or most other services. There’s a reason for that.

Connection Pools Are Serious Business

Imagine your database is a restaurant with exactly 100 tables.

If every customer (request) brought their own table and left it there, the restaurant would fill up instantly. Even worse, if you have 20 servers (workers) and each brings 10 tables per second… you see the problem.

So instead:

The restaurant has a pool of tables it manages (the engine)
Customers sit down, eat (do their work), and leave
The same table gets reused for the next customer

In code terms:

One engine per process manages a small pool of connections
Each request grabs a connection from the pool
When the request finishes, the connection goes back

This isn’t style. This is survival.

Transactions Need Their Own Space

A database session isn’t just a connection—it’s a transaction boundary.

Think of it like this: a session is a private notepad where you write down everything you want to change. At the end, you either tear out the page and hand it in (commit), or crumple it up (rollback).

If you share that notepad across multiple requests, suddenly you’re mixing everyone’s changes together. One request thinks it saved an order, another thinks it cancelled it, and the database has no idea what you actually want.

That’s why sessions are strictly per-request. One request, one notepad, clean start to finish.

What About S3?

S3 is interesting because it sits on the boundary differently.

Yes, S3 stores files that persist. Upload something today, download it tomorrow. It’s absolutely stateful.

But—and this is the key difference—you talk to S3 over HTTP. Every upload, every download is its own independent request. There’s no “transaction” that spans multiple operations. No notepad that tracks changes before you commit them.

Think of it like mail:

Database: You’re in a room working on documents. You can see everything you’ve written, make changes, and decide later whether to file them or throw them out.
S3: You’re sending letters. Each letter is complete and independent. The post office doesn’t remember your previous letters or hold them in some draft state.

Both are stateful systems below the line. But databases need more careful handling because of connections and transactions.

The Real Meaning of “Stateless”

Here’s where my confusion cleared up.

When people say “build stateless APIs,” they don’t mean “never keep anything in memory.”

They mean: each request should not depend on hidden state from previous requests.

In practice:

❌ Don’t keep a database session alive between requests
❌ Don’t store “current user” in a global variable
❌ Don’t rely on some mutable object that changes across requests
✅ Do keep shared infrastructure (engines, clients, config)
✅ Do create fresh sessions/contexts for each request
✅ Do read and write actual state from databases, caches, and storage

The shared objects are tools, not business state. Your real state lives below the boundary, where it belongs.

When This Really Mattered: Background Workers

All of this became concrete when I started building background workers.

In a web framework, you get this for free. The framework handles creating sessions per request and cleaning them up. You mostly just write your business logic.

But in a background worker? Suddenly you have to decide:

What goes in the worker’s context (shared across all tasks)?
What gets created fresh for each task?

It’s the boundary decision, made explicit.

A clean pattern:

# In worker setup (long-lived)
context["db_session_factory"] = SessionFactory(engine)
context["s3_client"] = S3Client(config)

# In each task (short-lived)
async def process_document(context, document_id):
    session = context["db_session_factory"].create()
    s3 = context["s3_client"]

    # Do work with fresh session
    # Session tracks its own transaction
    # Then it's done and cleaned up

The factories and clients live on the boundary. The session and your business logic live above it, clean and independent.

Why This Mental Model Is Worth Having

I didn’t realize I was on autopilot until I had to wire things myself.

The FastAPI tutorial says: “Do this.” So I did it. The Litestar docs say: “Put this here.” So I put it there.

And that works… until you step off the happy path:

Multiple workers
Background tasks
Mixing databases, S3, Redis, message queues
Debugging weird connection issues

At that point, copy-paste stops being enough. You need to understand why things are shaped the way they are.

For me, the breakthrough was seeing the boundary:

Below: Persistent systems (Postgres, S3, Redis) where real state lives
On: Client objects (engines, session factories, S3 clients) that bridge the gap
Above: Stateless-ish request handlers that do work and move on

Once you see it, a lot of “magic patterns” become obvious design decisions.

You’re not keeping a database engine around because of some weird Python quirk. You’re keeping it around because creating connection pools is expensive and they’re meant to be shared.

You’re not creating sessions per request because the tutorial said so. You’re doing it because transactions need clean boundaries and connection pools need to reuse connections.

You’re not being inconsistent when you share an S3 client but create fresh database sessions. You’re recognizing that different systems have different interaction models.

TL;DR

If you’re coming back to this later and just need the core ideas:

Stateless doesn’t mean no shared objects. It means each request doesn’t rely on hidden mutable state from previous requests.

The boundary model:

Below: Persistent systems (databases, S3, Redis)
On: Client infrastructure (engines, session factories, clients)
Above: Per-request logic (sessions, services, handlers)

Databases feel special because:

Connection pools have hard limits
Transactions need clean boundaries
Sessions track changes before commit/rollback

In practice:

Share: engines, clients, configuration, factories
Create fresh: sessions, request contexts, transaction boundaries

The next time you see engine, sessionmaker, Session, or s3_client, you’ll know where they live in your architecture and why they’re shaped that way.

Not just magic patterns. Conscious design decisions about where the line is between your code and the stateful world below it.

(Written by Human, improved using AI where applicable.)

Why AI Cannot Engineer

Thu, 20 Nov 2025 00:00:00 GMT

I asked Claude to build me a customer dashboard last month. Ten minutes later, I had gorgeous React components, a clean API structure, and authentication that worked flawlessly on my laptop. I felt like a wizard.

Two days later, when we put it in front of actual users, everything fell apart. The API crumbled under concurrent requests. The authentication tokens expired in the middle of user sessions. The database queries that felt snappy with my 10 test records took 30 seconds with real data.

The code looked beautiful. It even worked—sort of. But it was a disaster waiting to happen, and I had no one to blame but myself. I’d asked for a construction worker when I needed an architect.

The Skyscraper Nobody Can Live In

Think about building a skyscraper for a moment. You need two completely different types of expertise:

The Architects and Engineers design the building. They figure out where the load-bearing walls go, how to route all the electrical wiring and plumbing, what materials can handle the wind shear at that height, how the building responds to earthquakes. They think about fire escapes and elevator shafts and how people will actually move through the space. They create detailed specifications for everything.

The Construction Workers build it. They know how to mix concrete, how to weld steel beams, how to install windows. Give them a good blueprint with all the specifications—“use this gauge of rebar, space them 6 inches apart, let the concrete cure for 48 hours”—and they’ll build you something solid and safe.

Here’s the interesting part: construction workers understand building principles. They know that rebar makes concrete stronger, that you can’t just drill holes wherever you want in a load-bearing wall, that certain materials expand in heat. They might not be able to calculate the exact compression loads or explain the physics, but they know how to build.

So in theory, if you asked construction workers to build a skyscraper without giving them architectural plans, they could do it. They’d use their knowledge to put up walls and install wiring and plumbing. The building would stand.

For a while.

Then someone tries to actually live in it. Or an earthquake hits. Or there’s a fire. And you realize the electrical system is a tangled mess that can’t handle the load. The plumbing creates massive pressure problems on the upper floors. There are no proper fire exits. The structure can’t flex with the wind. It looks like a building, but it’s not safe, not livable, not reliable. It’s a expensive disaster wrapped in a pretty facade.

You really needed those architects and engineers.

We Accidentally Merged Two Jobs

Now let’s talk about software. In our industry, we have the same two roles—but we’ve gotten confused about which is which.

Software Engineers are supposed to design systems. They think about scalability, reliability, security, maintainability. They establish patterns and guardrails. They consider edge cases: What happens when 10,000 users hit this endpoint simultaneously? How do we handle partial failures? What’s our data consistency model? How do we make this debuggable when something goes wrong at 3am? They create the “blueprints” that make the difference between software that works on localhost and software that works in production.

Programmers write code. They understand syntax, algorithms, design patterns. They know how to implement features, how to make things work. Given good specifications and architectural guidelines, they write solid, maintainable code that does exactly what it needs to do.

But here’s where we got confused: engineers also write code. They have to—you can’t design a system well if you don’t understand implementation realities. An architect who doesn’t understand how concrete and steel actually behave can’t design a building that stands. Similarly, a software engineer needs to understand how code actually executes.

Because of this overlap, we started treating them as the same job. Most companies just have “software engineers” who do everything—system design and implementation. We stopped distinguishing between the person who decides “we need a caching layer with these invalidation rules” and the person who implements Redis with that specification.

For years, this worked okay. The engineer-programmer would design the system in their head, then implement it. Both roles were happening, just inside one person.

Enter the AI Programmer

Now we have large language models that can write code. And here’s what I’ve realized: LLMs are incredible programmers, but terrible engineers.

An LLM is like that construction worker who can build you a skyscraper without blueprints. Ask it to “build me a todo list app,” and it will. The code will be clean. It’ll have proper separation of concerns. The variable names will make sense. It’ll work beautifully on your laptop.

But it’s missing all the engineering:

No load considerations: It’ll use an in-memory array for the todo list, which works great for testing but fails when you have 10,000 users
No failure handling: What happens when the database connection drops mid-request? The LLM’s code probably doesn’t handle that gracefully
No security thinking: Authentication might be present, but is it actually secure against common attacks? Are there SQL injection vulnerabilities?
No performance engineering: That nested loop through every user’s todos on every request? Didn’t consider that case
No operational thinking: Good luck debugging when something goes wrong—there’s minimal logging and no monitoring

The code looks professional. It follows good practices. It even works, in the ideal case. But the moment reality hits—concurrent users, network failures, edge cases, malicious input—it falls apart.

Just like that skyscraper built without architects.

What This Actually Means

I used to think the distinction between “engineer” and “programmer” was just semantic nitpicking. Now I realize it’s crucial, and we’re about to learn this lesson the hard way.

When you tell an LLM “build me an authentication system,” you’re giving it a task without constraints. It’s like telling a construction worker “build me a building” without specifying:

How many people it needs to support
What kind of disasters it needs to withstand
What the fire safety requirements are
How the utilities should be routed
What the budget constraints are

The LLM will build you something. That something might even impress you. But it won’t be robust, because nobody did the engineering.

Here’s a real example from my startup, Empath Legal. We’re building jury selection tools for attorneys. I could ask an LLM: “Create an API endpoint that analyzes jury questionnaires and returns insights.”

The LLM would build me something functional:

It would parse the questionnaires
It would call an LLM to analyze the text
It would return formatted results
The code would be clean and well-structured

But here’s what it wouldn’t consider without engineering input:

Business requirements I need to specify:

These questionnaires can be 50+ pages and attorneys need results in under 30 seconds
Our customers are lawyers who need citations for everything—we can’t just hallucinate insights
The analysis must be deterministic enough that an attorney can rely on it in court
We have a credit-based pricing model, so we need to track and limit usage

Technical guardrails I need to establish:

We need to chunk large questionnaires intelligently (by section, not arbitrary token counts)
We must implement streaming so attorneys see progressive results, not a 30-second blank screen
We need a caching layer so re-analyzing the same questionnaire doesn’t burn credits
We need robust error handling because LLM API calls fail sometimes
We need audit trails for compliance reasons

System design decisions I need to make:

Should this be synchronous or async? (Async, because of the 30-second requirement)
What happens if the LLM call fails midway? (We need idempotent retries)
How do we handle rate limits from the LLM provider? (We need a queue with backpressure)
What’s our data consistency model? (We need to decide what happens if analysis partially completes)

The LLM could write beautiful code for the happy path. But without me doing the engineering work—understanding the requirements, establishing the constraints, designing the system architecture—that code would be worthless in production.

The New Division of Labor

This isn’t about LLMs being bad. They’re phenomenal at what they do. This is about understanding what they do.

LLMs are expert programmers: Give them a well-specified task with clear constraints, and they’ll implement it beautifully. They know patterns, they write clean code, they can even debug and optimize within a defined scope.

Humans need to be the engineers: We need to understand the business requirements, design the system architecture, establish the guardrails and principles, consider the edge cases and failure modes. We need to ask: What are we really trying to achieve? What could go wrong? How does this need to scale?

This is actually liberating, if you think about it. We can offload the tedious parts—writing boilerplate, implementing standard patterns, translating specifications into code—and focus on the interesting parts: understanding user needs, designing robust systems, making architectural tradeoffs.

But only if we actually do the engineering work. If we just prompt “build me X” without providing context, constraints, and architectural guidance, we get that beautiful skyscraper that nobody can live in.

How to Actually Work with AI Coding Tools

Here’s what I’ve learned about working effectively with LLMs:

Bad prompt:

“Build me a payment system for my SaaS app”

Good prompt:

“Build me a payment system with these requirements:

Support credit-based pricing (users buy credits, features consume credits)

Must handle concurrent credit deductions safely (two API calls shouldn’t both succeed if there’s only enough credits for one)

Need audit trail for billing disputes

Should fail gracefully if payment processor is down (degrade to cached credit counts, log for reconciliation)

Performance requirement: credit check must add < 50ms to request latency

Use PostgreSQL with row-level locking for credit deductions. Implement idempotent credit operations so retries don’t double-charge. Include comprehensive logging for debugging billing issues.”

The second prompt does the engineering work. It specifies:

The business model (credit-based pricing)
The critical constraint (safe concurrent access)
The compliance requirement (audit trail)
The reliability requirement (graceful degradation)
The performance requirement (latency budget)
The technical approach (PostgreSQL with row locks)
The operational requirement (debuggable)

Now the LLM can write code that actually works in production, because I’ve given it the architectural blueprint.

The Uncomfortable Truth

Most of us who’ve been writing code for years have been doing both roles simultaneously for so long that we don’t even notice when we’re switching hats. When we sit down to “code,” we’re actually doing engineering work (thinking about requirements and constraints) and then programming work (implementing the solution).

With LLMs, we can’t do that anymore. The programming part gets delegated to the AI. But if we don’t explicitly do the engineering part ourselves—if we just treat the LLM as a magic “build me X” box—we get code that works in the demo but fails in reality.

And here’s the uncomfortable part: many people who call themselves engineers are actually just programmers. They’re really good at writing code, but they’ve never had to think deeply about system design because they were implementing someone else’s architecture, or working on small enough systems that the complexity didn’t matter.

With LLMs, this distinction now matters. The code-writing skills that used to be valuable are being commoditized. What’s becoming valuable is the engineering thinking: understanding requirements, designing robust systems, making good architectural tradeoffs, considering failure modes.

What This Means For You

If you’re learning to code right now, don’t just learn syntax and frameworks. Learn to think like an engineer:

When you build something, ask: “What happens when 1000 people use this simultaneously?”
Before writing code, ask: “What are all the ways this could fail, and how should it handle each one?”
Study real-world system design, not just toy examples
Learn to write specifications that would let someone else implement your vision correctly
Understand the why behind patterns, not just the how

If you’re already working as a developer, pay attention to which role you’re actually performing. Are you mostly implementing features based on specs? You’re in the programmer role, and LLMs are coming for that job. Start developing engineering skills: system design, requirements analysis, architectural thinking.

If you’re hiring, stop asking “can you code fizzbuzz?” and start asking “design a URL shortener that handles 1000 requests/second and explain your failure modes.” The code-writing part is increasingly automated. The thinking part isn’t.

The Punchline

Here’s the irony: I wrote this post with Claude’s help. Not because I couldn’t write it myself, but because Claude is a better programmer than I am. I gave it my core idea, my architectural guidelines (the blog writing guide), my requirements (make it engaging and human), and my constraints (use the construction analogy, include real examples).

Claude wrote beautiful prose. But I did the engineering: I decided what to communicate, how to structure the argument, what examples would land, what the reader needs to understand.

The future of software development isn’t “no human involved.” It’s humans doing what humans are uniquely good at—understanding messy real-world requirements, making tradeoffs with incomplete information, designing robust systems for complex environments—while AI does what it’s uniquely good at: writing clean, correct code that implements those specifications.

But only if we remember to do the engineering work. Otherwise, we’re just building skyscrapers without architects.

And we all know how that story ends.

What’s your experience with AI coding tools? Are you finding yourself doing more engineering thinking, or just prompting and hoping? I’d love to hear your stories—the spectacular failures are often more educational than the successes.

(Written by Human, improved using AI where applicable.)

The 12-Factor App: Building Software Like LEGO in the Cloud Era

Tue, 19 Aug 2025 00:00:00 GMT

Intro

Picture this: It’s 3 AM, and your app just went viral. Traffic spikes from 100 users to 100,000 in minutes. Half your team is asleep, the other half is panicking. Will your application gracefully scale to handle the load, or will it crumble under pressure?

As a startup, this scenario haunted me as I build our application—until I read something that fundamentally changed how I think about building applications. It’s called the 12-factor app methodology (knowledge and wisdoms discovered like this always humbles me—we are, after all, standing on the shoulders of giants, and hoping to see further into the future)

Here’s how I think about this: A 12-factor app is like a LEGO brick for infrastructure. You build it with zero assumptions about the outside world, purely implementing internal logic while letting the platform decide everything els—what inputs to feed it, where outputs go, when to start, stop, duplicate, or destroy it. The app becomes not just a one-off creation but an infinitely scalable building block (like lego for the cloud).

The Three Pillars: Understanding the Architecture

Before diving into the twelve factors, let me share the mental model that finally made everything click. Every interaction in a 12-factor app falls into one of three categories:

The App Itself - The immutable, stateless core of your logic
The Interface - How your app communicates with the outside world
The Platform - The environment that orchestrates everything

Think of it like this: Your app is a chef in a kitchen. The chef (the app) has specific skills and recipes. The kitchen setup—where ingredients come from, where dishes go, what equipment is available—that’s the interface. The restaurant management deciding when the chef works, how many chefs to hire, which orders to prioritize—that’s the platform.

This separation is what makes the magic happen. Let’s explore how each factor reinforces this architecture.

Part 1: The Foundation - Managing Your Code and Dependencies

Factor I: Codebase - Your Single Source of Truth

Remember the last time you heard “it works on my machine” or spent hours figuring out which version of the code was actually running in production? The codebase principle eliminates these nightmares.

Imagine your codebase as a map where every piece of code has exact coordinates—the X-axis represents different versions, the Y-axis represents different deployments. Any snapshot of your code can be pinpointed precisely on this map. When something breaks at 3 AM, you know exactly which code is running where.

This has not be a problem personally—since I adopted github blindly (shame on me) during college, I always put my code there (I naively thought of it as a cloud for my code. I can just pull code from anywhere—fun!) but stupid me: its way more complex than that, which I learned as I use github with teammates. The only way you truly understand how a version control navigates landmines is to actually use it wrong (which i did lol) and get hit on the head with a brick. Then you learn.

Factors II & III: Dependencies and Config - The Input Controls

These two factors are cousins—they both control how the outside world shapes your app’s behavior, but in subtly different ways.

Dependencies are like the ingredients list for a recipe. You declare exactly what you need (Python packages, Node modules, system libraries) in a manifest file. No assumptions, no “it should probably have this installed.” Every dependency is explicit.

Configuration, on the other hand, is like the knobs on a mixing board. Same equipment, different settings for different venues. Your database credentials, API keys, feature flags—these change between environments, but your code doesn’t.

Here’s the crucial insight: Your app’s config is everything that varies between deploys. If you can’t open-source your code right now without leaking credentials, you haven’t separated config from code properly.

for python, what I like to do with settings is just use dotenv + dataclass. Reliable, barebone yet powerful.

Factor IV: Backing Services - Your App’s Supporting Cast

Backing services are where input and output blur together. Your database, message queue, email service—they’re both sources of input (what data do I read?) and destinations for output (where do I write?).

The breakthrough principle here: treat every backing service as an attached resource. Your app shouldn’t care whether PostgreSQL is running on the same machine, in a different datacenter, or managed by a third party. It’s just a URL and credentials in your config.

For example, this really shines when you need to migrate from a self-hosted PostgreSQL to Amazon RDS—if you treat the database as an attached resource, the migration is simply config change. (the problem is never about coding, the problem is always about the bug that comes with new codes. LOL)

Part 2: The Build Pipeline - From Code to Running Process

Factor V: Build, Release, Run - The Three-Stage Rocket

Lets talk about bread. 4AM in the morning, You bake it (Build), then you got a bunch of breads at 9am when you open (releases), then you sell the breads during the day (run). Sure if you are a small bakery you can live with baking fresh breads and sell them right after (mix build and run) but if you bake the bread wrong, your customer would need to wait an extra hour for a new batch. It would be so much better if you bake early and have a bunch of ready bread and satisified customers!

Now that you have a rough understanding what the three stages are, lets dive deeper:

Build Stage: Your code + dependencies become an executable (compile, bundle, package)
Release Stage: That executable + configuration becomes a numbered release
Run Stage: That release executes in the production environment

Each release is immutable—a frozen snapshot combining a specific build with specific configuration. When release v427 starts acting weird, you can instantly roll back to v426. You’re not scrambling to figure out what changed; you’re switching between known, tested states.

The beauty? Problems in the build stage happen when developers are awake and watching. Problems in the run stage can be solved by rolling back to a known-good release. No more debugging in production at 3 AM.

Factor VI: Processes - The Stateless Mandate

Your app processes should be like workers on an assembly line—they process what comes to them but don’t store anything locally. Need to save data? Use a database. Need to cache something? Use Redis. Need to store files? Use S3.

When your processes are stateless, they become disposable. You can start them, stop them, crash them, multiply them—and your users never notice. It’s liberating.

Factor VII: Port Binding - Self-Contained Services

Your app should be completely self-contained, exporting its services by binding to a port. No runtime injection of web servers, no complex application containers—just your app listening on a port.

This means your Python app includes its own web server (like Gunicorn), your Ruby app brings Thin or Puma, your Java app packages Jetty. The app becomes a standalone service that says, “I’m listening on port 5000. Send me requests.” (This is why RESTful is so elegant—it is a standard that unify the world!)

Why does this matter? Because it makes your app composable. Today’s web app becomes tomorrow’s backing service for another app. Just point to its URL and port. It’s LEGO bricks all the way down.

Part 3: Operations - Running in the Wild

Factor VIII: Concurrency - Scale Out, Not Up

Typically when building local apps, the instinct is to make your app handle more concurrent request—add threads, increase the connection pool, optimize the event loop. They make things faster. But for web applications that needs to scale, the 12-factor way says: don’t.

Instead, keep your app simple—handle requests one at a time if that’s natural. Let the platform handle concurrency by running multiple copies of your process. Need to handle 10x traffic? Run 10x processes. It’s crude, but it works brilliantly.

Think of it like a restaurant. The traditional approach is training your one chef to cook faster, juggle more pans, multitask frantically. The 12-factor approach? Hire more chefs. Each chef works at a sustainable pace, and you scale by adding chefs, not by working them harder.

Factor IX: Disposability - Fast Startup, Graceful Shutdown

Your processes should be like Phoenix—ready to die and be reborn at a moment’s notice. Fast startup—meaning lazy approach, and graceful shutdown (finish current work, then exit cleanly).

This disposability enables the magic of modern deployment. Rolling updates, automatic scaling, self-healing systems—they all depend on processes that can be created and destroyed without drama.

Factor X: Dev/Prod Parity - Closing the Gap

The traditional gaps:

Time gap: Code written Monday, deployed next month
Personnel gap: Developers write, ops team deploys
Tools gap: SQLite in dev, PostgreSQL in production

The 12-factor approach obliterates these gaps:

Deploy hours or minutes after writing code
Developers are involved in deployment
Use the same backing services everywhere

We all know why mutex in multi-threading is important: it prevents race conditions where unpredictable things could happen when state is volatile. The same logic applies here: you want the gap to be as small and controlled as possible when you are between volatile / sensitive states so that you always have a preditive result, rather than chaos.

Part 4: Observability - Logs and Admin Tasks

Factor XI: Logs - The Event Stream

Your app should write logs like a diary writer who doesn’t care who reads it—just stream consciousness to stdout. Don’t manage log files, don’t rotate logs, don’t even think about where they go. Just write to stdout and let the platform handle the rest.

This seemed weird until I saw its power. In development, logs appear in your terminal. In production, the platform can route them anywhere—to files, to Elasticsearch, to DataDog, to multiple destinations simultaneously. Your app doesn’t know or care.

It’s the same philosophy: the app does one thing (emit events), the platform handles the complexity (routing, storage, analysis).

Factor XII: Admin Processes - One-Off Tasks in Familiar Territory

Database migrations, console sessions, data fix scripts—these admin processes should run in the same environment as your regular app processes. Same code, same config, same dependencies.

Why? Because nothing is worse than a migration script that works perfectly in staging but fails in production because of some subtle environmental difference. When admin processes run in identical environments, you eliminate an entire category of “works on my machine” problems.

The Revelation: It’s All About Contracts

The 12-factor methodology is never about the twelve specific factors. It’s about defining a clean contract between your application and the platform it runs on.

Your app promises:

To be stateless and disposable
To declare its needs explicitly
To communicate through standard interfaces
To log to stdout

The platform promises:

To provide configuration
To manage processes
To route requests
To handle logs

With this contract in place, something magical happens. Your app becomes truly portable. It can run on Heroku today, Kubernetes tomorrow, and whatever comes next. It can scale from one user to millions without code changes. It becomes a true building block—a LEGO brick that clicks perfectly into any modern infrastructure.