Functional and non-functional requirements

01Turn a product idea into three kinds of promise

Noor saves an article on her phone and wants to see it on her laptop. Write down three different kinds of promise:

1. Functional requirements describe actions. Noor can save an article link, list saved links and remove one.
2. Nonfunctional requirements describe measurable quality. For example, list requests must finish within a response-time target at a stated load.
3. Invariants describe rules that must always hold. For example, concurrent saves of the same user–article pair must leave one active entry.

Also decide whether the saved object is only a link or a permanent copy of the article. Copying content requires file storage and deletion rules that link storage does not.

Ask questions that change the design:

• Must the laptop see a phone save on its next request, or may it briefly show the old list?
• Is the list private, or can Noor share it?
• If protected article content is displayed, what happens after access is revoked?
• During an outage, may the service show an older list, or must it refuse the read?

Record the answers before choosing mechanisms. “Use a cache” proposes an implementation. “Return the list within 300 ms at the agreed load” states a need that might justify that implementation.

02Write targets that another engineer can test

For this exercise, use explicit requirements that another engineer can check.

Functional requirements:

1. FR1 — Save: Save an article link for the authenticated user. Repeating the same user–article save resolves to one active entry.
2. FR2 — List: List that user’s saved entries newest first, using the saved time and entry identifier to break ties. Return a cursor so another page continues that order.
3. FR3 — Remove: Remove an entry owned by the caller. Later list reads from the database omit it; state separately how soon any cached list must reflect that removal.

Nonfunctional and correctness requirements:

1. NFR1 — Latency: At 1,000 peak valid list reads/second, at least 99% finish within 300 ms from application receipt to completed response. Measure public-network delay separately.
2. NFR2 — Success: At least 99.9% of valid list reads succeed over a month. Define whether client errors, timeouts and partial responses count before measuring.
3. NFR3 — Uniqueness: At most one active entry exists for each user–article pair, including simultaneous saves and repeats.
4. NFR4 — Privacy: Check the required owner/content permission on every private response. Cached bytes and a known identifier do not grant access.

The response-time requirement uses the 99th percentile, written p99. It constrains the measured requests near the slow end, not just their average. A fast average can hide a small slow group.

Keep these storage questions separate:

• Durability: Will the accepted save survive the stated failures?
• Freshness: Which later reads must include that save, and how soon?

One database copy can safely retain the save while another still serves the old list. Such a copy is called a replica. State the read requirement; durability alone does not answer it.

03Trace concurrency and resolve a conflict

Let the article be a8; the saved pair is (Noor, a8). Two devices can both read “not saved” before either inserts. Separate application checks do not prevent two rows.

Make the database enforce the rule:

1. Store a key containing both user and article identifiers.
2. Add the database’s appropriate uniqueness constraint for that pair.
3. Each save attempts the insert through that constraint.
4. One creates the entry. The other encounters the existing pair and returns that entry or the documented already-saved response.

The database must check uniqueness while accepting the insert, as one indivisible operation. This is an atomic check and update. Without it, another insert can occur between an application’s check and write.

Then handle an unavailable permission check deliberately:

• An old public title may be acceptable under the freshness policy.
• An old permission can expose protected content after access was removed.
• If the service cannot establish the required permission, it waits or denies as agreed; it must not return protected bytes just because a cached copy exists.

Write an acceptance check for each promise:

1. Race two saves and verify one active pair.
2. Run the stated read workload and measure the response-time distribution and failures.
3. Revoke access while a cached copy remains, then verify that protected content is not returned.
4. Save on the phone and read from the laptop to test the agreed visibility delay.

These tests exercise different requirements. Passing a response-time test does not prove uniqueness or privacy.