# mehdihadeli/awesome-software-architecture architecture

> Architecture diagram of the GitHub repository mehdihadeli/awesome-software-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mehdihadeli/awesome-software-architecture
- Repository: https://github.com/mehdihadeli/awesome-software-architecture

## Overview

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`](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/README.md) (Docs index), [`docs/architectural-design-principles/architectural-design-principles.md`](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/architectural-design-principles/architectural-design-principles.md) (Principles), [`docs/microservices/microservices.md`](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/microservices/microservices.md) (Microservices), [`README.md`](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Root & publishing"]
  node_readme["README<br/>site entry<br/>[README.md]"]
  node_mkdocs["MkDocs<br/>site config<br/>[mkdocs.yml]"]
  node_assets[("Assets<br/>static media")]
end

subgraph group_knowledge["Knowledge taxonomy"]
  node_docs_readme["Docs index<br/>docs landing<br/>[README.md]"]
end

subgraph group_platform["Platform & ops"]
  node_cloud["Cloud<br/>topic cluster<br/>[cloud-native.md]"]
  node_devops["DevOps<br/>topic index<br/>[kubernetes.md]"]
  node_infrastructure["Infrastructure<br/>topic index<br/>[iaas.md]"]
end

subgraph group_distributed["Distributed systems"]
  node_microservices["Microservices<br/>topic index<br/>[microservices.md]"]
  node_messaging["Messaging<br/>topic index<br/>[messaging.md]"]
  node_event_driven["Event driven<br/>topic page"]
  node_consistency["Consistency<br/>topic page"]
end

subgraph group_foundation["Architecture foundations"]
  node_principles["Principles<br/>topic index"]
  node_ddd["DDD<br/>topic index"]
  node_clean["Clean arch<br/>topic page"]
  node_hexagonal["Hexagonal<br/>topic page"]
  node_onion["Onion<br/>topic page"]
  node_modular_monolith["Modular monolith<br/>topic page"]
end

subgraph group_modeling["Modeling & design"]
  node_modeling["Modeling<br/>topic index<br/>[modeling.md]"]
  node_patterns["Patterns<br/>topic cluster<br/>[design-patterns.md]"]
  node_refactoring["Refactoring<br/>topic page<br/>[refactoring.md]"]
end

subgraph group_contrib["Contribution & automation"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
  node_contributing["Contributing<br/>process guide<br/>[contributing.md]"]
end

node_readme -->|"indexes"| node_docs_readme
node_readme -->|"uses"| node_assets
node_readme -->|"published by"| node_mkdocs
node_docs_readme -->|"links"| node_principles
node_docs_readme -->|"links"| node_ddd
node_docs_readme -->|"links"| node_microservices
node_docs_readme -->|"links"| node_messaging
node_docs_readme -->|"links"| node_cloud
node_docs_readme -->|"links"| node_devops
node_docs_readme -->|"links"| node_modeling
node_docs_readme -->|"links"| node_patterns
node_docs_readme -->|"links"| node_refactoring
node_contributing -->|"guides"| node_docs_readme
node_ci -->|"validates"| node_mkdocs
node_ci -->|"checks"| node_docs_readme
node_ci -->|"checks"| node_readme
node_principles -->|"supports"| node_clean
node_principles -->|"supports"| node_hexagonal
node_principles -->|"supports"| node_onion
node_principles -->|"supports"| node_modular_monolith
node_ddd -->|"connects to"| node_event_driven
node_ddd -->|"connects to"| node_consistency
node_microservices -->|"depends on"| node_messaging
node_microservices -->|"depends on"| node_consistency
node_microservices -->|"operates in"| node_cloud
node_messaging -->|"enables"| node_event_driven
node_cloud -->|"implemented with"| node_devops
node_cloud -->|"includes"| node_infrastructure
node_devops -->|"uses"| node_infrastructure
node_modeling -->|"describes"| node_patterns
node_modeling -->|"supports"| node_refactoring

click node_readme "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/README.md"
click node_mkdocs "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/mkdocs.yml"
click node_docs_readme "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/README.md"
click node_assets "https://github.com/mehdihadeli/awesome-software-architecture/tree/main/assets"
click node_ci "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/.github/workflows/ci.yml"
click node_contributing "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/contributing.md"
click node_principles "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/architectural-design-principles/architectural-design-principles.md"
click node_ddd "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/domain-driven-design/domain-driven-design.md"
click node_clean "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/clean-architecture.md"
click node_hexagonal "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/hexagonal-architecture.md"
click node_onion "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/onion-architecture.md"
click node_modular_monolith "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/modular-monolith.md"
click node_microservices "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/microservices/microservices.md"
click node_messaging "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/messaging/messaging.md"
click node_event_driven "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/event-driven-architecture.md"
click node_consistency "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/eventual-consistency.md"
click node_cloud "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/cloud-native.md"
click node_devops "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/devops/kubernetes/kubernetes.md"
click node_infrastructure "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/iaas/iaas.md"
click node_modeling "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/modeling/modeling.md"
click node_patterns "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/design-patterns/design-patterns.md"
click node_refactoring "https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/refactoring.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_mkdocs,node_assets,node_ci,node_contributing toneBlue
class node_docs_readme toneAmber
class node_cloud,node_devops,node_infrastructure toneMint
class node_microservices,node_messaging,node_event_driven,node_consistency toneRose
class node_principles,node_ddd,node_clean,node_hexagonal,node_onion,node_modular_monolith toneIndigo
class node_modeling,node_patterns,node_refactoring toneTeal
```

## Components

### Root & publishing

Top-level entrypoints and site generation

- [README](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/README.md): site entry · Canonical overview and browseable index for the project · `README.md`
- [MkDocs](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/mkdocs.yml): site config · Defines documentation structure and navigation · `mkdocs.yml`
- [Assets](https://github.com/mehdihadeli/awesome-software-architecture/tree/main/assets): static media · Supporting images and visual resources for docs · `assets`

### Knowledge taxonomy

Markdown topic areas under docs/

- [Docs index](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/README.md): docs landing · Top-level documentation landing page · `docs/README.md`

### Platform & ops

Cloud, DevOps, runtime, and infrastructure topics

- [Cloud](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/cloud-native.md): topic cluster · Cloud architecture, Azure, and platform patterns · `docs/cloud-native.md`
- [DevOps](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/devops/kubernetes/kubernetes.md): topic index · Delivery tooling and operational practices · `docs/devops/kubernetes/kubernetes.md`
- [Infrastructure](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/iaas/iaas.md): topic index · IaaS, PaaS, and runtime platform topics · `docs/iaas/iaas.md`

### Distributed systems

Messaging, microservices, and consistency topics

- [Microservices](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/microservices/microservices.md): topic index · Service decomposition and communication patterns · `docs/microservices/microservices.md`
- [Messaging](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/messaging/messaging.md): topic index · Async messaging concepts and technologies · `docs/messaging/messaging.md`
- [Event driven](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/event-driven-architecture.md): topic page · Event-based architecture and integration flows · `docs/event-driven-architecture.md`
- [Consistency](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/eventual-consistency.md): topic page · Eventual consistency and distributed transactions · `docs/eventual-consistency.md`

### Architecture foundations

Core design and domain architecture topics

- [Principles](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/architectural-design-principles/architectural-design-principles.md): topic index · Architectural design principles and guidelines · `docs/architectural-design-principles/architectural-design-principles.md`
- [DDD](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/domain-driven-design/domain-driven-design.md): topic index · Domain-driven design concepts and patterns · `docs/domain-driven-design/domain-driven-design.md`
- [Clean arch](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/clean-architecture.md): topic page · Clean architecture boundary and dependency guidance · `docs/clean-architecture.md`
- [Hexagonal](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/hexagonal-architecture.md): topic page · Ports and adapters architecture · `docs/hexagonal-architecture.md`
- [Onion](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/onion-architecture.md): topic page · Layered domain-centered architecture · `docs/onion-architecture.md`
- [Modular monolith](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/modular-monolith.md): topic page · Modular single-deploy architecture · `docs/modular-monolith.md`

### Modeling & design

Diagrams, modeling, patterns, and refactoring

- [Modeling](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/modeling/modeling.md): topic index · Diagrams and modeling methods for architecture work · `docs/modeling/modeling.md`
- [Patterns](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/design-patterns/design-patterns.md): topic cluster · Design patterns and anti-patterns used across the site · `docs/design-patterns/design-patterns.md`
- [Refactoring](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/refactoring.md): topic page · Code and design improvement practices · `docs/refactoring.md`

### Contribution & automation

Community flow and repository checks

- [CI workflow](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/.github/workflows/ci.yml): automation · Repository workflow that validates the documentation build · `.github/workflows/ci.yml`
- [Contributing](https://github.com/mehdihadeli/awesome-software-architecture/blob/main/contributing.md): process guide · Rules and flow for adding or updating topics · `contributing.md`

## Connections

- 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
