Docs

Architectural patterns

Software architectural patterns 🧱

Good architecture does not perform miracles, but it prevents disasters. In production, that is worth about as much as a well-executed miracle.

This document gives you a reasoned map of the main architectural and design patterns, grouped into macro categories. The goal is to provide shared vocabulary and a practical map to decide what to use, when, and why, without falling in love with the buzzword of the week.

Style note: you will find older names such as master/slave updated to more accurate terminology, for example primary/replica. Diagrams can stay on the whiteboard. Here we go straight to the point.

Application architectures (structural) 🧩

Patterns that define the internal structure of an application and the separation of responsibilities.

Layered (n-tier) 🧩

Organizes the application into layers such as presentation, application, domain, and persistence, with one-way dependencies downward.

Pros: clear structure, high testability, easier onboarding, layer reuse.
Cons: rigidity between layers, waterfall-like hops that add latency, temptation to punch through the layers.
Example: enterprise CRUD app with moderate validation and business rules.

🎯 Quando usarlo

Simple or medium-complexity domains; fast onboarding and clear layer separation matter.

⚠️ Attenzioni

Avoid skipping layers; define contracts and DTOs. Measure the impact of multiple hops across layers.

MVC (model-view-controller) 🧩

Separates state handling (Model), presentation (View), and flow/interactions (Controller), a classic pattern for web UI.

Pros: separation of responsibilities, view and controller testability, parallel work between roles.
Cons: can become verbose; in simple domains it may add unnecessary layers.
Example: e-commerce with catalog/cart views and controllers for user actions.

🎯 Quando usarlo

Rich interfaces, SSR or SPA frameworks; clear separation between presentation and logic.

⚠️ Attenzioni

Avoid fat controllers; keep the logic in the domain; test views and controllers in isolation.

Hexagonal (ports & adapters) 🧩

Puts the domain at the center; everything involving I/O such as DB, APIs, queues, and UI connects through ports (interfaces) and adapters.

Pros: technology independence, excellent testability, adapter substitutability.
Cons: more abstractions to manage, steeper initial curve.
Example: payments core with multiple adapters for different PSPs.

🎯 Quando usarlo

When you expect technology changes such as DB, broker, or PSP, or want to test the domain in isolation.

⚠️ Attenzioni

Watch for infrastructure details leaking into the domain; keep ports minimal and stable.

Microkernel (plug-in) 🧩

A minimal core provides base services that are extended through independent plugins.

Pros: extensibility, fast experimentation, plugin isolation.
Cons: plugin lifecycle management, core API compatibility.
Example: rules engine or scheduler with plugin jobs.

🎯 Quando usarlo

Stable core with features extended by plugins; need to enable or update capabilities at the edges.

⚠️ Attenzioni

Core API compatibility, plugin versioning, lifecycle handling, and isolation.

Pipes & filters 🧩

A chain of independent filters transforms data through a pipeline.

Pros: composition, filter reuse, parallelization.
Cons: serialization overhead between filters, bottlenecks.
Example: log pipeline parse → enrich → route → store.

🎯 Quando usarlo

ETL, stage-based transformations, streaming with independent and reusable steps.

⚠️ Attenzioni

Back-pressure, parallelization, bottlenecks, and serialization between steps.

Modular monolith 🧩

A single codebase/process organized into well-isolated modules with explicit boundaries and controlled dependencies.

Pros: operational simplicity, local transactions, unified deployment.
Cons: coupling risk if boundaries are not respected; it scales only up to a point.
Example: business application with modules for orders, invoices, warehouse, and reporting.

🎯 Quando usarlo

Small or medium team, clear domain boundaries, but no need for distribution; you want to avoid a chaotic monolith and postpone microservices.

⚠️ Attenzioni

Enforce modular boundaries with linters or architectural rules, internal APIs between modules, one-way dependencies, and stable contracts.

Onion / Clean architecture 🧩

Variants that, like hexagonal architecture, keep the domain at the center and push dependencies outward.

Pros: testability, framework independence, easy infrastructure replacement.
Cons: more abstractions, adoption curve.
Example: service core with use cases in the application layer and repository interfaces at the edge.

🎯 Quando usarlo

Strong central domain; you want to reduce framework lock-in and make the core testable without I/O.

⚠️ Attenzioni

Keep dependencies always pointing outward; do not leak library-specific types into the domain.

MVVM (model-view-viewmodel) 🧩

UI pattern that separates the View from presentation logic (ViewModel). The ViewModel mediates and adapts the Model for the View, exposing state and behavior, and is ideal for data binding.

Pros: presentation-logic testability, reuse, and binding.
Cons: complexity if binding is not managed with discipline.
Example: mobile or desktop app with reactive binding between View and ViewModel.

🎯 Quando usarlo

Reactive UI with binding; need to test presentation logic without the View.

⚠️ Attenzioni

Limit logic in the View; avoid omniscient ViewModels; manage lifecycle and binding carefully.

Distributed and integration architectures 🌐

Patterns that organize systems made of multiple components or services and their interactions.

Microservices 🌐

An application composed of small, autonomous services that can be deployed independently, ideally each owning its own data.

Pros: targeted scalability, faster delivery for teams, resilience to local failures.
Cons: distributed transactions, observability, higher operational costs.
Example: e-commerce with separate services for catalog, orders, payments, and recommendations.

🎯 Quando usarlo

Organization built around autonomous teams, broad domains with different scaling needs.

⚠️ Attenzioni

End-to-end observability, contract testing, consistency management with sagas or outbox, API governance; avoid shared databases and plan gradual data separation during transitions.

SOA (service-oriented) 🌐

More coarse-grained and standardized services, often orchestrated; historically ESB-centric, today usually lighter.

Pros: stable contracts, service composition, governance.
Cons: risk of a central bus becoming a bottleneck; rigidity.
Example: enterprise services for master data, billing, and reporting shared across applications.

🎯 Quando usarlo

Enterprise integration with stable contracts and broad reuse.

⚠️ Attenzioni

Avoid centralized buses as a single bottleneck; version contracts properly; monitor everything.

Event-driven 🌐

Asynchronous communication based on events produced and consumed by decoupled components.

Pros: decoupling, scalability, extensibility through new consumers without changing producers.
Cons: ordering and deduplication, schema evolution, eventual consistency.
Example: orders → event OrderPlaced → notifications/shipping/analytics.

🎯 Quando usarlo

Loose integration between domains, real-time behavior, fan-out, reactivity.

⚠️ Attenzioni

Schema evolution, ordering and partitioning, idempotency, DLQ, and traceability.

Broker 🌐

A mediator handles routing, transformations, and remote invocations between components.

Pros: decoupling, centralized observability.
Cons: latency, contention point, lock-in.
Example: integrating legacy systems through a message broker with schema transformations.

🎯 Quando usarlo

Technological heterogeneity and need for centralized routing or transformations.

⚠️ Attenzioni

Do not move business logic into the broker; avoid lock-in; watch latency.

Pub/Sub 🌐

Producers publish to topics, consumers subscribe and receive events.

Pros: adding consumers without affecting producers, horizontal scalability.
Cons: end-to-end testing, ordering and partitioning management.
Example: push and email notifications triggered from a single event.

🎯 Quando usarlo

Event fan-out, notifications, multi-consumer streams.

⚠️ Attenzioni

Delivery semantics such as at-least-once or exactly-once, ordering and partitioning, end-to-end testing.

API gateway 🌐

A single entry point that provides routing, auth, rate limiting, aggregation, and observability toward downstream services.

Pros: simplifies clients, centralizes policies and security.
Cons: bottleneck risk, complex configuration.
Example: gateway exposing public endpoints and routing to internal microservices.

🎯 Quando usarlo

Many internal services and a need for cross-cutting controls like auth, quota, and logging.

⚠️ Attenzioni

High availability for the gateway, configuration rollback, performance, and cold starts if serverless.

Backend for Frontend (BFF) 🌐

A dedicated backend for each front-end type such as web or mobile, adapting APIs, performance, and aggregations.

Pros: APIs tailored to user experience, reduced over-fetching and under-fetching.
Cons: more artifacts to maintain, duplication risk.
Example: mobile BFF with aggregated responses and minimized payloads.

🎯 Quando usarlo

Different clients such as web and mobile with different needs; need to optimize UX and payloads.

⚠️ Attenzioni

Keep frontend teams aligned; share contracts and common policies; avoid putting business logic inside the BFF.

Service mesh / sidecar 🌐

Infrastructure layer such as Envoy or Istio that pushes networking, mTLS, retries, circuit breakers, and observability into sidecars.

Pros: consistent policies without touching application code, rich telemetry.
Cons: operational complexity, resource overhead.
Example: microservices with sidecar proxies for mTLS and traffic control.

🎯 Quando usarlo

Many services, with a need for consistent security, traffic control, and advanced observability.

⚠️ Attenzioni

Mesh version management, overhead cost, SRE training; application logic still has to manage business errors that the mesh cannot interpret.

Service discovery 🌐

Dynamic resolution of service endpoints through DNS or registries so clients can find active instances.

Pros: resilience to changes and scaling, no hardcoded endpoints.
Cons: health-check and caching complexity.
Example: clients resolving instances via Consul, Eureka, or DNS.

🎯 Quando usarlo

Dynamic environments such as Kubernetes and cloud platforms with frequent scaling and rolling updates.

⚠️ Attenzioni

Caching and TTL, retries, accurate health checks, and timeouts aligned with SLA.

Serverless (FaaS/event-driven) 🌐

Provider-managed functions activated by events or HTTP, with automatic scaling and pay-per-use billing.

Pros: fast time-to-market, automatic scaling, variable costs.
Cons: cold starts, runtime limits, harder observability and local development.
Example: function processing queue events and updating a datastore.

🎯 Quando usarlo

Bursty or event-driven workloads, lightweight integrations, small backends without server management.

⚠️ Attenzioni

Cold starts mitigated with provisioned concurrency or warm-up, idempotency, timeouts and limits, lock-in to managed services; consider edge or read-through caching to reduce latency.

Client-server 🌐

Client requests resources or services, server processes and responds.

Pros: centralized data, simplified security.
Cons: single point of failure if not redundant.
Example: mobile app interacting with REST APIs.

🎯 Quando usarlo

Base pattern for web/mobile and centralized services.

⚠️ Attenzioni

Server redundancy, statelessness, caching, and rate limiting where needed.

P2P (peer-to-peer) 🌐

Peer nodes with no central authority, where each node can act as both client and server.

Pros: no SPOF, scalability with nodes.
Cons: variable security and quality of service.
Example: file sharing or edge synchronization.

🎯 Quando usarlo

Content distribution, decentralized synchronization, resilient networks.

⚠️ Attenzioni

End-to-end security, variable QoS, NAT traversal often managed by WebRTC or libp2p, node reputation.

Controller-responder 🌐

A controller coordinates writes, while responder nodes serve reads or replicas.

Pros: isolates read load, reduces contention.
Cons: synchronization and lag between copies.
Example: API reading from a replica and writing to the primary.

🎯 Quando usarlo

Read-heavy workloads; need to isolate the read path.

⚠️ Attenzioni

Replica lag, query routing, cache invalidation, and consistency policies.

Data, query, and persistence 💾

Patterns focused on how to model access to and management of data.

CQRS 💾

Clear separation between the write model (commands) and the read model (queries), so they can be optimized independently. It does not necessarily imply separate databases: separation can be logical only.

Pros: read performance, dedicated models, independent scaling.
Cons: eventual consistency, higher complexity.
Example: denormalized read model for analytical dashboards.

🎯 Quando usarlo

Many reads, complex queries, need for optimized projections.

⚠️ Attenzioni

Handle eventual consistency, idempotent projections, synchronization, and recovery.

Event sourcing 💾

State is derived from an append-only sequence of events and rebuilt by replaying them.

Pros: full traceability, time travel, ability to build new projections later.
Cons: event migration, schema evolution, growing storage needs.
Example: accounting or orders with a complete timeline.

🎯 Quando usarlo

Strong audit requirements, time travel, and evolving rules.

⚠️ Attenzioni

Version events, use snapshots, plan schema migrations; for privacy and GDPR consider redaction or selective encryption.

Repository 💾

Abstraction of data access behind domain interfaces.

Pros: testability, separation of concerns.
Cons: risk of hiding useful datastore-specific capabilities.
Example: OrderRepository.findOpenByCustomerId(...).

🎯 Quando usarlo

Testing the domain without infrastructure dependencies; separation between persistence and domain.

⚠️ Attenzioni

Avoid overly generic repositories; expose meaningful domain queries; do not hide useful datastore features.

Sharding 💾

Partitioning data across multiple nodes according to a key such as customerId.

Pros: horizontal scalability, load isolation.
Cons: hotspots if the key is unbalanced, operational complexity.
Example: multi-tenant setup with shards per customer or region.

🎯 Quando usarlo

Very large datasets or throughput requiring horizontal scalability.

⚠️ Attenzioni

Choose the partition key carefully; prevent hotspots; plan rebalancing and migration.

Primary/replica (replication) 💾

Writes go to the primary, reads go to asynchronous or synchronous replicas.

Pros: offloads the read path, supports failover.
Cons: lag, temporary inconsistencies.
Example: reporting on a replica, critical operations on the primary.

🎯 Quando usarlo

Scaling reads and guaranteeing HA with failover.

⚠️ Attenzioni

Replica lag, consistency-aware routing, route-level consistency, split-brain during failover.

Static content hosting 💾

Separation and delivery of static assets through CDN or edge, apart from dynamic content.

Pros: low latency, reduced backend costs.
Cons: cache invalidation and coherence.
Example: images and CSS/JS on CDN; dynamic APIs from the backend.

🎯 Quando usarlo

High-traffic websites, media, and static assets served from edge or CDN.

⚠️ Attenzioni

Cache invalidation, TTL, asset hashing, and environment differences.

Cache-aside 💾

Application code reads from cache first and, on miss, loads from the database and populates the cache.

Pros: simple, lowers latency and DB load.
Cons: complex invalidation, stale data risk.
Example: user profile lookups with TTL and invalidation on update.

🎯 Quando usarlo

Frequently read and rarely updated data; want to reduce DB latency and cost.

⚠️ Attenzioni

Invalidation strategies, proper TTL, and consistency under concurrent updates.

Read-through cache 💾

The cache intercepts reads and, on miss, loads automatically from the datastore and populates itself, transparently to the caller.

Pros: simpler application side, automatic warm-up, reduced duplication of loading logic.
Cons: less control over invalidation, risk of stampede without protections, dependency on cache-layer features.
Example: product catalog automatically fetched by the cache from DB on first access.

🎯 Quando usarlo

Heavily read and rarely updated data; you prefer delegating loading to the cache layer.

⚠️ Attenzioni

Coherent TTL, stampede protection via locking or batching, post-write consistency, targeted invalidation.

Outbox (transactional outbox) 💾

Write events into an outbox table within the same transaction as the main write; a separate process publishes them reliably.

Pros: reliable event publication without losing or duplicating messages.
Cons: dispatcher process to manage; ordering per aggregate.
Example: when saving an order, persist the event into outbox and publish to the broker.

🎯 Quando usarlo

Reliable event integration between DB and broker; need for idempotency and consistency.

⚠️ Attenzioni

Idempotency keys, outbox cleanup, tracing between write and event.

Lambda / Kappa architecture 💾

Data architectures for analytics: Lambda combines batch and speed layers, Kappa uses streaming only to simplify. Note: these are system architectures more than pure persistence patterns.

Pros: scale on large volumes, enable real-time processing.
Cons: infrastructure complexity for Lambda, stream semantics for Kappa.
Example: event pipeline with real-time projections and periodic batch consolidation.

🎯 Quando usarlo

Analytics on large volumes, near real-time insights, and periodic consolidations.

⚠️ Attenzioni

Schema management, different layer latencies, idempotent execution, operational costs.

Reliability, resilience, and traffic control 🛡️

Patterns that help prevent the whole system from collapsing when something goes wrong, because it will.

Circuit breaker 🛡️

Stops calls to degraded or failing dependencies to avoid avalanches of errors.

Pros: stabilizes the system, protects resources.
Cons: state management with open/half-open/closed, non-trivial tuning.
Example: degrading non-essential functionality when a service is down.

🎯 Quando usarlo

Unreliable or latency-sensitive dependencies.

⚠️ Attenzioni

Timeouts, retries with jitter and backoff, clear and monitored fallbacks.

Bulkhead 🛡️

Isolates resources such as thread pools or connections for different components, preventing one failure from saturating the whole system.

Pros: fault containment and resource protection.
Cons: tuning limits and resource fragmentation.
Example: separate pools for calls to service A and service B.

🎯 Quando usarlo

Dependencies with different latency profiles; prevent cascading failure by saturation.

⚠️ Attenzioni

Pool sizing, metrics, alerts; combine with circuit breakers and timeouts.

Queue-based load leveling 🛡️

Put work into a queue to absorb spikes, with consumers processing at a sustainable pace.

Pros: smooths spikes, protects backends, increases resilience.
Cons: added latency, DLQ and ordering management.
Example: queue to process orders instead of directly calling a slow service.

🎯 Quando usarlo

Unpredictable spikes against slow or expensive services; need to smooth load.

⚠️ Attenzioni

Idempotency, DLQ, backlog visibility, estimate throughput to size consumers.

Retry/Timeout with backoff 🛡️

Configure timeouts and retries with backoff and jitter to handle transient errors without amplifying congestion.

Pros: automatic recovery from glitches, better stability.
Cons: if badly configured, they worsen the problem through retry storms.
Example: HTTP calls with short timeouts and limited exponential retry.

🎯 Quando usarlo

External or network dependencies with transient failures.

⚠️ Attenzioni

Limit retries, use jitter, coordinate with breakers, measure to tune parameters.

Saga 🛡️

Coordinates distributed transactions through local steps and compensating actions.

Pros: logical consistency, scalability.
Cons: higher complexity, many error cases.
Example: order → payment → stock reservation → shipping with appropriate rollback.

🎯 Quando usarlo

Multi-service processes without 2PC; need for logical consistency.

⚠️ Attenzioni

Idempotent compensations, timeouts, DLQ, observability of the flow, retry policy.

Throttling / rate limiting 🛡️

Traffic limitation to protect resources, SLA, and cost.

Pros: predictable load, isolation.
Cons: user experience impact if too aggressive.
Example: 100 req/min for a free-tier API.

🎯 Quando usarlo

Public or multi-tenant APIs, protection from bursts, cost control.

⚠️ Attenzioni

Fair policies such as token bucket or leaky bucket, coherent 429 responses, telemetry, and alerts.

Scalability and performance ⚡

Patterns designed to handle load and traffic variability.

Space-based ⚡

Distributes state and load across stateless processing units, with middleware handling in-memory data, messaging, and scale.

Pros: no central bottleneck, near-linear scalability.
Cons: consistency complexity, harder end-to-end testing.
Example: bidding or offer systems with sudden spikes.

🎯 Quando usarlo

Unpredictable load, low latency, need for in-memory scaling.

⚠️ Attenzioni

In-memory consistency and replication, eviction policies, eventual persistence, and recovery.

Evolution and modernization 🔧

Strangler 🔧

Places a façade between clients and legacy, migrating one feature at a time until the legacy system can quietly disappear.

Pros: lower risk, easier rollback, measurable progress.
Cons: double run during transition, complex routing.
Example: moving legacy endpoints to new services with configurable proxy routing and gradual rollout.

🎯 Quando usarlo

Progressive modernization of mission-critical monoliths.

⚠️ Attenzioni

Parallel routing and observability, characterization tests, rollback plans, feature flags.

Anti-corruption layer (ACL) 🔧

A layer that translates and reshapes data between systems or bounded contexts to protect your model from external impurities.

Pros: isolates the domain from third-party models; reduces semantic coupling.
Cons: translation code to maintain; added latency.
Example: adapter mapping legacy DTOs into domain value objects.

🎯 Quando usarlo

Integration with legacy or messy external contracts; protecting the internal model.

⚠️ Attenzioni

Transformation traceability, versioning, contract tests, and backward compatibility.

Strategic modeling approaches 🎯

Domain-Driven Design (DDD) 🎯

Modeling approach that guides architectural choices through ubiquitous language, bounded contexts, aggregates, and separation of the core domain.

Pros: business alignment, clear boundaries, expressive code.
Cons: initial investment, risk of over-engineering on simple CRUD.
Example: see also Domain Driven Design 🧩 in this section.

🎯 Quando usarlo

Complex domains with evolving rules; tight alignment with the business.

⚠️ Attenzioni

Start with strategic design; avoid a 1:1 mapping between bounded context and microservice; prevent over-engineering on CRUD.

How to choose (in 5 moves) 🧭

Clarify expected qualities: performance, scalability, time-to-market, compliance. No, you cannot optimize everything to the maximum at the same time.
Evaluate the domain: complex and evolving? DDD plus clear boundaries. Data-intensive? CQRS or event sourcing. Heavy integration? SOA or event-driven.
Look at the organization: small teams and few SREs? A good monolith or modular monolith. Multiple autonomous teams? Microservices, but only with mature platform and observability.
Deal with the ecosystem: cloud-native, legacy, vendor lock-in, internal skills. The perfect architecture that the team cannot operate is not perfect.
Move incrementally: feature flags, strangler, objective measurements. Changing course early is cheap; late is expensive.

Quick usage map 👇

Want to move fast on a non-complex domain? Layered or MVC plus repository.
Lots of reads and hard queries? CQRS, possibly with tailored projections.
Reactivity across heterogeneous services? Event-driven plus pub/sub.
High-value domains with stubborn rules? DDD plus hexagonal.
Modernizing mission-critical legacy? Strangler plus characterization tests.
Unpredictable peaks? Space-based plus caching or edge.

Compact comparison between patterns 🧪

Below is a compact table for some key patterns. Ratings are indicative, low/medium/high, and always need context.

Pattern	Scalability	Complexity	Team fit
Layered	Medium	Low	Small or mixed teams
MVC	Medium	Medium	Teams with separate UI and backend skills
Hexagonal	Medium	Medium	Domain and test-oriented teams
Microkernel	Medium	Medium	Teams managing plugins or extensions
Pipes & Filters	High	Medium	Data and processing teams
Microservices	High	High	Multiple autonomous teams plus SRE or Platform
SOA	Medium	Medium	Enterprise teams with strong governance
Event-driven	High	High	Teams skilled in messaging or streams
Pub/Sub	High	Medium	Integration and real-time teams
Client-server	Medium	Low	Generalist teams
P2P	High	High	Teams experienced in networking and distributed systems
API gateway	N/A	Medium	Backend or platform teams
BFF	Medium	Medium	Collaborative frontend/backend teams
Service mesh/sidecar	N/A	High	SRE or platform teams
Service discovery	N/A	Medium	Backend or DevOps teams
Serverless (FaaS)	High	Medium	Teams adopting managed services
CQRS	High (read)	High	Teams comfortable with projections
Event sourcing	Medium	High	Data-intensive or audit-focused teams
Repository	N/A	Low	Any test-oriented team
Sharding	High	High	Experienced DBA or ops teams
Primary/replica	Medium (read)	Medium	Backend teams with DBA support
Static hosting	High	Low	Web/app teams using CDN
Cache-aside	N/A	Medium	Backend/API teams
Read-through cache	N/A	Medium	Backend/API teams
Outbox	N/A	Medium	Backend/DB/stream teams
Lambda/Kappa	High	High	Data/stream teams
Circuit breaker	N/A	Medium	Backend/platform teams
Bulkhead	N/A	Medium	Backend/platform teams
Queue-based leveling	N/A	Medium	Backend/platform teams
Retry/Timeout	N/A	Low	Backend teams
Saga	N/A	High	Experienced distributed teams
Throttling	N/A	Medium	API/gateway teams
Space-based	High	High	Performance and low-latency teams
Strangler	N/A	Medium	Modernization teams
Anti-corruption layer	N/A	Medium	DDD/integration teams
Modular monolith	Medium	Medium	Small and medium teams
Onion/Clean	Medium	Medium	Domain-centric and test-centric teams
MVVM	Medium	Medium	UI teams
DDD	N/A	Medium-High	Product and domain-centric teams

Conclusion ✅

Patterns are tools, not religions. Choose the ones that maximize value in your context, observe their effects over time, and keep the system evolvable. Real seniority is knowing what not to apply.

Last updated on 3 May 2026

Domain Driven Design