DEV Community: Brian Pfeil

Study computer science, university-style: 15 free resources

Brian Pfeil — Tue, 29 Sep 2026 21:38:06 +0000

Real university courses, lectures and full curricula, free.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 15 resources, with the ones I'd start with marked ⭐.

OpenCourseWare, by MIT ⭐: Lecture notes, videos and exams from 2,500+ real MIT courses.
MITx, by MIT: MIT's online courses, free to audit.
Open Learning Library, by MIT: Self-paced MIT course material you can work through any time.
Open Learning Initiative, by Carnegie Mellon: Carnegie Mellon's research-backed courses that adapt as you learn.
Free courses, by Stanford Online: Stanford's free courses and recorded lectures, computer science included.
Coursera: University courses you can audit for free; you pay only for a certificate.
edX: Courses from Harvard, MIT and more, free to audit.
OSSU Computer Science ⭐: A complete computer science degree assembled from free courses.
Teach Yourself Computer Science: The nine subjects every software engineer should know, with one book and one lecture series for each.
CS video courses: A huge index of university computer science courses with free lecture videos.
Free online courses, by Open Culture: 1,700+ free courses from top universities, across every subject.
NeetCode: Coding-interview practice, with a clear video explanation for each problem.

Made here

eBPF: See inside the running Linux kernel — observability and tracing with eBPF and bpftrace, taught from an app-developer starting point.
macOS Kernel & System Extensions: Demystify how third parties extend macOS — from legacy kexts to modern user-space System Extensions — and build, install, and watch your own one run on Apple Silicon, all from the CLI.
Nix: Reproducible builds and dev environments with Nix — derivations, the store, and flakes.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/university/.

Understand how AI works: 15 free resources

Brian Pfeil — Tue, 29 Sep 2026 21:36:22 +0000

From the maths of a neuron to building your own language model.

Neural Networks: Zero to Hero, by Andrej Karpathy ⭐: Build neural networks from scratch in code, all the way up to GPT.
Neural networks, by 3Blue1Brown ⭐: The best visual explanation of how neural networks and transformers work.
Practical Deep Learning, by fast.ai: A top-down, code-first deep learning course for people who can already program.
Machine Learning Crash Course, by Google: Google's fast-paced, practical introduction to machine learning.
Introduction to Deep Learning (6.S191), by MIT: MIT's intro to deep learning, with lectures and labs posted free each year.
Courses, by DeepLearning.AI: Andrew Ng's platform, with dozens of free one-hour short courses on LLMs and agents.
LLM Course, by Hugging Face: Transformers, fine-tuning and LLMs with the Hugging Face libraries.
AI Agents Course, by Hugging Face: Build AI agents, from the fundamentals to frameworks, with a certificate.
Dive into Deep Learning: An interactive deep learning textbook with runnable code; used at 500+ universities.
Neural Networks and Deep Learning, by Michael Nielsen: The clearest free book on how neural networks learn.
An Introduction to Statistical Learning: The classic statistical learning textbook, free as a PDF, with labs in R and Python.
Deep Learning, by Goodfellow, Bengio & Courville: The deep learning textbook, free to read online.
Reinforcement Learning: An Introduction, by Sutton & Barto: The standard reinforcement learning textbook, free online.
AI Canon, by a16z: A curated reading list for getting up to speed on modern AI.

Made here

PyTorch: Become fluent reading and writing real PyTorch — tensors, autograd, and the training loop — from first principles, with every example runnable on Apple Silicon (MPS).

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/ai/.

Get good with a specific AI model: 19 free resources

Brian Pfeil — Tue, 29 Sep 2026 19:12:09 +0000

Each lab's own courses, cookbooks and docs — Claude, ChatGPT, Gemini, Llama, Mistral — and how to run open models yourself.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 19 resources, with the ones I'd start with marked ⭐.

Anthropic · Claude

Anthropic Academy ⭐: Anthropic's free courses: Claude 101, Claude Code, the API and MCP.
Courses on GitHub: Anthropic's notebook courses: API fundamentals, prompting, evaluations and tool use.
Interactive prompt engineering tutorial: A nine-chapter, hands-on course in prompt engineering.
Claude Cookbooks: Copyable recipes for building with Claude: RAG, tools, agents and more.
Claude docs: The Claude API documentation, guides and prompt library.
Claude Code docs: How to use Claude Code, Anthropic's coding agent, in your terminal and editor.

OpenAI · ChatGPT

OpenAI Academy: OpenAI's free courses, livestreams and events for every level.
OpenAI Cookbook: Example code and guides for building with OpenAI's models.
API docs: OpenAI's API guides and reference.

Google · Gemini

Gemini API docs: Guides and quickstarts for building with Google's Gemini models.
Google AI Studio: Try Gemini models in the browser, free, and export working code.
Gemini Cookbook: Notebooks and examples for the Gemini API.

Meta · Llama

Llama Cookbook: Meta's recipes for running, fine-tuning and building with Llama models.

Mistral AI

Mistral docs: Guides for Mistral's open and commercial models.

Run models on your own machine

Ollama: The easiest way to run open models on your own laptop.
MLX LM: Run and fine-tune language models fast on Apple silicon Macs.
llama.cpp: The engine that makes local models run on everyday hardware.

Made here

Agentic Loop Engineering: Designing tight, verifiable agent loops with Claude Code — the verify step, tools, and feedback.
mlx-lm: Run, quantize, serve, and fine-tune LLMs locally on Apple Silicon with Apple's mlx-lm — the CLI and Python surfaces, from first principles, every example verified on an M4 Pro.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/models/.

Help a kid start coding: 13 free resources

Brian Pfeil — Tue, 29 Sep 2026 19:11:58 +0000

Block coding, games and first apps for young learners.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 13 resources, with the ones I'd start with marked ⭐.

Scratch, by MIT ⭐: MIT's drag-and-drop coding for kids, with millions of shared projects.
Code.org: Hour of Code and full courses for every grade.
Khan Academy Kids: A free learning app for ages 2 to 8.
Lightbot: A puzzle game that teaches programming logic without typing any code.
App Inventor, by MIT: Build real phone apps with blocks.
Swift Playgrounds, by Apple: Apple's app for learning to code in Swift on an iPad or Mac.
Roblox Creator Hub, by Roblox: Learn to make Roblox games in Lua, straight from Roblox.
Minecraft Education: Coding and STEM lessons inside Minecraft.
CoderDojo: Free, volunteer-led coding clubs for young people around the world.

Made here

Mathmon Battle League: A creature-collecting card battler where every attack is a maths problem.
Animal Fun: iPhone and iPad app to help kids learn about animals.
Alpha Sound: A simple ABC's learning program for children.
Vehicle Fun for Kids: Interactive vehicle app with real pictures and sounds for young children.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/kids/.

Read the papers behind it: 7 free resources

Brian Pfeil — Tue, 29 Sep 2026 19:11:47 +0000

The original ideas, straight from the source.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 7 resources, with the ones I'd start with marked ⭐.

Attention Is All You Need, by Vaswani et al., 2017 ⭐: The 2017 paper that introduced the transformer behind every modern AI model.
Dynamo: Amazon's Highly Available Key-value Store, by DeCandia et al., 2007 ⭐: The 2007 paper that shaped a generation of distributed databases.
Papers We Love: A community-curated library of computer science papers worth reading.
The Morning Paper, by Adrian Colyer: Years of accessible write-ups of important CS papers, one each weekday.
arXiv: Where new AI and computer science research appears first, free to read.
martinfowler.com, by Martin Fowler: Decades of clear writing on software design, refactoring and architecture.
High Scalability: Case studies of how real companies built systems at scale.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/papers/.

Learn to code from zero: 11 free resources

Brian Pfeil — Tue, 29 Sep 2026 19:11:38 +0000

Never written a line of code? Start here.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 11 resources, with the ones I'd start with marked ⭐.

CS50x, by Harvard ⭐: Harvard's intro to computer science, the most popular course of its kind. Scratch, C, Python, SQL and the web.
freeCodeCamp: Thousands of hours of interactive lessons and projects, with free certifications.
The Odin Project: A full-stack web curriculum where you build real projects on your own machine.
Computing, by Khan Academy: Gentle, interactive programming and computer science lessons.
Learn web development, by MDN: HTML, CSS and JavaScript taught by the people who write the web's reference docs.
The Missing Semester, by MIT ⭐: The shell, git, editors and debugging — the tools school never teaches.

Made here

Web Authentication: A mental model of modern web auth — sessions vs tokens, OAuth2/OIDC, passwordless and passkeys — built concept-first but always landing on how you'd wire it into a real app.
V8 JavaScript Engine: How V8 turns JavaScript into fast machine code — parsing, the JIT pipeline, and hidden classes.
C++ Standard Library: A practical, category-by-category tour of the most-used C++ standard library classes — containers, strings, smart pointers, algorithms, and more — so you reach for the right one by reflex.
Browser-Testing Playground: Claude Code as an autonomous E2E/UI tester — driving a browser and verifying behavior.
Stripe: Hand-build payment integrations that sell digital products — checkout, webhooks, subscriptions.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/code/.

Learn from the people I follow: 8 free resources

Brian Pfeil — Tue, 29 Sep 2026 19:09:04 +0000

The builders and thinkers I read and listen to most, and where they teach for free.

I keep a directory of free ways to learn at brianpfeil.com/learn, sorted by goal, and every link opens without signing in. This is one of its paths: 8 resources, with the ones I'd start with marked ⭐.

Simon Willison

Simon Willison's Weblog ⭐: Daily, hands-on notes on using LLMs to build software. The best single place to keep up with AI as an engineer.
LLM: A command-line tool for talking to almost any model, local or hosted. Its docs double as a tutorial.

Lex Fridman

Lex Fridman Podcast: Long-form conversations with AI researchers, engineers and scientists. Full episodes with transcripts.

Andrew Huberman

Huberman Lab: How the brain and body work, and science-based habits for sleep, focus and learning.

Addy Osmani

Patterns.dev ⭐: Design, rendering and performance patterns for modern web apps, free, including his JavaScript design patterns book.
AddyOsmani.com: Essays from a Google engineering lead on AI-assisted coding, working with agents and web performance.

Mitchell Hashimoto

Writing: The HashiCorp co-founder on building Ghostty, systems programming in Zig and how he works with AI agents.

Pieter Levels (@levelsio)

levels.io: How one person ships and runs profitable products alone: building in public, keeping the stack simple, launching fast.

The up-to-date list, and the other paths (code, cloud, AI, kids and more), is at brianpfeil.com/learn/people/.

The Architecture Review Checklist: 41 Questions I Ask

Brian Pfeil — Tue, 29 Sep 2026 10:43:18 +0000

I've sat on the reviewing side of a few hundred cloud architecture reviews.
Different teams, vendors and business problems — but the same forty-odd
questions come up again and again. Here they are, grouped the way I think
about them.

Use it two ways: if you're presenting, answer every question before the
meeting and the review becomes a conversation instead of an interrogation.
If you're reviewing, it's a starting point; add the questions your
organisation keeps having to ask.

Key point: The goal of a review isn't to catch a team out. It's to make sure the
architecture that gets built is the one everyone agreed to, and that
nobody is surprised six months later by a bill, an outage or an audit.

1. Compute: why not something more managed?

My default order of preference is SaaS, then serverless, then containers, then
servers (more on that ladder). Most of these
questions are about moving one rung up.

☐ Could this be SaaS? If not, write down why not.
☐ Why not serverless? The burden of proof is on the less-managed option.
☐ If it needs containers, why not a serverless container platform rather than a self-managed cluster?
☐ Is the workload really stateless, or does it quietly depend on local disk?
☐ Is this a lift-and-shift? Where's the chance to move up the stack later?
☐ What starts each process? Could a cron job or a poller become an event?
☐ Will anything hit a limit? Function timeouts, payload sizes, header sizes, API quotas. Check the service quotas before you design around a service.

2. Vendor and ownership

Vendor products show up in a lot of reviews, and the questions are always
about who does the work after go-live.

☐ Who installs, patches and upgrades it, and on what cadence?
☐ How does the vendor ship updates? Are their images and packages scanned?
☐ Who supports it in production, and what does that support actually cover?
☐ What's the exact split of responsibility between you, the vendor and the cloud provider?

3. Identity, access and secrets

☐ How do people sign in? Does it support single sign-on over SAML or OIDC?
☐ For each component: what authenticates to it? If it isn't native cloud IAM, why not?
☐ Where do credentials, keys and tokens live, who can read them, and is rotation automatic?
☐ Is any automation running on a person's credentials? That's an anti-pattern — use a role.
☐ Does every function and task have its own least-privilege role? Prefer narrow custom policies over broad managed ones.
☐ For a public endpoint with no auth, what stops abuse? A web application firewall, throttling, API keys, all three?

4. Data and compliance

☐ What's the data classification and business criticality? Is any of it regulated?
☐ How is data encrypted at rest and in transit? Does anything need encrypting on the client side?
☐ How long is data kept? Can it move to cheaper storage tiers, or be deleted?
☐ Are there audit requirements, and could you produce the evidence tomorrow?
☐ Is sensitive data kept out of the logs?
☐ Does it matter where the data physically lives?

5. Networking

☐ Which ports and protocols does it need? Anything inbound other than 443 needs a reason.
☐ What has to be public, and why?
☐ How does it connect to other environments, on-premises and partners? Who provides and who consumes each private link?
☐ How is DNS handled? Put a stable name in front of generated endpoints.
☐ Why does the application care about IP addresses at all? Identity beats IP allow-lists.

6. Resilience, high availability and disaster recovery

☐ What are the recovery time and recovery point objectives? Is DR even required?
☐ Is it multi-AZ? For anything that isn't, what compensates?
☐ Is anything stateful sitting in the recovery path?
☐ Can lost data be rebuilt or replayed from another source?
☐ Are handlers idempotent, so a retry is safe? Where do failures go — a dead-letter queue — and who replays them?

7. Observability and operations

☐ Which logs and metrics exist, and which ones alarm? Every error metric should either page someone or trigger self-healing. An error nobody hears about isn't monitored.
☐ Are logs structured, with metrics derived from them?
☐ Is there distributed tracing across the serverless pieces?
☐ Can it be built, deployed and run without anyone clicking in the console?

8. Delivery and cost

☐ Is all of the infrastructure versioned as code, with a pipeline that runs on every commit?
☐ Is there one account per environment?
☐ Are the required tags applied?
☐ What will it cost — including the idle cost and data transfer, which are the two numbers most estimates leave out?

What gets a team sent back

In my experience it's rarely a bad idea that sinks a review. It's a missing
answer. The usual gaps are failover, backups, alarms, the support model and
cost. If your diagrams and docs cover those, you're most of the way there —
here's how I'd prepare.

Watch out: A concession is fine — every real system has some. But write it down with
a date to fix it. An undated exception is a permanent one.

Originally published at brianpfeil.com, part of a series of cloud architecture guides drawn from the reviews I run.

How to Prepare for an Architecture Review

Brian Pfeil — Tue, 29 Sep 2026 10:43:08 +0000

Most architecture reviews that go badly go badly for the same reason: the team
arrives with a good design and an incomplete story. The reviewers spend the
hour discovering gaps instead of discussing trade-offs, and everyone books a
second meeting.

This is what I'd tell any team preparing for one. None of it is specific to a
company; it's what reviewers everywhere are trying to find out.

📐 Diagram — Review flow: pre-read, review, recommendations, target-state document, build (see it in the original)

1. Meet the entry criteria

Before anyone looks at a diagram, reviewers want five facts. If any are
missing, that's the first thing they'll ask about.

Bring	Why they ask
The business need and a short executive summary	Every trade-off is judged against what the system is for.
The proposed architecture	Obviously — but as diagrams, not prose (see below).
Whether it's regulated	Changes the controls, the evidence and sometimes the region.
The data classification	Drives encryption, access, retention and logging.
The business criticality	Drives availability targets and whether DR is needed at all.

2. Bring diagrams reviewers can read

A good diagram answers questions before they're asked. Draw it in your cloud
provider's reference-architecture style, number the steps of the main flow,
and show the boundaries: internet, your company, on-premises, other clouds,
partners and SaaS; accounts, regions, networks, availability zones and
subnets; devices and users.

One diagram can't show everything. I ask for four:

The core solution — the request and data flow, numbered.
Build and deploy — the pipeline, from commit to production.
Availability, backup and recovery — what fails over to where.
The vendor or partner lifecycle, if there is one — who ships updates and how they arrive.

There's more on this in Diagrams and decision records reviewers trust.

3. Cover the cross-cutting concerns

These are the topics teams leave out, and each one is a reason to be sent back.
Put an answer to every row on a page or a diagram.

Concern	The question behind it
Infrastructure as code	Can the whole thing be rebuilt from a repository?
CI/CD	What happens on every commit?
IAM, per component	What can each piece do, and nothing more?
Secrets	Where are they, and do they rotate?
App configuration	Where does it live, and how does it change safely?
Logs, metrics, alarms	Who finds out when it breaks?
Backups	What's backed up, how often, and has a restore been tested?
Self-healing	What recovers without a human?
Disaster recovery	Recovery time and point objectives, and how you'd meet them.
Versioning	APIs, schemas, artefacts.
Audit	What evidence exists, and where?
Cost	Including idle cost and data transfer.

4. Mark every service's status

If your organisation keeps a list of approved cloud services, mark each service
on the diagram as approved, approved with conditions, not approved
or not yet requested, and bring a list of the gaps. It turns a vague worry
("are we allowed to use that?") into a tracked action.

5. Justify anything that isn't managed

Reviewers will push anything that isn't fully managed and pay-per-use up the
ladder: servers toward containers, containers toward serverless, custom code
toward a managed service. That's fine — sometimes there's a real reason. But
come ready to show you understand your workload in detail: its traffic shape,
its state, its runtime, its limits. "We've always run it on a VM" is not a reason.

6. Leave with decisions, not just notes

Keep a shared parking lot for questions nobody can answer in the room, and a chat channel for follow-ups, so the meeting doesn't stall.
Expect recommendations in two tiers: the primary target, and an interim step you can ship now on the way there.
Once you've picked an option, write the target-state architecture document and get it approved before you build. Come back only when something significant changes.
Record the big choices as architecture decision records.
Store every artefact, versioned, in one predictable place linked to the ticket that tracks the work.

Key point: The more completely your diagrams and documents capture the agreed
architecture, the more likely it is that the thing that gets built matches it.
That's the whole point of the exercise.

Before you send the invite

☐ Executive summary, business need, regulation, data classification, criticality
☐ Core, CI/CD, availability/DR and (if relevant) vendor diagrams, numbered and bounded
☐ An answer for every cross-cutting concern in the table above
☐ Every service marked with its approval status; gaps listed
☐ A reason for everything that isn't managed and pay-per-use
☐ A cost estimate with idle cost and data transfer
☐ The review checklist answered

Originally published at brianpfeil.com, part of a series of cloud architecture guides drawn from the reviews I run.

The Compute Ladder: Serverless-First, Then Work Backwards

Brian Pfeil — Tue, 29 Sep 2026 10:42:53 +0000

When a team asks "where should this run?", I don't start with their stack. I
start at the top of a ladder and ask what stops us from staying there.

📐 Diagram — The compute ladder: SaaS at the top, then serverless, containers, and servers at the bottom. Higher rungs mean less to operate. (see it in the original)

The rule

Design the ideal, most-managed version first. Then work backwards, one rung
at a time, and only for a constraint you can name.

The mistake I see most often is the reverse: start from what the team already
runs, and only move up if someone insists. That produces architectures shaped
by habit rather than by the problem.

Why each rung up is worth it

Every step up the ladder hands a whole category of work to someone else:

Moving from…	…to	You stop owning
Servers	Containers	OS images, most patching, bin-packing by hand
Containers	Serverless	Cluster capacity, scaling policy, idle cost
Serverless	SaaS	The code itself

That's why I treat less-managed options as the ones that need justifying. The
burden of proof sits with the servers, not the functions.

Within each rung, there's a ladder too

The same thinking applies inside a rung.

Serverless functions, most managed first:

The provider's managed runtime
The managed runtime plus layers for shared code
A container image as the function package
A custom runtime

Containers, most managed first:

A managed batch service, for work that runs and finishes
Serverless containers — no cluster to manage
A container orchestrator, when you genuinely need its control

What a "preferred" service looks like

When I'm choosing between services, the ones I reach for share four traits:

Pay-per-use — no idle cost when nothing is happening.
Fully managed — no patching, no capacity planning.
Highly available by default — multi-AZ without extra work.
The provider carries most of the shared-responsibility model.

The more of those a service has, the less your team has to build and run
around it.

Services are Lego blocks

Serverless architecture is mostly composition, not programming. Think of a
cloud provider's managed services the way you think of a language's standard
library: you wouldn't write your own hash map, so don't write your own queue,
retry loop or workflow engine.

Two habits follow from that:

Configuration over code. If a service can do the job through configuration — a direct integration, a routing rule, a lifecycle policy — prefer that to a function. Code is a liability: it has to be tested, patched and owned.
Learn the blocks. You can't compose what you don't know. Read the limits and quotas page of every service before you design around it; that's where most surprises live.

Good reasons to step down a rung

Stepping down isn't failure. These are constraints I'd accept:

Execution time or resources beyond what functions allow.
A vendor product that only ships as a container or a server image.
Real local state or specialised hardware.
A proven cost crossover at sustained high load — with the numbers, and including the operations cost you're taking back on.

And ones I wouldn't: familiarity, "we might need it later", or a design that
only needs a server because it polls on a timer (make it
event-driven instead).

Key point: If you do step down, record why in a
decision record
and give the next step up a date. Today's constraint is often next year's
new managed feature.

Originally published at brianpfeil.com, part of a series of cloud architecture guides drawn from the reviews I run.

Cloud Architecture Anti-Patterns (and What to Do Instead)

Brian Pfeil — Tue, 29 Sep 2026 10:38:31 +0000

These are the patterns I flag most often in architecture reviews. None of them
is a disaster on its own. Each one adds operational work, hides a failure mode,
or makes the next change harder — and they compound.

The examples use AWS service names because that's what I review most, but every
major cloud has an equivalent.

Integration

Glue code in a function

Instead: a direct service integration. If a function exists only to take a
message from one managed service and hand it to another, let the services talk
directly — API Gateway straight to a queue, a workflow calling an SDK
integration, an event rule targeting the next service. Code is a liability:
every line has to be tested, patched and owned.

One big function or script that does many steps

Instead: a workflow engine (Step Functions), one step per function. You get
retries, error handling, timeouts and per-step visibility for free, and each
step stays small enough to reason about.

Several workflows chained together

Instead: one parent workflow that calls the others. A run is then one
thing you can see, retry and reason about, rather than a relay race.

A synchronous API in front of a long job

Instead: accept the request onto a queue and return immediately with an
ID; let the client poll (or be notified) for the result. Synchronous calls
turn slow work into timeouts and retries into duplicate work.

Storage events wired straight to a function

Instead: put a queue in between — stable storage first. The queue
absorbs bursts, retries failures and gives you a dead-letter queue to inspect,
instead of silently dropping events when the function is throttled.

Calling a flaky or someone-else's downstream API directly

Instead: go through a queue or event bus, so you get buffering and
back-pressure. Their outage becomes your backlog, not your outage.

Polling and cron

Instead: event-driven triggers. A job that wakes every five minutes to ask
"anything new?" is either late or wasteful, and it's usually the only reason
the design needs a server. Most sources can emit an event when something
changes.

Compute

A fixed fleet of virtual machines

Instead: managed or serverless compute, or at least an auto-scaling group.
See the compute ladder.

Routing logic in application code

Instead: let the API gateway or load balancer route. Routing in
configuration is visible, reviewable and changeable without a deploy.

Function URLs for internal APIs

Instead: an API gateway with a private endpoint, so internal APIs get
authentication, throttling, logging and a stable name in one place.

Security

Credentials in environment variables or on disk

Instead: a secrets manager or parameter store, read at runtime by a role
that's allowed to read exactly that secret — with rotation turned on.

Automation running on a person's credentials, or long-lived keys

Instead: roles. Pipelines, scheduled jobs and integrations should assume a
role with temporary credentials. When the person leaves, nothing breaks; when a
key leaks, it has already expired.

SSH through a jump host

Instead: a session manager (Systems Manager Session Manager or similar):
no inbound ports, no shared keys, and every session is logged.

Data

A relational database by default

Instead: ask what the access pattern really is. Analytics over files is
often object storage plus a SQL query layer; spiky transactional work may suit
a serverless relational database or a key-value store. An always-on database
for a workload that runs twice a day is paying for a lot of idle.

Raw CSV as the long-term format

Instead: a columnar format (Parquet) with lifecycle rules that move old data
to cheaper tiers. Queries get faster and cheaper, and retention stops being
manual.

Database links between systems

Instead: an API or events. A database link couples two systems' schemas,
release schedules and outages, and hides the dependency from everyone who
reads the architecture diagram.

Tooling

Two tools doing one job

Instead: pick one. Two API management layers, or a CI server moonlighting
as the integration runtime, doubles the patching, the permissions and the
places to look when something breaks.

Key point: The common thread: prefer managed services composed through configuration,
connected by queues and events, and accessed through roles. Most of the
anti-patterns above are a missing queue, a missing role, or code standing in
for a service that already exists.

Want the questions that surface these? They're in
the architecture review checklist.

Originally published at brianpfeil.com, part of a series of cloud architecture guides drawn from the reviews I run.

Architecture Diagrams and Decision Records Reviewers Trust

Brian Pfeil — Tue, 29 Sep 2026 10:38:15 +0000

Two artefacts do most of the work in an architecture review: the diagram,
which shows what you're building, and the decision record, which shows why.
Get both right and the meeting is about trade-offs, not archaeology.

Diagrams

Use the reference-architecture style

Draw in the style of your cloud provider's reference architectures, with the
provider's official icons. Reviewers read that visual language fluently, and it
stops arguments about what a box means. Free tools are fine — draw.io
(including its VS Code extension) ships the major providers' icon sets.

Number the flow

Put a number on every arrow of the main path — 1, 2, 3 — and explain each
step in a short list beside the diagram. A reviewer can then say "at step 4,
what happens if…" and everyone is looking at the same place.

Draw the boundaries

Most security and networking questions are really questions about boundaries.
Show them:

Boundary	Why it matters
Internet · your company · on-premises	What's exposed, and what crosses the edge
Other clouds · partners · SaaS	Who you depend on and how you connect
Accounts · regions	Blast radius, data residency, DR
Networks · availability zones · subnets (public/private)	Reachability and high availability
Devices · users	Who actually starts each flow

One diagram can't do everything

I ask for a small set rather than one poster:

Core solution — the numbered request and data flow.
Build and deploy — commit to production.
Availability, backup and recovery — what fails over to where, and what gets restored from what.
Vendor or partner lifecycle — how their updates reach you, if relevant.

Key point: If a cross-cutting concern — secrets, alarms, backups, cost — isn't on any
diagram or page, reviewers will assume it hasn't been designed. Usually they're
right.

Decision records

An architecture decision record (ADR) is a short document that captures one
significant decision: what you chose, what you didn't, and why. They're
cheap to write, and they save hours when someone asks "why on earth did we…?"
a year later — often you.

Write one whenever you choose between real options: a database, a compute
rung, a vendor, an integration style, or a concession you plan to fix later.

A template

# ADR-NNN: <short decision title>

- Status: proposed | accepted | superseded by ADR-MMM
- Deciders: <roles, not just names>
- Date: YYYY-MM-DD

## Context and problem
What forces are at play? What question are we answering?

## Decision drivers
- e.g. time to deliver, team skills, cost, risk, compliance

## Options considered
1. Option A
2. Option B
3. Option C

## Decision
We chose <option>, because <the drivers it satisfies best>.

### Positive consequences
### Negative consequences (and how we'll live with them)

## Pros and cons of each option
### Option A
- Good, because …
- Bad, because …

Tips that make ADRs useful

Include the options you rejected. The rejected options are what stop the same debate happening again.
Name the drivers before the decision. It keeps the choice honest.
Supersede, don't edit. When a decision changes, write a new record and link the old one. The history is the value.
Record concessions with a date. "We'll run it on servers for now" is a decision; "…and move to serverless containers by Q3" makes it a plan.

Recommendations in two tiers

When I write up a review, recommendations usually come as:

Primary — the target architecture we'd want if nothing held us back.
Interim — a step the team can ship now, often "run it as-is on managed compute", that moves toward the primary without blocking delivery.

Where there are several candidate services, I list them in the order to
evaluate, most managed and cheapest first — so the team stops at the first
one that works rather than the first one they know.

The target-state document

Once the team has chosen, they write a target-state architecture document —
the agreed architecture, diagrams and decisions in one place — and get it
approved before the build starts. They come back only when something
significant changes. Store it, versioned, next to everything else in one
predictable place linked to the work item.

Originally published at brianpfeil.com, part of a series of cloud architecture guides drawn from the reviews I run.