Docs menu
On this page

Contribute

Writing practice problems

Last updated

The practice page (frontend/practice/, code in frontend/src/practice/) serves system design problems. Each problem is a folder of plain files in frontend/src/practice/problems/; there is nothing to register. The practice page, the landing page's list and proschi problem check all read the same folders. The idea behind the format is in the design.

Contributing a problem? CONTRIBUTING.md has the step-by-step checklist, from scaffolding to the pull request; this page is the reference for the format.

Folder layout #

frontend/src/practice/problems/<id>/
  problem.md            front matter + the statement (Markdown)
  given.proschi         the problem as Proschi, read-only for the solver
  starter.proschi       starts with: import "problem.proschi"
  solution.proschi      the reference solution; starts with the same import
  lesson.md             optional: the lesson shown before the problem
  interview.md          optional: interview mode's questions and estimates
  guided.md             optional: guided mode's steps (roadmap stage 1 only)
  wrong/<name>.proschi  optional: plausible wrong designs that must fail

The folder name is the problem id and its URLs: practice/#/url-shortener in the practice app, and practice/url-shortener/, a static page with the title, summary, statement and lesson (not the hints) that search engines index and the sitemap lists. Lowercase letters and digits, words joined by -; problem is taken by that page's template, and roadmap, approach, review and progress by practice pages of their own (RESERVED_IDS in problemFiles.ts). Other files are an error, so a typo like solutoin.proschi is caught. Wrong design names follow the same rule (wrong/miss-never-fills-cache.proschi).

problem.md #

---
title: URL Shortener
summary: Cache-first redirects that survive losing any single machine.
difficulty: easy
tags: [caching, read-heavy, durability]
order: 1
strict: true
hints:
  - Redirects outnumber shortening 100 to 1. What can answer a redirect without touching the database?
  - "One instance of anything is a single point of failure: use x2 or more on every component."
---

Design a service that turns long URLs into short codes …

## Functional requirements
…
Field Required Meaning
title yes Shown in the list and on the problem page
summary yes One line, shown on the landing page
difficulty yes easy, medium or hard
tags yes A list of strings, used by the list's tag filter
company no A string, e.g. Twitter: the company whose published system the problem is based on, cited in a ## Based on section of the statement. It says where the design comes from, never that the company asks the problem in its interviews. The list shows it as a badge and filters by it (only companies some problem names); the problem page and its static page show the badge
order no A number: the position within its difficulty
hints yes A list, from a nudge to nearly the answer; the page reveals them one at a time
version no A whole number, 1 when absent. Bump it when a change to the given, the tests or the requirements can change whether a design solves the problem, or its cost or p99: proschi.app's global stats and the problem's leaderboards (cheapest and lowest-p99 passing designs) then count only solves of the new version, and a signed-in user's next run starts their stats for the problem over
strict no true grades designs in strict mode: a step label that names no operation of its target's type, or a status or header the type does not list, is an error and the tests do not run. Absent or false: these are warnings

The list is sorted by difficulty (easy first), then order (problems without one come after those with one), then title.

The front matter is a strict subset of YAML: key: value lines, # comment lines, lists either as [a, b] on one line or as - item lines under a key with no value. A value is a plain string, a "double-quoted" string (JSON escapes), a 'single-quoted' string ('' for a quote), a number, or true or false. A plain value that YAML could read differently is an error with its line number: quote it when it contains : or #, starts with one of - ? : , [ ] { } # & * ! | > ' " % @ ` or reads as yes, no, off, null and the like. Unknown fields and duplicate keys are errors too.

The statement is everything after the closing --- (surrounding blank lines are dropped). It says what to build: a short context, then ## Functional requirements (name every use case in bold, e.g. **Redirect**, and the scenario names the tests refer to), ## Scale, ## Constraints and ## What is given. The renderer (frontend/src/practice/markdownReader.ts) understands headings, paragraphs, bullet and numbered lists (one level of nesting), fenced code (```proschi blocks, also ```proschi fragment, are highlighted), GFM pipe tables (they scroll in their own box on phones), > blockquotes (shown as a callout), inline code, bold, italics and links; HTML is shown as text. Headings get ids from their text, GitHub style (## What you'll learn is what-youll-learn).

lesson.md #

The lesson teaches the ideas behind the problem before the solver tries it: each roadmap step is Learn → Challenge → Review. A problem from the roadmap (practice/#/roadmap/<id>) opens on the step the learner was last on, a first visit (no notes saved yet) on the lesson (P52, P58); the lesson is the first step in the step bar, a page of its own with a table of contents and a button at the top and the bottom that leads on to the steps (see below), and the browser remembers once it was read. A problem from the list (practice/#/<id>) opens straight on the workspace (the statement, the editor and the diagram in resizable panes, the tests folded under them until the first run), with no lesson first. There the Lesson button opens the lesson in a drawer, and a failed run's common mistake links to its section. practice/#/<id>/lesson opens that workspace with the drawer open, and practice/#/roadmap/<id>/lesson always opens on the lesson. Lessons are never locked: on the roadmap only a step's challenge waits (until every earlier step is solved, and signed out past stage 1), and the address of a locked challenge shows the roadmap with what unlocks it; lessons need no sign-in. The static page practice/<id>/ shows the lesson under the statement as an article with heading anchors, and the roadmap shows each step's reading time (about 200 words a minute).

It is plain Markdown, no front matter, with these level-2 headings in this order (other ## sections may sit between them, and ### subsections are welcome, especially under Concepts):

## What you'll learn
## The problem, explained
## Back-of-the-envelope
## Concepts
## Designing it step by step
## Common mistakes
## In the interview
## Further reading

proschi problem check and the tests report a missing or out-of-order heading, an empty lesson, and any link that is not http:// or https:// (no relative links: the same text is shown in the app and on the static page). Every problem needs a lesson; LESSONS_PENDING in frontend/src/practice/lesson.test.ts lists the ones still being written, and the test fails once a listed problem has one, so remove its id then.

Writing a good lesson (1,500 to 2,500 words; url-shortener/lesson.md is an example):

  • Write original prose. Explain in your own words; never copy text from books, courses or other sites. Quote nothing longer than a phrase.
  • Cite your sources under Further reading: links to freely available material (the System Design Primer, official documentation, engineering blogs, papers), and books by author, title and chapter title, without links to copies.
  • Teach the why. Do the estimation with numbers from the statement, and for every concept say what problem it solves and what it costs.
  • Explain why each wrong design fails, under Common mistakes: the shortcut, what breaks, and which requirement or test catches it (the wrong/ designs are a good list).
  • Do not paste the reference solution. Describe the design step by step and its trade-offs; a ```proschi fragment may illustrate a pattern on a different example, but the solver writes the design.
  • Keep it scannable. Short paragraphs (three or four sentences), tables for numbers, and the lesson blocks below: open with a tldr, put the key figures of Back-of-the-envelope in a numbers row, mark the one sentence to remember with a callout, fold long tangents into a deepdive, and end a few sections with a quiz from the problem's review cards.

Lesson blocks #

Lessons (and guides) can use five blocks, written as fenced blocks whose language names them. The app draws them as cards; the static page shows the same content as plain HTML (a deep dive as <details>, a quiz as its questions linked to the cards' pages).

Block Opening line Body
TL;DR ```tldr Markdown: the lesson in two to four lines, shown first as "In 30 seconds".
Callout ```callout <tone> [title] Markdown. tone is tip, pitfall, interview or takeaway; the title defaults to Tip, Pitfall, In the interview or Key takeaway.
Key numbers ```numbers One value | label per line: a big figure and inline Markdown under it. Three to six tiles read best.
Deep dive ```deepdive <title> Markdown, closed until opened: detail the main path can do without.
Quick check ```quiz Review card ids, one per line, answered in place and graded with the card's explanation. Practice only: answers are not reviews and leave the schedule as it is.
```tldr
Reads outnumber writes 100 to 1: put a cache in front of the database.
```

```numbers
100:1 | reads per write
500 rps | reach the database
```

```callout pitfall
Averages hide the slow 5%: **p99 is decided by cache misses**.
```

````deepdive Base62 vs hashing
Markdown, and code fences too: the block around them takes four backticks.
````

```quiz
cache-aside
```

Inside a block, headings must be ### or smaller, so the lesson's sections stay its own. A block that holds a fenced code block uses a longer fence around it ( ````), as in CommonMark. proschi problem check and the tests report an unknown callout tone, a deep dive without a title, a numbers line without |, an empty block, a #/## heading inside a block and a quiz naming a card that does not exist.

Reading progress #

A lesson counts as read once its end comes into view or its challenge is started; a guide once its end comes into view. The roadmap shows a Read chip on each lesson and guide read, and its "Up next" offers the next step's lesson until it is read. Reads are kept in the browser (proschi.lessons) and, signed in, sent to the account (POST /api/me/lessons, the lesson_reads table), so they show on every device; on sign-in the reads of the browser and of the account are joined. The reading badges count them (docs/CARDS.md, "Achievements": lessons, stage-lessons, all-lessons).

The steps #

A problem opened from the Roadmap (the guided path) is worked through in steps; one opened from All problems (the open list) stays the plain workspace of the lesson section above (the statement, editor and diagram, Run tests, the Interview mode and Guided walkthrough buttons, Design partner), like a coding-practice site, with no step bar. Solved state and saved code are shared between the two entries; the step notes only exist on the roadmap. The steps are self-paced: Lesson, Clarify (your own questions first, then the interviewer's answers from interview.md), Estimate (its estimates, each checked after you commit to a number), Design (the whiteboard, with the full editor one click away) and Wrap-up (the tests, the review and a recall prompt). The notes of each step are kept per problem in the browser (proschi.practice.stages.<id>); a problem opens on the step it was left on, a first visit on the lesson. On the steps, the AI chat is the Interview coach rather than Design partner (with paid plans, signed in, paid in credits): it helps you answer the interviewer (what to clarify, a sanity check of your estimates, how to structure and explain your design and its trade-offs, the wrap-up) by asking you questions, and writes no design for you unless you ask for "Show me the changes". Each message sends it the step you are on and your notes of the steps, so it knows where you are. Select any text on a step (the brief, the lesson, your notes, a failing test) and choose Ask Interview coach to ask about it; a tip under the step bar says so until you use it or dismiss it. See docs/design/paid-plans.md P50, P51, P52, P58 and P59.

interview.md #

The mock interview has pages of its own: the Mock interview tab (practice/#/interview, its set-up keeps the practice tabs; the room has none), or Practice this as a mock interview in a problem's Wrap-up, which opens it with that problem chosen. It goes in three steps.

  1. Set up. The problem is Surprise me by default: a random one you have not done in a mock interview yet, revealed only in the room, with optional difficulty and topic filters. Choose a problem opens a searchable list, and Same as last time is there after the first. Then the length (30, 45 or 60 minutes), voice or text with a mic check, sound effects, and who interviews you (below).
  2. The room (practice/#/interview/<problem>). The whiteboard, the visual canvas, takes the page: add components from the palette, connect them, change their settings, and add each use case's steps and scenarios under Flows. Check my design runs the problem's tests on it. The Code | Visual switch is the editor's, and remembered with it: Visual (the default) shows the code read-only under View code; Code puts it beside the whiteboard, which then only looks. The rail on the right holds the problem, and the conversation or the phase's questions; on phones it is its own tab, the first one. The top bar has the four phases (Clarify, Estimate, Design, Wrap-up, 10/10/70/10 of the time), the clock and the switches. Short synthesized sounds mark a new phase, the last 5 and 1 minutes, a hint, the checks and the end (on by default, switched off in the set-up or the top bar).
  3. The result: the verdict or the summary, New interview (another random problem) and Try this problem again.

On my own (free, no interviewer) runs the phases from this file: Clarify shows the statement without its ## Scale and ## Constraints sections and a list of clarifying questions to pick from, Estimate grades back-of-the-envelope answers against a range, then shows the worked answer, Design is the whiteboard against the clock (pausable), and Wrap-up is a self-review checklist, then a summary. The session, time per phase and the summaries stay in the browser; nothing is sent to the server.

Mock interviews #

Signed in, and when the server has an ANTHROPIC_API_KEY, the set-up offers a Mock interview with an interviewer (chosen by default) next to On my own, with its estimate in credits for the chosen length against your balance ("about 35–55 credits for 45 min; you have 760", never more than what you have or the session's cap), and, without enough, a top-up and a link to the plans. The old practice/#/<problem>?interview=mock (and ?interview=ai) open the set-up with that problem and the interviewer chosen. The interview is charged for what it uses (the free plan gets 100 credits at sign-up); if the credits run out, it moves to the wrap-up and still gives its verdict. A line over Start names what is sent to Anthropic: starting is the agreement. The interviewer is Claude by Anthropic (backend src/ai/, routes in src/interviews.ts), and the session lives on the server, so a reload picks it up again.

  • A chat next to the whiteboard, in the room's rail. The interviewer greets, then answers clarifying questions from the hidden ## Scale and ## Constraints, asks this file's estimates in the Estimate phase and the lesson's "In the interview" follow-ups in Design and Wrap-up. It never asks again for what you already know: the statement you were shown and every fact it gave this session. It checks numbers with a calculator and takes an estimate within 10x of its reference as the right order of magnitude. Replies stream in.
  • Voice or text, chosen in the set-up and switchable in the top bar. In text mode you type, and the mic dictates into the box. In voice mode the mic listens hands-free and your answer goes after about two seconds of silence, with a countdown to Cancel or Send now; the replies are read aloud in the browser's voice while the mic waits, and Interrupt, talking or typing cuts them off. The mic uses the browser's own speech recognition where there is one (free), otherwise short recordings written down on the server (about 0.1 credit a minute of speech). A blocked microphone says how to allow it, and typing always works.
  • On phones the first tab is Chat, so the conversation has a whole screen, then Whiteboard. A reply that comes while you are on the whiteboard says so, with a button back.
  • The phase and the clock: the same four phases and 10/10/70/10 split of 30, 45 or 60 minutes. The clock moves the phase on; Next phase moves on earlier. Whatever the length, a session stops taking turns after 60 minutes or at its credit cap (100, 150 or 200 credits for 30, 45 or 60 minutes); the verdict can always be asked for.
  • Coaching hints after a turn, under the reply in the chat and as toasts clear of the chat (above the composer on phones, two at most, each closable): Focus now (what to do next in this phase), Can improve (what to fix in what you just said) and Wrap up (near the end of a phase).
  • Send my design attaches the whiteboard's design to the message. The server runs the problem's tests on it and hands the model those results; it never trusts the page's.
  • The verdict, on Finish and get the verdict: pass or fail, a score from 1 to 5 for requirements, estimation, design, trade-offs and communication, what went well and what went wrong per skill, and up to five next steps.

On Pro, the verdict also links Practise them here: the 3 picks made after it (below, "Your next steps").

An answer that fails on our side isn't charged; one the model gave is, even when it was cut off or declined. If the interviewer fails on the first turn, the session ends. Transcripts are kept 90 days, the verdicts for history (Privacy).

Interview history, on the progress page (practice/#/progress, signed in, when the server has an Anthropic key): each finished mock interview with its problem, date and pass or fail, linking to its verdict (practice/#/progress/interview/<id>). Pro also sees every past session and the score of each skill over time, as five small charts on the same 1 to 5 scale (with a table for screen readers). Other plans see their latest verdict, and, with billing on, how many earlier ones are kept and a link to Pro (GET /api/interviews/history, backend src/interviews.ts).

Every problem has an interview.md (interviewFile.test.ts fails without one). It holds exactly two sections, each item a ### heading opened by - key: value lines and followed by Markdown:

## Questions

### How many redirects a second at peak?
- kind: good
- fact: Redirects: 10k rps

About **10k redirects a second**: reads outnumber writes 100 to 1.

### Can I use Kubernetes?
- kind: weak

Deployment tooling is not what is assessed; ask about load and constraints.

## Estimates

### If the cache answers 95% of redirects, how many reach the database each second?
- answer: 500
- unit: reads/s
- range: 400 to 650

10,000 × 5% = **500 reads a second**.
  • Questions: up to 12, at least 3 good and 2 weak (aim for about 5 and 3). A good question's fact is words copied from the statement's Scale or Constraints section (compared ignoring case, spaces and *, _, `); its text is the interviewer's answer. A weak question has no fact; its text says why it is weak and what to ask instead. The page shows the questions in a fixed shuffled order.
  • Estimates: 1 to 4 (aim for 2 or 3). answer is a number above 0 (2300, 2.3k, 5M, 1.6T), unit says what it counts, and range: <low> to <high> gives the accepted answers around it; tolerance: <factor> (1.1 to 10) may replace the range, and without either the answer within a factor of 2 counts. The text is the worked answer, from the statement's numbers. The phase links the Numbers to know page.

guided.md #

Guided mode (Walk me through it, step by step in a problem's Design stage) is an optional step-by-step guide on the roadmap's first stage (ROADMAP[0] in roadmapStages.ts): each of those problems has a guided.md, and no other problem does (guidedFile.test.ts). Each step is a ## heading, its checkpoint as - key: value lines, then a short explanation in Markdown:

## Store every code in a database
- node: any database
- edge: any service -> any database
- test: Codes are stored before they are returned

A code that only lives in the API's memory is gone when that machine restarts…

Checks, any number per step and at least one, all of which must pass:

Check Passes when
- node: <node> a node matches
- edge: <node> -> <node> a connection or a use case step goes from one to the other
- usecase: <name> the design defines that use case
- replicas: <node> x<n> a node matches, and every match has at least n replicas (n ≥ 2)
- test: <name> that requirement or test passes (runs the simulation)

A <node> is an id (visitor) or any <kind> (any cache), as in tests. "Check my design" runs the current step's checks on the editor's design and unlocks the next step when all pass; a step can be skipped. Progress is kept in the browser. Write 2 to 10 steps that build from the starter to the reference solution, the last ones usually the requirements.

The Proschi files #

given.proschi is the problem as Proschi. The editor resolves import "problem.proschi" to it, so it is merged into whatever the solver writes:

  • title "Name" "Summary"
  • the fixed nodes the solver connects to: the client, and any existing system the problem is about (orders "Orders API" [REST API] x5)
  • traffic { … } with the rate of every use case and the scenario mix
  • requirements { … }: latency, availability, durability, failure and cost
  • capacity { … } when the problem needs non-default numbers for a node (a slow external gateway, a provider's rate limit). Only the given may set capacity; see the capacity rule.
  • test "…" { … } blocks that encode the key insight of the problem, e.g. the cache is read before the database, rejected calls never reach the backend

No import inside the given.

starter.proschi begins with import "problem.proschi" and gives a small, valid start: usually one use case with its first step.

solution.proschi is a complete design that passes every requirement and test, written like a good answer: replicas sized for the traffic, entity blocks, decision blocks that explain the trade-offs, and when conditions on the scenarios. The page shows it after solving, or before with a confirmation.

wrong/<name>.proschi is a plausible wrong design: the mistake a candidate would make, usually the reference solution with one change. It starts with one or more # expect-fail: lines naming, exactly, the requirements or tests it must fail; other comment lines may follow; then the import:

# expect-fail: Misses fill the cache
# A cache miss that never fills the cache.
import "problem.proschi"
…

Test names are the test "…" names, and for requirements the name the test panel shows, such as p99 of Redirect < 100 ms, cost ≤ $3,000/month or survive any node failure (proschi problem check prints each wrong design's failures, which is the easiest way to copy them).

Known mistakes #

Failing tests teach: when a solver's run fails, the problem page finds the wrong design whose failures it shows and, under the tests, names the mistake (Common mistake: …), explains it, links the lesson section that teaches the fix and lists the review cards that train it, with Add these cards to my review, which puts them first in the daily review, due now (CARDS.md). So each wrong design says which mistake it makes, in comment lines under its # expect-fail: lines:

# expect-fail: Misses fill the cache
# mistake: Cache misses that never fill the cache
# explain: The miss reads the database and answers but never writes the code into the cache, so the hit rate decays toward zero and the database takes the full read load. After a miss, SET the code in the cache.
# lesson: cache-aside-lazy-loading
# cards: cache-aside, hit-rate-to-db-load, average-latency-with-cache
# A cache miss that never fills the cache.
import "problem.proschi"
Line Required Meaning
# mistake: yes The mistake in one line, shown after Common mistake:
# explain: yes Two or three sentences: what breaks, and what to do instead. Several # explain: lines are joined with spaces
# lesson: when there is a lesson The id of a heading of lesson.md that teaches the fix, GitHub style (### Cache-aside (lazy loading) is cache-aside-lazy-loading); usually a subsection of Concepts, or common-mistakes
# cards: no (the repository's designs all have them) Review card ids, comma-separated, from frontend/src/practice/cards

Write the explanation for a learner whose design merely fails the same way, not for the author of the wrong file: they have not seen it.

Matching (matchMistake in frontend/src/practice/mistakes.ts): a wrong design matches a run when the run fails every test its # expect-fail: lines name, or, short of that, at least one of its test blocks (a requirement such as survive any node failure alone has too many causes to name one). Full matches win; then the design whose failures, all of them, are most like the run's (the page runs each wrong design once to know them); then the one sharing the most named failures. The page shows the best match only, and nothing for a run of the untouched starter. The tests check that a run of each wrong design is matched to its own mistake, or to one of a design that fails exactly the same tests.

Strict mode and typed tests #

Every node with a type knows its operations, statuses and headers. A problem can grade against them in two ways.

Typed tests. The given's tests can name an operation, a request or a header instead of only a node (see typed assertions):

test "Misses fill the cache" {
  "Redirect" scenario "Cache miss" uses SET on any cache after any database
}
test "Every charge sends the idempotency key" {
  "Retry charge" sends header Idempotency-Key to gateway
}
test "Redirects redirect" {
  "Redirect" calls any service with GET /{code}
  "Redirect" responds 302
}

Name operations a solver can reach whatever product they pick: SET on any cache holds for Redis and Memcached alike, because both inherit SET from Cache. uses PutItem on any database would force DynamoDB.

Strict mode. With strict: true in the front matter, every design is parsed with strictOps: the solver's design in the editor, on the server when a solve is recorded, the reference solution, the starter and each wrong design. A step label that names no operation of its target's type (api -> db : persist row to a PostgreSQL), a response status the responder does not list, or a header the target does not list is then an error. The Results tab shows the errors instead of running the tests, so a solver must name a real operation in every step to a typed node. Nodes whose type has no operations (Service, Worker, the languages and frameworks) accept any label, strict or not.

A step to a system's entry point (orders.api) is checked against the type of the node behind it: the sender of the mapped use case's first request, or its receiver when that sender is a client. A stub system, with a capacity block and no from file, has no node behind it, so steps to it are not checked.

Bump version when you turn strict mode on: designs that solved the problem before may not any more.

What problem check enforces #

proschi problem check and the frontend test suite apply the same rules, defined once in frontend/src/practice/validate.ts:

  • The folder has the four files and nothing unexpected; the front matter has valid fields; the statement is not empty and has a ## Functional requirements section.
  • lesson.md, when there is one: the eight sections in order, not empty, links to http(s) addresses only.
  • interview.md, when there is one: only ## Questions and ## Estimates; enough good and weak questions, each good one with a fact found in the statement's Scale or Constraints; each estimate with a numeric answer, a unit, a range around the answer and a worked answer.
  • guided.md, when there is one: 2 to 10 steps, each with valid checks and an explanation; ids, use cases and tests the problem has; and every check passing on the reference solution.
  • Every use case in the given's traffic is named in bold in the statement and defined (usecase "…") by the solution.
  • given: no import, parses without errors (with strictOps for a strict problem), in canonical format (proschi fmt).
  • strict problems: the solution, the starter and every wrong design are parsed with strictOps, as grading does, so an unknown operation, status or header in any of them is an error and a violation.
  • solution: starts with the import, has no diagnostics at all (not even warnings), is in canonical format and passes every requirement and test.
  • starter: starts with the import, has no errors, and fails at least one test.
  • each wrong design: has at least one # expect-fail: line, the import right after the comments, no errors, and fails every test it names. Tests it fails without naming them are listed, not violations. It names its mistake: # mistake: and # explain:, a # lesson: that is a heading id of the lesson (required when there is a lesson), and # cards: that exist (checked when a cards folder sits next to the problems folder, as in the repository).
proschi problem check                                 # inside the repository: frontend/src/practice/problems
proschi problem check path/to/problems                # any problems directory
proschi problem check --format github                 # an annotation per violation, for CI
proschi problem check --format json                   # every report, with what each wrong design fails
✓ url-shortener: 10 tests, the starter fails 8, 1 wrong design, interview (9 questions, 3 estimates), guided (6 steps)
    wrong/miss-never-fills-cache: fails "Misses fill the cache" (Cache misses that never fill the cache)
…
40 problems, 149 wrong designs: no violations

It exits with 1 on any violation. npm test in frontend/ runs the same checks on every problem and every wrong design.

The capacity rule #

The simulation believes capacity lines, so a solution could otherwise write capacity { db 1m rps cost 1 usd/month } and pass any load and budget. When a design is evaluated against a problem (the practice page, proschi problem check, the frontend tests), capacity is taken from the given only: a capacity line in the solver's file, and so in the starter, the solution or a wrong design, is an error, capacity is set by the problem; change the design (replicas, shards, caching) instead, and the simulation ignores it.

One part stays with the solver: shards <n>. How many shards a store is split into is a design decision (each shard is a full set of replicas, and costs like one), so capacity { db shards 2 } in the solver's file is accepted and used. Everything else (rates, latency, availability, cost, durability, consistency, bandwidth, egress, timeout) belongs to the problem: a solver who set timeout 1ms would pass every failure scenario. Regular documents in the editor and proschi check/proschi test are not affected.

Calibrating a problem #

A problem is good when the intended design passes and the tempting shortcuts do not, and the limits in requirements decide that:

  1. Measure the reference solution: open the problem in npm run dev and use Show reference solution and the Analysis tab, or on the command line copy given.proschi to problem.proschi in a scratch folder next to the design and run proschi analyze solution.proschi. Note its p99 per use case, its cost and its availability.
  2. Write the brute-force designs a candidate might try: no cache, everything in one database, bytes through the API, a load balancer instead of a CDN, twice the replicas. Note their numbers too.
  3. Put each limit between the two: loose enough that the reference passes with room (a design that is right should not fail on a rounding change), tight enough that the brute-force design fails. If they are too close, change the scale (traffic, payload sizes) until the key idea makes a clear difference.
  4. Prove it: add each brute-force design as wrong/<name>.proschi with the tests it must fail in # expect-fail: lines and the mistake it makes. Flow tests catch the designs numbers cannot (the cache read after the database, a call that waits for a queue).

When the simulation's model changes, problem check shows which problems need recalibrating. How the simulation works lists every formula and default number the limits are measured against, and explains to solvers what a passing verdict does and does not mean.

Use case and scenario names #

Traffic, requirements and tests refer to use cases and scenarios by name, so the statement must spell out the exact names ("Cache hit", "Cache miss") and the solver must use them. The test messages name what is missing when they do not match.

The interview prep roadmap #

practice/#/roadmap is a guided path through the problems, in stages from foundations to large systems. Each step is the problem's lesson, then the problem; above the stages, a "Read first" article, frontend/src/practice/guide/approach.md, explains how to approach a system design interview (practice/#/roadmap/approach, readable without signing in, and the static page practice/approach/). Guides are listed in frontend/src/practice/guide/guides.ts; their ids are reserved. On the roadmap a problem opens only once every problem before it is solved (with the same progress as the list, in the browser or synced when signed in); the problem list itself stays open. A problem opened from the roadmap (practice/#/roadmap/<id>) shows its stage and, once solved, a link to the next one.

The page answers "what do I do now" first. Under the title, one line holds the progress (solved, a bar, the current stage) and, on Max, the interview plan's link. Then one Up next card with one primary button, by one rule (upNext in roadmap.ts): for a newcomer, the unread "Read first" guide (the first problem one smaller link away); else the next step, its lesson while unread (the challenge one link away), then its challenge; signed out past stage 1, a sign-in. At its foot, Also today lists the day's chores (a retry of a recent mistake, the cards due, the daily challenge) and More opens the rest of the rule-based next steps with their reasons, the Pro picks or the way to Pro. These never suggest a problem locked on the roadmap (lockedSteps). The stages follow: the current one open, the others one line each (done, or how many problems and what unlocks them), any of them opened on demand; what a stage waits for is said once, and a locked problem's lesson stays a link.

Anyone can see the stages and work through the first one signed out, with the progress kept in the browser; the stages after it take an account: signed out, they open only their lessons, "Up next" offers the sign-in once stage 1 is done, and practice/#/roadmap/<id> of a later step shows the roadmap instead of the problem (sign-in returns to that address). The exception is OPTIONAL_STEPS in roadmapStages.ts: the first step, hello-proschi, a tutorial that teaches the language one idea per test (nodes, connections, a use case's request and response, the traffic, requirements, a replica), opens signed out too. It is optional: recommended first to a learner who has solved nothing, but unsolved it locks no later step, keeps no stage from counting as complete and is in no badge's target (requiredStages). The rule is roadmapAccess in roadmap.ts. A build without accounts (VITE_ACCOUNTS unset, as in local development and the e2e build) has nothing to sign in to, so the roadmap is open there.

Your next steps is the roadmap's paid part (Pro), gated next to it by aiRoadmapAccess. After a Pro user's mock interview verdict, one Claude Haiku call picks the next 3 steps, each with a one-sentence reason. It gets the verdict, the weakest card topics, and every roadmap problem (solved or not) and card topic (with your mastery) by id; it only picks from those, and the server drops any pick whose id is not a real problem or topic. The verdict never waits on the picks: they are made after it is answered, and the page shows "Picking your next steps…" and asks again about 2, 5 and 10 s later, then says quietly if none came. A failed pick never fails the verdict. On the roadmap, More in "Also today" links each pick to its roadmap step (practice/#/roadmap/<id>, or its lesson while the step is still locked) or its card deck (practice/#/review/<topic>); the verdict links the same picks, and the progress page's "What to do next" shows them in place of its own suggestions. Signed in without Pro, with billing on, it shows the way to Pro instead. Without an Anthropic key on the server (GET /api/roadmap/next answers 501), or with no picks yet, the roadmap keeps its own order (backend src/roadmap.ts, src/ai/roadmap.ts).

The stages are plain data in frontend/src/practice/roadmap.ts (ROADMAP): each has an id, a title, a sentence or two on what it teaches and why it comes at that point (why), and its problem ids in the order they are solved. To change the path, edit that list:

  • Every problem must appear in the roadmap exactly once, so a new problem needs a place in a stage; npm test fails otherwise.
  • An id that is not a problem fails the tests too, unless it is in PENDING in roadmap.test.ts (problems being added in parallel). The page skips ids that do not exist and stages left empty.
  • Earlier stages are prerequisites of later ones: put a problem after the ideas it builds on, easier problems first within a stage.

Adding a problem in 5 steps #

  1. Scaffold it: proschi problem new seat-map (inside the repository it goes to frontend/src/practice/problems/; elsewhere pass --dir). The template is a small complete problem that already passes the check.
  2. Write problem.md: title, summary, difficulty, tags, hints and the statement; name every use case in bold and spell out the scenario names. Then write lesson.md and interview.md (and guided.md if it joins the first roadmap stage).
  3. Write given.proschi: the fixed nodes, the traffic, the requirements, any capacity the problem needs, and the tests that encode the key insight.
  4. Write the solution and the starter, then calibrate (above) and replace the example wrong design with the shortcuts your limits must reject.
  5. Check it: proschi problem check (or npm test in frontend/), then open practice/#/seat-map in npm run dev to read it as a solver would. The landing page and the practice list pick the folder up by themselves; add its id to a stage of the roadmap.

Edit this page on GitHub