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 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 |
👉 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 |
📜 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.
📝 Now fully bilingual — all 34 tutorial chapters, 26 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
- 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.
- 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.
- 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 Contributor
- @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.
Contributing
Contributions are welcome — new templates, fixes, and especially English translations of the tutorial and existing templates.
- Copy
templates/_TEMPLATE.mdinto a new folder, e.g.templates/your-system/README.md. - 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?
- Draw diagrams in ASCII (plain text, viewable everywhere, never breaks).
- 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.
💬 评论