How mehdihadeli/awesome-software-architecture works
1. This repository is a documentation-centric knowledge base, not an application runtime. Its core artifact is a curated set of Markdown pages that make up the “Awesome Software Architecture” site, with the public entrypoint advertised as awesome-architecture.com.
2. The main content system lives under docs/. Each folder represents a topic boundary: architecture styles, design principles, cloud, DevOps, messaging, databases, modeling, AI, and related practices. The top-level docs/README.md and category index pages act as landing pages for each topic area.
3. The repository is organized as a taxonomy of architecture knowledge rather than feature code. Major subsystems include:
- foundational architecture topics such as Clean, Hexagonal, Onion, CQRS, DDD, and modular monoliths
- distributed-systems topics such as microservices, messaging, event-driven architecture, eventual consistency, distributed transactions, and locking
- platform/operations topics such as Azure, Kubernetes, Docker, reverse proxies, service discovery, and service mesh
- modeling and design-support topics such as diagrams, principles, patterns, anti-patterns, and refactoring
4. The primary data flow is editorial: contributors write or update Markdown pages in docs/, which are then rendered into a static documentation site. The links and tables in README.md form the browseable index, while mkdocs.yml defines the site structure and navigation.
5. assets/ contains visual/static resources used by the documentation, most notably the banner image referenced in the README. This is a supporting content boundary, not a code execution boundary.
6. .github/workflows/ci.yml provides repository automation. Its role is likely to validate the documentation site build and keep the curated link set consistent. The CI workflow is the main quality gate before changes are merged.
7. The project follows an “index + topic pages” pattern. README.md is the canonical overview and marketing entrypoint, while the deeper information is distributed across smaller topic pages under docs/. That keeps the root page readable and pushes detail into topic-specific boundaries.
8. There is no backend service, API layer, or persistent datastore in the repository. All “state” is the content itself: Markdown text, link tables, and static assets. The architecture is therefore static-site generation and publication, not request/response application logic.
9. The documentation has a strong knowledge-domain separation. For example, cloud patterns and Azure services are kept distinct from DDD and architectural principles, which is useful for diagramming because each topic tree can be modeled as an independent content module with shared navigation.
10. Contribution is part of the system design. contributing.md and the GitHub contribution flow define how new topics are added, which matters architecturally because the repository is intended to scale through community curation rather than code ownership.
11. If you draw an architecture diagram, the key flow is: contributors edit Markdown -> repository stores categorized content -> CI validates the docs build -> MkDocs renders the site -> readers consume the published static documentation site. The main boundary is between source content and generated site output.
Main entry points: docs/README.md Docs index · architectural-design-principles.md Principles · microservices.md Microservices · README.md README
Components 22
Root & publishing
Top-level entrypoints and site generation
Knowledge taxonomy
Markdown topic areas under docs/
- Docs index · Top-level documentation landing page
docs/README.md
Platform & ops
Cloud, DevOps, runtime, and infrastructure topics
- Cloud · Cloud architecture, Azure, and platform patterns
docs/cloud-native.md - DevOps · Delivery tooling and operational practices
docs/devops/kubernetes/kubernetes.md - Infrastructure · IaaS, PaaS, and runtime platform topics
docs/iaas/iaas.md
Distributed systems
Messaging, microservices, and consistency topics
- Microservices · Service decomposition and communication patterns
docs/microservices/microservices.md - Messaging · Async messaging concepts and technologies
docs/messaging/messaging.md - Event driven · Event-based architecture and integration flows
docs/event-driven-architecture.md - Consistency · Eventual consistency and distributed transactions
docs/eventual-consistency.md
Architecture foundations
Core design and domain architecture topics
- Principles · Architectural design principles and guidelines
docs/architectural-design-principles/architectural-design-principles.md - DDD · Domain-driven design concepts and patterns
docs/domain-driven-design/domain-driven-design.md - Clean arch · Clean architecture boundary and dependency guidance
docs/clean-architecture.md - Hexagonal · Ports and adapters architecture
docs/hexagonal-architecture.md - Onion · Layered domain-centered architecture
docs/onion-architecture.md - Modular monolith · Modular single-deploy architecture
docs/modular-monolith.md
Modeling & design
Diagrams, modeling, patterns, and refactoring
- Modeling · Diagrams and modeling methods for architecture work
docs/modeling/modeling.md - Patterns · Design patterns and anti-patterns used across the site
docs/design-patterns/design-patterns.md - Refactoring · Code and design improvement practices
docs/refactoring.md
Contribution & automation
Community flow and repository checks
- CI workflow · Repository workflow that validates the documentation build
.github/workflows/ci.yml - Contributing · Rules and flow for adding or updating topics
contributing.md
Connections 31
- README → Docs index: indexes · Primary browseable documentation entrypoint
- README → Assets: uses · References banner and other static media
- README → MkDocs: published by · Site navigation is defined for the docs build
- Docs index → Principles: links · Landing page routes readers into major topic families
- Docs index → DDD: links · Landing page routes readers into major topic families
- Docs index → Microservices: links · Landing page routes readers into major topic families
- Docs index → Messaging: links · Landing page routes readers into major topic families
- Docs index → Cloud: links · Landing page routes readers into major topic families
- Docs index → DevOps: links · Landing page routes readers into major topic families
- Docs index → Modeling: links · Landing page routes readers into major topic families
- Docs index → Patterns: links · Landing page routes readers into major topic families
- Docs index → Refactoring: links · Landing page routes readers into major topic families
- Contributing → Docs index: guides · Contribution flow adds and updates Markdown topics
- CI workflow → MkDocs: validates · Checks documentation structure and build integrity
- CI workflow → Docs index: checks · Ensures the curated index remains consistent
- CI workflow → README: checks · Ensures the public overview stays consistent
- Principles → Clean arch: supports · Foundational architecture guidance informs core styles
- Principles → Hexagonal: supports · Foundational architecture guidance informs core styles
- Principles → Onion: supports · Foundational architecture guidance informs core styles
- Principles → Modular monolith: supports · Foundational architecture guidance informs core styles
- DDD → Event driven: connects to · Domain concepts inform integration and event boundaries
- DDD → Consistency: connects to · Domain modeling interacts with distributed state changes
- Microservices → Messaging: depends on · Service communication commonly uses async messaging
- Microservices → Consistency: depends on · Service decomposition introduces distributed consistency concerns
- Microservices → Cloud: operates in · Microservices are commonly paired with cloud-native infrastructure
- Messaging → Event driven: enables · Messaging provides the transport for event-driven systems
- Cloud → DevOps: implemented with · Cloud architectures are delivered through deployment and platform tooling
- Cloud → Infrastructure: includes · Cloud topic area spans runtime and provisioning models
- DevOps → Infrastructure: uses · Operational tooling overlaps with IaC and platform setup
- Modeling → Patterns: describes · Modeling pages document structure and reusable design forms
- Modeling → Refactoring: supports · Modeling and refactoring reinforce design evolution