A master level reference for software patterns. Every entry is written from primary sources, carries eighteen mandatory dimensions, and cites every claim.
There is no documentation site yet (no rendered docs build to badge). Tracked
as an open item in docs/GOVERNANCE-AUDIT-2026-08-03.md.
Say you are adding a long running upload to a product. The obvious version takes ten minutes to write. The request comes in, the file uploads, a response goes out. Then the real questions show up. Does the upload run synchronous inside the request, or does it hand off to a queue. If it hands off, does the queue guarantee at least once delivery or exactly once. If it is at least once, what happens the second time the same file arrives. Does a crashed worker lose the upload or retry it. Does a retry double charge a customer if the next step is billing. Who logs the failure, and what gets paged. What happens to an in flight upload during a deploy.
None of that is exotic. It is the normal shape of a real system, and every one of those questions already has a name, a set of known answers, and a set of known failure modes, worked out by people who hit them first and wrote down what they learned. That is what a pattern is here. Not a UML diagram. A worked answer to a question you are about to hit anyway.
Think of it as a decision book, not a code library. You do not copy code out of it. You read the entry for the situation you are in, see the trade offs laid out, and make the call yourself, or hand the entry to your coding agent so it makes the call with real information instead of a guess.
Take Circuit Breaker as a worked example. You describe the problem in plain words. Our API becomes slow when traffic increases and a dependency starts failing. The entry for Circuit Breaker lays out when it fits, what it costs, what it does not solve on its own, and what it is usually paired with. You read it, and either use it, or explicitly decide not to and know why.
The three step shape above is the whole loop. Describe the problem in your own words, not the pattern name. Pull up two or three relevant entries and compare them side by side, including the ones this repository recommends against for your case. Decide, write the decision down somewhere your team or your AI assistant will see it again, then implement.
If code is not your job, you can still use this repository to ask better questions of the people or the AI building something for you. Five common starting points.
- Wondering if a plan for a new system is missing something. Start at docs/BY-PROBLEM.md and look for the situation that matches what you are building.
- Concerned about cost or reliability of something running in the cloud. Read patterns/08-cloud-distributed/.
- Curious what an AI agent or chatbot should and should not be allowed to do on its own. Read patterns/17-ai-agentic/.
- Told that a codebase is a mess and needs a rewrite. Read patterns/02-code-smells/ and patterns/03-refactoring/ before agreeing to a rewrite. Most messes have a named smell and a smaller named fix.
- Handling anything that touches money, health, or identity. Read patterns/15-security/.
- Asking whether a launch is actually ready. Read patterns/21-sre-operations/ and patterns/22-observability/.
You do not need to understand every dimension of an entry to get value from it. The applicability section, what it is for and what it is not for, and the trade off table are usually enough to make a call.
Five concrete ways people and their AI assistants use this repository.
- Plan before writing code. Describe the system you are about to build and ask your assistant to check the relevant families here before it proposes an architecture.
- Review a proposed architecture. Paste a design doc or a plan and ask what pattern it is really describing, what it is missing, and what named failure mode it is exposed to.
- Use it while coding. When you hit a decision mid implementation (retry logic, a cache, an event shape) look up the entry instead of guessing from memory.
- Challenge AI generated architecture. When an agent proposes a design, ask it to name the pattern, cite the entry, and state the trade offs before you accept the plan.
- Turn it into a standing instruction. Add this repository to your agent's rule file so it is consulted automatically, every time, not only when you remember to ask.
A short instruction that works in AGENTS.md, CLAUDE.md, a Cursor rule, or
.github/copilot-instructions.md.
# Patterns decision reference
[](https://openroots.org/licenses/ora/2.3)
Before proposing an architecture, a retry strategy, a data flow, or a fix
for a design smell, consult .patterns/docs/BY-PROBLEM.md and the relevant
family under .patterns/patterns/ for the named pattern that covers this
situation. State which pattern you are applying, why it fits this specific
case, and what it costs. If nothing in the reference fits, say so plainly
and proceed on your own judgment.
Patterns are decision options, not mandatory implementation rules. Do not
use a pattern simply because it exists. Do not over-engineer simple
problems.
Before building a new application. The value is not more code. It is making the important decisions before the code exists. Describe the goal, consult the relevant entries, compare the candidates, approve a plan, then build.
On an existing application that already works. Patterns become a review lens instead of a starting point. Show your assistant the app, ask it to compare the current design against the entries here, and pick the smallest safe change instead of a large risky one.
Inside a coding agent, as a standing habit. The difference between an
agent that only reacts to what you type and one that thinks before it
builds is whether it has a shared playbook to consult. Wiring this
repository into an agent's rule file, per the AGENTS.md example above, is
what makes that automatic.
The same loop applies to a single feature inside an app that is already shipped and working. Say what feels wrong in plain words, let the assistant check this repository for a safer version of what you already have, and add the improvement in small, tested steps rather than a large rewrite.
Patterns fits into the middle of the path from an idea to something running in production. It does not replace requirements work or testing. It is the step where a vague direction becomes a compared, defensible decision.
idea
-> requirements
-> problems and constraints
-> candidate approaches <- Patterns
-> compare trade offs <- Patterns
-> reject the weak ones <- Patterns
-> decision
-> plan
-> code
-> tests
-> observability
-> production
-> review
Worked example. A team needs a feature that lets a user upload a large file and get notified when processing finishes. Without a reference, the first working version is often a synchronous request that blocks until the file is fully processed, which times out under load. With this repository, the team compares an asynchronous request reply pattern against an event driven pipeline, reads the failure modes and idempotency requirements for each, and picks the one that matches their actual traffic and their actual tolerance for a duplicate notification.
An LLM can describe Circuit Breaker from memory. What it cannot do reliably, on its own, is cite a specific named production use with a real source, list the trade offs against the alternatives your team actually considered, or admit plainly when a pattern does not apply. Every entry here is checked for exactly that. A citation that does not resolve fails CI. A missing non-applicability list fails CI. The value is not the definition. It is the parts a model tends to skip or invent.
A reference you can hand to a staff engineer and have them find something they did not know. Not a tutorial. Not an overview. Not a set of one paragraph summaries with a UML picture.
Most pattern catalogues answer one question. What is this pattern. This one answers the eighteen questions an engineer actually has when they are deciding whether to use it, how it will fail, what it costs, how to test it, how to see it in production, and how to remove it later.
Every entry carries all eighteen dimensions. An entry missing one is not
merged. This is checked mechanically by tools/check-structure.py in CI, not
by good intentions.
| # | Dimension | The question it answers |
|---|---|---|
| 1 | Name, aliases, lineage | What is it called, by whom, since when |
| 2 | Problem and context | What situation creates the need |
| 3 | Forces | Which pressures it balances and which it sacrifices |
| 4 | Applicability and non-applicability | When to reach for it, and when NOT to |
| 5 | Structure | Participants, responsibilities, relationships |
| 6 | ASCII structure diagram | The shape, readable in a terminal |
| 7 | Dynamics | How the parts interact at runtime |
| 8 | Implementation variants | The real ways it gets built |
| 9 | Known production uses | Named systems, with sources |
| 10 | Consequences | The good and the cost, both listed |
| 11 | Failure modes and misuse | How it breaks, and how people get it wrong |
| 12 | Trade-off matrix | How it compares to named alternatives |
| 13 | Related and incompatible patterns | What composes, what conflicts |
| 14 | Refactoring path in and out | How to adopt it, and how to leave |
| 15 | Testing and verification | What got easier to test, what got harder |
| 16 | Observability signals | What to log, trace, and measure |
| 17 | Security and privacy | What surface it opens or closes |
| 18 | References | Every claim, independently checkable |
Dimension 4's second list and dimension 11 are the ones most catalogues skip. They are the reason this repository exists.
Eight of the eighteen dimensions above, shown one at a time. Every image in
this repository lives under assets/images/, named for what it shows, and
each one below illustrates a different dimension. None repeats another.
The status words below mean exactly one thing each, and every count in this
README is generated from repository state by tools/gen-catalogue-status.py,
never hand-typed. See docs/PROGRESS.md and dist/catalogue-status.json for
the live, machine-readable numbers.
| Term | Meaning | Enforced by |
|---|---|---|
| Published | A file exists in patterns/ and passes every CI gate |
tools/check-structure.py |
| Planned | Named in docs/AUTHORING-QUEUE.json, not yet on disk |
tools/next-batch.py |
| Total catalogue scope | Published plus planned, tracked in docs/SCOPE-TARGET.json |
manual reconciliation, see that file |
| canonical / established / emerging / contested / deprecated | Per-entry epistemic maturity, declared in frontmatter | tools/check-structure.py |
Draft, in-review, and superseded are not yet modelled by the tooling. They
are open work, listed in docs/GOVERNANCE-AUDIT-2026-08-03.md, and this
README does not claim they are implemented.
This table is the source of truth for family folder names under patterns/.
A folder's slug always matches the slug linked here, enforced in CI. See
docs/FAMILY-NAMING.md.
| # | Family | Origin | Published | Planned | Target |
|---|---|---|---|---|---|
| 01 | Design Patterns (GoF) | Gamma, Helm, Johnson, Vlissides 1994 | 33 | 0 | 33 |
| 02 | Code Smells | Fowler and Beck, Refactoring | 28 | 0 | 28 |
| 03 | Refactoring Techniques | Fowler, Refactoring 2nd ed | 66 | 0 | 66 |
| 04 | Principles and Laws | Martin, Larman, Brewer, Conway | 42 | 0 | 42 |
| 05 | Architectural Patterns | Buschmann POSA 1, Bass SEI | 31 | 0 | 31 |
| 06 | Enterprise Application Architecture | Fowler, PoEAA | 60 | 0 | 60 |
| 07 | Enterprise Integration | Hohpe and Woolf | 54 | 0 | 54 |
| 08 | Cloud and Distributed | Azure Architecture Center | 44 | 0 | 44 |
| 09 | Concurrency and Parallelism | Schmidt POSA 2 | 40 | 0 | 40 |
| 10 | Microservices | Richardson | 49 | 0 | 49 |
| 11 | Domain-Driven Design | Evans, Vernon | 35 | 0 | 35 |
| 12 | Data and Storage | Kleppmann | 45 | 0 | 45 |
| 13 | Frontend and UI | Framework documentation | 34 | 0 | 34 |
| 14 | Testing | Meszaros, xUnit Test Patterns | 30 | 0 | 30 |
| 15 | Security | OWASP ASVS | 38 | 0 | 38 |
| 16 | Functional Programming | Category theory in practice | 39 | 0 | 39 |
| 17 | AI and Agentic | Papers and vendor engineering, 2023 to 2026 | 65 | 0 | 65 |
| 18 | Anti-Patterns | Brown et al, AntiPatterns | 51 | 0 | 51 |
| 19 | API and Interface Design | REST, GraphQL, gRPC specifications | 11 | 0 | 11 |
| 20 | Release and Deployment | Humble and Farley | 10 | 0 | 10 |
| 21 | SRE and Operations | Google SRE, AWS Well-Architected | 12 | 0 | 12 |
| 22 | Observability | OpenTelemetry, RED and USE methods | 7 | 0 | 7 |
| 23 | Workflow and Orchestration | Durable execution literature | 6 | 0 | 6 |
| 24 | Stream Processing | Dataflow model, Kafka docs | 7 | 0 | 7 |
| 25 | MLOps | Google ML design patterns | 9 | 0 | 9 |
| 26 | Interaction and HCI | Tidwell, Designing Interfaces | 10 | 0 | 10 |
| 27 | Mobile Architecture | Official Android/iOS architecture guidance | 11 | 0 | 11 |
| 28 | Embedded and Hardware-Software | Embedded systems engineering literature | 14 | 0 | 14 |
| 29 | Real-Time Simulation | Nystrom, Game Programming Patterns | 9 | 0 | 9 |
Family 04 is named Principles and Laws rather than patterns, because SOLID, CAP, and Conway's Law are principles and laws, not patterns. They live here because a reference without them has a hole, and they are marked as what they are.
By problem. Start at docs/BY-PROBLEM.md. It maps symptoms you can observe in a codebase to the patterns that address them.
By family. Pick a family above. Each family has an index with a one line summary per entry.
By language. docs/BY-LANGUAGE.md lists which patterns change shape in which language, and which ones a language makes unnecessary.
By maturity. Every entry declares canonical, established, emerging,
contested, or deprecated in its frontmatter. Emerging and contested entries
state plainly what is unsettled.
Every word here is original. Patterns are ideas that belong to the people who found and named them, and those people are credited in every entry and in ATTRIBUTION.md.
No text, diagram, or code sample is copied from any pattern catalogue. Where an existing catalogue was consulted, it was consulted as a checklist of what a reader would expect to find, never as a source of prose. This is stated in full in ATTRIBUTION.md along with the licence terms of every catalogue involved.
If you hold rights in anything here and believe it goes past fair citation,
open an issue titled attribution and it will be corrected or removed.
Every diagram in this README lives under assets/images/, named for what
it shows. Fourteen appear inline above. Four more were produced covering the
same three usage scenarios (a new application, an existing application, and
an application already shipped) in a different visual style. Rather than
show the same scenario twice, only the version paired with a without and
with comparison is shown. The other four are kept in assets/images/ for
reference and are not repeated in the body, so no scenario appears twice.
Every file is stored as lossless WebP rather than PNG, roughly a third smaller in total with no pixel changed, verified against the original PNG before it was removed. A clone of this repository carries about ten fewer megabytes of image data than it would with the PNG originals.
| File | Why it exists |
|---|---|
usage-new-application.webp |
Same scenario as scenario-before-building.webp, a shorter four step version with no before and with comparison. Kept for reference. |
usage-existing-application.webp |
Same scenario as scenario-existing-application.webp, a shorter four step version with no comparison. Kept for reference. |
usage-improve-working-app.webp |
The four step version of improving a shipped application, summarized in prose in "Three ways teams put this to work" above. Kept for reference. |
usage-enhance-working-app.webp |
A second pass at the same improving a shipped application scenario. Duplicate angle of usage-improve-working-app.webp. Kept for reference, not shown twice. |
Nothing merges without passing all of these.
| Gate | Tool | What it blocks |
|---|---|---|
| Structure | tools/check-structure.py |
A missing dimension, bad frontmatter, fewer than three code languages, under 1200 prose words |
| Citations | tools/validate-refs.py |
Any cited URL that does not resolve |
| Prose | tools/check-prose.py |
Em dashes, en dashes, AI slop vocabulary, emojis, triple-dash separators |
| Markdown | markdownlint-cli2 |
Malformed markdown, emphasis used as a heading |
| Code | tools/check-code.py |
Non-compiling examples (Python, TypeScript, Java, Go, Rust, Swift) |
| Catalogue status | tools/gen-catalogue-status.py |
A README, docs/PROGRESS.md, or dist/ export that has drifted from real repository state |
A per-file internal link checker does not exist yet. It is tracked in
docs/GOVERNANCE-AUDIT-2026-08-03.md as open work, not claimed as done.
Run the whole set locally.
make check- Non technical founders and product people. A way to check whether a plan sounds right before it is built, without needing to read code.
- Developers. A reference to consult mid task instead of guessing from memory or copying the first search result.
- Staff and principal engineers. A tool for review, not for learning. The trade off tables and failure modes are written for someone who already knows the basics and wants the parts a quick summary skips.
- AI assisted developers. A way to hold an agent accountable to a real, citable trade off instead of an invented sounding justification.
- Coding agents themselves. A machine readable reference, laid out identically in every entry, that an agent can consult and cite the same way a person does.
- Not a rule saying every system needs a pattern. A good outcome may be, do not use a pattern here, keep the code simple.
- Not a tutorial. It assumes you already understand basic software design.
- Not a code generator. There is no scaffolding tool here, only reference entries with illustrative code, and none of it is meant to be copied word for word into a real system.
- Not a replacement for testing, review, or judgment. It informs a decision. It does not make the decision for you.
If you are not sure whether a pattern applies, read its non-applicability list first, dimension 4's second half. More entries here exist to tell you when not to use something than to tell you to use it.
For deeper technical detail on every dimension, read the eighteen dimension table, the terminology, and the full family catalogue above.
Clone this repository into your own project as a local reference the agent can read without leaving the project.
git clone --depth 1 https://github.com/mjmirza/patterns.git .patterns
echo ".patterns/" >> .gitignoreThen add the AGENTS.md or CLAUDE.md instruction shown earlier in this
README under "What you can actually do with it," pointing the agent at
.patterns/docs/BY-PROBLEM.md and .patterns/patterns/. Nothing else
changes about how you work with the agent. It reads the same requests it
always did. It now also has a named reference to check its own answer
against before it writes code.
What changes in practice.
Before. You describe a feature. The agent picks an approach silently
and starts writing code. You find out the trade offs later,
usually the first time something breaks.
After. You describe a feature. The agent checks .patterns/, names the
approach it is choosing, states the trade off against at least
one alternative, and asks before it writes code if the choice
is not obvious.
This is a reference sitting beside your code that your AI assistant consults while planning, not a framework it must adopt.
Read .github/CONTRIBUTING.md first. The short version.
- One entry per pull request.
- All eighteen dimensions, or it is sent back.
- Original prose. If a sentence could be diffed against a source and match, rewrite it.
- Every claim cited. Every cited URL verified on the day you submit.
- Production usage names a real system with a real source.
Contributions are licensed under the same OpenRoots Agent License 2.3 as the rest of this repository.
If you use Claude Code, Cursor, Codex, or a similar agent, paste this prompt into it. It fetches the real rules from this repo rather than trusting a stale copy of them, and it enforces the branch-first-then-PR workflow this project requires.
You are contributing one entry to github.com/mjmirza/patterns, a master
level software pattern catalogue. Follow these steps exactly, in order.
1. Fork the repo (if you do not already have write access) and clone it.
Do NOT work directly on main.
2. Read .github/CONTRIBUTING.md, docs/ENTRY-TEMPLATE.md, and one existing
published entry under patterns/ end to end. These are the real, current
rules. Do not assume you already know them.
3. Check docs/AUTHORING-PLAN.md for an unclaimed pattern, or pick a pattern
the maintainer has not catalogued yet.
4. Create a branch named entry/<slug>, for example entry/circuit-breaker.
Never commit to main.
5. Open a DRAFT pull request immediately, naming only the branch and the
pattern you intend to write, before writing the entry. This draft PR is
how you CLAIM the entry so nobody else duplicates your work. CI will
reject a second PR that claims the same entry.
6. Write the entry to docs/ENTRY-TEMPLATE.md's exact eighteen-dimension
shape. Original prose only, never paraphrased from a source close enough
to diff-match it. Every factual claim gets a real, working citation you
have actually checked, not one you assume exists.
7. Run this repo's own local checks before pushing (see the CI job names in
.github/workflows/ci.yml for the exact commands: structure, prose, code
samples, citations, markdown style).
8. Push, mark the PR ready for review, and fill in
.github/PULL_REQUEST_TEMPLATE.md with real command output, not a claim
that it passed.
9. Wait. The maintainer (mjmirza) reviews and merges every PR by hand. Do
not merge your own PR, do not force-push over review feedback without
discussion, and do not touch .github/workflows/ or any other
CI-controlling file, those changes are blocked for anyone without the
maintainer's 'security-reviewed' label.
If anything in this prompt conflicts with the actual .github/CONTRIBUTING.md
in the repo, the file in the repo wins, not this prompt.
See docs/AUTHORING-PLAN.md for the family by family authoring order and the current state of each family.
Built by Mirza Iqbal.
The patterns catalogued here were discovered and named by the authors listed in ATTRIBUTION.md. This repository documents their work. It does not claim it.
Content is licensed under the OpenRoots Agent License 2.3, effective 2026-08-27. The NOTICE file carries the short summary, the canonical legal text lives at openroots.org.
Free and unconditional at or below two million US dollars in annual revenue, and for any individual, nonprofit, school, or government body. Above that threshold, a revenue share applies, capped per year. AI training on this work is not granted by either tier and requires a separate Compute license. On 2029-08-24 this release converts automatically to Apache-2.0. Anyone who obtained an earlier release under this repository's prior license keeps those rights permanently, that grant does not change.
"Patterns" by Mirza Iqbal, OpenRoots Agent License 2.3
https://github.com/mjmirza/patterns