Worked example
Doubles-to-Go: a worked example you can read and run
The workshop teaches with one small, real system: a pre-order app for street-food vendors in Trinidad. You get its complete arc42 document and a working app built to match it, so you can see each section turn into code, and watch the design cope when things go wrong.
01What is in it
Four parts that fit together
The arc42 document
All twelve sections: goals, constraints, context, strategy, building blocks with three contracts, runtime scenarios with failure branches, deployment, crosscutting concepts, six decisions, eleven quality scenarios, eight risks and three items of technical debt. Every one has a stable ID.
The working app
One small Node service with no dependencies, plus plain web pages for customers and vendors. The payment provider and SMS gateway are faked inside it, so everything runs offline on your laptop.
Tests that guard the document
33 tests check the contracts, the quality scenarios and the block boundaries. A checker fails if the arc42 uses an ID it never defines. Documentation and code are kept honest by the build.
An agent guide
A short AGENTS.md tells a coding agent where to start, which rules never bend and which commands to run. It is the “agents as readers” idea, made concrete.
02Run it
Five minutes to a running system
Node 22.13 or newer. Nothing else to install. Unzip, then in a terminal:
cd app
npm start # http://localhost:3000, with /vendor/ and /demo/
npm test # 33 tests: contracts, scenarios, architecture rules
npm run simulate # 1,000 customers with dropped connections
npm run docs:check # the arc42 checks its own consistency (needs python3)What you can try
- Order and pay, then watch the status reach Paid
- Send the same order twice and get one order
- Lose a payment confirmation and see it settle by itself
- Switch the SMS gateway off and see the order still become Ready
- Break a rule on purpose and watch a test name it
03Honest limits
Where the code is deliberately simpler
- It is a teaching example, not production software. Sign-in uses fixed demo tokens.
- The arc42 describes two app instances, but the queue worker is not yet safe to run twice. That is recorded as risk R8, found while building the app.
- Data retention is left for the business owner to confirm; no deletion job exists.
Each of these is a good question to ask of any real system.