Lesson Method 2• 4 min read

Step 2: A high level design

Sketch the main components and the arrows between them, trace every use case through them, and justify each box.

What you will learn

  • Sketch one box per kind of work and one arrow per way a request travels.
  • Test the sketch by tracing every use case through it.
  • Justify each component in one sentence tied to a use case or assumption.

Step 2: sketch and justify

The primer's second step is short: outline a high level design with all the important components. Sketch the main components and the arrows between them, and justify your ideas.

"All the important components" means one box for each kind of work the use cases need, and one arrow for each way a request travels. It does not yet mean caches, replicas or extra servers: those answer bottlenecks, and you have not found any yet. The primer is explicit about this in step 4: do not jump straight from the initial design to the final one.

Follow each use case through the sketch

A good test of the sketch is to trace every in-scope use case through it. If a use case has no path, a component is missing; if a box is on no path, it may not be needed.

For Pastebin, the primer's design has a client, a web server acting as a reverse proxy, a Write API and a Read API, a SQL database, an object store and an analytics box:

  • Create a paste: client → web server → Write API, which saves a row to the SQL database and the paste text to the object store, then returns the link.
  • View a paste: client → web server → Read API, which looks the link up in the SQL database and, if it exists, fetches the text from the object store.
  • Track analytics: monthly counts, not real time, so a batch job over the web server's logs, outside the request path.
  • Delete expired pastes: a job that scans the database for expired rows, also outside the request path.

Justify each choice

Every box should have a reason you can say in one sentence, tied to a use case or an assumption:

  • Separate Read and Write APIs, because reads outnumber writes 10 to 1 and the two can then be scaled independently.
  • An object store for the text, so the database holds only small rows, and nobody has to manage file servers.
  • A SQL database used as a large hash table from link to path. The primer notes a NoSQL key-value store would also work, and that the choice is a trade-off to discuss.
  • Batch analytics, because the assumptions say analytics need not be real time.

If you cannot give a reason, the component is probably premature.

Client1× instanceWeb server (reverseproxy)1× instanceWrite API1× instanceRead API1× instanceSQL database1× instanceObject store1× instanceClient1× instanceWeb server (reverseproxy)1× instanceWrite API1× instanceRead API1× instanceSQL database1× instanceObject store1× instanceClient1× instanceWeb server (reverseproxy)1× instanceWrite API1× instanceRead API1× instanceSQL database1× instanceObject store1× instance
Figure 1

The primer’s first Pastebin design, with one path for writes, one for reads, and the text in an object store.

Follow each use case through the boxes. Creating a paste goes from the client through the web server, acting as a reverse proxy, to the Write API, which saves a row to the SQL database and the text to the object store. Viewing a paste goes through the same web server to the Read API, which looks the link up in the database and fetches the text from the object store. Every box is on a path, and there is one of each: no cache, no replicas and no extra servers, because no bottleneck has been found yet. The primer’s design also has an analytics box, a batch job over the web server’s logs outside the request path; the figure leaves it out.

  • Client: 1 × Users
  • Web server (reverse proxy): 1 × Load balancer
  • Write API: 1 × App server
  • Read API: 1 × App server
  • SQL database: 1 × Relational database
  • Object store: 1 × Object store
  • Client sends requests to Web server (reverse proxy)
  • Web server (reverse proxy) sends requests to Write API
  • Web server (reverse proxy) sends requests to Read API
  • Write API sends requests to SQL database
  • Write API sends requests to Object store
  • Read API sends requests to SQL database
  • Read API sends requests to Object store

Key takeaways

  • Leave caches, replicas and extra servers out of the first sketch: they answer bottlenecks you have not found yet.
  • A use case with no path means a missing component; a box on no path may not be needed.
  • If you cannot give a reason for a box, it is probably premature.
Sources4