DEV Community: Jose Maria Cabeza Rodriguez

Domain-Driven Design: The Feynman Explanation

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 06:58:03 +0000

If you've been in software engineering long enough, you've likely encountered a codebase that feels impossible to understand. A simple feature request—like adding an urgent tag to an order—ends up breaking the shipping module and corrupting the billing records.

Why does this happen? Usually, it's because the software was built without deeply understanding the real-world business it was supposed to solve. Developers focused on database tables and APIs instead of focusing on the domain.

Enter Domain-Driven Design (DDD). Coined by Eric Evans in his seminal 2003 book, it is an approach to software development that centers the project on the core business domain.

Let's break down this famously dense topic using the Richard Feynman technique—simplifying complex ideas with everyday analogies.

1. The Big Picture: Strategic vs. Tactical

Domain-Driven Design is broadly divided into two distinct halves: Strategic Design and Tactical Design.

The interplay between Strategic (the "What" and "Why") and Tactical (the "How") design.

Strategic Design is for architects and business leaders. It's about deciding what to build, identifying what is truly important, and establishing clear boundaries so teams don't step on each other's toes.
Tactical Design is for the developers in the trenches. It provides specific coding patterns (like Entities, Value Objects, and Aggregates) to build complex business logic cleanly.

You cannot have a successful DDD project using only Tactical patterns—that's just writing clean code for the wrong problem. You must start with Strategy.

2. Strategic Design: The Restaurant Analogy

Before writing a single line of code, you must distill the large problem domain into smaller, manageable chunks called Subdomains.

Imagine you are building the software for a massive, global Restaurant Chain. The entire operation is your Business Domain. But you can't build it all at once, and not all parts are equally important.

Focus your best engineers on your core competitive advantage.

According to DDD, there are three types of subdomains:

Core Subdomain (The Secret Recipe): This is your competitive advantage. It's what makes the business unique. For a highly innovative restaurant, it's the recipe creation and menu optimization. The business must build this in-house with its best developers because it dictates their success.
Supporting Subdomain (The Reservation System): This is necessary for the business to function, but it doesn't give you a competitive edge. Your reservation system needs to work perfectly, but nobody chooses to eat at your restaurant because of the reservation software. You dedicate fewer resources here, or perhaps outsource it.
Generic Subdomain (Accounting & Payroll): This is a complex problem, but it's the exact same problem every other company has. You do not gain a competitive advantage by inventing your own payroll software. You simply buy an off-the-shelf solution.

3. Resolving the Tower of Babel: Ubiquitous Language

The number one reason software projects fail isn't technology; it's miscommunication between the people building the software and the people using it.

Developers talk about "Rows," "Foreign Keys," and "DTOs." Business experts talk about "Policyholders," "Claims," and "Underwriting."

Eradicating translation layers through a shared language.

DDD forces both sides to agree on a Ubiquitous Language. This is a strict, shared vocabulary. If the business expert calls it a "Guest," the developer cannot create a database table called Users. The code must reflect the business language perfectly. If a new developer reads the code, it should read like a manual for the business.

4. Setting Fences: Bounded Contexts

As a company grows, the Ubiquitous Language hits a wall. Different departments use the exact same word to mean completely different things.

A word is only meaningful within a specific boundary.

Take the word Customer.

To the Sales Team, a Customer is a lead—someone they are trying to convert. They care about email open rates and sales funnels.
To the Shipping Team, a Customer is a physical address and a box dimension.
To the Customer Support Team, a Customer is a ticket history and an SLA (Service Level Agreement).

If you try to build one giant Customer class in your code that satisfies all three departments, you will create a monstrous, fragile "Big Ball of Mud."

Instead, DDD tells us to create Bounded Contexts. A Bounded Context is a strict boundary (usually a separate microservice) where a specific model applies. Inside the "Shipping Context," the word Customer strictly means a shipping profile. Inside the "Sales Context," it strictly means a lead.

The Context Map

Because these Bounded Contexts eventually need to talk to each other to form a working business, architects draw a Context Map to define their relationships.

Defining the political and technical integration between teams.

For instance, if the Shipping Context relies on a shady third-party logistics API, you build an Anti-Corruption Layer (ACL) between them, so the messy third-party code doesn't infect your pristine internal model.

5. Tactical Design: The Solar System of Aggregates

Once the strategy is set, we move to the code. Complex business logic involves objects updating each other. If any object can update any other object directly, your database becomes a tangled web of inconsistencies.

To solve this, DDD introduces the concept of an Aggregate.

Aggregates act as the strict gatekeepers of consistency.

Think of an Aggregate like a Solar System.

The Sun (Aggregate Root): There is one main object at the center, like an Order.
The Planets (Entities and Value Objects): Other objects orbit it, like OrderLines (the items bought) or the ShippingAddress.

The strict rule of DDD is that nothing outside the solar system is allowed to touch the planets directly.

If the payment service wants to change an OrderLine, it cannot just reach in and update it. It must go to the Sun (the Order Aggregate Root) and ask it to make the change. The Order will then check all the business rules (e.g., "Is the order already shipped?") and only then modify the OrderLine.

By forcing everything through the Aggregate Root, you guarantee that your business rules are never bypassed and your data is always perfectly consistent.

The Verdict

Domain-Driven Design is not easy. It requires an upfront investment in time, communication, and architectural planning that many teams are too impatient to make.

However, when you are building complex enterprise software, DDD provides a vocabulary and a roadmap to prevent your codebase from degenerating into a chaotic mess. It reminds us that our primary job isn't to write algorithms—it's to capture business knowledge and turn it into working software.

References

This guide synthesizes principles and concepts from the following definitive texts on the subject:

Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans (The "Blue Book")
Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy by Vladik Khononov
Domain-Driven Design: A Pragmatic Approach by Eduard Ghergu
Domain-Driven Design: The First 15 Years (Essays from the DDD Community)

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-ddd.

The Feynman Guide to Co-Intelligence

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 06:58:01 +0000

Imagine walking into a library where the books have literally read themselves. They’ve absorbed every word, every comma, and every rhythmic cadence of human thought.

But there’s a catch: the library doesn’t have a librarian. It just has a very, very talented parrot.

Welcome to the world of Large Language Models (LLMs). To master them, we have to understand the difference between mimicry and meaning.

1. The Talented Parrot (Statistical Mimicry)

Richard Feynman once said, "Knowing the name of something isn't the same as knowing the thing."

LLMs are the ultimate "name-knowers." At their heart, they are statistical engines. When you ask an LLM a question, it isn't "thinking" in the biological sense. It is calculating a probability distribution over the next possible token (a word or piece of a word).

Using a mathematical function called Softmax, the model looks at the context you've provided and predicts which word is most likely to follow. If I say, "The cat sat on the...", the model doesn't "see" a mat. It sees that in billions of lines of text, the token "mat" follows that sequence with 98% probability.

Key Takeaway: LLMs are "Stochastic Parrots." they are incredibly good at mimicking the structure of human knowledge without necessarily possessing a model of the world.

2. The Common Sense Gap

As Gary Marcus argues in Rebooting AI, statistical models have a "Common Sense Gap." They can write a beautiful poem about a glass of water, but they might not realize that if you flip the glass, the water will fall.

Because they learn from text, not from physical interaction, they lack a World Model. They understand symbols, but not the grounded reality behind them. This is why an LLM can provide a perfect medical diagnosis in one breath and hallucinate a non-existent law in the next. They are playing a game of "infinite word-association."

3. The Digital Butler (Autonomous Agents)

How do we fix a parrot that doesn't understand the world? We give it a Librarian.

In modern engineering, we call these AI Agents. An Agent is an LLM wrapped in a "reasoning loop" (like ReAct: Reason + Act). Instead of just answering you, the Agent can:

Search for real-time data (RAG - Retrieval Augmented Generation).
Use Tools (Calculators, APIs, Python interpreters).
Reflect on its own errors and try again.

By connecting the "brain" (the LLM) to "hands" (APIs), we bridge the gap between theory and action. The Agent doesn't just talk about the library; it goes to the shelf, grabs the right book, and checks the facts.

4. Co-Intelligence: The Partnership Era

The final shift isn't technical—it's psychological. Ethan Mollick, in Co-Intelligence, suggests we are moving past the era of "AI as a tool" and into the era of "AI as a partner."

Think of it like a Handshake. You bring the human intent, the moral compass, and the common sense. The AI brings the vast, statistical scale, the tireless processing, and the creative spark.

When these two meet, you don't just get a better search engine. You get Co-Intelligence—a collaborative intelligence that is greater than the sum of its parts.

📚 References & Further Reading

This post was synthesized from the foundational concepts found in:

Raschka, Sebastian. Build a Large Language Model (From Scratch). Manning Publications. (Structural mechanics of transformers).
Marcus, Gary & Davis, Ernest. Rebooting AI: Building Artificial Intelligence We Can Trust. Pantheon. (The Common Sense Gap).
Mollick, Ethan. Co-Intelligence: Living and Working with AI. Portfolio. (The partnership framework).
Lanham, Michael. AI Agents in Action. Manning Publications. (Agentic design patterns).
Alammar, Jay. Hands-On Large Language Models. O'Reilly Media. (Visualizing the attention mechanism).

Master the deepest functional layers of modern AI—from the foundational next-token prediction to the high-level orchestration of agentic systems.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-co-intelligence.

Modular monolith vs microservices: a practical guide

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:54:26 +0000

Modular monolith vs microservices: a practical guide

The debate usually goes like this:

"We should move to microservices. Monoliths don't scale."

Or the backlash:

"We should go back to a monolith. Microservices are overengineered."

Both positions are wrong because they are categorical. They treat architecture as theology rather than engineering.

The right question is not which is better. The right question is which is appropriate for our current constraints, team size, and growth trajectory.

Let me give you a practical framework.

What a modular monolith actually is

A modular monolith is not a big ball of mud. It is a single deployable unit where the code is organised into well-defined modules with explicit boundaries, enforced through code rather than network.

Think of it as microservices at the code level instead of the infrastructure level. Each module owns its domain logic. No cross-module access to internals. Communication happens through defined interfaces.

The boundary is a Java package, a Python module, a TypeScript namespace — not an HTTP endpoint.

The advantages

Simpler operations: one thing to deploy, one thing to monitor, one database to care about
Lower latency: in-process calls instead of network calls
Easier refactoring: moving code across module boundaries is cheaper than re-designing service contracts
Atomic transactions: you can use ACID transactions across domain boundaries trivially
Faster onboarding: new engineers can understand the system by reading the code

The trade-offs

Scaling is all-or-nothing: you can't scale your hot module independently
Technology lock-in: the whole app runs on one tech stack
Deployment coupling: a bug in one module can take down everything
Team coordination: merge conflicts and PR reviews cross module boundaries

What microservices actually buy you

Microservices are not about scalability. Or rather, they are, but not in the way most people think.

The real value of microservices is independent deployability. The ability for one team to change, test, and ship their service without coordinating with any other team. That is the primary reason to reach for them.

As a consequence of independent deployability, you get:

Independent scaling — you can allocate resources where the load is
Technology flexibility — each service can use the right tool for the job
Blast radius reduction — a failing service can be isolated

But you also inherit:

Distributed systems complexity: network partitions, partial failures, eventual consistency
Operational overhead: service discovery, load balancing, distributed tracing, per-service CI/CD
Data management complexity: cross-service joins, sagas, event sourcing
Organisational prerequisites: you need Conway-aligned teams to make this work

A decision framework

Here is how I think about the choice:

Start with a modular monolith if:

You are building something new (0→1)
Your team is smaller than ~20 engineers
You have not yet found product-market fit
You cannot invest in serious platform infrastructure
Your main scaling concern is code complexity, not infrastructure throughput

The modular monolith keeps you fast. You can iterate quickly, refactor aggressively, and you do not need a DevOps team to manage your deployment topology.

Extract services when:

A specific module has demonstrably different scaling requirements
A specific team needs completely autonomous deployment velocity
A module has such a different availability requirement that it needs independent SLOs
You are adding a fundamentally different technology that cannot co-exist in the current stack

Notice the emphasis on specific. Not "let's carve out services in advance" but "this module, right now, has a concrete need that only a service boundary solves."

The migration path

If you're starting a modular monolith today, design it with a service extraction path in mind:

Enforce module boundaries from day one — use linting or architecture tests to prevent cross-module coupling
Design module APIs as if they were service APIs — explicit inputs, explicit outputs, no shared state
Use domain events internally — even within the monolith, emit business events that other modules consume asynchronously
Own your data per module — even if it's the same database, keep tables namespaced to their owning module

When the time comes to extract a service, you lift the module out. The API is already defined. The data ownership is already clear. You change the transport layer from function calls to HTTP/events.

That is the strangler fig pattern applied intentionally from day one.

The bottom line

The best codebase I have ever worked on was a well-structured modular monolith serving 10M users. The worst distributed system I have ever inherited was an over-engineered microservices mesh with 60 services and a team of 8 engineers who could not deploy anything without breaking three other things.

Architecture is a trade-off, not a verdict. Use the right tool for your current moment — and build with the next moment in mind.

Originally published at https://chemacabeza.dev/writing/monolith-vs-microservices.

Performance is a product feature

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:53:51 +0000

Performance is a product feature

There is a mental model that corrupts how most engineering teams think about performance:

"Functional requirements first. Non-functional requirements later."

Performance gets put in the "nice to have" box. It is addressed retroactively, after the feature is shipped, after users are complaining, after the performance regression has baked into the architecture.

This is exactly backwards.

Performance is not a technical constraint. It is a product experience. And like any product experience, the later you address it, the more expensive it becomes to fix.

The data is not ambiguous

A 100ms improvement in page load time correlates with +1% revenue for e-commerce (Amazon, 2012)
53% of mobile users abandon sites that take more than 3 seconds to load (Google)
Pinterest reduced page load time by 40% and saw a 15% increase in SEO traffic
A 1-second delay in response time results in 7% reduction in conversions

These figures are old. The bar has gotten higher, not lower. Users have been conditioned by the best-performing apps in the world. Slack, Linear, Figma — perception of speed is now a key differentiator.

The slow app is the bad app. Even if it has more features.

Performance as user experience

Think about what it feels like to use a slow product.

You click something. There's a delay. You wonder if it registered. You hover. You click again. Now you've done it twice. The UI catches up with a double-action. You feel friction. You feel mild anxiety. Over 100 sessions, that anxiety accumulates into a general negative perception of the product.

Fast software feels respected. It says: we value your time. Every interaction affirms that the product was built with care.

Slow software communicates the opposite: we didn't think about you.

Performance is not about benchmarks. It is about the emotional texture of using a product.

It compounds in both directions

The dangerous thing about performance regressions is that they compound.

Each feature ships with a marginal performance cost. Database query that doesn't have an index. Synchronous call that could be async. One extra round trip to validate something that could be cached.

Individually, invisible. Cumulatively, devastating.

After 18 months, the fast startup app that could load in 400ms now takes 2.3 seconds. The team does not know when it happened. Bisecting the git history reveals dozens of commits each contributed 20ms. No single villain. Death by a thousand cuts.

The inverse is also true. Systematic performance hygiene compounds into product excellence. Every engineer who thinks about the cost of what they ship creates a culture where performance is maintained, not recovered.

What systematic performance culture looks like

Measure what matters. Set SLOs on user-facing latency (P50, P95, P99 — not just average). Track bundle size. Track Core Web Vitals. Make regressions visible on every PR.

Treat performance budgets like test coverage. Would you merge a PR that drops test coverage by 20%? Then why merge one that increases bundle size by 40KB with no justification?

Design for performance. The most impactful performance work happens in the design phase, not the optimization phase. The right data model, the right caching strategy, the right API contract — these decisions are made before a line of code is written.

Celebrate performance wins publicly. When an engineer reduces P95 by 40%, that is a product improvement. Treat it like one. Put it in the changelog. Mention it in the all-hands. Signal that this work is valued.

Make it easy to understand performance. Every engineer should have access to production latency dashboards, flame graphs, and query plans. Observability is the prerequisite for performance culture.

The engineering manager's responsibility

If you are an engineering manager, you are ultimately responsible for the performance culture of your team.

That means:

Including performance criteria in your definition of done for every feature
Refusing to accept "we'll fix it later" as an answer for known performance issues
Prioritising performance work in your roadmap before it becomes critical
Praising and rewarding the engineers who do the unsexy work of making things faster

You get the culture you tolerate. If you tolerate slow, you get slow.

Close

The next time you hear "we'll optimize after the feature is shipped" — that is a red flag.

Performance is not something you bolt on. It is something you design in. It is the difference between a product that feels like a pleasure to use and one that feels like a chore.

Ship fast code. Your users will know the difference, even if they can't articulate why.

Originally published at https://chemacabeza.dev/writing/performance-is-a-product-feature.

Microservices vs Monoliths: The Feynman Explanation

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:53:50 +0000

If you spend enough time around software engineers, you'll eventually hear a heated debate about Monoliths versus Microservices. People argue about them as if choosing the wrong one will doom a company forever.

But what do these terms actually mean? If we cut out the jargon and the buzzwords, how do they actually work?

Let's use the Richard Feynman technique—simplifying complex concepts using everyday analogies—to break down this massive debate. We'll also layer in some deep insights from industry giants I've been studying, like Sam Newman and Mark Richards.

1. The Monolith: The Giant Swiss Army Knife

Imagine you are going camping. You decide to buy a survival tool. You buy an enormous, 150-tool Swiss Army Knife. It has a knife, a saw, a magnifying glass, a compass, a spoon, a laser pointer—everything you could possibly need, all built into a single, cohesive handle.

This is exactly what a Monolithic Architecture is.

A monolithic architecture is like a massive, deeply interconnected machine. Everything runs together in one place.

In software, a monolith is an application where all the code—the part that handles user login, the part that processes credit cards, the part that sends emails—is packed into one single program. It all deploys together, runs together, and lives together.

Why the Monolith is Great

It's simple to build: When you start a company, you don't need a complex factory. You just need a tool that works. Development is fast because all the code is right there in one place.
It's easy to test and deploy: To put it on the internet, you just copy one big folder to a server and hit "run."
Everything communicates instantly: Because all the tools are in the same handle, the user login system can directly "talk" to the email system with virtually zero delay (in-memory calls).

When the Monolith Fails

Eventually, your company grows.

You hire 500 engineers, and they are all trying to update the same single app at the same time. It's like 500 people trying to sharpen different tools on the same Swiss Army Knife simultaneously. People bump elbows. Things break. (We call this deployment coupling).
If the "credit card processor" part of the app crashes because of a bug, it brings the entire app down. The single handle breaks.

2. Microservices: The Workshop of Experts

Because the giant Swiss Army knife got too heavy and kept jamming, you decide to change your strategy.

Instead of one tool that does everything, you build a workshop. You hire a master chef who only cooks. You hire a master lumberjack who only cuts wood. You hire an expert navigator who only reads compasses. They each have their own independent, specialized tools and they work in separate rooms.

This is a Microservices Architecture.

A microservices architecture functions like a constellation of specialized, flying drones. They operate independently but talk to each other over a network.

In software, you chop your giant Monolith into dozens (or hundreds) of tiny, independent programs. One program only handles login. Another only processes payments. They communicate with each other by sending messages over the network (like the chef calling out an order to the lumberjack).

Why Microservices are Great

Independent Teams: You can have 10 engineers working on the "Payment Service" and 10 working on the "Email Service." They don't step on each other's toes because they are working in entirely separate codebases.
Independent Scaling: If it's Black Friday and the payment service is getting hammered, you can just duplicate the "Payment" expert 50 times without needing to duplicate the rest of the application.
Blast Radius: If the email service crashes, the rest of the app (like logging in or buying things) can stay alive.

When Microservices Fail

Microservices are heavily romanticized, but they introduce a terrifying new type of complexity.

The network is unreliable: In the monolith, changing data was instant. Now, your services have to yell at each other over the internet. What if a message gets lost?
Data is scattered: You no longer have one giant database. You have 50 small databases. Trying to put together a single "Order History" requires asking five different services for pieces of the puzzle. This violates the simplicity of absolute truth.
Debugging is a nightmare: When a user clicks a button and gets an error, that request might have bounced through 15 different microservices. Finding out which one failed is like finding a needle in a haystack.

3. Insights from the Masters

If we look at the heavyweights in System Design, they all agree on one thing: There are no silver bullets, only trade-offs.

In Software Architecture: The Hard Parts, Neal Ford and Mark Richards emphasize that breaking apart a monolith isn't just about code—it's about managing data. Once you split the database, achieving consistency (making sure all the systems agree on the truth) becomes incredibly difficult. They coined the phrase: "Architecture is the stuff you can't google."

Martin Kleppmann, in Designing Data-Intensive Applications, points out that distributed systems (like microservices) force you to deal with partial failures. You have to assume that at any given moment, something is broken, and build your system to tolerate it.

And Sam Newman, author of Monolith to Microservices, has a stark warning for the industry: Start with a monolith. He advises against building microservices from day one. You should only adopt them when the monolith becomes too painful for your organization to scale. Microservices primarily solve organizational problems (too many developers stepping on each other), not necessarily technical problems.

The Verdict

If you are a startup or a small team, build a Monolith. Keep the Swiss Army Knife. It is fast, efficient, and reliable. Understand your domain first.

If you are Netflix, Amazon, or a massive organization with hundreds of engineering teams, you need Microservices. You need the specialized workshop, even if it means paying a massive "distributed systems tax" in complexity.

Architecture is not about finding the "best" pattern. It's about finding the pattern that fits the problems you have right now.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-microservices.

Serverless Computing: The Feynman Explanation

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:53:15 +0000

Serverless is one of those buzzwords that gets thrown around constantly in modern software engineering. If you read the marketing materials, it sounds like some kind of magic that eliminates all your infrastructure problems. On the other hand, if you read internet forums, it sounds like an overcomplicated, overpriced nightmare.

But what does "Serverless" actually mean?

Let's use the Richard Feynman technique—simplifying a complex concept by breaking it down into everyday analogies—to understand what Serverless really is, where it came from, and why it matters.

1. The Evolution of Hosting: From Bedrooms to the Cloud

To understand Serverless, we first have to understand what came before it. Let's look at the evolution of how we host software.

From physical hardware to invisible utility computing.

Physical Servers: In the beginning, you literally owned a computer. You bought it, plugged it in, and connected it to the internet. If the power went out, your site went down.
Colocation: You realized your bedroom wasn't a great place for a server, so you started renting space in a professional data center. You still bought the server, but they provided reliable power and internet.
Virtualization / Cloud: Instead of buying physical hardware, you rented "virtual" computers (Virtual Machines) from companies like Amazon or Google. You could get a new server in minutes instead of weeks.
Platform as a Service (PaaS): Companies started offering platforms where you just upload your code, and they handle the virtual machines and web servers for you.
Serverless: The final evolution. The servers become entirely invisible. You just write small functions, and the cloud provider runs them, scales them, and manages everything automatically.

(Wait, so there are still servers in Serverless? Yes! The "-less" in Serverless doesn't mean "without servers." It means "servers are invisible to you." Just like "wireless" internet still uses wires, it's just that *your device doesn't have a wire plugged into it.)*

2. The Restaurant vs. The Food Truck

The best way to understand the core benefit of Serverless is billing and utilization.

Imagine you want to start selling burgers.

You rent a traditional restaurant building. You hire a chef. You pay for electricity, water, and rent.
During the lunch rush, you are slammed. But at 3:00 AM? Your restaurant is completely empty. Your chef is sitting there, bored. The lights are on. You are burning money. You pay rent whether you have 100 customers or zero.

This is exactly how traditional servers work. You rent a server, and you pay for it 24/7, even when no one is visiting your website.

With Serverless, you only pay exactly for what you consume.

Now, imagine a magical Food Truck on Demand.
When a customer walks up and asks for a burger, the truck pops into existence, cooks the burger, hands it over, and then vanishes. This is Serverless.

With Serverless, you don't pay "rent" for an idling server. You only pay for the exact milliseconds that your code is actually running. If nobody visits your website for a month, your hosting bill is exactly $0.00.

3. How a Serverless Function Actually Works

In a Serverless architecture, you don't build one giant application. Instead, you write tiny snippets of code called Functions (like AWS Lambda).

These functions are designed to do exactly one thing, and they only wake up when something explicitly triggers them.

A function wakes up, does its job, and goes back to sleep.

Here is the lifecycle of a Serverless function:

The Trigger (Event): Something happens. A user clicks a button, a file is uploaded, or a scheduled timer goes off.
The Wake Up: The cloud provider spins up a tiny, invisible container for your code.
The Execution: Your code runs. It might read from a database, process some data, or return a JSON response.
The Sleep: Once the function finishes returning the response, the container is destroyed. You stop paying.

4. The Event-Driven Workshop

Because everything in Serverless is built out of these tiny, temporary functions, the architecture looks very different from a traditional system.

It becomes an Event-Driven Architecture. Instead of one central program giving orders, you have a giant nervous system where different services react to events as they happen.

In an event-driven system, functions react seamlessly to changes, working together like a symphony.

Think of it like a chain reaction factory:

A user uploads an image to cloud storage.
Event! The storage bucket yells, "I got a new file!"
The ImageResizer function hears this, wakes up, compresses the image, and saves it.
Event! The ImageResizer yells, "I made a smaller image!"
The DatabaseUpdater function hears this, wakes up, and records the new image URL in the database.

It is a deeply uncoupled, highly scalable way to build software. If 10,000 users upload an image at the exact same second, the cloud provider simply wakes up 10,000 copies of your ImageResizer function simultaneously. No servers crash, no systems slow down.

5. The Trade-offs: The Cold Start Problem

If Serverless is so amazing, why doesn't everyone use it for everything?

Remember earlier when we mentioned the "magical food truck" that pops into existence? Well, popping into existence takes a tiny bit of time.

If a function hasn't been used recently, the cloud provider will tear down its container to save resources. When the next request comes in, the system has to find an empty server, download your code, configure the environment, and load your program into memory before it can actually run.

This is called a Cold Start.

Cold starts add latency to your first request.

If your car is already running (a Warm Start), hitting the gas makes you move instantly.
If your car is cold in the garage, it takes time to open the door, turn the key, let the engine catch, and finally shift into drive.

For many applications, a cold start delay of a few hundred milliseconds is completely unnoticeable. But if you are building an ultra-low-latency high-frequency trading platform, or a fast-action multiplayer game, that slight hesitation can be a dealbreaker.

The Verdict

Serverless represents a monumental shift in how we think about computing. By giving up control over the physical infrastructure, engineers gain the ability to scale infinitely without actively managing servers, and businesses gain a pricing model that perfectly matches their actual usage.

Just like moving from physical servers to the Cloud, Serverless isn't just a different way to host code—it's a fundamentally different way to design and build systems.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-serverless.

Large Language Models: The Feynman Guide

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:53:12 +0000

Have you ever wondered how ChatGPT or Claude seems to "understand" you? To many, it feels like magic. To others, it's just "fancy autocomplete."

But if we peel back the layers and look at the actual engineering—the same stuff I've been studying in books by pioneers like Sebastian Raschka and Jay Alammar—we find something far more fascinating than magic.

Let's use the Richard Feynman technique—simplifying complex systems using everyday analogies—to understand how Large Language Models (LLMs) actually work.

1. Tokenization: The Lego Bricks of Language

Computers don't actually read words like "Elephant" or "Hydrogen." They only understand numbers. So, how do we bridge the gap?

Imagine you have a massive box of Legos. Every word in the human language is built from smaller, reusable blocks. Instead of having a single block for "unhappy," we might have a block for "un" and a block for "happy."

Tokenization is the process of breaking language into subword units. It allows the model to understand words it has never seen before by looking at their pieces.

This is Tokenization. Most modern LLMs use a technique called Byte Pair Encoding (BPE). It breaks words down into the most efficient "bricks" possible. This is why an LLM can understand "Antidisestablishmentarianism"—it doesn't need to know the whole word; it just snaps together the pieces it already knows.

2. Attention: The Spotlight in the Library

Once the model has the Lego bricks, it needs to figure out what they mean in context. This is where the Transformer architecture comes in, and its secret weapon is called "Self-Attention."

Imagine you are in a pitch-black library with a single spotlight. You are trying to figure out what the word "it" refers to in the sentence: "The bank was closed because it was a holiday."

Does "it" refer to the bank? Or the holiday?

The Attention mechanism acts like a spotlight, allowing the model to focus on the most relevant words in a sentence to determine context.

The model uses its spotlight to scan the entire sentence at once (not left-to-right, like a human). It shines the light on "bank" and then on "holiday." It calculates which word has the strongest "relationship" to the word it's currently looking at. In this case, the spotlight lingers on "holiday" to explain the "why." This mathematical spotlight is what allows AI to "understand" nuance.

3. Training: The Self-Reading Student & The Teacher

How does the model learn where to shine the spotlight? It goes through two main phases of school.

Phase 1: Pre-training (The Self-Reading Student)

The model is given the entire internet. It plays a game of "Guess the Next Word" billions of times. It's like a student who reads 100,000 libraries but has no teacher. It learns the patterns of language, but it doesn't always learn how to be helpful. It might learn how to write a poem, but also how to argue or be rude.

Phase 2: RLHF (The Teacher's Feedback)

To turn that raw "pattern-matcher" into a helpful assistant, we use Reinforcement Learning from Human Feedback (RLHF).

Human "teachers" review the model's outputs and give it a thumbs up or thumbs down. Over time, the model "grows" into a helpful and safe assistant.

Think of it like watering a plant. We "water" the responses that are helpful, honest, and harmless, and we "prune" the ones that are confusing or dangerous. This is how we get from a chaotic text-guesser to a tool like ChatGPT.

4. RAG: The Open-Book Exam

One big problem with LLMs is that they have a "knowledge cutoff." They only know what they read during their initial school years. If you ask them about news from yesterday, they might guess (or "hallucinate").

To fix this, we use Retrieval Augmented Generation (RAG).

Imagine you are taking a history exam. You are a smart student with a great memory, but your teacher lets you use a library during the test. When you get a question you aren't 100% sure about, you don't guess—you walk to the shelf, grab the right book, and read the answer.

RAG allows the model to look up real-time, factual information from a secure "Vector Database" before answering, drastically reducing errors.

This is why modern AI "Agents" are so powerful. They don't just "know" things; they know how to find things.

References & Further Reading

This post was synthesized from the foundational concepts found in these exceptional engineering resources:

Build a Large Language Model (From Scratch) by Sebastian Raschka. (Essential for understanding the Transformer architecture and Attention).
LLM Engineer’s Handbook by Paul Iusztin & Maxime Labonne. (Great for RAG and Production patterns).
Hands-On Large Language Models by Jay Alammar & Maarten Grootendorst. (The gold standard for visual explanations of NLP).
Building LLMs for Production by Louis-François Bouchard. (Deep dive into reliability and evaluation).

The Verdict

LLMs aren't thinking beings—they are massive, incredibly sophisticated pattern-matching engines. They break language into bricks, use spotlights to find context, learn from human teachers, and pass open-book exams using databases.

By understanding these simple components, we can stop seeing AI as a "black box" and start seeing it for what it truly is: The most powerful language tool humanity has ever built.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-llms.

Why most microservices architectures fail

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:52:01 +0000

You have almost certainly worked in a codebase that someone called a "microservices architecture" — and you have almost certainly thought: this is worse than a monolith.

You are not wrong. Most microservices implementations are worse than the monolith they replaced. The promise was independence, speed, and resilience. The delivery was a distributed mess of HTTP calls, a shared database with 12 owners, and log files scattered across 30 services.

Let me explain why this keeps happening — and what the engineers who get it right have in common. I am going to use the Richard Feynman technique: if I cannot explain it simply enough for a 12-year-old to understand the core idea, I do not understand it well enough myself.

The material here synthesizes insights from the most important books in the field: Sam Newman's Monolith to Microservices, Neal Ford and Mark Richards' Software Architecture: The Hard Parts, Martin Kleppmann's Designing Data-Intensive Applications, and Adam Bellemare's Building Event-Driven Microservices.

The Feynman Foundation: What is a Microservice, Really?

Before we talk about failure, let us make sure we agree on what the thing actually is.

Imagine a pizza restaurant. In a monolith, one person does everything: takes the order, makes the dough, adds the toppings, cooks the pizza, delivers it to the table, and processes the payment. Everything is in one place. Easy to understand. Easy to debug. If that one person gets sick, everything stops.

In a microservices architecture, you hire specialists. One person takes orders. One chef makes dough. One manages toppings. One operates the oven. One delivers. Each person can be replaced independently. You can hire two oven operators on a busy Saturday without hiring two of everyone else. That is independent scaling.

Sounds great, right?

Here is where the analogy breaks down — and where most real implementations go wrong. Those specialists still need to communicate. They need to coordinate orders. They need to share information about which pizzas are ready. And crucially, they need someone to be in charge of knowing the state of every order.

In software, that coordination problem is everything. Most teams solve the technical decomposition (splitting the code) but completely ignore the coordination problem (splitting the data and managing consistency). That is the root of every failure mode we will discuss.

Failure Mode 1: The Distributed Monolith

Six services, six teams — one shared database. This is not microservices. This is a monolith you made more expensive to operate.

This is the single most common failure, and it is almost poetic in its irony.

A team splits their application into six services. The OrderService, UserService, PaymentService, and three others. They deploy them on separate pods. Different Git repositories. Different CI pipelines. It feels like microservices.

But all six services connect to the same PostgreSQL database.

Here is what Neal Ford and Mark Richards call the core problem in Software Architecture: The Hard Parts: the database is the real contract between services. When OrderService reads from the users table that UserService owns, you have created a silent coupling that no amount of separate deployments can fix. Change the schema in UserService, and you silently break OrderService. You cannot deploy independently. You are back to a monolith — but now you also have network calls instead of in-process calls.

The Feynman version: Imagine our pizza restaurant where all six specialists write their notes in the same shared notebook. If the order-taker changes the format of her entry, the chef misreads the toppings. You have not made the restaurant more efficient; you have made the notebook a single point of failure that everyone has to negotiate around.

The fix from Sam Newman is unambiguous: each service must own its data storage entirely. Cross-service data access flows through APIs or events. Never through a shared database. Period.

Failure Mode 2: Synchronous Everything — The Cascade of Death

A chain of six synchronous HTTP calls. One slow service at the end turns into a 503 for the entire system.

Here is a call pattern I find in nearly every struggling microservices codebase:

User Request
  → Gateway (REST)
    → OrderService (REST)
      → PaymentService (REST)
        → InventoryService (REST)
          → NotificationService (REST)  ← 500ms timeout

Every call is synchronous. Every service waits for the next one. The chain is six hops long.

Martin Kleppmann dedicates a significant section of Designing Data-Intensive Applications to what he calls partial failures — a property unique to distributed systems and completely absent from monoliths. In a monolith, a function either succeeds or throws an exception. In a distributed system, a remote service can be slow, partially available, or return a stale response without any clear signal about which it is.

When NotificationService takes 500ms to respond, InventoryService is blocked waiting. That means PaymentService is blocked waiting for InventoryService. That means OrderService is blocked waiting for PaymentService. The user's request now takes 3 seconds just from waiting, before even adding the actual processing time.

The Feynman version: Imagine our pizza specialists forming a line where each one has to wait for the next before doing anything. The pizza-delivery specialist stands still until the oven operator is done. The oven operator stands still until the topping specialist finishes. One slow step blocks the entire kitchen.

The fix is to default to asynchronous, event-driven communication. If NotificationService is not in the critical path (does the user need the email confirmation before their order is confirmed?), publish an event to a message broker. NotificationService consumes it when it is ready. The user's order goes through in 50ms. The email arrives slightly later. The system as a whole is far more resilient.

Adam Bellemare's Building Event-Driven Microservices makes this case with industrial-scale examples: organisations that truly decouple their services through events stop having cascading failures. The blast radius of a single service failure is contained because nothing is waiting synchronously upstream.

Failure Mode 3: The Wrong Decomposition — Services Along Technical Layers

This failure mode is less dramatic but deeply debilitating. It happens when engineers decompose their system by technical concern rather than business capability.

I have seen this more times than I can count:

FrontendService owns all the React code
BackendService owns all the Java code
DatabaseService manages the data layer

Three "services." None of them independently deployable in any meaningful way. Adding a new business feature — say, a user preference panel — requires changing all three simultaneously, coordinating three deployments, and testing the integration between all three.

Mark Richards and Neal Ford describe this as a failure to understand bounded contexts, drawn from Domain-Driven Design. A bounded context is the natural language boundary of a domain. Inside it, every term has a single, unambiguous meaning. The Customer in the Billing context might be entirely different from the Customer in the Support context. Trying to merge them into a single CustomerService owned by three teams is a recipe for infinite coordination overhead.

The Feynman version: Imagine our restaurant decided to specialise by ingredient type rather than role. One specialist handles everything involving tomatoes. One handles everything involving cheese. One handles everything involving dough. To make a Margherita pizza, all three have to coordinate work at the same time. You have not made the kitchen more independent; you have forced three people to tightly collaborate on every single pizza.

The fix is to decompose around business capabilities: OrderManagement, CustomerNotifications, InventoryControl. Each one maps to a team, owns its own data, and can be deployed, scaled, and rewritten independently.

Failure Mode 4: Conway's Law Violated

When the organisation is structured around technical layers, the architecture it produces will be a technically-layered distributed monolith.

Melvin Conway observed in 1967 that "organisations which design systems are constrained to produce designs which are copies of the communication structures of those organisations." This was a sociological observation, not a technical one. But it is one of the most powerful lenses for understanding why microservices fail.

If your organisation has a separate Frontend Team, Backend Team, and DBA Team — your microservices will be a FrontendService, BackendService, and a shared database. Not because engineers made bad technical decisions, but because teams naturally build systems that mirror how they communicate.

Neal Ford and Mark Richards are explicit about this in Software Architecture: The Hard Parts: you cannot fix an architectural problem without fixing the organisational problem first. If the org chart forces two teams to own the same service, or one team to own five services that need to change together — no architectural pattern will save you.

The Feynman version: Imagine a kitchen where the chefs report to one manager, the waiters to another manager, and the kitchen cleaners to a third. Every decision about how to improve service requires all three managers to agree. The kitchen will reflect that friction — slow handoffs, unclear ownership, constant coordination overhead.

The fix — what Spotify famously called "squads" and what Sam Newman calls "stream-aligned teams" — is to structure your teams around business outcomes, not technical functions. Each team owns a full slice of the system from end to end.

Failure Mode 5: No Observability

In a monolith, debugging is simple. In microservices without distributed tracing, a production bug is a ghost in a machine with 30 compartments.

Here is a scenario that will be uncomfortably familiar to many engineers.

A user reports that their checkout process sometimes fails. In a monolith, you grep the log file. You find the exception. You fix it. Twenty minutes of work.

In a microservices system with 15 services and no distributed tracing: you look at the API Gateway logs. No error there. You check OrderService. No error. You check PaymentService. A warning, but it resolved. InventoryService? NotificationService? You are now in hour three, SSH-ing into different container logs, trying to find one failed request among millions.

This is the observability gap. Ian Gorton, in Foundations of Scalable Systems, describes distributed systems observability as a first-class architectural concern — not a post-launch operational task. Without three things — structured logging with correlated trace IDs, distributed tracing (OpenTelemetry), and meaningful SLIs and SLOs — debugging a microservices system at production scale is functionally impossible.

The Feynman version: Imagine 30 pilots flying in formation, and your dashboard in the control tower shows you... nothing. No altimeters. No fuel gauges. No radio. If any pilot deviates, you will not know until they crash.

The fix is non-negotiable: every service ships with structured JSON logs that carry a traceId on every log line. Every service emits distributed traces using OpenTelemetry. You never add a service without adding its observability layer first.

The Right Way: Extract, Don't Prematurly Decompose

The decision to extract a service should be driven by demonstrated organisational or scale pain — not architectural ambition.

Sam Newman's Monolith to Microservices offers what I consider the most honest advice in the field: start with a monolith. Build your understanding of the domain first. Let the bounded contexts emerge from real usage. Then, when specific, demonstrable pain appears — a team that cannot deploy independently, a component that needs a different scaling profile — extract that component surgically.

The organisations I have studied that run microservices well share a set of traits that the failing ones do not:

Trait	Failing Organisations	Successful Organisations
Starting point	Greenfield microservices	Well-understood monolith
Decomposition driver	Tech blog posts	Demonstrated team friction
Data ownership	Shared database	Strict per-service data isolation
Communication style	Synchronous REST chains	Async events by default
Observability	Logs in production	OpenTelemetry from day one
Team structure	Functional (Frontend/Backend)	Stream-aligned (business domain)

The key insight from Software Architecture: The Hard Parts is that every architectural decision is actually a trade-off analysis. Microservices give you independent deployability and scale — they cost you network complexity, data consistency challenges, and operational overhead. That trade is worth it when you have large teams with clear bounded contexts. It is catastrophically expensive when you do not.

The Uncomfortable Conclusion

Microservices are not a technology decision. They are an organisational design decision that happens to have technical implications.

If your organisational structure cannot support independent team ownership, if your engineers have not internalized eventual consistency, if your operations team cannot instrument distributed traces — microservices will not fix those problems. They will amplify them.

The engineers who laugh at microservices are usually the ones who were handed a distributed monolith and told it was a success. The engineers who swear by them are usually the ones who had the discipline to establish bounded contexts, event-driven communication, and observability before decomposing.

The architecture is never the problem. The maturity to execute it is.

References

This guide synthesizes principles and concepts from the following definitive texts on distributed systems and software architecture:

Monolith to Microservices: Evolutionary Patterns to Transform Your Monolith by Sam Newman
Software Architecture: The Hard Parts — Modern Trade-Off Analyses for Distributed Architectures by Neal Ford, Mark Richards, Pramod Sadalage & Zhamak Dehghani
Designing Data-Intensive Applications by Martin Kleppmann
Building Event-Driven Microservices: Leveraging Organizational Data at Scale by Adam Bellemare
Foundations of Scalable Systems: Designing Distributed Architectures by Ian Gorton

Originally published at https://chemacabeza.dev/writing/why-microservices-fail.

The Feynman Guide to Software Architecture

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:51:58 +0000

Software Architecture often sounds like a mystical art practiced by gray-bearded wizards in ivory towers. In reality, it's just about making the hard decisions—the ones that are difficult to change later.

To demystify these concepts, I've applied the Richard Feynman Technique: taking complex ideas from the incredible O'Reilly 2024 Software Architecture collection and explaining them using simple, relatable analogies.

Let's dive in.

1. The Architect Elevator

In The Software Architect Elevator, Gregor Hohpe explains that a modern architect isn't just a technical genius; they are a communicator.

Imagine a massive corporate skyscraper. At the top, in the luxurious penthouse boardroom, business executives are plotting the company's strategic goals. At the very bottom, in the noisy, bustling engine room (the data center or development floor), engineers are wiring cables and writing code.

The Architect Elevator connects the penthouse strategy to the engine room execution.

The Concept: The architect is the person riding the elevator. They must be able to speak the language of business ("ROI," "Time to Market") in the penthouse, and then ride the elevator down to the engine room and translate that into technical reality ("Latency," "Database Sharding," "Microservices"). If the elevator is broken, the strategy never becomes reality.

2. The First Law of Architecture: "It Depends"

If you ask an architect a question, the answer is almost always: "It depends." Neal Ford and Mark Richards emphasize this in Fundamentals of Software Architecture and Software Architecture: The Hard Parts.

Think of architecture like designing a car. Do you want a Formula 1 race car or a Volvo station wagon? You can't have both.

Balancing the scales: Speed and Agility vs. Security and Stability.

The Concept: In software, there are no perfect solutions, only trade-offs. You are constantly balancing "-ilities":

Scalability (handling more users) often costs Money.
Security (locking things down) often reduces Usability.
Agility (moving fast) can sometimes threaten Stability. An architect's job isn't to find the "right" answer; it's to find the trade-off that best fits the business goal.

3. Breaking the Monolith: Lego Blocks vs. A Ball of Yarn

Sam Newman's books (Building Microservices and Monolith to Microservices) tackle one of the biggest trends of the last decade: breaking apart massive applications.

Imagine your software is a giant, tangled ball of multicolored yarn (a Monolith). If you pull one red string on the left side, a blue string on the right side tightens. Everything is connected. Changing one thing might break something completely unrelated.

A tangled ball of yarn (Monolith) vs. neatly organized Lego blocks (Microservices).

The Concept: Microservices are like playing with Lego blocks. You break the giant ball of yarn into small, independent pieces. If you want to replace a red 2x4 Lego brick with a blue one, you can do it without destroying the whole castle. However, managing 1,000 separate Lego blocks comes with its own massive operational headache (the "Distributed Monolith" trap).

4. Domain-Driven Design (DDD): The Shared Dictionary

Before you write a single line of code, you need to understand what you are building. This is the core of Vlad Khononov's Learning Domain-Driven Design.

Imagine a group of French chefs trying to build a house with Japanese carpenters, but neither speaks the other's language. The chefs ask for a "soufflé station," and the carpenters build a "tatami room." Disaster.

Building a 'Ubiquitous Language' bridge between business and engineering.

The Concept: The most important part of DDD is the Ubiquitous Language. Business experts and software developers must sit down and create a shared dictionary. If the business calls a customer a "Guest," the code shouldn't call them a "User." The code must strictly reflect the actual business domain. Code is just the physical manifestation of business rules.

5. Evolutionary Architecture: Buildings That Expect Change

Historically, software architecture was like building a concrete bridge. Once it's built, changing it is incredibly painful. But the business world changes daily. Neal Ford, Rebecca Parsons, and Patrick Kua explore a different approach in Building Evolutionary Architectures.

Imagine building a skyscraper not with concrete, but with massive, modular shipping containers. As the company grows, a giant crane can lift out an old container and slot a new, upgraded one right into its place without the building falling down.

A building designed for constant upgrades and interchangeable modules.

The Concept: Evolutionary Architecture assumes that change is the only constant. Instead of trying to predict the future, architects build systems that are designed to be easily modified. They use "fitness functions" (like automated architectural tests) to ensure that as the system evolves, it doesn't degrade in performance or security.

The Verdict

Software Architecture is less about coding and more about communication, balancing trade-offs, and predicting where things might go wrong. By using the Feynman Technique to understand the underlying principles—elevators, scales, Legos, dictionaries, and modular buildings—we can strip away the jargon and focus on what really matters: solving human problems with technology.

References & Further Reading

This post is a synthesis of the following excellent resources from the O'Reilly 2024 Software Architecture collection:

The Software Architect Elevator by Gregor Hohpe
Fundamentals of Software Architecture by Mark Richards and Neal Ford
Software Architecture: The Hard Parts by Neal Ford, Mark Richards, Pramod Sadalage, and Zhamak Dehghani
Building Microservices (2nd Edition) by Sam Newman
Monolith to Microservices by Sam Newman
Learning Domain-Driven Design by Vlad Khononov
Building Evolutionary Architectures (2nd Edition) by Neal Ford, Rebecca Parsons, and Patrick Kua

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-software-architecture.

How System Design Fails: A Visual Guide

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:51:23 +0000

System Design isn't just about drawing boxes and arrows on a whiteboard. It's about predicting how things will inevitably break and engineering around those failures.

When you scale from a single server to a distributed network of thousands of machines, failure is no longer a possibility—it is a mathematical certainty. Drawing upon the foundational concepts from textbooks like Designing Data-Intensive Applications (DDIA), System Design Interview, and Software Architecture: The Hard Parts, let's explore how systems actually fail in the real world.

When one node goes down, how does the rest of the cluster respond?

1. The Single Point of Failure (SPOF)

The most basic, yet most devastating, failure mode is the Single Point of Failure (SPOF). This happens when an entire system's availability relies on one specific component.

Imagine a massive highway (your network traffic) that suddenly merges into a single, one-lane toll booth (your single server). It doesn't matter how fast the cars are driving; the toll booth becomes an insurmountable bottleneck.

Traffic bottlenecking at a critical, un-replicated node.

The Concept: In system design, any piece of architecture without redundancy is a SPOF. This could be a primary database without a replica, a load balancer without a failover, or even a single domain name registrar. The solution? Redundancy. We scale horizontally, deploying multiple instances behind a load balancer so that if one dies, traffic effortlessly routes to the survivors.

2. Network Partitions & The Split-Brain Problem

When we talk about distributed systems, we must acknowledge the "Fallacies of Distributed Computing." The biggest fallacy? That the network is reliable.

In Designing Data-Intensive Applications (DDIA), Martin Kleppmann highlights the danger of Network Partitions. A partition occurs when the network connecting two halves of your system simply drops.

A digital fault line severing communication between two database clusters.

The Concept: Imagine two managers running a busy restaurant, communicating via walkie-talkie. If their walkie-talkies break (network partition), they can no longer synchronize. If Manager A accepts a reservation for Table 5, and Manager B accepts a reservation for the exact same table, you have a conflict.

In a database, this is the Split-Brain Problem. The CAP Theorem dictates that during a network partition, you must choose between Consistency (refusing to accept new writes until the network heals) or Availability (accepting writes on both sides and risking conflicting data).

3. The Danger of Clock Skew

Another hard lesson from DDIA: You cannot trust time.

In a distributed system, every server has its own internal quartz clock. Due to temperature changes and minor hardware differences, these clocks drift apart. One server might think it's 12:00:01, while another thinks it's 12:00:05.

The Concept: If Server A writes a record at 12:00:02 (according to its clock), and Server B writes an update at 12:00:01 (according to its slower clock), the database might process Server B's write as the "newer" one and silently overwrite Server A's data, even though Server A's write actually happened later in the physical world! This is why distributed systems rely on logical clocks (like Vector Clocks) instead of wall-clock time to determine the strict ordering of events.

4. The Microservice Trap: The Distributed Monolith

Sam Newman (Monolith to Microservices) and Neal Ford (Software Architecture: The Hard Parts) frequently warn about the dangers of splitting architectures too aggressively.

Microservices promise agility, but if you split your domains incorrectly, you don't get independent services. Instead, you create a tangled, highly-coupled mess called a Distributed Monolith.

A tangled web of synchronous microservice dependencies.

The Concept: If Service A cannot complete a user request without synchronously calling Service B, which calls Service C, which calls Service D... you haven't decoupled anything. You've simply taken in-memory function calls and replaced them with slow, unreliable network calls. If Service D fails, the entire chain collapses. This is why asynchronous event-driven architectures (like Kafka) and careful Domain-Driven Design (DDD) boundaries are critical to surviving microservices.

Conclusion: Designing for Failure

Systems don't fail because engineers are careless; they fail because complexity scales exponentially. The mark of a senior architect isn't building a system that never fails—it's building a system that fails gracefully.

By anticipating SPOFs, respecting network partitions, doubting system clocks, and managing microservice boundaries, we move from writing code to truly engineering systems.

Originally published at https://chemacabeza.dev/writing/how-system-design-fails.

The Feynman Guide to Content Delivery Networks

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:51:21 +0000

Every time you load a webpage, stream a movie on Netflix, or scroll through your social media feed, there is a silent, invisible system working behind the scenes to make it feel instant. Without it, the internet would feel like dial-up in the 90s—agonizingly slow, constantly buffering, and perpetually frustrating.

This system is called a Content Delivery Network, or CDN.

Despite being the backbone of the modern internet, most engineers have only a vague, hand-wavy understanding of how CDNs actually work. Let's fix that using the Richard Feynman Technique—breaking down the complex engineering of CDNs into simple, everyday analogies that anyone can understand.

1. The Problem: Why One Server Isn't Enough

Imagine you open a single pizza restaurant in Madrid. Your pizza is legendary. Word gets out, and suddenly people in Tokyo, São Paulo, Sydney, and New York want to order your pizza.

There's a problem. Every single order has to be fulfilled from your single kitchen in Madrid. A customer in Tokyo places an order—the pizza has to travel 10,000 km. By the time it arrives, it's cold. The customer in Sydney? Even worse. And during peak hours, your single kitchen is overwhelmed with thousands of global orders at once.

This is exactly what happens when a website runs on a single origin server. A user in Australia requesting a webpage hosted in Virginia, USA, has to send a request across the Pacific Ocean, wait for the server to process it, and then wait for the response to travel all the way back. Every millisecond of that round trip is called latency, and it's the number one enemy of user experience.

A CDN distributes copies of your content to edge servers across the globe, dramatically reducing the distance between the user and the data.

The Concept: A Content Delivery Network solves this by placing copies of your content on hundreds or thousands of servers distributed across the globe. These servers are called Edge Servers or Points of Presence (PoPs). When a user requests your website, the CDN routes them to the nearest edge server instead of the faraway origin. The data travels a few hundred kilometers instead of ten thousand.

2. The Pizza Chain Analogy: Edge Caching

The solution to our pizza problem isn't to build a faster oven in Madrid. It's to open franchise locations in every major city. Each franchise pre-stocks the most popular pizzas. When a customer in Tokyo orders a Margherita, the local Tokyo franchise serves it instantly from its own supply—no need to call Madrid at all.

Instead of every request traveling to the distant origin server, CDN edge servers cache content locally, serving it to nearby users in milliseconds.

This is Edge Caching, and it is the fundamental mechanism of every CDN. Here's how it works:

First Request (Cache Miss): The first customer in Tokyo requests your homepage. The Tokyo edge server doesn't have it yet, so it fetches it from the origin server in Madrid, serves it to the user, and stores a copy in its local cache.
Subsequent Requests (Cache Hit): The next hundred customers in Tokyo request the same homepage. The edge server already has the copy. It serves it directly—without ever touching the origin server. Response time drops from 300ms to 20ms.

The origin server is now relaxed. It only gets contacted when the cache expires or a genuinely new piece of content is requested. This concept—reducing the load on the origin while speeding up delivery—is the beating heart of a CDN.

3. The Smart Receptionist: DNS-Based Routing

So how does the CDN know which edge server to send a user to? The answer lies in the Domain Name System (DNS)—the internet's phonebook.

When you type www.example.com into your browser, your computer doesn't know where that is. It asks a DNS server: "What is the IP address of www.example.com?" Normally, the DNS returns the IP of the origin server. But with a CDN, something smarter happens.

The CDN's intelligent DNS server acts like a smart receptionist, directing each user to their nearest and healthiest edge server.

The CDN operates its own Intelligent DNS Server. When a user's DNS query arrives, the CDN doesn't just blindly return an IP. It considers:

Geographic proximity: Where is this user located? Route them to the nearest edge server.
Server health: Is the nearest edge server overloaded or down? Route to the next best one.
Network conditions: Is there congestion on a particular path? Route around it.

This entire decision happens in microseconds, and the user never knows it occurred. They simply experience a fast-loading page.

4. Cache Hit vs. Cache Miss: The Hot Kitchen

Understanding the difference between a Cache Hit and a Cache Miss is crucial to understanding CDN performance.

Think of the edge server as a kitchen with a warming shelf. If a dish is already on the shelf (a Cache Hit), the waiter grabs it and serves it in seconds. If the dish isn't on the shelf (a Cache Miss), the kitchen has to cook it from scratch—the waiter walks to the back, fires up the stove, waits for it to cook, puts a copy on the warming shelf for next time, and then serves it. Much slower.

A Cache Hit is served instantly from the edge. A Cache Miss requires a round trip to the origin server, adding significant latency.

The performance of a CDN is often measured by its Cache Hit Ratio—the percentage of requests served directly from the edge cache without touching the origin. A well-configured CDN achieves a hit ratio of 95-99%, meaning only 1-5% of requests ever reach the origin server.

Key factors that affect the cache hit ratio:

TTL (Time to Live): How long the CDN keeps a cached copy before considering it stale. A longer TTL means more cache hits but potentially stale content.
Cache Keys: The CDN uses the URL (and sometimes headers, cookies, or query strings) to identify unique content. Misconfigured cache keys can destroy your hit ratio.
Content type: Static assets (images, CSS, JavaScript) cache beautifully. Dynamic, personalized content (user dashboards, shopping carts) is much harder to cache.

5. Beyond Speed: The Shield

Most people think CDNs are only about speed. But one of the most powerful—and least understood—benefits of a CDN is security.

Remember our pizza franchise model? Now imagine a rival sends a flash mob of 100,000 fake customers to your original Madrid restaurant to overwhelm it. Your single kitchen collapses under the load. This is a Distributed Denial of Service (DDoS) attack.

A CDN absorbs massive attack traffic across its distributed edge network, shielding the origin server from being overwhelmed.

But with your franchise model (CDN), that attack is automatically distributed across hundreds of locations worldwide. No single location is overwhelmed. The CDN's edge servers absorb the attack traffic like a sponge, and the origin server remains calm and protected behind the shield.

Modern CDNs like Cloudflare, Akamai, and AWS CloudFront provide:

DDoS Mitigation: Absorbing terabits of malicious traffic per second.
Web Application Firewall (WAF): Filtering SQL injection, XSS, and other application-layer attacks at the edge.
TLS/SSL Termination: Handling the computational cost of encryption at the edge, offloading it from the origin.
Bot Management: Distinguishing legitimate users from malicious bots before traffic ever reaches your infrastructure.

The Verdict

A Content Delivery Network is not just a performance optimization—it is a fundamental architectural layer of the modern internet. By distributing content to the edge of the network, CDNs transform the laws of physics from a problem into a non-issue. Users get faster pages, origin servers get less load, and the entire system becomes more resilient against both traffic spikes and malicious attacks.

The next time a webpage loads instantly, remember: it's not magic. It's a CDN edge server, sitting quietly in a data center near you, serving a cached copy of that content before you even finished blinking.

References & Further Reading

This post synthesizes concepts from the core literature on content delivery networking:

Content Delivery Networks: Fundamentals, Design, and Evolution by Dom Robinson.
Content Delivery Networks: Web Switching for Security, Availability, and Speed by Scott Hull.
Content Distribution Networks: An Engineering Approach by Dinesh C. Verma.
A Practical Guide to Content Delivery Networks (2nd Edition) by Gilbert Held.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-cdns.

The Feynman Guide to Java Modules

Jose Maria Cabeza Rodriguez — Tue, 21 Jul 2026 04:50:45 +0000

For over two decades, Java developers lived with a dirty secret. The language that championed encapsulation with private, protected, and public had a gaping hole at the architectural level: there was no way to hide a package from the outside world. If you made a class public, it was public to everyone—not just your intended consumers, but every single JAR on the classpath.

This led to a phenomenon so painful it earned its own name: Classpath Hell.

In Java 9, the platform finally got its fix: the Java Platform Module System (JPMS), codenamed Project Jigsaw. But what exactly are modules, and why should every Java developer understand them?

Let's use the Richard Feynman Technique—breaking complex ideas into simple, everyday analogies—to understand Java Modules from the ground up.

1. Classpath Hell: The Problem Modules Solve

Before Java 9, your entire application was a flat pile of JAR files thrown onto the classpath. The JVM would search through this pile to find classes at runtime. It sounds simple, but it created catastrophic problems:

No versioning: If two JARs contained the same class (e.g., different versions of a library), the JVM would silently pick one at random. Your program would crash with mysterious NoSuchMethodError exceptions, and you'd have no idea why.
No encapsulation: Every public class in every JAR was accessible to every other JAR. Internal implementation classes that were never meant to be used externally (like sun.misc.Unsafe) were used by half the ecosystem.
No explicit dependencies: There was no way to declare "this JAR requires that JAR." If a dependency was missing, you'd only find out at runtime, when your application exploded.

Before modules: a tangled mess of JARs with no boundaries. After modules: clean, explicitly connected components with enforced encapsulation.

Think of the old classpath like a building with no walls, no doors, and no locks. Every room is open to every visitor. Someone can walk into the CEO's office, rummage through confidential files, and leave—and the building has no mechanism to stop them.

Modules add the walls, the doors, and the locks.

2. The City Analogy: Modules as Districts

The best way to understand the Java Module System is to think of a well-planned city.

Each module is a self-contained district with walls, controlled entry points, and explicit connections to other districts.

Imagine a modern city divided into districts (modules). Each district has:

Walls: A hard boundary that separates its internal buildings (packages) from the outside world.
Public-facing shops: Some buildings are deliberately placed at the district's entrance, visible and accessible to visitors (these are exported packages).
Private facilities: Other buildings—warehouses, utility rooms, staff quarters—are hidden behind the walls, invisible to outsiders (these are internal packages).
Bridges with guards: To travel between districts, you must cross a controlled bridge. The guard checks if your district has a permit (requires) to access the destination district. No permit? No entry.

This is exactly how Java modules work. A module is a named, self-describing collection of packages that explicitly declares:

What it needs (requires) — which other modules it depends on.
What it shares (exports) — which of its packages are accessible to other modules.
What it hides — everything not exported is completely invisible, even if the classes are public.

3. The Module Descriptor: Your Blueprint

Every module has a single file that acts as its identity card and access policy: module-info.java. This file sits at the root of your module's source tree, and the compiler enforces every rule declared in it.

The module-info.java file is the control center of every module, declaring its dependencies, exports, and service bindings.

Here's what each clause does:

requires — "I depend on this module." The compiler and JVM will verify that the required module is present. If it's missing, your program won't even compile—no more runtime surprises.
exports — "I'm making this package available to the world." Only exported packages can be accessed by other modules. Everything else is locked down.
requires transitive — "I depend on this module, and so should anyone who depends on me." This forwards a dependency through the chain, so consumers don't have to manually list every transitive dependency.
opens — "I'm allowing runtime reflection access to this package." This is critical for frameworks like Spring and Hibernate that rely on reflection to inspect and instantiate classes.
provides ... with — "I implement this service interface with this concrete class." This enables the ServiceLoader pattern for pluggable architectures.
uses — "I consume this service interface." The counterpart to provides.

A simple module descriptor looks like this:

module com.myapp.billing {
    requires java.sql;
    requires com.myapp.common;
    exports com.myapp.billing.api;
    opens com.myapp.billing.model to com.google.gson;
}

This reads naturally: "The billing module needs java.sql and the common module. It exposes its API package to the world. It allows Gson to reflect into its model package for JSON serialization."

4. The Dependency Graph: No More Surprises

One of the most powerful consequences of the module system is the dependency graph. Because every module explicitly declares what it requires, the JVM can build a complete picture of your application's dependency tree before a single line of code runs.

Modules form a clear, layered dependency graph. The requires transitive keyword forwards dependencies through the chain.

This solves the three nightmares of Classpath Hell:

Missing dependencies are caught at startup. If module A requires module B, and B isn't on the module path, the JVM refuses to start. No more ClassNotFoundException after 3 hours of production runtime.
Duplicate modules are forbidden. The module system enforces that each module appears exactly once. No more silent conflicts between JAR versions.
Circular dependencies are illegal. If module A requires B, and B requires A, the compiler rejects it. This forces you into clean, layered architectures.

Every module implicitly depends on java.base—the foundational module containing java.lang, java.util, java.io, and other core packages. You never need to write requires java.base; it's always there.

5. Custom Runtimes: Shipping Only What You Need

Here's where modules deliver perhaps their most dramatic practical benefit. Before Java 9, deploying a Java application meant shipping the entire JRE—a ~300MB behemoth containing CORBA, Swing, JavaFX, JNDI, and dozens of other APIs your application never touched.

With modules, the JDK itself is modularized into ~70 platform modules. And Java provides a tool called jlink that lets you assemble a custom runtime image containing only the modules your application actually uses.

jlink strips the JDK down to only the modules your application needs, reducing deployment size by up to 90%.

A microservice that only uses java.base and java.sql can be packaged into a self-contained runtime of ~30MB instead of 300MB. This is transformative for:

Container deployments: Smaller Docker images mean faster pulls, faster scaling, and lower storage costs.
Serverless functions: Smaller cold-start times when the runtime footprint is minimal.
Edge devices and IoT: Java can now run in memory-constrained environments where the full JRE was simply too large.

The command is straightforward:

jlink --module-path $JAVA_HOME/jmods:myapp.jar \
      --add-modules com.myapp \
      --output custom-runtime

This produces a complete, self-contained runtime directory that you can ship without requiring Java to be installed on the target machine.

The Verdict

The Java Platform Module System represents the most significant architectural change to Java since generics. By introducing explicit boundaries, enforced dependencies, and strong encapsulation at the module level, JPMS finally gives Java the tools to build large-scale systems that are maintainable, secure, and efficient.

Classpath Hell isn't just an inconvenience—it's an architectural cancer that silently degrades reliability as systems grow. Modules are the cure. They force you to think about your architecture explicitly, declare your boundaries clearly, and ship only what you need.

The walls, doors, and locks are now built into the language itself.

References & Further Reading

This post synthesizes concepts from the core Java literature:

Modern Java in Action by Raoul-Gabriel Urma, Mario Fusco, and Alan Mycroft — Chapter 14: The Java Module System.
Java: The Complete Reference (12th Edition) by Herbert Schildt — Chapter 16: Modules.
Core Java, Volume I: Fundamentals by Cay S. Horstmann — Chapter 12: The Java Platform Module System.
Effective Java (3rd Edition) by Joshua Bloch.

Originally published at https://chemacabeza.dev/writing/the-feynman-guide-to-java-modules.