CityCycle

CityCycle is a fictional docked bike-sharing service for the city of Riverside. Riders unlock a bike, ride, and return it. Operators restock stations. Months later, the city adds electric bikes.

There is no application code here. The documents are the point. Start with the tour: it walks the same files in the order they were written, and names the advantage of each one. New projects should start from the empty template, not from this repository.

Read in this order

1. Goals — 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.