Design docs example — CityCycle

A filled-in example of the engineering design playbook. The product is fictional. The documents are the point.

Reading view: openmove.github.io/design-docs-example. Start with the tour.

CityCycle is a bike-sharing service for a mid-size city. Riders unlock a bike from a station, ride, and return it. Operators restock stations. A later change adds electric bikes.

This repository has no application code. It shows how architecture documentation, ADRs, and RFCs look when they are used together on a small, concrete system.

Read in this order

1. Architecture, section 1 — what CityCycle is for, and the three quality goals that drive the design.
2. Context diagram and section 3 — who touches the system.
3. Solution strategy — how those quality goals become technical choices.
4. Container diagram and building blocks — the deployable pieces.
5. The ADRs, in order:
   • 0000 — use MADR
   • 0004 — Node.js and Fastify
   • 0001 — PostgreSQL for trips and inventory
   • 0005 — who can reach PostgreSQL
   • 0002 — Redis for station availability
6. RFC 0001 — add electric bikes — a later change with real trade-offs.
7. ADR 0003 — the decision that RFC produced.
8. RFC 0002 — hold a bike while walking to it — the next change, still in review. ADR 0006 is only proposed, and the runtime view has not been rewritten.

That sequence is the practice: map the system first, record durable choices as ADRs, propose ambiguous work as an RFC, and let an approved RFC leave new ADRs behind. Step 8 is what the docs look like in the middle of a change.

What this is not

• Not a product for Riverside, and not related to any real operator.
• Not a complete arc42 fill-in. Sections that would be empty noise are left short on purpose.
• Not a substitute for the template. New projects should start from engineering-design-playbook, not from this example.