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 fragmentmay 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 anumbersrow, mark the one sentence to remember with acallout, fold long tangents into adeepdive, and end a few sections with aquizfrom 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.
- 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).
- 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). - 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
## Scaleand## 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
goodand 2weak(aim for about 5 and 3). A good question'sfactis 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 nofact; 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).
answeris a number above 0 (2300,2.3k,5M,1.6T),unitsays what it counts, andrange: <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 mixrequirements { … }: latency, availability, durability, failure and costcapacity { … }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 requirementssection. - 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
## Questionsand## Estimates; enough good and weak questions, each good one with afactfound in the statement's Scale or Constraints; each estimate with a numericanswer, aunit, 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
trafficis named in bold in the statement and defined (usecase "…") by the solution. - given: no
import, parses without errors (withstrictOpsfor 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 acardsfolder 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:
- Measure the reference solution: open the problem in
npm run devand use Show reference solution and the Analysis tab, or on the command line copygiven.proschitoproblem.proschiin a scratch folder next to the design and runproschi analyze solution.proschi. Note its p99 per use case, its cost and its availability. - 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.
- 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.
- Prove it: add each brute-force design as
wrong/<name>.proschiwith 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 testfails otherwise. - An id that is not a problem fails the tests too, unless it is in
PENDINGinroadmap.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 #
- Scaffold it:
proschi problem new seat-map(inside the repository it goes tofrontend/src/practice/problems/; elsewhere pass--dir). The template is a small complete problem that already passes the check. - Write
problem.md: title, summary, difficulty, tags, hints and the statement; name every use case in bold and spell out the scenario names. Then writelesson.mdandinterview.md(andguided.mdif it joins the first roadmap stage). - Write
given.proschi: the fixed nodes, the traffic, the requirements, any capacity the problem needs, and the tests that encode the key insight. - Write the solution and the starter, then calibrate (above) and replace the example wrong design with the shortcuts your limits must reject.
- Check it:
proschi problem check(ornpm testinfrontend/), then openpractice/#/seat-mapinnpm run devto 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.