Note
Architecture for small tools
How I keep small internal tools simple enough to maintain.
For small tools, I optimize for the shortest path to a durable result.
The default shape is:
- Keep the domain model small.
- Push complexity to the edges.
- Store the minimum state needed to recover from failure.
- Prefer boring deployment and explicit documentation.
That means I avoid abstracting too early. If a tool only has one or two workflows, the best architecture is usually a thin route layer, a few focused modules, and a clear data boundary.
The test I use is simple: can another person read the code in ten minutes and understand where to change it without tracing through a framework maze?
If the answer is yes, the architecture is good enough. The same pressure toward small, understandable systems also drives Build over buy, where the point is to stay close to the work instead of outsourcing the interesting part.
It also shows up in Composable automation, where the goal is to keep the blocks high-level enough to chain cleanly without turning every change into a rewrite.