Architecture Principles

Why Architecture Principles Matter

Most teams do not fail at microservices because they pick the wrong queue or the wrong language. They fail because they skip the principles and build services around technical layers (a “DB service,” a “CRUD service,” a “helper service”) instead of around business capability. The result is services that all change together, all release together, and all break together — a monolith with a network in the middle.

The principles below are the canon. They predate “microservices” as a buzzword: SOLID (Robert C. Martin), Domain-Driven Design (Eric Evans, 2003), Conway’s Law (1968), the Twelve-Factor App (Heroku, 2011), and Sam Newman’s Building Microservices codify them. If a tutorial argues against one of these, be suspicious.

Single Responsibility & Bounded Contexts

The Single Responsibility Principle from SOLID, applied to a service, becomes: each service owns one bounded context and one business capability. Not one endpoint. Not one database table. One coherent piece of the business.

The same word means different things

The classic example: a “Customer” in Sales is not the same as a “Customer” in Support or Shipping. Forcing one model on all three is what kills monoliths.

# Sales context — Customer as buyer
class Customer:
    customer_id: str
    credit_limit: Decimal
    purchase_history: list[Order]
    loyalty_points: int
    payment_methods: list[PaymentMethod]

# Support context — Customer as case
class Customer:
    customer_id: str
    support_tier: str          # bronze, silver, gold
    open_tickets: list[Ticket]
    satisfaction_score: float
    contact_preferences: dict

# Shipping context — Customer as recipient
class Customer:
    customer_id: str
    shipping_addresses: list[Address]
    delivery_preferences: dict
    delivery_instructions: str

Three classes, all called Customer, all correct. They share an ID — that is the integration point — and nothing else. Each lives in a different service.

How to find a bounded context

You do not find bounded contexts at a whiteboard with a UML editor. You find them by listening to the business. The technique is Event Storming (Alberto Brandolini): get domain experts in a room and write every event the business cares about on sticky notes — OrderPlaced, PaymentAuthorized, ItemShipped, TicketEscalated. Group events that always travel together. Each cluster is a candidate bounded context.

Service decomposition by capability

A useful exercise: list everything a monolith does, then split by what the business calls each thing.

What a single-responsibility service looks like in code

// User Service — ONLY manages user profiles.
// Does NOT handle authentication or payments.
const express = require('express');
const app = express();

class UserService {
    async createProfile(userId, profileData) {
        const profile = {
            userId,
            firstName: profileData.firstName,
            lastName: profileData.lastName,
            email: profileData.email,
            preferences: profileData.preferences || {},
            createdAt: new Date()
        };
        await db.users.insert(profile);
        return profile;
    }

    async updateProfile(userId, updates) {
        const profile = await db.users.findOne({ userId });
        if (!profile) throw new Error('Profile not found');
        const updated = { ...profile, ...updates, updatedAt: new Date() };
        await db.users.update({ userId }, updated);
        return updated;
    }
}

app.get('/users/:id', async (req, res) => {
    res.json(await userService.getProfile(req.params.id));
});

app.put('/users/:id', async (req, res) => {
    res.json(await userService.updateProfile(req.params.id, req.body));
});

app.listen(3001);

Loose Coupling, High Cohesion

Loose coupling: what it actually means

Loose coupling does not mean “no calls between services.” It means: if Service B changes its internals — language, database, deploy schedule — Service A does not have to change. That is achieved by:

• Owning your own data. No service reads another’s tables. The boundary is the API, not the schema.
• Stable, versioned contracts. Communicate over HTTP/JSON, gRPC, or events — never via a shared library that drags you into the other team’s release cadence.
• Async where possible. Events and queues decouple in time as well as in code.
• Tolerant readers. Ignore fields you don’t understand; never explode on an extra key.

High cohesion: things that change together live together

The flip side of loose coupling. If a single business change forces edits in three services, those three responsibilities probably belong in one service. The classic test: write down the next ten user stories. Color-code each one by which service it touches. If most stories paint multiple services, your boundaries are wrong.

The Anti-Corruption Layer

One of the most useful coupling tools from DDD: when you must integrate with a messy or external model, do not let it leak into your domain. Build a thin translator at the boundary.

# Your clean domain model
class Order:
    def __init__(self, order_id, customer, items):
        self.order_id = order_id
        self.customer = customer
        self.items = items

# Legacy system has a messy model
class LegacyOrderData:
    ORD_NUM: str
    CUST_CODE: str
    LINE_ITEMS: str      # comma-separated SKUs!

# Anti-Corruption Layer translates
class LegacyOrderAdapter:
    def to_domain(self, legacy: LegacyOrderData) -> Order:
        customer = self.customer_service.get_by_code(legacy.CUST_CODE)
        items = self._parse_line_items(legacy.LINE_ITEMS)
        return Order(order_id=legacy.ORD_NUM, customer=customer, items=items)

    def to_legacy(self, order: Order) -> LegacyOrderData:
        return LegacyOrderData(
            ORD_NUM=order.order_id,
            CUST_CODE=order.customer.code,
            LINE_ITEMS=",".join(i.sku for i in order.items),
        )

Without the adapter, every consumer of the legacy system bends to its shape. With it, the legacy system is contained. The pattern works equally well for third-party SaaS APIs you cannot change.

Context mapping: how services relate

Service Autonomy & Decentralization

Sam Newman calls this independent deployability. Martin Fowler calls it decentralized governance. The principle is the same: push decisions out to the team that owns the service. The two-pizza team (Amazon’s phrase) does not ask permission to ship.

What autonomy requires

• Database per service. No shared schemas. The service’s data is its own; the API is the only way in.
• Independent CI/CD. One pipeline per service. No release trains. No quarterly “big bang” deploys.
• Backward-compatible contracts. If you must coordinate releases, the contract is wrong. Use additive changes and deprecation windows.
• Local tech choice. Within reason. Polyglot is fine; chaos is not. Most shops settle on 2–3 sanctioned stacks.

Conway’s Law works both directions

Decentralized data

The most painful coupling in any distributed system is shared state. Two services that write to the same table are not two services — they are two clients of one database, with all of the lock contention, schema-change drama, and consistency questions that implies.

The principle: each service owns its database. If another service needs the data, it asks via API or subscribes to events. Yes, this means duplication. Yes, this means eventual consistency in places. That is the price of decoupling, and on a system at any real scale, it is worth paying.

# BAD: two services share a database
[order-service] ---> [orders DB] <--- [reporting-service]
                       ^                  ^
                  schema change           breaks both deploys

# GOOD: each service owns its data, events flow between them
[order-service] ---> [orders DB]
       |
       | publishes OrderPlaced
       v
   [event bus] ---> [reporting-service] ---> [reporting DB]

Smart Endpoints, Dumb Pipes

A “dumb pipe” is HTTP, gRPC, Kafka, RabbitMQ used as a transport. The transport routes; it does not interpret. A “smart endpoint” is a service that owns its own validation, business rules, and translation. If the endpoint is smart enough, the pipe can be gloriously simple.

Domain events are how you keep the pipe dumb

Instead of one service calling another, services announce things they did. Other services subscribe to what they care about. The bus does not know about “order” or “payment” — it just delivers messages.

// Domain event — past tense, immutable, named for the business
public class OrderPlacedEvent {
    private final String orderId;
    private final String customerId;
    private final Money totalAmount;
    private final Instant occurredAt;
}

// Aggregate raises the event as part of state change
public class Order {
    private List<DomainEvent> domainEvents = new ArrayList<>();

    public void place() {
        if (orderLines.isEmpty())
            throw new BusinessException("Cannot place empty order");
        this.status = OrderStatus.PLACED;
        this.domainEvents.add(new OrderPlacedEvent(id, customerId, totalAmount));
    }
}

// Service publishes after a successful save
@Service
public class OrderService {
    @Transactional
    public void placeOrder(Order order) {
        order.place();
        orderRepository.save(order);
        order.getDomainEvents().forEach(eventPublisher::publish);
        order.clearDomainEvents();
    }
}

The shipping service subscribes to OrderPlaced. So does the recommendation service. So does the analytics pipeline. None of them know about each other. The order service doesn’t know they exist. That is loose coupling delivered by a dumb pipe.

The Published Language

Whatever flows over the dumb pipe — JSON schema, Protobuf, Avro — is the Published Language between services. Treat it like a public API: versioned, additive-only changes, deprecation announcements. Internal model changes do not change the contract; the contract is what your consumers depend on.

Design for Failure

Cascading failures are the signature outage of a microservices system. Service B slows down, Service A’s threads pile up waiting on it, Service A starts rejecting requests, A’s callers retry and add load to a sick system, the blast radius doubles every hop. Within minutes the whole mesh is down. Designing for failure is how you stop step two — “the caller doesn’t notice.”

The non-negotiable patterns

Each is covered in depth in the Circuit Breaker & Resilience tutorial. The principle here is: build them in from day one. Bolting them on after the first incident is twice as expensive and half as effective.

Chaos engineering: prove it works

Resilience patterns that have not fired in production are theoretical. Netflix invented Chaos Monkey to kill random instances during business hours; the discipline is now standard at any shop running real-scale services. The point: practice the failure on your terms, with monitoring, in business hours, with a rollback plan, before the failure picks the time itself.

Statelessness vs Managed State

The Twelve-Factor App (Heroku, 2011) codified the modern stateless-service style. Factor VI: Execute the app as one or more stateless processes. State that must persist goes to a backing service — a database, a cache, a session store, an object store. The application tier is replaceable.

What state can live where

Stateful services exist — and that is fine

Databases. Stream processors. Cache nodes. Workflow engines. These are supposed to be stateful and they have their own scaling story (sharding, replication, consensus). The principle is not “eliminate state.” The principle is: be deliberate about which services hold state and which do not. The vast majority of your business services should be stateless replicas behind a load balancer. The handful that are not should be operated by people who know what they signed up for.

Observability as a First-Class Concern

The three pillars are Logs, Metrics, and Traces. Each answers a different question:

The minimum bar for any service

• Structured logs to stdout with request_id, trace_id, service, level. The platform ships them; the app does not own log files.
• The four golden signals as metrics: latency, traffic, errors, saturation (Google SRE).
• Distributed tracing via OpenTelemetry. Propagate traceparent on every outbound call.
• Health and readiness endpoints (/healthz, /readyz) that the orchestrator can probe.
• SLOs with error budgets. Pick the few user-visible numbers you commit to. Alert on burning the budget, not on every stack trace.

# Structured log line — one JSON object per event
{
  "ts": "2026-05-12T14:22:01.337Z",
  "level": "info",
  "service": "checkout",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "request_id": "req_8f3kd9",
  "customer_id": "cus_19",
  "event": "order.placed",
  "order_id": "ord_551",
  "latency_ms": 182
}

Real-World Examples

The principles above sound abstract until you see them at scale. Here is how four well-known shops apply them.

Amazon: cells, two-pizza teams, and “you build it, you run it”

Amazon’s service architecture predates the term “microservices.” The doctrine: every team owns a service end-to-end — code, deploy, on-call. Teams are small (the “two-pizza team”), services are owned, and inter-team communication happens over APIs, not Slack threads. Amazon’s cell-based architecture takes design-for-failure further: each service is split into independent cells, customers are assigned to cells, and a bug in one cell affects ~1/N of users instead of 100%.

Netflix: bounded contexts and the Simian Army

Netflix runs thousands of services on AWS. Every cross-service call goes through a circuit breaker. Chaos Monkey kills random instances during business hours. The Simian Army extends that to latency injection, AZ failure, and region failure. The result: the blast radius of any single service failure is bounded by design, and the team that finds out in an outage is rare.

Spotify: the squad model and the Inverse Conway Maneuver

Spotify designed the org to get the architecture they wanted. Small autonomous squads own a slice of product end-to-end. Squads with related missions group into tribes. Specialists across squads form chapters and guilds for cross-cutting concerns. Each squad picks its tech, ships its services, and runs its on-call. Conway’s Law, working on purpose.

Shopify: services around merchant workflows

Shopify serves 2M+ merchants. Service boundaries follow how a merchant thinks — Products, Orders, Checkout, Shipping — not how the database is structured. Multi-tenancy is enforced at the data layer (partition by shop_id) and resource limits prevent noisy neighbors. Webhooks are domain events all the way down — billions per day — letting third-party apps integrate without coupling to Shopify’s internals.

LinkedIn: from monolithic Rails to 500+ services

LinkedIn evolved from a single Rails app to a microservices estate over several years using the Strangler Fig pattern (gradually extract services from a monolith, route traffic away, retire the old code). Identity was extracted first because it was the most critical. Comprehensive monitoring went in before decomposition started. Backward compatibility was maintained throughout. The result: hundreds of teams, thousands of deploys per day, four 9s of uptime.

Subdomain classification: where to invest engineering effort

Not every service deserves the same investment. DDD splits the world into three:

A useful rule of thumb: spend 60–70% of engineering effort on the Core, 20–30% on Supporting, and as little as possible on Generic. The Core is what your competitors cannot copy; the Generic is what your competitors are also paying Stripe for.

Best Practices

Final checklist for a service boundary

Canonical references

• Eric Evans — Domain-Driven Design (2003). Bounded contexts, aggregates, ubiquitous language, anti-corruption layers.
• Sam Newman — Building Microservices. The practitioner’s guide; covers nearly every principle here in depth.
• Robert C. Martin — SOLID. Single Responsibility applies just as well to services as to classes.
• Adam Wiggins / Heroku — The Twelve-Factor App. The canonical statelessness, config, and process model for cloud services.
• Martin Fowler & James Lewis — Microservices (2014). The original essay, where “smart endpoints, dumb pipes” comes from.
• Melvin Conway — How Do Committees Invent? (1968). Conway’s Law.
• Google SRE Book. Error budgets, golden signals, and the discipline of running production at scale.