Every System Has a Shape
Before you can contribute to a codebase, you need to see its shape. Not the individual files — the architecture. How does data flow? Where do decisions get made? What depends on what?
Common Shapes
The Monolith. Everything lives together. One deployment, one database, one codebase. Simple to understand, simple to deploy, hard to scale independently. Most software should start here.
The Layered Cake. Presentation layer, business logic layer, data layer. Each layer only talks to the one below it. Clean but rigid. You know exactly where code goes, but sometimes the layers feel like bureaucracy.
The Pipeline. Data flows in one direction through a series of transformations. Input → Process → Output. Great for data processing, terrible for interactive applications.
The Microservices Sprawl. Many small services, each with its own database, deployment, and team. Powerful at scale, catastrophic prematurely. If you have fewer than 50 engineers, you probably don’t need this.
I once suggested microservices for a todo app. Three services, two message queues, a service mesh, and it still couldn’t mark a task as done without a 200ms round trip.
How to See the Shape
- Follow a request. Pick one user action and trace it from the UI to the database and back. This reveals the actual architecture, not the intended one.
- Look at the dependency graph. What imports what? The shape of your imports is the shape of your system.
- Find the center of gravity. Every codebase has a few files that everything depends on. Those files are the heart of the system. Understand them first.
Match the shape to the problem. A todo app doesn’t need microservices. A banking platform doesn’t belong in a single 5,000-line file. The right architecture is the simplest one that handles the actual requirements — not the theoretical ones.