Awesome Architecture · 架构图谱

An open-source knowledge base about architecture — not code. Battle-tested architecture maps of real, popular systems, paired with a tutorial that trains you to think like an architect.

English · 简体中文

🌐 Read online (interactive · bilingual, HTTPS): https://study8677.github.io/awesome-architecture/en/

📚 Community EPUB: Awesome Architecture: 架构图谱 — community learning edition — an unofficial Chinese EPUB prepared by @toby-bridges from this project's Chinese content and independently checked by the project author. It works for offline reading in Apple Books and other EPUB readers; Issue #33 includes the download, checksums, and reproducible build instructions.

🏆 Community attention: On 2026-06-08, this project reached PickGithub #1 on the Vue Trending chart for the day.

🧭 Companion skill: architecture-copilot — turns this knowledge into an interactive skill that guides you through architecture design inside Claude Code / Cursor / Codex.

🤖 Recommended project: AgentCode — turns real development tasks and AI PR review into a practice ground for the engineering delivery skills that matter in the Agent era; the project is currently polishing V0, and PRs and issues are welcome.

---

Why this repo exists

For the past two decades, a programmer's core edge was writing code correctly and fast.

But something is happening right in front of us: "writing code" is disappearing. Not getting harder, not getting scarcer — ending, as a craft that humans do. At frontier labs like OpenAI and Anthropic, almost all code is already written by AI; human engineers no longer type out implementations by hand. They do just two things: tell the AI what to build, then judge whether it got it right. Once a machine spits out working code in seconds, knowing "for vs map, that API, this syntax" — the old craft — is worth nothing overnight.

What isn't depreciating — and is in fact getting more valuable — is a different skill:

Before you write the first line of code, figure out what the system should actually look like.

Where does data come from, where does it go? What must be strongly consistent, what can be eventual? Where will it break first? When users grow from 10K to 100M, what's the first bottleneck? To get A, which B am I willing to give up?

That is architectural thinking. It's independent of language, of framework, even of what's trendy this year. It's the judgment to read the map before you hit the road.

Our belief: the great developer of the future is first a person who makes sound architectural judgments, and only second a person who writes code. Understand what you're building at the architecture level first — code is just one way to make that understanding real.

---

What's inside

awesome-architecture/
├── tutorial/      📚 Tutorial  — systematically teaches you how to *think like an architect*
├── templates/     🗺️ Templates — architecture maps of real systems; architecture only, no syntax
└── cases/         🧪 Cases     — concrete products from zero to launch, then into real pressure

📚 tutorial/ — Become a sharper architect

Not "how to use framework X", but a transferable way of thinking: how to turn a vague requirement into constraints, how to make decisions under trade-offs, how to draw architecture diagrams that actually communicate, and how to design a brand-new system from scratch.

Ch.	Topic	What you'll learn
01	Why architecture-first thinking	Why "architecture first" is the core skill of this era
02	The architect's thinking framework	The universal flow: requirements → constraints → quality attributes → trade-offs
03	Reading & drawing architecture diagrams	Use the C4 model to get the system out of your head and onto paper
04	10 core architecture patterns	Layered, microservices, event-driven, CQRS… what each one actually solves
05	Data & state	Why data is the real hard part of any system
06	Quality attributes & trade-offs	Performance / availability / consistency / cost — how to weigh them
07	Designing a system from 0 to 1	A step-by-step methodology you can actually follow
08	ADRs & evolution	Record decisions with ADRs and let architecture grow with the business
09	Architectural taste	What separates good architects beyond the framework; grow judgment via real cases (microservices→monolith, big-company tastes)

🚀 Advanced track (10–17, new) — taming the hard rock that bites once a system gets big or critical:

Ch.	Topic	What you'll tame
10	Distributed systems: the hard truths	Partial failure, no global clock, the cost of consensus, the exactly-once illusion
11	The engineering of data consistency	Saga, Outbox, idempotency, event sourcing, CQRS
12	Designing for failure: resilience	Cascading failure, circuit breakers, bulkheads, load shedding, SLOs, chaos
13	The mechanics of scale	Consistent hashing, hot keys, multi-region, tail latency & fan-out
14	Evolving & splitting large systems	Strangler fig, parallel run, zero-downtime migration, splitting the monolith
15	Organization as architecture	Conway / inverse Conway, Team Topologies, platform engineering
16	Security & multi-tenancy	Threat modeling, zero trust, blast radius, tenant isolation
17	Architecting in the age of LLMs	Vibe coding, nondeterminism, context engineering, agentic hard parts

🎯 Practice track (18–22) — put the method on real cases; bridge tutorial → templates:

Ch.	Topic	What you'll practice
18	Reading the map: deconstruct unfamiliar systems	Reverse-engineer why a templates/ map is designed that way; practice on RAG / AI chat product
19	Full design walkthrough: medium complexity	Run the ch.07 eight-step flow — design an AI customer-service assistant that looks up orders and issues refunds (with token-cost math)
20	Evolution playbook: MVP → scale	Ch.08 + evolution trigger signals — three life stages of one AI assistant
21	Splitting & migration in practice	Ch.14 as a case: strangler, branch by abstraction, shadow traffic, zero-downtime vector-store swap
22	AI-native system design	Upgrade the assistant into an autonomous Agent; land ch.17's three new constraints; bridge to the AI-collab track

🤝 AI-collaborative design track (23–26) — collaborate with AI without losing judgment:

Ch.	Topic	What you'll master
23	Spec as architecture: constraints for AI	ADR / AGENTS.md → enforceable guardrails; pairs with architecture-copilot
24	Review checklist: what AI output omits by default	Production-grade review checklist from ch.11/12/16
25	Eval-driven: bake "good enough" into architecture	Eval as a CI gate for nondeterministic systems
26	Collaboration decision tree: when to vibe, when to spec-first	Prototype vs production workflow — the capstone

🧰 Technology stack selection track (27–34) — turn "what tech to use" into architecture judgment:

Ch.	Topic	What you'll judge
27	Languages & backend frameworks	How language/framework affects runtime, ecosystem, team, and maintenance cost
28	Databases & storage	How source of truth, read models, search, object storage, and vector stores divide work
29	Cache, queues & events	What fits read hotspots, spike smoothing, and fact broadcast
30	APIs & service communication	REST / gRPC / GraphQL / Webhook boundaries
31	Cloud native & deployment	When PaaS, containers, Serverless, or K8s are worth it
32	Observability & reliability	Work backward from SLOs to metrics, logs, traces, alerts, incidents
33	AI infrastructure	When model API, RAG, vector DB, inference serving, and evals should upgrade
34	Technology selection decision tree	Turn stage, failure mode, team capability, and exit plan into an ADR

🧠 Foundation Model Training Decisions (T01–, bilingual) — separate from the numbered Chapters 01–40:

Ch.	Topic	What you'll judge
T01	Training Plans Are Not an Algorithm Leaderboard: Layer the Decision First	Start from goals, tasks, data, and learning signals to judge when SFT, DPO, PPO, or GRPO fits—and what system costs follow

👉 New here? Start with en/tutorial/README.md for the full learning path.

🧪 cases/ — Turn architecture from answer into reasoning

cases/ is not more templates. It walks a concrete product from zero to launch, then into real pressure. It fills the final gap between tutorial/ and templates/: templates tell you what this class of system usually looks like; cases show why one concrete scenario forces these trade-offs.

The first batch of six core cases is complete:

Case	Capability area	What it drills
01 · StarArena: concert ticketing	Online ticketing / e-commerce / payment	Limited inventory, virtual waiting room, seat locking, payment state machine, reconciliation
02 · PatchDesk: lightweight ticketing SaaS	Standard Web / SaaS backend	Modular monolith, tenant isolation, RBAC, Outbox, async notifications, search/report evolution
03 · DocuMind: enterprise RAG knowledge base	RAG / AI chat / vector database	Ingestion, chunking, hybrid retrieval, Graph RAG, reranking, citations, permissions, prompt injection, evals
04 · SyncRoom: realtime collaboration workspace	Realtime chat / collaborative docs / notifications	Long connections, server seq, offline catch-up, multi-device sync, OT / CRDT, presence, notification degradation
05 · FeedStream: content distribution	Social feed / video / search	Hybrid fanout, top creator fanout, timeline inboxes, ranking, search indexes, transcoding, CDN, moderation recall
06 · CodePilot: coding Agent platform	AI Agent / Codex / Claude Code	Tool calls, permission gateway, sandboxing, human approval, context compaction, checkpoints, subagents, trace, eval gates

👉 See en/cases/README.md for the case overview. The reading rule: do not memorize diagrams; watch why the starting architecture was reasonable, which quantified signal forced an upgrade, and what the new design chose and gave up.

🗺️ templates/ — Architecture maps of real systems

Each template is an "architecture map". We deliberately avoid discussing language or framework — only: what problem this class of system solves, what parts it's made of, how data flows, how the key trade-offs are made, and where it dies at scale.

Classic / general systems

Template	Representative products	Key architecture themes
AI Chat Product	Claude, ChatGPT	LLM inference, streaming, context management, RAG, cost control
Browser Extension	Honey, Grammarly	Content/background split, page injection, privacy boundaries, monetization
Standard Web App	Corporate sites, blogs, SaaS dashboards	Classic three-tier, caching, read/write splitting — "good enough"
Mobile App	Most iOS/Android apps	Offline-first, data sync, client state, push
E-commerce Platform	Amazon, Shopify, Taobao	Inventory, orders, payments, overselling, traffic spikes
Social Feed	Twitter/X, Instagram	Feed push/pull, follow graph, viral fan-out
Video Streaming	Netflix, YouTube	Transcoding, CDN, adaptive bitrate, recommendations
Realtime Chat	WhatsApp, Slack, WeChat	Long-lived connections, message ordering, offline delivery, group fan-out
URL Shortener	Bitly, TinyURL, t.co	Read-heavy, caching, 301/302, distributed unique IDs
Payment System	Stripe, Alipay, PayPal	Idempotency, double-entry ledger, reconciliation, state machine
Search Engine	Google, Elasticsearch	Inverted index, relevance ranking, recall + rerank, sharding
Ride-Hailing	Uber, Lyft, DiDi	Geospatial index, real-time location, supply–demand matching
Collaborative Doc	Google Docs, Figma	OT/CRDT, single-writer serialization, operation log
Cloud Storage	Dropbox, iCloud	Chunking, content-addressed dedup, incremental sync
Notification System	Novu, FCM/APNs	Multi-channel fan-out, dedup/throttling, async retry
Online Ticketing	Ticketmaster, 12306	Virtual waiting room, atomic stock decrement, seat-lock TTL

🤖 AI-native systems (new)

Template	Representative products / prototypes	Key architecture themes
AI Gateway / Relay	One API, LiteLLM, Portkey	Unified API, billing & rate-limit, load balancing, caching
RAG Knowledge Base	RAGFlow, LlamaIndex, Dify	Chunking, vector retrieval, hybrid search + rerank, citations
AI Agent / Workflow	Dify, Coze, LangGraph	Action loop, tool sandbox, memory, guardrails
Inference Serving	vLLM, SGLang, Triton	Continuous batching, paged KV cache, quantization
Vector Database	Milvus, Qdrant, pgvector	ANN, HNSW/IVF, recall–latency trade-off

🦾 AI Coding & Autonomous Agents (new — real, in-the-wild agent product architectures)

Template	Representative products / prototypes	Key architecture themes
Claude Code	Claude Code (Anthropic)	Local-first coding agent; subagents/hooks/skills/MCP; two-tier permissions + OS sandbox; context compaction
OpenAI Codex	Codex CLI + Cloud	Local CLI & cloud async sandbox; sandbox × approval axes; offline-by-default anti-injection; opens PRs
OpenClaw (the lobster 🦞)	OpenClaw (formerly Clawdbot)	Self-hosted gateway; chat apps as the UI; heartbeat/cron; pluggable harness; memory as plain text
Hermes	Hermes (Nous Research)	Always-on & self-growing; FTS5 persistent memory; auto-distilled skills; cron; multi-channel/provider

🏭 Industrial / Embedded systems (new — where software bugs become physical-world consequences)

Template	Representative products / prototypes	Key architecture themes
Embedded Device Firmware	Smart locks, wearables; Zephyr, FreeRTOS	HAL layering, state machines, watchdog, A/B dual-bank OTA
IoT Device Platform	AWS IoT Core, Tuya; ThingsBoard, EMQX	Millions of long-lived connections, per-device identity, device shadow, staged OTA
Industrial Edge / SCADA	Factory data acquisition; EdgeX, OPC UA	Protocol normalization, edge autonomy, OT/IT isolation (Purdue), gated reverse control
Automotive E/E	Tesla-style central compute; openpilot, AUTOSAR	ASIL isolation, CAN + automotive Ethernet, whole-vehicle OTA, shadow mode
Robotics System	Vacuums, AGVs, drones; ROS 2, PX4	Sense→plan→act frequency layering, independent safety loop, record & replay, fleet ops

📜 System Prompt Architecture

Template	Representative products / prototypes	Key architecture themes
System Prompt Architecture	Claude Fable 5, ChatGPT, Gemini, Grok, Cursor	Layered Agent OS, decision-tree routing, externalized Skills, compliance hard rules, runtime injection

👉 Want to add your own template? Follow the unified format in templates/_TEMPLATE.md.

📝 English translation coverage — 34 of 40 tutorial chapters, all 31 templates, and the first 6 cases are available in English. Use the language switch (top-right on the site), or browse en/ in the repo.

---

How to use this repo

If you're a beginner / shifting toward architectural thinking: Read tutorial/ in order. After each chapter, pick a system in templates/ you find interesting and try to "read" it using the framework you just learned. After chapter 07, start using cases/ for complete product walkthroughs.

If you're about to design a new system: Start with tutorial/07 for the methodology, then find the map closest to your scenario in templates/. Treat it as a starting point, not an answer — walk through its "key decisions" and "common pitfalls" and ask yourself each one. If your scenario resembles one of the first-batch cases, compare against the full reasoning in cases/.

If you're prepping for system design interviews: Every template covers high-frequency topics (overselling, feed fan-out, message ordering, streaming output…), all in a consistent format — great for systematic review. cases/ is better for practicing a complete answer from requirements to trade-offs.

If you're a senior engineer / architect: Jump straight to each template's "Key Decisions & Trade-offs" and "Evolution Path" — the most concentrated parts. PRs sharing the scars you've earned are welcome.

---

Three reading principles

1. Ask "why" before "how". Every architecture choice sits on top of a constraint or a trade-off. If you can't see the trade-off, you haven't understood it.
2. There is no best architecture, only the most fitting one. "Chat" for an internal tool and "chat" for WeChat are worlds apart. Scale, team, cost, and compliance decide everything.
3. Architecture grows. Don't force a mature-stage architecture onto an MVP. Every template includes an "evolution path" telling you when to upgrade — and when you're over-engineering.

---

The one-sentence version

Code tells the computer what to do; architecture decides whether the thing is worth doing, can be done, and will hold up. This repo trains you for the second kind of judgment.

---

🤝 Core Contributors & Community Acknowledgements

• @h13181278389 — core contributor. Thank you for supporting Awesome Architecture and helping it keep improving.
• @flyw1015 — core contributor. Thank you for supporting Awesome Architecture and helping it keep improving.
• @toby-bridges — thank you for turning the project's Chinese content into an unofficial Apple Books-compatible EPUB community edition, complete with reproducible build tools, checksums, and device verification that make the material easier to read offline.

---

Contributing

Contributions are welcome — new templates, fixes, and especially English translations of the tutorial and existing templates.

1. Copy templates/_TEMPLATE.md into a new folder, e.g. templates/your-system/README.md.
2. Fill in all 14 sections (including real reference-prototype links) and stay strictly at the architecture level — the moment you start writing "use library YY in language XX", stop and ask: is this an architecture decision, or an implementation detail?
3. Draw diagrams in ASCII (plain text, viewable everywhere, never breaks).
4. Add a row to the template list.

The bar: an engineer who has never touched this domain can, after reading your template, explain "why this class of system is designed this way, and where it dies".

---

⭐ Star History

If this repo helped you, a Star is the best encouragement.

---

🔗 Friends

• LINUX DO — "Where possible begins." A new ideal-type community for developers who love tech and sharing.