System Architecture

System architecture is the overall shape of a system: its parts, how they connect, and the rules for how it may change. It gives a team one shared picture, so decisions stop depending on who remembers what.

• Software architecture: the inside of one application: its modules, layers and APIs.
• System architecture: the wider view, adding hardware, networks, storage, outside systems and people.
• System design: one level down. Architecture names the parts, design explains how each part works.
• The standard: ISO/IEC/IEEE 42010 treats an architecture and the documents describing it as two separate things.

Every real system is made of the same four things. What changes from one system to the next is how you combine them.

• Hardware and infrastructure: servers, storage and networks, usually rented as cloud services and defined as code.
• Software: the code that does the business work, usually split into presentation, logic and data layers.
• Interfaces: the contracts between parts. A clean one lets you swap a payment service in a sprint, not a quarter.
• Data: where information lives and how it moves: API calls, event streams or scheduled batch jobs.

Services need a contract. The right protocol depends on who is calling and how chatty the conversation will be, and a gateway keeps the outside world away from your internals.

• REST: resources over HTTP. Easy to cache and debug, and the usual choice for public APIs.
• GraphQL: clients ask for exactly the fields they need. Great for varied front ends, harder to cache.
• gRPC: compact binary calls with generated clients. Great between internal services.
• WebSockets: a long-lived, two-way connection for chat, live dashboards and games.
• API gateway: one front door that handles auth, rate limits and routing to the services behind it.

One codebase, built, deployed and scaled as one unit. It is quick to build, which is why most successful products began this way. The trouble starts when it outgrows what the team can hold in their heads.

• Best for: small teams, early products and one well-understood domain.
• Scales: mostly upwards, by moving to a bigger machine.
• Modular monolith: still one deployable, but with strict boundaries between modules. Often the right answer for far longer than people expect.
• The cost: one bad deploy or crash takes everything down together.

Two roles: a server owns the resources and a client asks for them. The web runs on this, and so do most mobile apps. It is the default mental model for software because it is simple.

• Best for: web apps, business software and mobile backends.
• Scales: well at first, by adding servers behind a load balancer.
• The cost: the central server can become the bottleneck.

The product is split into small services that run on their own, own their own data and talk over the network. You get independent deploys and scaling, and in exchange you inherit all the problems of distributed systems.

• Best for: large engineering organisations with domains that can evolve separately.
• Scales: one service at a time.
• The cost: network failures, eventual consistency and much harder debugging.
• Common trap: copying this style because a big company uses it, long before you have their problems.

Instead of one service calling another, a service announces that something happened and whoever cares reacts. Producers and consumers no longer need to know each other, which scales well but makes cause and effect harder to follow.

• Best for: real-time pipelines, integrations and asynchronous workflows.
• Scales: very well, because consumers work at their own pace.
• The cost: tracing why something happened takes real tooling.

You upload short-lived functions and the cloud provider runs them. There are still servers, but they are no longer your job. You pay per run, and scaling happens without you.

• Best for: spiky workloads, glue code and event processing.
• Scales: automatically, from zero upwards.
• The cost: cold starts, tighter ties to one vendor, and a poor fit for long-running work.

The application is split into horizontal layers with one job each. It is the pattern sitting inside most monoliths and many microservices.

• Presentation: what people see and touch.
• Business logic: the rules of the product, like who can refund an order and when.
• Data access: the only layer that talks to storage.
• The cost: a change that crosses layers, like a new field, ripples through all of them.

Business logic sits in the middle and knows nothing about the outside. It exposes ports, and adapters plug the outside world into those ports. Replacing a database means replacing one adapter, not rewriting the core.

• Best for: long-lived business logic that needs thorough testing.
• Port: an interface the core defines, such as "save an order".
• Adapter: one real implementation of a port, such as a Postgres repository.
• The cost: more upfront structure than a simple app needs.

No style is best in general. The right one depends on your team size, your workload and how much operational work you can carry. Real systems usually mix several.

• Constraints first: team size, budget, compliance and existing systems narrow the choice before any preference does.
• Mixing is normal: an online shop might use microservices, events and serverless together behind one gateway.
• Choose boring: pick the simpler option when it is good enough.

Good architecture comes from honest constraints, not from getting everything right on day one. These four steps repeat for as long as the system lives.

• Requirements: write down what it must do, plus its limits on speed, uptime, security and cost.
• Pattern: choose a style that fits those constraints. The AWS Well-Architected Framework is a useful checklist.
• Dependencies: map every service, database and data flow so hidden coupling shows up early.
• Failure: plan for it with circuit breakers, retries, spare capacity and good monitoring.

Most architecture work is not a blank page. Usually a new front end must keep talking to old systems that still own important rules, and the job is managing the border between them.

• Integration layer: a gateway and event bus that translate between new and old.
• Move in slices: replace one capability at a time while the old system keeps running.
• Measure debt first: modernisation goes better when you size the problem before choosing the new runtime.

The same problems appear in almost every system that grows past its first design. They feed each other, which is why they tend to arrive together.

• Technical debt: hardcoded settings and tight coupling buy speed now and charge interest later.
• Overengineering: building for scale you do not have. It is one of the most common mistakes of all.
• Lost visibility: diagrams go stale within weeks, and soon nobody knows the whole system.

Plain layers group code by technical job, so every controller sits with every other controller and any class can reach any other. As the system grows, nothing stops one feature from reaching into another. A modular monolith regroups the code by business capability, and each module keeps its own layers.

• The problem with layers: public classes everywhere make code hard to reuse, and easy to misuse.
• Module: one business capability with its own Controller, Service, Repository and Model.
• Interface: the only door between modules. Everything else stays private.
• Internal and external: external services are for other modules, internal ones only for the module itself.
• Why it pays off: still one deployment, but each module could later become its own service.

A Model usually holds everything about a record, including things a caller should never see. Returning it directly is a common way data leaks. A Data Transfer Object carries only the fields one request needs.

• Excessive data exposure: sending a whole object when the client asked for a small part of it.
• External DTO: what other modules and clients may see.
• Internal DTO: richer data used only inside a module.
• Different views: a dropdown and a profile page can use different DTOs from one Model.

Run each module as its own application and you have microservices, along with new problems. Clients would need to know every address, and in the cloud those addresses change on every restart. A gateway gives clients one address, and a registry keeps track of where each service is.

• API Gateway: one front door for routing, filters and rate limits.
• Service Discovery: each service registers its name and address when it starts.
• Call by name: clients ask for order-service, not for an IP address.
• Spring example: Eureka is the registry, and a gateway route such as lb://order-service looks it up.

Sharing a single database across microservices creates a bottleneck, and quietly couples them back together. Giving each service its own database means each one can scale and fail on its own.

• Scale by need: grow the orders database for a sale without touching anything else.
• Stronger security: a compromised service can reach only its own data.
• Clear ownership: other services must ask through an API or an event.
• The cost: no joins across services, and keeping data consistent gets harder.

With REST, the caller waits for each service in turn, so a slow service slows the whole chain. With Kafka, a service writes an event to a durable log and moves on. Other services read it when they are ready.

• Topic: a named stream of events, stored on disk.
• Partition: a topic is split so many consumers can share the work.
• Consumer group: consumers in a group divide the partitions, so each event is handled once per group.
• Replica: copies of each partition on other brokers. If one broker dies, a copy takes over.
• When to use which: REST when the caller needs an answer now, events when it does not.

Frontends need structure as much as backends do. The usual path runs from technical layers, to components grouped by business domain, to headless components where behaviour is completely separate from appearance.

• Layer-based: separate folders for UI, handlers, API calls and state. Simple, but one feature ends up spread across all of them.
• Modularized component: each domain, such as Cart, holds its own UI, Hook, API calls and state.
• Headless component: a reusable piece with behaviour and no styling of its own.
• Shared parts: keep one config for backend URLs, and one helper for all requests.

One diagram cannot satisfy everyone, because a developer, a tester and an operations engineer ask different questions. Philippe Kruchten's 4+1 model describes one system from four views, then ties them together with scenarios.

• Logical view: what the system does, for end users. Class diagrams fit here.
• Process view: what runs at the same time, for performance and scaling.
• Development view: how the code is organised, for programmers.
• Physical view: what runs on which machine, for system engineers.
• Scenarios: the +1. Key use cases that walk through the other four views and check they agree.

A good diagram answers one question at one level of detail. The C4 model is the most widely used standard because it makes you choose your zoom level: Context, Container, Component, Code. The next four notes draw the same online shop at each level.

• Always include: the parts that matter, arrows with direction and protocol, outside systems, and a clear title.
• Worth adding: notes on how each part fails or scales, and why it was chosen.
• Keep it in code: tools like Structurizr and Mermaid let you version diagrams alongside the code.

The big picture. Your whole system is one box, surrounded by the people who use it and the outside systems it depends on. Anyone in the company should be able to read this one.

• Shows: people, your system, and external systems.
• Hides: all technology. No databases, no frameworks.
• Audience: everyone, including managers and customers.

Zoom into the shop. A container is anything that runs or stores data on its own: a web app, an API, a database, a queue. It has nothing to do with Docker specifically. This is where technology choices appear.

• Shows: each app and data store, its technology, and how they talk.
• Example styles: this shop mixes microservices, events and a serverless function.
• Audience: developers, and operations and support staff.

Zoom into one container, here the Orders API. A component is a group of related code behind a clear interface. Draw this only for containers that are complex enough to need it.

• Shows: the main parts of one container and what each is responsible for.
• Audience: the developers working on that container.
• When to skip: small containers, where the code is already easy to follow.

Zoom into one component to see classes and interfaces. Most teams skip this level, because good tools can generate it and the code itself says the same thing.

• Shows: classes, interfaces and how they relate.
• Audience: the developers changing that exact code.
• When to use it: for the tricky corner of a system, not everywhere.