Marta has made the decision, and Luis has been tasked with carrying it out. Before drawing a single service, the team needs a shared set of design principles: simple rules for judging every decision ("is this boundary a good one?", "is this call in the right place?", "is this service too small?"). Without explicit principles, each developer will design according to their own intuition, and the result will be the distributed monolith that lesson 01-04 already warned us about.

This lesson presents the ten principles that will guide all of module 2 and, really, the whole course: cohesion and coupling, single responsibility, autonomy, the contract as the only door, decentralized data, design for failure, appropriate size, Conway's Law, smart endpoints, dumb pipes, and automation. To keep them from remaining theory, each principle is applied to TechCorp's monolith and, at the end, we return to the six problems we flagged in createOrder in lesson 01-05 to classify them by the principle they violate. The decomposition itself (which services come out of the monolith) is the subject of 02-02, and defining their boundaries is the subject of 02-03: here we set the criteria we will judge them by.

1. Why start with principles rather than boxes
2. High cohesion and low coupling: the four kinds of coupling
3. Single responsibility and modeling around business capabilities
4. Autonomy and independent deployment
5. The contract as the only door: hiding internal details
6. Decentralized data (statement)
7. Design for failure (statement)
8. Appropriate size: "micro" does not mean tiny
9. Conway's Law applied to TechCorp's teams
10. Smart endpoints, dumb pipes
11. Automation as a design principle
12. An X-ray of createOrder: which principle each problem breaks

When a team decides to "do microservices", the immediate temptation is to grab a whiteboard and draw boxes. The problem is that the boxes draw themselves: six areas in the monolith, six services, done. What does not draw itself is the quality of the boundaries between those boxes, and that is where a distributed system succeeds or fails.

Principles serve three purposes:

• Deciding with a rationale when the domain is not obvious. At TechCorp, does stock reservation belong to Inventory or to Orders? Do shipping addresses belong to Customers or to Orders? Principles give a reasoned answer; intuition does not.
• Reviewing other people's designs with a shared vocabulary. When Luis reviews the Payments team's design, he wants to be able to say "this introduces temporal coupling", not "I don't like this".
• Detecting drift over time. Systems degrade through the accumulation of small exceptions ("just this once I'll read another service's table"). Principles are the baseline against which drift is measured.

The principles that follow are not an invention of this course: they come from the work of Sam Newman, Martin Fowler, James Lewis, Chris Richardson and the DDD community. What we do here is organize them and ground them in TechCorp's store.

This is the parent principle; all the others are ways of achieving it.

• Cohesion: things that change together should live together. If every time a business rule changes you have to touch three services, cohesion is low.
• Coupling: the degree to which a change in one service forces a change in (or affects the operation of) another. We want it to be the bare minimum.

The classic phrase is "changing one thing should require touching a single service and deploying only that service". In TechCorp's monolith the opposite happens: when Notifications changed a query on orders, it broke an Orders report (problem 3 in 01-05).

Coupling is not a single thing. Distinguishing its kinds is what makes it possible to attack it:

Two important observations:

• Contract coupling is the good kind. Two services that communicate have to share something: the shape of the message. The design goal is for that to be the only coupling, and for it to be explicit, small and stable.
• Temporal coupling is the most treacherous, because it is invisible in the code: a chain of synchronous HTTP calls looks clean and modular, but if five services call each other in a chain, the availability of the whole is the product of the five (0.99⁵ ≈ 0.95) and the latency is the sum. A schematic example:

This code "does microservices" and yet reproduces exactly the monolith's defect: an email outage still prevents selling. Notice that the last await is indefensible from the business's point of view: a charged order is an order, whether the email was sent or not. Principles exist precisely to catch this before it gets written.

A microservice should have one reason to change, and that reason should be a business capability: something the company does that a business owner would recognize in a single sentence ("manage the catalog", "charge orders", "notify the customer").

What is not a good unit of responsibility:

At TechCorp, the six functional areas from 01-05 (customers, catalog, inventory, orders, payments, notifications) are recognizable business capabilities: each has a different business owner, its own vocabulary and its own pace of change (the catalog changes daily; the charging rules, a few times a year). That is a sign the cut is headed in the right direction, although in 02-03 we will refine the boundaries more rigorously.

A quick test Luis will use: "Can I explain what this service does in one sentence without using the word 'and'?". "Manages stock and reservations" passes (reserving is part of managing stock). "Creates orders and sends emails" does not.

A service is autonomous when its team can change it, test it and deploy it without asking permission or coordinating with other teams, and when it can keep working (even in a degraded mode) when others are not there.

Autonomy has three faces:

1. Code autonomy: a repository or, at the very least, a module with a clear owner and its own pipeline.
2. Data autonomy: nobody else reads or writes its storage (principle 6).
3. Runtime autonomy: it does not depend on another service being alive to answer the requests it can resolve on its own.

The acid test is independent deployment: if putting catalog-service v2.3 into production requires deploying orders-service at the same time, there is no autonomy; there is a monolith spread over several processes. That is TechCorp's problem 1 (fearful weekly deployments, 4 out of 12 rolled back): the Thursday-night deployment exists because nothing can be deployed separately.

Autonomy does not mean total isolation: services collaborate. It means the collaboration happens through stable contracts (principle 5) and that one service's availability does not drag the others down (principle 7).

A microservice exposes a contract (an HTTP API, a set of published events, or both) and everything else is private: its tables, its collections, its files, its internal module structure, its technology decisions. It is the system-scale application of the encapsulation you already know from object-oriented programming.

Direct consequences:

• No service accesses another service's database. Not even to read. Not even "just for one report".
• No service imports another's business code (require('../../catalog-service/models/product') is a violation).
• A service can change its internal technology (from PostgreSQL to MongoDB, as the catalog will) without anyone noticing.
• The contract is the only thing that has to be versioned and protected (03-06).

Compare the two ways Orders can learn a product's price:

Note the detail: in the second version, orders-service does not know that the catalog has an active column or that a products table exists. It only knows the contract. When the catalog moves to MongoDB in 02-04, this line will not change.

A less obvious consequence: the contract must express business operations, not data operations. POST /reservations ("reserve these quantities for this order") is a business contract; PATCH /stock/{id} with { reserved: 7 } is exposing the table over HTTP, and it forces callers to know the inventory's internal logic (that reserved cannot exceed quantity, for instance).

Each service is the exclusive owner of its data: it decides its schema, its technology and its lifecycle, and it is the only one that writes it. Other services obtain that data through the contract (by querying the API or subscribing to the events the owner publishes), never by reading its storage.

This is the principle that generates the most resistance, because it has a real cost: you lose JOINs across areas and you lose the single transaction. At TechCorp, that is exactly what createOrder does: one transaction that touches customers, products, stock, orders, order_lines and payments. Lesson 02-04 develops the database-per-service pattern, how cross-area foreign keys are broken and what alternatives exist for the queries that are a JOIN today; 02-05 replaces the transaction with a saga. Here it is enough to set the rule: one table, one owner.

In a monolith, a function call does not fail because of the network. In a distributed system, every interaction between services can fail, take longer than expected or run twice. The eight fallacies of distributed computing from 01-02 are the list of what cannot be assumed.

Designing for failure means, from the design phase onward:

• Deciding what each service does when its dependency does not respond: does it fail? Does it answer with cached data? Does it queue the work for later?
• Assuming messages can arrive duplicated and designing idempotent operations.
• Setting timeouts on every outgoing call and never leaving a request waiting indefinitely.
• Preferring partial degradation to total failure: if Notifications goes down, orders must keep coming in.

The concrete mechanisms (retries with backoff, circuit breakers, bulkheads, dead-letter queues) are studied in 06-03. In this module, the principle translates into design decisions: which interactions are synchronous and which asynchronous, and what compensations exist when a step in a flow fails (02-05).

The "micro" prefix has done a lot of damage. There is no number of lines of code, tables or endpoints that defines the right size. The useful criteria are different:

The practical rule: start with a few larger services and split when there is a reason (different scaling, different teams, different pace of change). It is far cheaper to split a service than to merge two that were designed separately with their own contracts and databases. That is why TechCorp will not have a reservations-service separate from inventory-service, nor an order-lines-service separate from orders-service.

In 1967, Melvin Conway stated that organizations design systems that mirror their communication structure. If three teams build a compiler, you get a three-pass compiler. Applied to microservices: if teams are organized by technical layer (front, back, DB), you get services by technical layer; if they are organized by business capability, you get services by business capability.

The practical consequence is the inverse Conway maneuver: decide first the architecture you want, and organize the teams so that they mirror it. At TechCorp today there is a single development team informally spread across areas, all on the same repository; the 20% of coordination time Luis complains about is Conway's Law in action.

Marta's proposal to accompany the migration:

Notice two decisions:

• No service has two owning teams and no team has more services than it can maintain. A service with two owners ends up with two design criteria; a team with six services ends up neglecting four.
• There is a platform team that owns no business, but rather the shared tooling (cluster, pipelines, observability). That is how automation (principle 11) avoids falling on each team separately.

Orders and Inventory sharing a team does not mean they share a database or code: principles 5 and 6 apply just the same within a team. What they share is pace and context: they are the two pieces that talk the most in the order flow, and it pays for their design conversations to be cheap.

This principle, formulated by Fowler and Lewis, is a reaction to the SOA era we reviewed in 01-01: back then, the Enterprise Service Bus (the "pipe") concentrated business logic: transformations, content-based routing, complex orchestrations. The result was a smart bus surrounded by dumb services, and the bus became a central monolith nobody dared to touch.

In microservices this is inverted:

• The endpoints are smart: business logic lives in the services. inventory-service decides whether it can reserve; nobody decides for it.
• The pipes are dumb: HTTP and the message broker (RabbitMQ in this course) transport bytes. They route, deliver, retry, but they do not know what an order is.

What this implies for TechCorp's design:

When the service mesh (Istio) appears in 05-05, we will see that it too respects this principle: the mesh handles networking, security and observability, never business logic.

It may be surprising that automation is a design principle rather than an operations one. The reason is that a design with six, twelve or twenty services is unworkable without automation, and so automation shapes the design from day one:

• If deployment is not automatic, nobody will deploy services independently and it will be back to "Thursday night".
• If contract tests are not automatic, nobody will dare to change a contract.
• If creating a new service is not automated (template, pipeline, metrics dashboard), the cost of creating a service will be so high that everything will get crammed into the existing ones.
• If there is no automatic observability, a flow spread over five services will be impossible to debug.

That is why TechCorp's design includes, as part of the system rather than as an add-on, GitHub Actions (05-03), Docker and Kubernetes (05-01, 05-02), Prometheus/Grafana/Loki (06-01) and OpenTelemetry (06-02). And that is why the platform team from section 9 exists. Luis's rule: "If it has to be done more than once per service, automate it before creating the second service".

In 01-05 we flagged six problems in the createOrder code. Now we can classify them precisely, and that classification is the script for the lessons to come:

And there is a seventh problem we did not flag back then because we lacked the vocabulary: deployment. createOrder lives in the same artifact as the catalog search, so a change in how search results are sorted forces a redeployment of the charging logic. That is pure deployment coupling, it violates autonomy, and it is what the module 5 lessons solve once the design allows it.

This table is module 2's "contract" with the reader: by the end of 02-05, every row will have a designed solution.

• Confusing "principle" with "absolute rule". Principles are weighed. Sometimes temporal coupling is accepted (a synchronous query to Catalog to display prices) because the alternative (replicating the whole catalog) is worse. What matters is that the exception is conscious and documented.
• Aiming for "small microservices" instead of "autonomous microservices". Size is a consequence, not a goal. A 30,000-line service that one team deploys ten times a day without coordinating with anyone is a good microservice.
• Designing services and leaving the teams as they were. Conway's Law always wins. If a single team maintains six services in six repositories, it will end up deploying them together "to keep things simple".
• Exposing the database over HTTP. A GET /stock/{id} that returns the row as-is and a PATCH /stock/{id} to modify it is not a business contract; it is data coupling in disguise. Contracts talk about reservations, charges and orders.
• Leaving automation "for later". Later never comes, and without it the second service already hurts.
• Tip: write the principles on a page of the team wiki, with one TechCorp example per principle, and use them as a checklist in every design review. That is what Luis will do starting this week.

For each situation in TechCorp's monolith, indicate which kind(s) of coupling it describes (temporal, deployment, data, contract) and which principle is being violated:

1. When Orders added a column to order_lines, the migration failed because of a lock held by a heavy Catalog query.
2. A change to the confirmation email template requires running the full 40-minute suite and deploying on Thursday.
3. If the payment provider takes 8 seconds to respond, the POST /orders request takes 8 seconds and the stock rows stay locked in the meantime.
4. The reporting module directly imports controllers/ordersController.js to reuse a function that computes totals.

Apply the "can I describe it in one sentence without 'and'?" test to these service candidates and decide whether each is a valid business capability, a service that is too big, or a nanoservice. Justify in one line:

1. vat-calculation-service
2. inventory-service (stock, reservations, releases, warehouse receipts)
3. orders-and-billing-service
4. notifications-service (emails and SMS triggered by events)

Marta proposes an alternative organization: a "Back-end" team (all the services), a "Front-end" team and a "Data" team (all the databases). Explain in 4-6 lines what architecture Conway's Law predicts for that organization and why it is incompatible with principles 4, 5 and 6.

Exercise 1

1. Data coupling (two areas on the same physical schema) with a deployment effect (one area's migration blocks the other). Violates decentralized data and autonomy.
2. Deployment coupling: a trivial change in one capability drags along the deployment of all of them. Violates autonomy and independent deployment; underneath, automation (a 40-minute suite does not allow frequent deployments).
3. Temporal coupling with the payment provider, aggravated by data coupling (locking stock, which belongs to another area). Violates design for failure and decentralized data.
4. Implicit, unmanaged contract coupling (it depends on the internal signature of a function that is not a public contract) and, at bottom, it violates the contract as the only door: reports should consume an API or an event, not another area's internal code.

Exercise 2

1. vat-calculation-service: nanoservice. It is a function, not a capability; nobody in the business would say "our capability to calculate VAT". It should be a library or part of Orders/Payments.
2. inventory-service: valid capability. "Manages stock" (reserving and releasing are stock operations). A warehouse manager recognizes it.
3. orders-and-billing-service: too big or, at the very least, two capabilities with different paces and owners (sales vs. accounting). A candidate for splitting as soon as there is a reason (for example, tax requirements that change without touching the order lifecycle).
4. notifications-service: valid capability. "Tells the customer what is happening" is a sentence without "and" (email and SMS are channels of the same capability, not different capabilities).

Exercise 3

Conway's Law predicts a layered architecture: a big "back-end" (which would tend to be a single service, or a set of services deployed together because a single team maintains them), a separate front-end, and a shared database managed by the Data team, with schemas designed by that team for everyone. It is incompatible with autonomy (no team can deploy a business capability end to end without coordinating with the other two), with the contract as the only door (the Data team would access everything and services would share tables by design) and with decentralized data (there would be a single owner of all the databases, i.e., the shared DB from 01-01: a distributed monolith). To get autonomous microservices, teams must be vertical, by business capability, with a horizontal platform team only for tooling.

We have set the criteria by which we will judge everything we design: high cohesion and low coupling (distinguishing temporal, deployment, data and contract coupling), single responsibility around business capabilities, autonomy with independent deployment, the contract as the only door, decentralized data, design for failure, appropriate size (two-pizza teams, "fits in your head"), Conway's Law applied to TechCorp's four teams, smart endpoints, dumb pipes and automation from the design stage. And we have gone back to createOrder to classify its six problems (plus the deployment one) by the principle they break: low cohesion, data coupling, single transaction, temporal coupling with the payment provider and with email, and lack of idempotency.

With these principles as a checklist, the next lesson tackles the first big practical question: how the monolith is decomposed. We will look at the strategies (by business capability, by subdomain, by use case, by team), the techniques for discovering the seams (including the coupling analysis of the SQL schema from 01-05), the techniques for safe extraction and, above all, the order in which TechCorp will extract its six services and why the catalog goes first.