Small Architecture

The bug that wasn't in the code

Slotwise is a five-developer SaaS for booking appointments. Last spring they shipped a reminders feature: 24 hours before an appointment, the customer gets a text. It worked perfectly, and support tickets went up anyway.

The team used one word, "appointment", for three things: the recurring slot a provider opens, the customer's booking of that slot, and the calendar event synced to Google. The reminders went out for open slots nobody had booked. The code was correct. The sentence the team had agreed on in standup was not, because two people had understood it differently.

Every small team has a version of this story, and a second one behind it: the only person who really knows how the calendar sync works is Lena, and Lena is one offer letter away from taking that knowledge with her.

These are architecture problems. You were told solving them takes an architect, a framework, and a quarter of ceremony. It takes neither. It takes three small models, kept fresh, owned by humans, maintained by an agent.

Two things this method refuses

Write-once documentation. The wiki page, the README diagram, the Notion doc: produced in a burst of good intentions, wrong within a quarter, then worse than nothing, because a wrong map is trusted in exactly the moment it hurts most. Documentation never dies from being hard to write. It dies from being hard to keep true. Everything in Small Architecture is shaped by that one fact.

The architect as a hire. Small teams hear "architecture" and picture a role they can't afford and wouldn't enjoy. But architecture is not a person; it is the shared understanding a team operates on. The judgment must stay with the humans who own the system. The drawing and the upkeep, the part that killed every previous attempt, no longer needs anyone's weekend: that part is now agent work.

The three models

1. The Dictionary

The 20 to 50 words your product runs on, each with a one-sentence definition a new developer could act on. This is where drifting words die: when two people use the same word for different things, the word becomes two entries with two different names.

With those three entries, the reminders bug becomes a sentence anyone can point at: reminders follow Bookings, never Slots. And the dictionary is not a glossary in a wiki. It is wired into every model: rename a term once and every diagram that uses it follows.

2. The Domain Model

One concept model of your business objects and their relationships, drawn as sentences: a Customer books a Slot; a Booking generates a Calendar event; a Provider publishes Slots. The shape of the problem, independent of the code that currently implements it.

This is not your database schema and not your service list. It is the ideas, drawn so the whole team can point at them, and so the corner cases surface early: "wait, can a Booking exist without a Customer?" (Slotwise: yes, walk-ins. That question found a null-pointer path two weeks before a customer did.)

3. The System Map

One architecture view of the running system: services, databases, queues, the external SaaS you depend on, and labeled arrows for what flows where. Slotwise's map is twelve boxes: the API, the web app, Postgres, Redis, the sync worker, Google Calendar, Outlook, Stripe, Twilio, and the webhook paths between them.

This is the map that answers "what breaks if Redis dies?" and "which systems touch customer data?" without a week of archaeology, and the one that stops routing every such question through Lena.

Sizing, for all three: every model answers one question, and it fits on one screen. If you can't name the question, delete the model. If it doesn't fit the screen, you are drawing more than you operate. That is rule three in practice: draw what means something to the business, never everything you can see.

Ownership, for all three: each model carries one human name. The point of the agent is to make the system clear to, and mastered by, humans. So a human owns every map; everyone else proposes, in threads anchored to the exact box in question.

Keeping it true: the trickle

Nothing above survives contact with a shipping team unless keeping it true costs minutes. So Small Architecture has no documentation sprint and no quarterly catch-up debt. It has a trickle.

The agent watches for drift. Your models are linked to a codebase. When reality moves, the agent proposes: it opens a thread on the exact node, or prepares the model change itself, the way a colleague prepares a pull request.

Humans review like they already review. Discuss in the thread, accept the change, or point your own agent at the proposal and review through MCP. Model changes ride the same habits as code changes, and they take minutes because the models are one screen each.

Freshness beats validity.

Here the method makes its most contrarian call. Small teams move too fast to keep a permanent "validated" stamp honest, and a method that demands one will be abandoned by month two. So Small Architecture doesn't ask "is this model valid?" It asks "who last walked this model, and when?" A map that says "reviewed by Lena and Sam, January 12" tells you exactly how much to trust it. A stale green badge tells you a comforting lie. Marking a model validated stays possible for the moments that deserve it: a compliance snapshot, the baseline before a big refactor. It is never required, and the method delivers its value without it.

When a model feels abstract or contested, trace one real case through it with actual values: this customer, this Tuesday 14:00 slot, this booking, this reminder. Scenarios are the honesty check; a real case that doesn't fit the model is the model telling you where it's wrong. Recommended whenever an argument goes in circles; required never.

Day one: "Draw my product"

You do not start Small Architecture with a blank canvas or a workshop. You start by telling your agent:

> draw my product

The agent explores what it can see (the codebase, the schema, the docs) and exercises judgment about what is worth drawing: which models mean something to the business, and which details are noise. It drafts them, lints its own work, looks at the rendered result the way you would, and comes back with a report: here is what I drew and why, here is where the code disagrees with itself, here are the four words your codebase uses inconsistently, here are the questions only a human can answer.

Slotwise's first draw took the agent an evening. The team's first session was not spent drawing boxes; it was spent on the report, correcting the agent's guesses and arguing about what "Slot" means. That argument was the method working: the point of every map is the shared understanding it forces, and the agent's job is to make sure human time is spent exactly there.

From then on, the loop is set: agents draft, humans decide, and the maps stay fresh because staying fresh costs minutes.

Built to run on Koncept

We built Koncept so this method has a home. The Dictionary, the Domain Model, and the System Map are native objects, not conventions to enforce. Threads anchor to the exact node under discussion. Reviews record who and when. And the MCP server gives your agent the same pen you hold: it drafts, renders, lints, proposes, and comments as a named teammate, live on the canvas your team already has open.

The method is yours either way. It works on a whiteboard. It just won't stay fresh there.