awesome-software-design

Awesome Software Design

The discipline of organizing and structuring software at the code and component level.

Contents

• Implementation Patterns & Reference Code
• API & Interface Design
• Decision Records (ADR/RFC)
• Documentation as Code
• Architecture Verification (CI Rules / Fitness Functions)
• Operational Case Studies (Curated, Short)
• Books
• Community

Implementation Patterns & Reference Code

• ThreeDotsLabs/watermill - Go library for building event-driven applications with Pub/Sub, CQRS, and middleware support.
• ThreeDotsLabs/wild-workouts-go-ddd-example - Production-ready Go example combining Clean Architecture, CQRS, and gRPC with detailed blog series.
• CodelyTV/php-ddd-example - PHP DDD skeleton with Hexagonal Architecture, CQRS, and event bus using Symfony.
• Microservices Patterns - Chris Richardson’s comprehensive catalog of microservice patterns including Saga, API Gateway, and CQRS.
• patchlevel/event-sourcing - Modern PHP Event Sourcing library with snapshots, projections, and Doctrine integration.
• Event Modeling - Visual method for designing event-driven systems with a timeline of commands, events, and views.
• ddd-crew/ddd-starter-modelling-process - Step-by-step DDD modelling process guide from discovery to bounded context design.

Design Patterns

• Refactoring.Guru - Visual catalog of all 23 GoF patterns with UML diagrams and code in 10+ languages.
• DesignPatternsPHP - All known design patterns in PHP 8.1+ with real-world examples, UML diagrams, and tests.
• kamranahmedse/design-patterns-for-humans - Guide explaining design patterns with real-world analogies, not academic jargon.
• iluwatar/java-design-patterns - Collection of GoF, enterprise, and architectural patterns implemented in Java.
• Source Making — Design Patterns - Comprehensive reference with UML diagrams, code examples, and anti-pattern explanations.
• Christopher Okhravi — Design Patterns - Video series walking through each GoF pattern with clear explanations and real-world context.
• faif/python-patterns - Collection of design patterns and idioms implemented in Python with concise examples.

API & Interface Design

• API Design Guide by Google - Google’s resource-oriented API design standard used across all Google Cloud APIs.
• Microsoft REST API Guidelines - Microsoft’s battle-tested guidelines for consistent, developer-friendly RESTful APIs.
• Use The Index, Luke - In-depth SQL indexing guide teaching developers how databases execute queries efficiently.

Decision Records (ADR/RFC)

• joelparkerhenderson/architecture-decision-record - Collection of ADR templates, examples, and best practices from real projects.
• adr/madr - Markdown Any Decision Records — lean template capturing context, decision, and consequences.
• Documenting Architecture Decisions - Michael Nygard’s original blog post that started the ADR movement and defined the format.
• adr.github.io - Central hub of the ADR GitHub organization aggregating tools, templates, and examples.
• log4brains - Docs-as-code knowledge base that auto-generates a searchable static site from ADR files.
• adr/e-adr - Embedded Architectural Decision Records for capturing decisions directly in source code.
• adr/adr-manager - Web-based interface for creating, editing, and managing Architecture Decision Records.
• phodal/adr - Lightweight CLI tool for managing ADRs with reporting and visualization support.
• Kubernetes KEPs - Real-world architecture decision process at scale — Kubernetes Enhancement Proposals.
• Spotify ADR Practice - Spotify engineering on when, why, and how to write effective ADRs.
• GOV.UK RFCs - UK Government Digital Service architecture decisions — excellent public sector ADR example.
• GitHub Actions Toolkit ADRs - Architecture Decision Records from GitHub’s official Actions toolkit.
• Rust RFCs - Rust language design decisions captured as RFCs — one of the best public RFC processes.
• Next.js RFCs - Vercel’s public RFC discussions for Next.js architectural changes and new features.
• Flutter Design Docs - Flutter’s public design document process for major architectural decisions.

Documentation as Code

• C4 Model - Simon Brown’s four-level model (Context, Container, Component, Code) for architecture visualization.
• D2 Language - Modern declarative diagramming language with auto-layout that compiles to SVG and PNG.
• Mermaid - JavaScript diagramming tool rendering flowcharts, sequence diagrams from Markdown syntax.
• Diagrams as Code - Draw AWS, Azure, GCP, and Kubernetes architecture diagrams in Python with provider icons.
• dependency-cruiser - Validate and visualize JavaScript/TypeScript module dependencies against architecture rules.
• Ilograph - Interactive architecture diagrams with multi-perspective views and drill-down navigation.
• Terrastruct - Commercial platform for creating interactive architecture diagrams powered by D2.
• Structurizr - Official C4 tooling by Simon Brown: architecture-as-code via DSL with interactive, zoomable diagrams.
• PlantUML - Widely-adopted diagrams-as-code tool for UML/C4 and architecture visuals with strong IDE and CI integration.

Architecture Verification (CI Rules / Fitness Functions)

• TNG/ArchUnit - Industry-standard Java library for checking architecture constraints as unit tests.
• TNG/ArchUnitNET - C# port of ArchUnit for enforcing architecture rules in .NET projects.
• LukasNiessen/ArchUnitTS - TypeScript port of ArchUnit for enforcing architecture rules with CI integration.
• phparkitect/arkitect - Define PHP architecture rules with expressive DSL — enforce layer dependencies in CI.
• pestphp/pest-plugin-arch - Fluent architecture testing for Laravel/Pest — expect()->toUseNothing() style assertions.
• LemonAppDev/konsist - Kotlin architecture linter enforcing coding conventions, project structure, and dependency rules.
• arch-go/arch-go - Architecture testing for Go with configurable rule sets for dependencies, naming, and layering constraints.
• roblaszczak/go-cleanarch - Go validator enforcing Clean Architecture dependency rules across packages.
• tach-org/tach - Rust-powered Python tool for enforcing module boundaries and dependencies with zero runtime cost.
• Shopify/packwerk - Ruby package boundary enforcement tool, production-proven at Shopify scale.
• dependency-cruiser - JavaScript/TypeScript module dependency validation against configurable architecture rules.
• Fitness Function-Driven Development - ThoughtWorks article on using automated fitness functions to guide architecture evolution.

Operational Case Studies (Curated, Short)

• Figma Multiplayer Architecture - How Figma built real-time collaboration with CRDTs and operational transforms.
• Slack Real-Time Messaging - How Slack built Flannel, an edge cache handling millions of concurrent WebSocket connections.
• Discord Architecture - How Discord migrated from Cassandra to ScyllaDB to store trillions of messages.
• Shopify Modular Monolith - How Shopify deconstructed their monolith into components while staying on a single deployment.
• Cloudflare Workers Architecture - How Cloudflare built Pingora, their custom Rust proxy replacing Nginx.
• GitHub Moving to Microservices - How GitHub re-architected push processing for better reliability and performance.
• Stripe’s Approach to API Design - How Stripe designs backward-compatible APIs at scale with versioning and careful evolution.
• Spotify System Model - How Spotify visualizes 2000+ microservices using Backstage and the C4 model.
• Linear Sync Engine - How Linear built and scaled their real-time sync engine for collaborative project management.
• Notion Postgres Sharding - How Notion horizontally sharded PostgreSQL to handle rapid growth at scale.

Books

• Domain-Driven Design — Eric Evans - The foundational “Blue Book” defining ubiquitous language, bounded contexts, and strategic design.
• Implementing Domain-Driven Design — Vaughn Vernon - Practical “Red Book” bridging DDD theory to working code with Aggregates and Event Sourcing.
• Learning Domain-Driven Design — Vlad Khononov - Modern, accessible DDD introduction connecting strategic and tactical patterns to real projects.
• Clean Architecture — Robert C. Martin - Principles for structuring software so business rules remain independent of frameworks and databases.
• Designing Data-Intensive Applications — Martin Kleppmann - Essential deep dive into distributed systems, replication, partitioning, and stream processing.
• Building Microservices — Sam Newman - Comprehensive guide to microservice decomposition, communication, and deployment strategies.
• Patterns of Enterprise Application Architecture — Martin Fowler - Classic catalog of enterprise patterns (Unit of Work, Repository, Data Mapper) still relevant today.
• Software Architecture: The Hard Parts — Neal Ford et al. - Decision framework for distributed architecture trade-offs like data ownership and service granularity.
• A Philosophy of Software Design — John Ousterhout - Concise guide to reducing complexity through deep modules and strategic interface design.
• Architecture Patterns with Python — Percival & Gregory - Hands-on DDD, event-driven architecture, and TDD patterns applied in Python with working code.
• Release It! (2nd Edition) — Michael T. Nygard - Stability patterns (circuit breakers, bulkheads) and anti-patterns for designing production-ready distributed systems.
• Team Topologies — Matthew Skelton & Manuel Pais - Practical application of Conway’s Law: team interaction modes, stream-aligned teams, platform teams, and cognitive load.
• Balancing Coupling in Software Design — Vlad Khononov - Three-dimensional coupling model (strength, distance, volatility) with practical guidance for controlling dependencies.

Community

• Software Architecture Monday - Mark Richards’ weekly YouTube series breaking down architecture concepts in 10-minute episodes.
• Martin Fowler’s Blog - Decades of essential writing on refactoring, microservices, and enterprise architecture patterns.
• InfoQ — Architecture & Design - Curated articles, conference talks, and trend reports on software architecture.
• Technology Radar - ThoughtWorks’ quarterly opinionated guide to emerging tools, techniques, and platforms.
• DDD Europe - Premier European conference on Domain-Driven Design with workshops and keynotes.
• QCon - International conference featuring practitioner talks on architecture and engineering culture.
• GOTO Conferences - Conference series with talks from industry leaders on modern software development practices.
• Software Architecture subreddit - Active Reddit community for discussing architecture patterns, trade-offs, and career advice.

Contributing

Contributions welcome! Read the contribution guidelines first.