Module 01: Systems And Architecture

Goal

Learn to break a product into components, boundaries, data flow, and failure modes.

The Mental Model

Architecture is responsibility placement.

Every serious system has parts that should not all do the same job. The frontend should not own payment truth. The database should not decide UI state. The API should not trust the browser. The worker should not require a user to wait.

Analogy

A hospital works because responsibilities are separated:

Reception identifies the patient.
Nurses collect vitals.
Doctors diagnose.
Pharmacy dispenses medicine.
Records store history.
Labs process slow tests.
Billing handles payment.

If reception starts prescribing medicine, people get hurt. If the database starts acting like the UI, software gets hurt.

Core Components

Component	Job	Common Failure
Frontend	User interaction and display state	Shows wrong state or sends bad request
Backend API	Trusted boundary and orchestration	Bad validation or wrong status code
Business service	Domain rules	Wrong rule or missing edge case
Database	Durable state	Bad schema, slow query, lost migration
Cache	Fast temporary state	Stale value
Queue	Buffer background work	Duplicate or stuck job
Worker	Process async tasks	Retry storm or partial failure
External API	Third-party capability	Timeout, quota, wrong response
Observability	Logs, metrics, traces	No evidence during incident

Visual: System Skeleton

component skeleton

UserNeeds an outcome, not code.

FrontendCollects input and shows state.

Backend APITrusted boundary for validation and orchestration.

Business RulesOwns domain decisions.

DatabaseDurable facts.

Queue + WorkerSlow or retryable work.

External APIOutside dependency with failure risk.

ObservabilityLogs, metrics, traces, and alerts connect every component to evidence.

Boundaries

A boundary is where data crosses responsibility.

Important boundaries:

User input to frontend.
Frontend to backend.
Backend to database.
Backend to external API.
Queue producer to queue consumer.
App to infrastructure.

At every boundary, ask:

What data shape is expected?
Who is allowed to call this?
What happens if data is missing?
What happens if the receiver is down?
What gets logged?

Architecture Drill

Design “upload a document and receive a summary later.”

Required components:

Upload screen.
API for upload.
Object storage for file.
Database record for document status.
Queue for summary job.
Worker that calls a model/API.
UI that shows pending, failed, or complete.

Failure Modes To Include

File too large.
Unsupported file type.
Upload succeeds but DB write fails.
Queue accepts job but worker crashes.
Model/API times out.
Summary is low quality.
User refreshes page during processing.
User lacks permission for the document.

Agentic Angle

Ask an agent for a failure-mode review:

Review this document-summary architecture. Find missing components, bad
boundaries, race conditions, security issues, and observability gaps. Do not
rewrite it. Return findings with severity.

Questions

Why should slow document processing use a queue?
What state should be stored in the database?
What should object storage own?
Which actions need authorization?
What metric tells you workers are falling behind?
What log line helps trace one document from upload to summary?

Tasks

Create portfolio/01-systems-and-architecture/document-summary-design.md.
Draw the component diagram.
Draw the request and job flow.
Mark every boundary.
List at least ten failure modes.
Add one log and one metric per component.
Ask an agent to critique the design.
Revise the design.

Done When

You can explain why every component exists.
You can trace the happy path and three failure paths.
You can identify where data is stored and who owns it.
You can explain how you would know the system is broken.