# Architectural Metapatterns is a pattern book that organises by structure, not by name

> Architectural Metapatterns is a free book and wiki by Denys Poltorak that collects architectural patterns and styles, arranges them in an ontology based on structure and function, and compares how different patterns approach the same problems. The repository holds the source, the diagrams and the small publishing tools that turn it into a PDF, an EPUB and a wiki.

**denyspoltorak/metapatterns** — Architectural Metapatterns book and wiki

- Repository: https://github.com/denyspoltorak/metapatterns
- Website: https://metapatterns.io
- Stars: 1,067 · Forks: 74
- Language: Python
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/denyspoltorak-metapatterns

## The repository is the book, not the tool that built it

Architectural Metapatterns is described as a book and wiki, and the README is explicit that the main content of the repository is the book Architectural Metapatterns: The Pattern Language of Software Architecture, written across 2024 to 2026. The primary language is listed as Python, which is misleading until you look at the top level entries, because the Python is in the tools directory and the rest is the book.

The listing shows the actual shape.

```
ArchitecturalMetapatterns/
Half-Proactor-Half-Async.pdf
IntroductionToSoftwareArchitectureWithActors/
LICENSE
README.md
tools/
```

So the substance is in the ArchitecturalMetapatterns directory, and the tools directory holds the small utilities that produced the published artefacts. The Half-Proactor PDF is a separate paper rather than part of the book.

The book is available in three forms. It can be downloaded in PDF or EPUB format from the latest release, read online as a website at metapatterns.io, or read as a wiki hosted in the repository itself. The diagrams and the ODT file are available separately under the CC BY license, with their own LICENSE file inside that directory, which is a meaningful detail because it means the figures and the source document can be reused in a course or an internal document without asking.

The version history is steady. The tags are v1.1 on 2025-07-16, v1.2 on 2026-05-26 and v1.2.1 on 2026-08-31, and the last push to main was on 2026-08-31 as well.

## Five promises, and the ontology is the one that matters

The README lists what the book provides, and the list is worth reading closely because it describes a different thing from a pattern catalogue.

A compendium of architectural patterns and styles. An ontology of patterns based on their structure and function. A brief overview of basic principles of software design. A comparison of ways in which various patterns approach the same problems. A map of evolutions of software architectures.

The second item is the differentiating one. An ontology based on structure and function means the classification is derived from what the patterns do and how they are shaped, rather than from a tradition of naming. Most pattern references group by problem domain, so service oriented patterns sit next to event driven patterns because of the vocabulary of the authors, not because of any shared internal property. An ontology that sorts on structure and function produces a different arrangement, one where two patterns from unrelated traditions can end up adjacent because they solve the same structural problem in the same way.

The fourth item is the one that will save the most reading time. Comparing how various patterns approach the same problems turns a reference into a decision aid. When a design question has four candidate answers, the comparison tells you what each one costs you and what it assumes, which is the information you actually need when you are choosing.

The fifth item, a map of evolutions of software architectures, is the most unusual of the five and the least often attempted. It places patterns in the historical sequence of how architecture practice moved, which is what lets a reader see which patterns are continuations of earlier ideas and which are genuinely new responses to new constraints. The final item, a brief overview of basic principles of software design, is deliberately brief, which signals that the book assumes you already write software and want the architecture level material.

## Three publishing tools that explain how the book is maintained

The Tools section of the README is short, and each entry is more interesting than a utility usually is, because together they describe the author's production pipeline for the book.

The first is a table of contents converter for Leanpub, txt to HTML, in tools/toc_to_html.py. The second is a guide on converting a Google Docs document into an eBook, in tools/Publishing_from_GoogleDoc.md, which is a written guide rather than a program. The third is an ODT to GitHub wiki converter, hosted as a separate project at github.com/denyspoltorak/odt2wiki.

Those three together describe a workflow. The book is written in a word processor, exported as ODT, converted into wiki markup for the GitHub wiki, and a table of contents is generated for the Leanpub edition, which has its own page carrying testimonials and a detailed table of contents.

That last detail matters for anyone evaluating the project. The Leanpub page carries testimonials and a detailed table of contents, alongside the downloadable PDF and EPUB, the website and the wiki.

The presence of a documented publishing guide rather than a script is a reasonable choice, since the messy parts of converting a word processor document into an eBook are decisions rather than transformations, and a person writing them down once is more useful than a script that half works. The tools are also honest about their scope, being described as a converter, a guide and a converter, rather than as an automated publishing pipeline.

## A wiki and a book are two different kinds of reference

The project offers the same material in two very different forms, and they serve different readers.

The website at metapatterns.io is the reading form. The wiki in the repository is the browsing form. A book has an argument and a sequence, so it can develop a position about what a pattern means and where it sits in an architectural history, and that position is lost if you read the entries out of order. A wiki is a set of pages that can be jumped into at any point, which is what you want when a specific question has brought you to the door.

The Medium series is described as the original and outdated version of the same material, and linking it is a good sign about how the author treats the project. Publishing the thing you later replace, and saying plainly that it is outdated, tells a reader where the current text is without pretending the earlier one did not exist. The Introduction to Software Architecture with Actors publication from 2023 and the Half-Proactor paper from 2020 sit in the same category, other writings by the same author that the repository collects under Other Publications.

The introductory slides are also part of the deal. They are available for download inside the ArchitecturalMetapatterns directory, as a Slides subdirectory, and for reading online on Speaker Deck. Slides built from the same source as the book is the right way to use a text that is also a teaching resource.

The practical consequence for a reader is that you can start with the slides to get the shape of the argument, then read the book for the argument, then use the wiki as a lookup while you work. That is three uses of one body of material, and the repository layout supports all three.

## Licensing is split between the book source and the repository

The licence situation needs reading carefully, and it is unusual.

The project's diagrams and the ODT file are available under the CC BY license, with a LICENSE file inside the ArchitecturalMetapatterns directory. That is a permissive licence that allows reuse and modification with attribution, which for a book about architecture is exactly what a teacher, a conference speaker or a company writing internal design guidance wants.

The repository as a whole, however, is listed with a custom licence that GitHub cannot classify, with a LICENSE file at the root. The two are not the same thing, and the difference between CC BY on the diagrams and an unclassifiable licence on the repository is the kind of thing that needs reading rather than assuming.

There is also a link in the README for the original, outdated Medium series, and the Leanpub page for the paid edition. So the material exists in at least four licensing contexts: the repository, the CC BY licensed diagrams and source document, the Leanpub publication, and the earlier Medium posts. Any organisation planning to redistribute figures, adapt chapters for internal training, or quote from the text needs to establish which of those applies to the specific artefact it wants, and the CC BY file covers the figures explicitly while the root LICENSE is where the rest is defined.

This is not legal advice and the README does not summarise the terms. It is a reminder that a repository with multiple licence surfaces needs checking, and that the CC BY grant on the diagram directory is the most permissive part of the project by a wide margin.

## What this project is not

The first limitation is obvious but worth stating. There is no code to adopt. The repository is a book, a wiki, a set of slides, a PDF of an earlier paper and three publishing tools. If the question you are answering is which library to use, or how to implement a pattern, this project is a reading list rather than a dependency, and nothing here ships as a package you can install.

The second limitation is scope. A pattern book is a general vocabulary, and a general vocabulary does not know your constraints. It cannot tell you whether a pattern fits a team of four or a platform team of forty, whether it works with your existing deployment, or what it costs in operations. The comparison chapter helps you understand the trade between patterns, and the map of evolutions helps you see where a pattern came from, but neither substitutes for the context only you have.

The third limitation is freshness. The book is described as spanning 2024 to 2026, and the current tag is v1.2.1 from 2026-08-31. Architecture patterns move slowly, so the age of a pattern description is less damaging than the age of a library description, but the pattern landscape does shift, and a book that stops being updated loses the current tag as a signal of currency even if the content is still sound.

The fourth limitation is that a single author voice is a strength and a weakness. One consistent ontology is what makes the classification usable, and it also means disagreements with other pattern vocabularies are resolved silently rather than argued in the text. A reader coming from Fowler, from the POSA catalogue or from a different school of architecture may find terms used in a way that differs from their habit, and the book does not appear to present the alternatives.

## Conclusion

Architectural Metapatterns fits an architect or senior engineer who wants one vocabulary for a set of patterns that are usually scattered across different books with incompatible naming, and it fits a teacher who needs a CC BY licensed source they can reuse in slides. It does not fit a team looking for implementation code, since the repository is a book, a wiki and three publishing tools, and it does not replace a pattern catalogue scoped to one technology stack. Before adopting it as a reference, read the ontology section rather than the pattern list, because the value is in the classification, and note that the current release is v1.2.1 from 2026-08-31 with the last push on the same day, and that the repository licence is a custom one GitHub cannot classify while the book source is CC BY.

## FAQ

### How do I read Architectural Metapatterns?

The book can be downloaded in PDF or EPUB format from the latest release, read online as a website at metapatterns.io, or read as a wiki hosted in the repository. Introductory slides are available for download inside the ArchitecturalMetapatterns directory or for reading online on Speaker Deck.

### What does the ontology in Architectural Metapatterns add?

The README lists an ontology of patterns based on their structure and function among the things the book provides, alongside a compendium of patterns and styles, a brief overview of design principles, a comparison of how various patterns approach the same problems, and a map of evolutions of software architectures.

### Can I reuse the diagrams from Architectural Metapatterns?

The book's diagrams and ODT file are available under the CC BY license, with a LICENSE file inside the ArchitecturalMetapatterns directory. The repository root carries a separate LICENSE that GitHub cannot classify, so the terms for the rest of the content are defined there rather than in the CC BY file.

### Does Architectural Metapatterns contain any code?

Only in the tools directory, which holds a table of contents converter for Leanpub as a Python script, a guide on converting a Google Docs document into an eBook, and a link to a separate ODT to GitHub wiki converter project. The rest of the repository is the book source, slides and the earlier Half-Proactor paper.

### What is the latest version of Architectural Metapatterns?

The tagged releases are v1.1 on 2025-07-16, v1.2 on 2026-05-26 and v1.2.1 on 2026-08-31, and the last push to main was on 2026-08-31. There is also a Leanpub page with testimonials and a detailed table of contents.

## Sources

- [denyspoltorak/metapatterns on GitHub](https://github.com/denyspoltorak/metapatterns)
- [Issues](https://github.com/denyspoltorak/metapatterns/issues)
- [Project website](https://metapatterns.io)
- [README](https://github.com/denyspoltorak/metapatterns/blob/main/README.md)
- [Releases](https://github.com/denyspoltorak/metapatterns/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/denyspoltorak-metapatterns