Writing

Source & Architecture

How to structure source code so it survives growth, teams, and change.

Practical, beginner-friendly deep-dives on software architecture and how source code is organised — from Ports & Adapters and Clean Architecture to dependency management, module boundaries, and the trade-offs behind each. Built on diagrams, real examples, and lessons that scale from solo projects to enterprise systems.

Scaling the Database: Indexes, Read Replicas, Caching, and Sharding — In That Order

The database is almost always the first thing to buckle under growth — and the first thing engineers over-engineer in a panic. A no-hype ladder for scaling the data layer: why you measure and add an index before touching hardware, how read replicas exploit the read/write asymmetry (and the replication-lag trap they bring), where caching helps and why invalidation is the hard part, and when you finally reach for partitioning and sharding — the one decision that is genuinely hard to undo.

Jun 4, 202614 min read

Source & Architecture

You Can't Fix What You Can't See: Logs, Metrics, Traces, and SLOs at Scale

In a monolith, debugging was almost cosy — one log file, one process, one place the truth lived. Distributed systems quietly took that away: one request now fans out across a dozen services, and when it breaks there is no single log to read. A no-hype guide to seeing your system at scale: the three pillars (metrics, logs, traces) and the question each one answers, why a single propagated trace ID is the highest-leverage habit you can adopt, how SLOs turn reliability into an error budget you can spend, and how to alert on symptoms so on-call doesn't burn out.

Jun 4, 202614 min read

Source & Architecture

Events, Queues, and the Art of Not Calling Each Other: Event-Driven Architecture, Explained

When services hold hands through synchronous calls, latency adds up and one slow dependency takes down checkout. A no-hype guide to event-driven architecture: sync vs async, commands vs events, what brokers really promise (at-least-once, not exactly-once), choreography vs orchestration, and exactly when NOT to reach for events.

Jun 3, 202613 min read

Source & Architecture

Who Owns the Data? Database-per-Service, Sagas, and Eventual Consistency Without Tears

Splitting code is the easy half — splitting data is where distributed systems humble you. A practical guide to owning data across services: why a shared database is a distributed monolith, the trade from ACID to eventual consistency, the dual-write bug and the outbox that fixes it, sagas with compensating actions, and when CQRS and event sourcing are worth their lifetime cost.

Jun 3, 202613 min read

Source & Architecture

The Distributed-Systems Tax, Paid: Timeouts, Retries, Circuit Breakers, and Idempotency

The moment a call leaves your process it can be slow, fail, or happen twice — and that is the normal case, not the exception. The resilience toolkit, explained plainly: why timeouts come first, how retries become a self-inflicted DDoS without backoff and jitter, why idempotency is the price of retrying, and how circuit breakers, bulkheads, graceful degradation, and observability keep one bad dependency from taking down everything.

Jun 3, 202613 min read

Source & Architecture

Ports & Adapters (Hexagonal Architecture), Explained Simply

A friendly, example-driven guide to Hexagonal Architecture: what ports and adapters really are, the one rule that makes it work, and exactly how much of it to apply — whether you are a solo founder or an enterprise team.

May 29, 202616 min read

Source & Architecture

Clean, Onion & Hexagonal Architecture: One North Star, Three Names

They look like three rival architectures. They are really the same idea — dependencies pointing inward, frameworks at the edge — drawn three ways. Here is what each one actually adds, and which to reach for.

May 29, 202615 min read

Source & Architecture

Dependency Injection & Inversion of Control, Without the Magic

DI containers feel like wizardry until you see the plain idea underneath: stop letting code create its own dependencies, and hand them in instead. A from-scratch guide, with real examples and the testing payoff.

May 29, 202614 min read

Source & Architecture

Structuring a Codebase: By Layer, By Feature, or By Domain?

Should your top-level folders be controllers/services/models, or orders/billing/auth? The choice quietly shapes how your codebase grows. A practical tour of by-layer, by-feature, and screaming architecture — with the trade-offs at each company size.

May 29, 202614 min read

Source & Architecture

Monolith, Modular Monolith, Microservices: An Honest Decision Guide

Microservices are a tax you pay for organisational scale — not a starting point. A no-hype walk from monolith to modular monolith to microservices, with the signals that tell you when (and whether) to split.

May 29, 202616 min read

Source & Architecture

Micro-Frontends: When They're Worth It, and What They Cost

Splitting the frontend into independently deployable pieces can free teams — or bury you in complexity. Written from shipping an Angular-host + React-modules setup at scale: when micro-frontends pay off, and the bill they come with.

May 29, 202615 min read