Architecture patterns and when to use them

HOW IT FITS TOGETHER

KEY TERMS

Structure vs topology

Layered, hexagonal, slices and MVC organise code; monolith, microservices and functions decide process and network boundaries. They are orthogonal: a hexagonal monolith and a layered microservice are both normal. Most arguments that conflate them end with a network boundary where a package boundary would do.

Ports, adapters and the dependency rule

Cockburn's ports are purposeful conversations the application owns; adapters convert a technology to that conversation. Driving (primary) adapters call in, driven (secondary) adapters are called out to. Clean and onion architecture restate the same rule: source dependencies point inward and the inner circle names nothing in the outer one.

Conway's law

A system's design copies its organisation's communication structure. Service boundaries that cut across team boundaries create constant cross-team coordination; the inverse Conway maneuver reshapes teams around the capabilities you want as boundaries. Architecture and team design have to move together.

Change coupling

What must change, test and deploy together. Layers couple a feature across folders; slices and capability modules keep it local. Across services, change coupling shows up as lockstep deploys, which means you are paying for distribution without getting independence.

Data ownership

One module or service writes a given table; others ask through its API or consume its events. Shared tables across services couple schemas and deploys more tightly than shared code. In a modular monolith, enforce it by convention or separate schemas; in microservices, by separate databases.

Operational maturity

Fowler's microservice premium: automated deployment, monitoring, distributed tracing, failure handling and eventual consistency are prerequisites, not follow-ups. A team that cannot yet trace a request across three services should not create thirty.

Latency budgets

Each synchronous hop adds network latency, serialisation and a new failure mode, and tail latencies compound across a call chain. If a page needs data from five services synchronously, the boundaries are probably in the wrong place, or you need event-carried copies of the data.

IN YOUR STACK

// domain/order.ts: pure rules, imports nothing from infrastructure
export class Order {
  constructor(readonly id: string, public status: "open" | "cancelled", readonly paidAt?: Date) {}
  cancel(now: Date) {
    if (this.paidAt && now.getTime() - this.paidAt.getTime() > 86_400_000) throw new Error("too late to cancel");
    this.status = "cancelled";
  }
}
// application/ports.ts: outbound port, declared and owned by the core
export interface OrderRepository { get(id: string): Promise<Order | undefined>; save(o: Order): Promise<void> }
// application/cancel-order.ts: inbound port as a use case
export const cancelOrder = (orders: OrderRepository, now: () => Date) => async (id: string) => {
  const order = await orders.get(id);
  if (!order) throw new NotFound(id);
  order.cancel(now());
  await orders.save(order);
};
// adapters/in-memory-orders.ts: test adapter; PostgresOrders implements the same port
export class InMemoryOrders implements OrderRepository {
  private rows = new Map<string, Order>();
  async get(id: string) { return this.rows.get(id); }
  async save(o: Order) { this.rows.set(o.id, o); }
}
const cancel = cancelOrder(new PostgresOrders(pool), () => new Date()); // main.ts: composition root
app.post("/orders/:id/cancel", async (req, res) => { await cancel(req.params.id); res.sendStatus(204); });

package billing // the consumer declares the ports it needs, nothing more
type Invoices interface {
	Overdue(ctx context.Context, asOf time.Time) ([]Invoice, error)
}
type Notifier interface {
	Remind(ctx context.Context, customerID, invoiceID string) error
}
type Reminders struct {
	invoices Invoices
	notify   Notifier
}
func NewReminders(i Invoices, n Notifier) *Reminders { return &Reminders{invoices: i, notify: n} }
func (r *Reminders) Run(ctx context.Context, now time.Time) error {
	overdue, err := r.invoices.Overdue(ctx, now)
	if err != nil {
		return fmt.Errorf("load overdue: %w", err)
	}
	for _, inv := range overdue {
		if err := r.notify.Remind(ctx, inv.CustomerID, inv.ID); err != nil {
			return fmt.Errorf("remind %s: %w", inv.ID, err)
		}
	}
	return nil
}
// package postgres: NewStore(db) returns a concrete *Store that satisfies billing.Invoices implicitly

// order/domain/OrderRepository.java: the port, owned by the domain
public interface OrderRepository { Optional<Order> findById(OrderId id); void save(Order order); }
// order/application/CancelOrder.java: use case, depends only on ports
@Service
public class CancelOrder {
  private final OrderRepository orders;
  private final Clock clock;
  public CancelOrder(OrderRepository orders, Clock clock) { this.orders = orders; this.clock = clock; }
  @Transactional
  public void handle(OrderId id) {
    Order order = orders.findById(id).orElseThrow(() -> new OrderNotFound(id));
    order.cancel(clock.instant());
    orders.save(order);
  }
}
// order/adapter/out/JdbcOrderRepository.java: driven adapter, package-private
@Repository
class JdbcOrderRepository implements OrderRepository {
  private final JdbcClient jdbc;
  JdbcOrderRepository(JdbcClient jdbc) { this.jdbc = jdbc; }
  public Optional<Order> findById(OrderId id) { /* SELECT ... -> map to Order */ }
  public void save(Order order) { /* UPDATE orders SET status = ? WHERE id = ? */ }
}

// src/features/
//   cancel-order/   endpoint.ts  handler.ts  handler.test.ts
//   list-orders/    endpoint.ts  query.ts
// src/features/cancel-order/handler.ts
import { z } from "zod";
import { db } from "../../shared/db"; // shared infrastructure is fine; shared feature logic is not

export const CancelOrder = z.object({ orderId: z.uuid(), reason: z.string().max(200) });

export async function cancelOrder(input: z.infer<typeof CancelOrder>, userId: string) {
  return db.transaction().execute(async (trx) => {
    const order = await trx.selectFrom("orders").selectAll()
      .where("id", "=", input.orderId).where("user_id", "=", userId)
      .forUpdate().executeTakeFirst();
    if (!order) return { status: 404 } as const;
    if (order.status !== "open") return { status: 409, error: "not cancellable" } as const;
    await trx.updateTable("orders")
      .set({ status: "cancelled", cancel_reason: input.reason })
      .where("id", "=", order.id).execute();
    return { status: 204 } as const;
  });
}

// .dependency-cruiser.cjs  (CI: npx depcruise src --config .dependency-cruiser.cjs)
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
  forbidden: [
    {
      name: "modules-only-via-public-api",
      comment: "Import another module through its index.ts, never its internals",
      severity: "error",
      from: { path: "^src/modules/([^/]+)/" },
      to: { path: "^src/modules/[^/]+/", pathNot: ["^src/modules/$1/", "^src/modules/[^/]+/index\\.ts$"] },
    },
    {
      name: "domain-is-framework-free",
      severity: "error",
      from: { path: "^src/modules/[^/]+/domain/" },
      to: { path: ["^node_modules/(express|pg|@aws-sdk)/", "^src/modules/[^/]+/adapters/"] },
    },
    { name: "no-circular", severity: "error", from: {}, to: { circular: true } },
  ],
  options: { tsConfig: { fileName: "tsconfig.json" }, doNotFollow: { path: "node_modules" } },
};

// com/acme/shop/inventory/package-info.java
@org.springframework.modulith.ApplicationModule(
  allowedDependencies = { "order :: events" }
)
package com.acme.shop.inventory;

// com/acme/shop/order/events/package-info.java: the only part of order others may use
@org.springframework.modulith.NamedInterface("events")
package com.acme.shop.order.events;

// src/test/java/com/acme/shop/ModularityTests.java
class ModularityTests {
  ApplicationModules modules = ApplicationModules.of(ShopApplication.class);

  @Test
  void verifiesModuleStructure() {
    modules.verify(); // no cycles, no access to internal packages, only allowed dependencies
  }

  @Test
  void writesDiagrams() {
    new Documenter(modules).writeModulesAsPlantUml().writeIndividualModulesAsPlantUml();
  }
}

// functions/reserve-slot.ts: a driving adapter; the core never sees API Gateway types
import type { APIGatewayProxyHandlerV2WithJWTAuthorizer } from "aws-lambda";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { reserveSlot, SlotTaken } from "../core/reserve-slot"; // pure use case
import { DynamoSlots } from "../adapters/dynamo-slots"; // implements the Slots port

// Created once per execution environment and reused by later invocations.
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const slots = new DynamoSlots(ddb, process.env.TABLE_NAME!);

export const handler: APIGatewayProxyHandlerV2WithJWTAuthorizer = async (event) => {
  const body = JSON.parse(event.body ?? "{}");
  if (typeof body.slotId !== "string") return { statusCode: 400, body: "slotId required" };
  const userId = String(event.requestContext.authorizer.jwt.claims.sub);
  try {
    const booking = await reserveSlot(slots, { slotId: body.slotId, userId });
    return { statusCode: 201, body: JSON.stringify(booking) };
  } catch (err) {
    if (err instanceof SlotTaken) return { statusCode: 409, body: err.message };
    throw err; // let Lambda record the failure
  }
};

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Distributed monolith: services that share a database or must deploy in lockstep. You pay network, consistency and ops costs and get none of the independence.
• Splitting by technical layer across teams or services (a UI service, a logic service, a data service). Every feature then crosses every boundary; split by business capability instead.
• Hexagonal theatre: an interface, an implementation and a DTO mapper for every class, with no second adapter and no tests using fakes. Add a port where you need a seam, not by reflex.
• Boundaries enforced only in diagrams. Without a dependency-cruiser, ArchUnit or Spring Modulith check in CI, imports across module internals creep in during the first deadline.
• Synchronous call chains between services with no latency budget. Tail latencies and failure probabilities multiply; use event-carried state or co-locate the data instead.
• One Lambda per endpoint, each opening its own database connections. Bursts exhaust the database; use a proxy or pool and keep a shared core library.

WHEN IT BREAKS IN PRODUCTION

• The team wants microservices too early
• A brief blip turns into a long outage
• Requests hang waiting for a database connection

SOURCES

• Alistair Cockburn: Hexagonal architecture (opens in new tab)Checked 2026-10-11
• Martin Fowler: Presentation Domain Data Layering (opens in new tab)Checked 2026-10-11
• Jimmy Bogard: Vertical Slice Architecture (opens in new tab)Checked 2026-10-11
• Martin Fowler: MonolithFirst (opens in new tab)Checked 2026-10-11
• Martin Fowler: Conway's Law (opens in new tab)Checked 2026-10-11
• Azure Architecture Center: Architecture styles (opens in new tab)Checked 2026-10-11