Requirements clarification

In the previous module you built a small store by asking what its callers needed and then choosing which promises the database had to keep. That habit scales up. Hand yourself a bigger brief, "design a link shortener", and the first job is not to draw. It is to find the unanswered questions whose answers would change the design.

The brief and the product hiding inside it

A shortener takes a long address and hands back a short one. Later, someone opens the short address and is sent to the long one. Two sentences, and yet several different products fit inside them. Does the person creating the link choose its name, or does the service? Can the destination change after the link has been printed on a poster? Does a click need to be counted, and if so, counted how?

Each answer is a rule your implementation has to enforce, and enforcing rules costs code, storage, and sometimes latency. The point of clarification is not to collect requirements for their own sake. It is to avoid building rules nobody asked for and to avoid discovering, late, a rule everybody assumed.

A test for whether a question is worth asking

Before you ask, finish this sentence privately: "If the answer is yes, I would have to change…" Then try the same sentence with no. If both answers lead to the same design, park the question. The colour of the create button matters to someone, but it does not tell you where the link mapping should live.

Names and their owners

Can a creator pick the short name?

If someone can request /summer-sale, the service has to say whether that name is free, and it has to refuse when someone else owns it. Silently handing back a different name would break the request. Generated names give you room to retry after a collision, as long as the address you return is the one you stored.

For this version, choose generated names. A uniqueness constraint in the store already rejects duplicates; the alphabet and length can wait until capacity planning gives you numbers. Custom names are a fine feature for a product selling memorable campaign links, but they bring an ownership dispute this brief has not asked you to settle.

Can a destination change?

Suppose the shortener returns /00f4240 and the creator puts it in an email. With a fixed destination, every later redirect consults the same mapping and the answer is stable. With edits, an address that has already been shared becomes a moving reference, and the product now owes readers an explanation of what they will see.

Choose fixed destinations. A creator who needs a different target creates a new link. That removes a public editing path, a permission check, and a conflict rule, all in one decision. Adding editing "just in case" would add all three back.

Who can create, and who can follow?

Creation is restricted to approved callers; following a link is open to anyone. A person receiving an address should not need an account. That puts a permission check on the creation path and keeps the redirect path free of one, which matters because the redirect path is the hot one.

It also leaves abuse as a real concern. A public address can point somewhere harmful, and a production release needs a policy for refusing or disabling links. This walkthrough bounds the ordinary paths; the security lessons later in the course own the enforcement.

The click and the report

"Record clicks" hides a consequential ambiguity. It could mean recording every accepted redirect request, counting distinct people, or proving that the destination page loaded. Only the first is something your server directly observes. A person can retry, and a browser that receives the redirect can still fail to reach the destination.

Choose accepted redirect requests as the recorded event. It gives the implementation an observable moment and gives the report an honest label. Counting distinct people would need an identity, and proving page loads would need cooperation from a page you do not control.

Now separate recording the event from computing the report. You could wait until the event is durably stored before replying, or reply immediately and risk losing the event if the process dies. Deferring the expensive part is fine; deferring the promise is not.

Engineering note. Keep "record the request" and "update the report" as two separate lines in the brief. A creator who is happy to see a report an hour late has agreed to delayed calculation. They have not agreed to missing records. Different answers permit different implementations.

Load and lifetime

The course's shortener brief assumes 100 million redirects and 1 million new links a day, with mappings kept for at least five years. Those are inputs to a design exercise, not facts about any real product. Capacity planning will turn them into work per second and bytes stored, then compare them with measurements.

The lifetime changes the design before any arithmetic happens. A link shared today must still resolve while its mapping is inside the retention promise, so reclaiming its name for another destination is unacceptable. This version offers no early expiry and no name reuse.

Here is the pressure each clarified answer puts on the design. Read the last column as the obligation you would otherwise forget, not as a list of technologies to install.

When the brief says this	Default for this version	Design pressure
Readers follow links without signing up	Public redirect path	Creation permission cannot be a redirect prerequisite
The service chooses a fixed mapping	Generated names, no destination edits	Resolve collisions before returning the saved address
Each accepted request is recorded	Store the event before the response	A recording failure can block a redirect
Mappings last at least five years	Retain without automatic name reuse	Capacity includes every link ever created

A brief another engineer can build from

Build the ordinary creation and redirect paths first. An approved creator submits a destination and receives a generated address whose destination stays fixed. Anyone can follow it, and the mapping stays stored through the retention window. Custom aliases and editing are out of scope; either would reopen a decision made above.

Treat click recording as part of an accepted redirect. Store the request event before responding, let the report be computed later, and count requests rather than people or destination page views. A lost response can lead to a retry and a second event; that follows from the definition, so the report should say "requests" and mean it.

You can now hand this brief to someone making the drawing and explain why each responsibility exists. Several answers still contain words like "fast" and "later", though. The next lesson, non-functional requirements, turns those words into targets a test can check.