From whiteboard sketch to working software
The most accurate description of your system was drawn on a whiteboard and photographed once. Here is what changes if you keep it.
Every system in the world starts the same way. Someone stands at a whiteboard and draws boxes with arrows between them, and for about forty minutes everyone in the room shares a completely accurate mental model of what is going to be built.
Then someone photographs it, the photo goes into a chat thread, the board gets wiped, and that shared understanding begins decaying immediately. Within a month the only description of the system is the code, and the code does not explain itself.
Why the drawing was better than the document
It is worth being precise about what is lost, because the instinct to say "we should have written a proper spec" is wrong. The specification would have been worse.
- It was structural. Boxes and arrows are the actual shape of a system. Prose describing a graph is a lossy encoding of one.
- It was complete at the level that mattered. Every part, every connection, nothing else. A document would have had four pages about one component and nothing about the rest.
- Everyone could read it. The designer, the founder, the engineer and the person from finance all understood the same picture. Almost nothing else in software has that property.
- It was fast. Forty minutes. Which is why it actually got made.
The whiteboard is the highest-bandwidth architecture tool we have, and we throw the output away every single time.
What has to be true for a sketch to be more than a picture
Photographing it is not enough. That just gives you a stale picture in a slightly more durable format. Three things have to change.
The boxes need types
A rectangle labelled "Payments" is a rectangle. A node that knows it is a service, connected to something that knows it is a table, is data, and data can be checked. Type is what turns a drawing into a description.
It has to be connected to the code
Each box has to know which files implement it. Without that link there is no way to ask whether the drawing is still true, and a drawing nobody can check is a drawing that will quietly stop being true.
The check has to be automatic
Not a quarterly architecture review. Something that runs after every change and reports what no longer matches, because divergence found in week twelve has already cost what it was going to cost.
What that makes possible
Graphlit is built around exactly this. You draw the architecture on a whiteboard, on paper, or on a canvas, and it becomes a typed graph: services, routes, tables, jobs, and the edges between them. Photographs work too. They are read by deterministic offline code (shapes, arrows, handwriting) and only reach a vision model if that read fails, because a picture of a whiteboard is often somebody's unreleased architecture.
Four boxes, three arrows. No prompt.
Four things follow from the drawing being real data rather than an image:
| Because the sketch is typed | You get |
|---|---|
| Every box knows what kind of thing it is | The gaps you did not draw (auth, sessions, jobs) can be inferred and shown as suggestions you can delete |
| Every box maps to files | A build plan where each task names the files it may touch, so a change that strays is stopped rather than reviewed |
| The graph can be compared to code | Drift becomes a report: what moved, what vanished, what was never built |
| Rules can be attached to edges | "Nothing reaches the database except through the API" becomes a check instead of a hope |
The part that does not change
Being honest about the boundary matters more than the pitch.
A drawing that is faithfully implemented and continuously verified can still be the wrong drawing. If the architecture is a bad idea, checking it rigorously produces a rigorously verified bad idea. None of this replaces the judgement about what to build. It only guarantees that what you decided is what you got.
That turns out to be a large share of the problem in practice. Most systems do not fail because someone designed them badly at the whiteboard. They fail because the thing that was built slowly stopped resembling what was agreed, and nobody noticed until it mattered. That is architecture drift, and it is the failure this is aimed at.
Start with the forty minutes
Whatever you build with, the highest-value thing you can do before writing code is still the oldest one: draw the parts and the arrows between them.
The only change worth making is not wiping the board afterwards. Everything above is a way of taking that seriously. If you want the drawing checked against the code automatically, that is what we are building. You can create an account and try it.
Common questions
Can you generate an application from a diagram?
Yes, provided the diagram is typed rather than a picture: nodes that know whether they are a service, a table or a route, connected by edges with meaning. An image of a diagram carries none of that, which is why photographing a whiteboard does not give you anything a machine can build from.
What makes a good architecture sketch?
One box per part, one arrow per connection, and every box named after something real. Fitting on a single screen is a useful discipline. If it does not fit, you are drawing two diagrams at once. Level of detail matters far less than completeness at whatever level you chose.
Do I need to be technical to draw my system's architecture?
No. Boxes for things that exist and arrows for what talks to what is a description anyone who understands their own product can produce. The technical vocabulary is a naming convention, not a prerequisite.
How is this different from UML or model-driven development?
Earlier model-driven approaches tried to generate complete systems from exhaustive formal models, and foundered on the effort of keeping the model complete. The difference here is scope and direction: the graph describes structure rather than behaviour, and it is continuously compared against real code rather than treated as the source everything is generated from once.
Draw it. Then keep it true.
Graphlit turns an architecture drawing into a typed graph, builds against it, and proves the code still matches. Free to start.