Skip to content
Vedya Vedya

System Design Field Notes

Mental Model

Section titled “Mental Model”

System design is choosing where responsibilities live.

Every component should have:

  • A job.
  • Inputs.
  • Outputs.
  • Data ownership.
  • Failure modes.
  • Observability.

The Basic Product Shape

Section titled “The Basic Product Shape”

basic product shape

UserHas a job to complete.
FrontendTurns intent into structured input.
Backend APITrusted boundary and orchestration.
Business logicRules, permissions, workflows.
DatabaseDurable state.
Queue + WorkerBackground work and retries.
External serviceModel, payment, email, integration.
Logs and metricsEvidence from API and worker behavior.

What To Decide Early

Section titled “What To Decide Early”
  • What is synchronous?
  • What is asynchronous?
  • What data is durable?
  • What data is temporary?
  • What needs authentication?
  • What needs authorization?
  • What can be retried?
  • What must never happen twice?
  • What must be logged?
  • What must be auditable?

Common Patterns

Section titled “Common Patterns”
NeedPattern
User waits for immediate resultSynchronous API
Slow or unreliable workQueue plus worker
Avoid duplicate side effectsIdempotency key
Protect sensitive actionAuthorization check plus audit log
Fast repeated readsCache
Long file storageObject storage
Search by textSearch index
Human reviewPending state plus approval action

Failure Thinking

Section titled “Failure Thinking”

For each component, ask:

  • What if it is down?
  • What if it is slow?
  • What if it returns wrong data?
  • What if it returns partial data?
  • What if the user retries?
  • What if two users act at the same time?
  • What if the deploy changes schema before code is ready?

Field Design Template

Section titled “Field Design Template”
# Design


## Problem


## Users


## Current Workflow


## Proposed Workflow


## Components


## Data Model


## API Contract


## Failure Modes


## Security And Privacy


## Tests


## Deployment And Rollback


## Open Questions

Done When

Section titled “Done When”

You can explain the system at three levels:

  • User workflow.
  • Component diagram.
  • Request/data flow.