wtf( )unctionsystem design, drawn
← wtfunction

Architecture you build, not read

Every problem is a real diagram with something already broken in it. Put the database in the wrong subnet and you'll be told exactly what that costs you — then watch the fixed design run, step by step.

AWS SA Pro

The spoke that borrowed the hub's circuitHardPlace what actually gets the payments VPC to the corporate network. No second circuit may be ordered — the business has one, and it terminates in the hub.The guardrail at the root that the billing job ignoredHardPlace the account the billing exporter should be running in, so the organization's guardrail actually constrains it.Two designs, one peering attachmentHardRead both route tables. Choose the design that actually routes between the Regions.The endpoint that works for everyone except the people who need itHardPlace what the on-premises callers use to reach S3 privately. The in-VPC path must keep working and must not start costing money.Four recovery plans, and the one the business actually boughtHardPut the four strategies in order of how quickly they restore service — fastest first.The resolver they built, and the half of it they did notHardPlace what resolves corporate names for instances inside the VPC. The direction that already works must keep working.Two designs, and the account that could not fix the other oneHardBoth diagrams are peered, both are active, both resolve. Choose the one where BOTH directions reach a private address.The packets crossed, and the name did notHardPlace what makes that zone answer for the other account's VPC. The zone stays where it is.Two designs, and the load balancer the endpoint service will not takeHardChoose the design that can actually be built as an endpoint service, without giving up the routing the ALB is doing.Two designs, and the firewall that only sees half a conversationHardBoth designs route everything through the inspection VPC. Choose the one where the appliance that sees the request also sees the reply.Two designs, and the DR test that passed while every write failedHardBoth designs point the application at a name. Choose the one that is still pointing at a writable cluster after a failover.Two designs, and the zone that is not the zoneHardBoth designs pin consumer and provider to one zone. Choose the one where that is the same physical zone.Six findings from the endpoint review, and the three that are realHardTap every finding that is a real problem.Four migration steps, and the one that is right twice for opposite reasonsHardPut the four steps in the order they must run.Two plans for one account move, and the DNS that dies on the wayHardBoth plans end with the account in the Regulated OU and the rule shared to it. Choose the one where DNS never stops.The logins that take thirty seconds, and the lookup nobody wrote a rule forHardPlace what resolves the lookup that is timing out. The forward direction already works and must keep working.The endpoint that was added, and the half of the fleet still paying to leaveHardPlace what puts the remaining subnet's traffic on the endpoint. The endpoint itself already exists and is healthy.Two cutover plans, and the six weeks nobody replicatedHardBoth plans cut over to a target holding every row. Choose the one that is still running on Monday.Three database instances, and the reads all land on oneHardChoose the deployment that adds read capacity and automatic failover without making writes slower.One zone went, and three zones lost the internetHardus-east-1a is impaired. Tap everything that loses outbound internet access with it.The DNS fix that was applied, confirmed, and did nothing for three hoursHardBoth plans end with the VPC pointed at a working resolver. Choose the one where the incident actually ends when the change is made.The migration validated clean, and three of these were never comparedHardTap every object that the validation report is not evidence for.The S3 endpoint was built, and the NAT bill did not moveHardTap everything that is still reaching S3 the expensive way.The writer failed, and the reporting team never noticedHardThe writer instance fails. Tap everything that stops working until failover completes — not the writer itself.

Databases

Fast on your laptop, four seconds in productionEasyAdd what turns a full scan into a direct lookup.Tags in a comma-separated columnEasyModel the relationship the way the database can actually use it.One query, then two hundred moreMediumReplace the per-row lookups with a single request.Every request brings its own connectionMediumPut the right thing between the app tier and the database.The address that was right in four places and wrong in oneMediumGive the customer's details one home.Six joins deep and getting slowerMediumStore the relationships in a shape whose cost follows the connections rather than the table.The setting that saved, then didn'tHardRoute each of the three reads to the store that can actually answer it correctly.Picking the column the whole system hangs onHardChoose the column to shard on.Every edit rewrote a hundred rows, and the bill arrivedHardCompose the data platform. Tier 1 is where changes land and what reshapes them, tier 2 is what reporting still reads.Adding the fifth shard moved everythingHardCompose the placement. Tier 1 is how a key finds its shard and how exceptions are made, tier 2 is what to do about the customer who does not fit.They saved it, the page reloaded, and the old value was backHardRoute each reader to the thing that can serve it. Tier 1 is the write path, tier 2 the read paths, tier 3 the photos.Two edits to the same profile, and the one that landed second was olderHardCompose the serving path. Tier 1 is what a region holds and what settles the order of two writes to one record, tier 2 is who may touch the store.The analytics job that filled the production diskHardAdd what notices the pipeline has stopped, before the disk does.The one query that forgot the tenantHardMove the tenant rule somewhere it can't be forgotten.Two withdrawals, one balance checkHardMake the second transaction wait for the first.A document model borrowed from the relational schemaHardShape the document around the read that actually happens.

Resilience

The inner timeout outlived the outer oneEasyOrder the timeouts so each layer gives up before the layer waiting on it.Everything in one buildingMediumDuplicate the tier into the second zone and place the standby.The burst was survived, and the notifications arrived at four in the morningMediumCompose the egress path. Tier 1 is what sets the rate and what sits between the producers and the senders, tier 2 is where the senders draw their capacity.Retrying politely into a wallMediumAdd the states that let the service answer at once while the dependency is down, and probe carefully rather than resuming all at once.A forty-second blip that restarted everythingMediumWire each check to the consequence that fits it.The retries that kept it downHardInsert the thing that stops a client from calling a service that's already failing.Ten thousand things changed at once and nothing slowed downHardCompose the configuration path. Tier 1 assembles it and carries it, tier 2 is what a serving node holds.The limit was a hundred, and they got four hundredHardCompose the limiter. Tier 1 is which counter a request reaches and how the count is changed, tier 2 is what happens when that is impossible.Four days long, and the vendor may never call youHardCompose the parts the vendor cannot supply. Tier 1 is how the workers and the vendor talk and what makes a four-day sleep survive, tier 2 is how an operator finds a stuck process.The backups were untouchable and nobody could get anything backHardCompose the recovery side. Tier 1 is where a second copy lives and what a restore lands in, tier 2 what the restore needs in order to read anything.Region A went, region B was healthy, and every viewer rebufferedHardCompose the live path. Tier 1 is what fixes the segment boundaries and how the second region is run, tier 2 is what the delivery tier reads from.The limit that counted the wrong thingHardBound the thing that actually consumes the resource, and close the second route to the same end state.The runbook needed the thing that was downHardTap the parts of the recovery path that the outage has already taken away.Finishing work nobody is waiting forHardBound what the service will accept.A node upgrade took auth downHardConstrain how many can be evicted at once, and stop them stacking in one place.The health check that removed every serverHardMake the shared-dependency failure survivable.

AI Engineering

Paying twice for the same answerEasyPlace what should answer before the model is called at all.Retrieval that returns nothing usefulMediumPlace the model on the query path.The agent that runs code you didn't writeMediumPut the execution somewhere a bad script can't hurt anything.The right document was there, just not in the top fiveMediumPlace the stage that reorders candidates before they reach the model.The error code that semantic search can't findMediumRun both retrievers and place what combines their results.Rendering the model's answer as HTMLMediumPut the boundary where it belongs.A one-line prompt change shipped on FridayMediumPut the gate in the pipeline that code already has.The backfill that ate the assistantMediumStop the overnight job from spending the capacity the assistant is holding.Exact search stopped fittingHardChoose the index for a 20M-vector collection that must answer in tens of milliseconds.The agent that read the wrong web pageHardBreak the chain: place the control on the outbound action.Scaling that arrives after the trafficHardFix what the scaler watches, and what a new node has to do before it can serve.One tenant's documents crowding out another'sHardMove the tenant boundary into the search itself.The moderation that ran after the user read itHardMove the guard inside the stream, without giving up streaming.Eight replicas were slower than twoHardGive the router what it needs to send a question to a replica that already holds that contract.Review this evaluation setupHardTap every component whose input makes the score mean something other than what the team thinks.

Distributed Systems

The request that waits for a video to encodeEasyBreak the long job off the request path.Why this app can't scale inMediumMove the session store out of the instances so any server can serve any request.The message that blocked the queueMediumGive the message somewhere to go after it has failed enough times.The same message, twiceMediumMake a second delivery do nothing.Stock that drifts negativeMediumChoose what decides which partition an event goes to.Which side do you upgrade first?MediumOrder the two deploys under backward compatibility, where new code must be able to read old data.Reads and writes that want opposite thingsHardPlace what carries changes from the write model to the read model.Two writes, one of which will failHardMake the event part of the same transaction as the order.Three teams, one order changeHardWire the order-change path. Tier 1 is the write side, tier 2 the distribution, tier 3 what the timeline reads.Ten thousand tenants, and one of them is on fireHardCompose what sits in front of the copies. Tier 1 is the shared front and what it reads, tier 2 is what a copy is allowed to lose.One partner is down, and every partner's data stopsHardCompose the delivery path. Tier 1 is accepting the event, tier 2 is the pending work, tier 3 is what happens when the window closes.One stream, two consumers, opposite fearsHardCompose how each consumer runs, and what a failover resumes from. Tier 1 is the pricing view and earnings, tier 2 is the record of where earnings had got to.Every region computed the price, and two of them published itHardCompose the tail of the pipeline. Tier 1 is what decides who publishes and where the number lives, tier 2 is what the customer's request actually reads.Charged for a booking that doesn't existHardAdd what owns the sequence and knows how to undo it.Two leaders, both certainHardMake the storage layer able to reject the stale writer.

API Design

"Something went wrong"EasyReplace the error body with something a client can act on.The request that runs for four minutesEasyAnswer immediately, and give the client a way to find out when it's done.Twelve round trips to draw one screenMediumInsert the layer that turns one client request into one response.Three failures, three different codesMediumGive each of these three failures the code that tells the client what to do.The retry that created three ordersMediumAssign each operation the method whose guarantees actually match it.Page two skipped four recordsMediumReplace what the client sends to ask for the next page.The field nobody meant to exposeMediumConstrain what a request body is allowed to touch.Sending the same payload sixty times an hourMediumLet an unchanged response cost almost nothing.One bad row failed the whole batchMediumReport the outcome at the granularity the caller can act on.The retry that charged them twice, and the one that charged them wrongHardCompose the guarantee. Tier 1 is what recognises a repeat and what proves it is really the same request, tier 2 is what stops two of them at once.The notification said one thing and the screen behind it said anotherHardCompose the push path. Tier 1 is what decides a push is warranted and what builds its body, tier 2 what the app gets when it asks directly.Two edits, one survivorHardGive the write a way to notice it's based on a stale read.Changing the id in the URLHardAdd the check that's missing between identifying the caller and returning the record.

Supply Chain

WebSockets

The socket that anyone could openEasyMake the server refuse a handshake that did not come from your own page.Connections that died quietly every sixty secondsMediumKeep the connection off the idle timer, and give both ends a way to detect a dead peer.A socket for a one-way feedMediumChoose the channel that matches the shape of the traffic.The message that only reached half the roomHardInsert the component that carries a message from one gateway to all the others.Two cursors, one paragraphHardCompose the editing path. Tier 1 is how a client stays connected and what decides, tier 2 is what survives.The gateway stopped watching after the handshakeHardCompose what the upgrade took away. Tier 1 is what still counts and how a message crosses nodes, tier 2 is what a reconnecting client lands on.What did I miss?HardCompose the recovery path. Tier 1 is what can answer that question and how far back it can answer, tier 2 is the live path it must not be confused with.The connection outlived the process that accepted itHardCompose what has to exist when nothing is running. Tier 1 is who is connected and how a message reaches them, tier 2 is what survives an eviction.The room says forty people are here and there are nineHardCompose presence. Tier 1 is who may be here and who IS here, tier 2 is how anyone finds out it changed.She walked out of the building and the server never noticedHardCompose what survives a network change. Tier 1 is who this is and what happens to the old connection, tier 2 is what happens to messages sent in between.The new server sat almost empty for six hoursHardCompose the deploy path. Tier 1 is how a new connection picks a server and what that decision is based on, tier 2 is how a server is emptied.They added servers and the backplane got slowerHardCompose the backplane. Tier 1 is what a publication survives and who has to see it, tier 2 is what receiving it twice costs.

Architecture

Microservices

One front door, not sixEasyPlace the component that terminates every inbound request at the boundary.The private service that wasn'tMediumGive the public API a way to reach billing that never leaves the private network.The service that trusted its caller's wordMediumGive the internal call something that proves the caller and something that proves the subject.One slow dependency, every endpoint downHardGive the risky dependency its own bounded share, so exhausting it cannot exhaust everything.Five languages, one retry policy, and no libraryHardCompose the policy layer. Tier 1 is what each call actually goes through and what proves who is calling, tier 2 is what hands out the rules.The search service issued a refundHardCompose the authorization path. Tier 1 is what decides whether a call is allowed at all and what payments itself may do to the ledger, tier 2 is what has to be running before any of it starts refusing anything.Three services, four retries each, sixty-four requests at the leafHardCompose the call path. Tier 1 is what bounds the work one user request may cause and how the overloaded service says stop, tier 2 is what actually stops.Search was never allowed to call payments, so it asked something that wasHardCompose the delegation path. Tier 1 is what recommendations presents to payments and what decides the delegation may exist, tier 2 is what recommendations may hand to the hop below it.Analytics got slow, and nobody could check outHardCompose the order path. Tier 1 is what distributes work to checkout's instances and what stands between checkout and the calls it must make, tier 2 is what takes the work the answer does not depend on.Three teams, one database, and every migration is a meetingHardGive each team its own data and its own front door. Tier 1 is the edge, tier 2 is how services find each other, tier 3 is the stores and the reporting path.

ML Engineering

Observability

One label, and the metrics store fell overEasyKeep the per-account question answerable without making the counter a per-account counter.The trace stops at the queueMediumCarry the context across the asynchronous hop, and connect the two sides with the relationship that is actually true.The dashboard is green and the customer is angryMediumTap every belief that the histogram does not support.The dashboard that went blank during the incidentMediumAttach each dimension to the store built to hold it.They kept one percent of traces, and one percent of the errorsHardCompose the sampling path. Tier 1 is where the spans of one trace meet and what holds them while it waits, tier 2 is what chooses.The containers that mattered had already exitedHardBuild the log path. Tier 1 is what gets lines out of a container, tier 2 is what absorbs a burst and what labels a line, tier 3 is where it all lands and what a tenant is allowed to see.The vendor offered to delete it on arrivalHardCompose the path a crash report takes on its way out. Tier 1 is what strips it and what holds the credential, tier 2 what happens when the vendor is down.Ten percent everywhere, and no complete tracesHardMake the sampling decision once and make it stick, and put the decision that needs the whole trace where the whole trace exists.Paged for a blip, silent for a slow bleedHardBuild the alert out of two windows rather than one threshold, and give the slow burn its own severity.Traces missing half their spansHardRoute spans so a sampling decision can be made on a whole trace.

Payments

Charged for something that never shippedEasySplit the payment into the step that reserves the funds and the step that takes them, and put the fulfilment check between them.Anyone can POST to your webhookMediumPlace the verification gate and the thing that stops duplicate work.The prettier checkout that widened the auditMediumRedraw the card-data path so it never crosses your server.Three readers, three completely different bargainsHardCompose the record layer. Tier 1 is the source of truth and the authorisation lookup, tier 2 is the screen everyone reads.The bank had a slow afternoon and the shop went downHardTake the acquirer off the checkout path. Tier 1 is what checkout hands the capture to before answering and where a capture goes once its retries are spent, tier 2 is what the shopper's page polls.Twenty seconds, or it never happenedHardCompose the path an incoming payment takes. Tier 1 is where a message rests once it is off the rail, tier 2 is the two checks that must finish before the bank answers, tier 3 is what signs the answer.Two cards, one balance, and the network gave us one chanceHardCompose the decision path. Tier 1 is how the funding request is answered and what decides there is money, tier 2 is what stands in front of the call that decision makes.The timeout that charged twiceHardPlace the idempotency key, and the moment it becomes durable.The refund arrived before the paymentHardMake the handler's outcome independent of the order the notifications arrive in.The number that could not be explainedHardReplace the mutable number with something that can be recomputed and audited.

Caching

Networking

Authentication

Browser Security

Cloud Practice

Containers

Deployment

Policy & IAM

Cookies

Security

Web Performance

Accessibility

Email

MCP

OSI Model