How this example works

CityCycle is a fictional bike-sharing service. The product is an excuse. The documents are the point.

This page is the tour. It does not add a fourth format. It shows the same files you already have, in the order they were written, and names the advantage of each one. After this, read the files themselves.

What the three documents do here

Question on CityCycle	Document	What it is in this repo
How should we add e-bikes?	RFC	RFC 0001, then RFC 0002 still in review
Why is the trip ledger PostgreSQL?	ADR	ADR 0001
How does the system look today?	arc42	Sections 1–5 and the container diagram

The rule is the same as in the playbook: an RFC is a proposal, an ADR is a closed decision, arc42 is the current map. Mixing them is how documentation rots.

What you would lose without them

Imagine the same product with only tickets and chat.

• Six months later, nobody can say why trips are not in Mongo. The person who chose PostgreSQL has left. ADR 0001 still lists the options and why they lost.
• The architecture page is a fifty-page document last touched at kickoff. Nobody updates it, so nobody trusts it. Here, the e-bike work updates only section 5 and the container diagram.
• The e-bike debate happens again when a new engineer joins. RFC 0001 already has the alternatives, including “put every battery sample in PostgreSQL”.

That is the whole method: memory, a map that can stay current, and a debate you do not have twice.

The story, in three moments

timeline
  title CityCycle documentation over time
  March : Map the new system
        : Founding ADRs (runtime, database, cache)
  June  : RFC for electric bikes
        : ADR 0003 accepted, map updated
  August : RFC for a bike hold
         : ADR 0006 still proposed, map unchanged

1. March — the system does not exist yet

Nobody writes an RFC of the whole product. The first day is a short map plus the choices that map rests on.

Read, in this order:

1. Goals — unlock under 3 seconds, map counts at most 30 seconds stale. Those numbers, not “it should be fast”, later force Redis.
2. Context and the context diagram — riders, operators, docks, payments. Everything else is outside the box.
3. Strategy — half a page. Each quality goal points at an ADR.
4. Building blocks and the container diagram — one Fastify process, PostgreSQL, Redis.
5. The founding ADRs, by date, not by number:
   • 0004 — Node.js and Fastify
   • 0001 — PostgreSQL is the ledger
   • 0005 — the ledger is private, two roles
   • 0002 — Redis for the hot path

Advantage. A new person can answer “why Redis?” from the quality goals and ADR 0002, without sitting in the original meeting. Sections 6, 8, 10 stay short until there is something real to write.

2. June — a later change, finished

The city adds 200 electric bikes. The solution is not obvious: battery samples every 10 seconds would drown the trip database.

The work goes through the chain:

1. RFC 0001 — Implemented. Alternatives, rollout, a flag.
2. ADR 0003 — accepted. Samples go to a second TimescaleDB instance (battery_samples hypertable). The latest percent stays on bikes for unlock.
3. The container diagram gains TimescaleDB. Section 5 names a telemetry module. The RFC is not the map.

Advantage. The debate is over, and it is still readable. The map matches production. Nobody has to reconstruct June from Slack.

3. August — a later change, still open

Support keeps hearing: the map showed a bike, the rider walked three minutes, someone else took it.

That work is not in the map yet:

1. RFC 0002 — In review. Hold the bike for 90 seconds in Redis. No trip until the dock acks.
2. ADR 0006 — proposed. Not accepted.
3. Runtime view still describes today’s unlock. It points at the RFC. POST /holds is not in section 5.

Advantage. You can tell a proposal from the system as it is. If this RFC is rejected, the map does not have a ghost feature. If it is accepted, the same loop as June closes: accept the ADR, then update section 5 and section 6.

How to tell the documents apart

Open any file and ask one question.

If you see…	You are in…
Alternatives, a rollout, status Draft or In review	An RFC. It can still change.
“Chosen option”, status accepted, a date	An ADR. Do not rewrite it.
Status proposed on an ADR	A decision that has not happened. The map must ignore it.
A diagram of people and systems, or a list of deployable pieces	arc42. This is today.
Status superseded by ADR-NNNN	An old decision. The new ADR is the current one.

After the tour

Start a project from the empty template, not from this repository. CityCycle is the filled notebook. Copying it would give you someone else’s bike-sharing system.

If you only read three files after this page, read section 1, ADR 0002, and RFC 0001. That is the method: a measurable goal, a decision with losers, a later change that leaves a new decision and an updated map.