<!-- ===== pixi-vault/CLAUDE.md ===== -->

# Pixi Vault Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/pixi-vault/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to: Vault architecture, Wiki Compiler Maps, AgentWikis compatibility, namespace compiler logic, source/output repo boundaries, and pixi-wiki publication model.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== pixi-vault/README.md ===== -->

---
title: Pixi Vault
created: 2026-06-16
updated: 2026-07-07
type: namespace-overview
status: compiled
category: knowledge-systems
namespace: pixi-vault
confidence: medium
---

# Pixi Vault

> Namespace for the private `pixi-vault` source system and its generated `pixi-wiki` public publishing surface.

## Scope

### Covers

Vault architecture, Wiki Compiler Maps, AgentWikis compatibility, namespace compiler logic, source/output repo boundaries, and pixi-wiki publication model.

### Not Covered

General agent workflow behavior unless it changes vault/compiler architecture; project-specific implementation details unless they affect the namespace compiler.

### Current As

2026-07-07 — Pixi Wiki hardening and feature delivery recorded: CI, browser-verified deploys, human search, Updates, rendering correctness, mobile navigation, SEO, shared CSS, MCP performance, and route contract tests are now part of the public artifact.

## Canonical Source Roots

- `Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md`
- `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`

## Crosslinks

- [[../agent-workflows/README|agent-workflows]]
- [[../local-ai-infrastructure/README|local-ai-infrastructure]]
- [[../eval-trace/README|eval-trace]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/pixi-vault/README.md
/raw/pixi-vault/wiki/index.md
/wiki/pixi-vault/README.md
/wiki/pixi-vault/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== pixi-vault/wiki/concepts/wiki-compiler-map-and-source-classes.md ===== -->

---
title: Wiki Compiler Map and Source Classes
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: pixi-vault
tags: [pixi-vault, wiki-compiler-map, source-of-truth, namespace-routing]
sources:
  - Wiki Compiler Maps/Namespace Wiki Compiler Map.md
  - Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md
confidence: high
---

# Wiki Compiler Map and Source Classes

A **Wiki Compiler Map** is an internal routing artifact that maps authoring-source notes into compiled AgentWikis namespaces. It replaces the old MOC mental model when the job is source-to-namespace routing.

## Why this exists

The vault has many useful authoring surfaces: `Knowledge/`, `Projects/`, scratch chronology, generated reports, and project artifacts. Future agents need a durable contract for deciding which of those are canonical enough to compile into public/agent-facing wiki pages.

## Source classes

### Canonical

Canonical sources can directly feed compiled namespace pages after normal review. Examples include `Knowledge/concepts/*.md`, `Projects/<Project>/Index.md`, PRDs, ADRs, source inventories, verified project reports, and committed repo artifacts with stable paths.

### Supporting

Supporting sources guide routing and maintenance. Examples include Wiki Compiler Maps, taxonomy maps, verified generated reports, lint reports, and issue tracker parent/child tables. They are not usually public wiki content unless rewritten deliberately.

### Scratch

Scratch sources are volatile capture. They can help agents find context, but they do not compile directly unless Jamie/Pixoid promotes or verifies the relevant material against canonical sources.

## Namespace routing rules

- Use one primary namespace for each compiled page.
- Use crosslinks for secondary relevance.
- Duplicate only when a source is rewritten for a genuinely different namespace-specific purpose.
- Promote projects or concepts to standalone namespaces only through an explicit decision.

## Promotion rule

A source cluster can become a namespace when it has at least two of five signals: independent audience, multiple document types, raw source corpus, ongoing update lifecycle, or clear covers/not-covered scope.

## Source

Compiled from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` and `Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md`.


<!-- ===== pixi-vault/wiki/entities/pixi-wiki.md ===== -->

---
title: Pixi Wiki
created: 2026-06-16
updated: 2026-07-07
type: entity
status: active
namespace: pixi-vault
tags: [pixi-vault, pixi-wiki, agentwikis, public-wiki, rag]
sources:
  - wikis/pixi-vault/wiki/syntheses/pixi-vault-to-pixi-wiki-publishing-model.md
  - wikis/local-ai-infrastructure/wiki/concepts/rag-over-agent-wikis.md
  - https://github.com/pixiiidust/pixi-wiki
confidence: high
---

# Pixi Wiki

`pixi-wiki` publishes Jamie's notes, project docs, and research as maintained knowledge bases so humans can browse a clean wiki and agents can read, search, and cite the same Markdown corpus.

## What it does

Pixi Wiki turns each compiled knowledge base into:

- rendered HTML pages for human browsing;
- raw Markdown pages for source-backed retrieval;
- `llms.txt` files for compact agent routing and onboarding;
- `llms-full.txt` files for full-corpus agent context;
- `index.json` registries for tools, tests, and retrieval pipelines;
- a local read-only MCP server so agents can list, search, and read the same KB Markdown files;
- an Agent Setup page and replication guide that explain how agents and other users connect to or copy the pattern;
- client-side search, a shareable search results page, an Updates history, heading anchors/TOCs, sitemap/404, and browser-tested responsive navigation for human use.

## Why it exists

The project turns messy private knowledge work into a shareable publishing surface. Humans browse the web wiki; agents consume the raw Markdown, routing files, registry, and local MCP tools. The private vault remains the source of truth.

## Potential uses

- **RAG over compiled wiki pages:** use maintained pages as the retrieval corpus before adding vector/search infrastructure.
- **Hallucination reduction:** route agents to scoped, cited, freshness-aware pages instead of letting them answer from memory.
- **Agent onboarding:** give new sessions a compact `llms.txt` map before they read deeper pages.
- **Project memory:** preserve decisions, entities, concepts, syntheses, and publication boundaries across sessions.
- **Portfolio surface:** expose selected knowledge/project work as a coherent public system.
- **Eval target:** test whether agents retrieve from the right namespace and cite the right source.

## Namespace classification

Pixi Wiki is primarily an **entity/project artifact** inside the `pixi-vault` namespace because it is the generated public output of the vault compiler system.

Its retrieval use case cross-links to `local-ai-infrastructure`, especially [[../../../local-ai-infrastructure/wiki/concepts/rag-over-agent-wikis|RAG over Agent Wikis]]. Its workflow/use-contract side cross-links to [[../../../agent-workflows/README|Agent Workflows]].

## Current milestone

As of 2026-07-07, the public mirror has moved from a useful generated surface into a hardened wiki product:

- compiled namespace pages for project/domain clusters;
- correct Markdown rendering for emphasis, tables, ordered lists, blockquotes, code spans, and link attributes;
- collapsible grouped namespace sidebars, mobile navigation, visible theme toggle, skip links, and labeled controls;
- rendered Markdown pages with metadata, raw Markdown links, report-a-mistake links, heading anchors, table of contents, and previous/next navigation;
- client-side header search, `/` keyboard shortcut, shareable `search.html?q=...` results, title-weighted ranking, highlighting, namespace badges, and result pagination;
- `updates.html`, `updates.json`, date-section pagination, month strip, namespace dropdowns, and recent-page redirect;
- shared hash-versioned `site.css`, SEO metadata, sitemap, and 404 page;
- a repository README and GitHub About description that frame Pixi Wiki as a publishing surface for human and agent KB access;
- a simplified homepage IA: `WIKIS`, `AGENT SETUP`, `GITHUB`, dark toggle, and an “Agents start here” command using `curl https://pixiiidust.github.io/pixi-wiki/llms.txt`;
- a reusable approach guide at `docs/REPLICATE_APPROACH.html` for adapting the pattern to other Markdown KBs;
- MCP setup docs at `docs/MCP_SERVER.md`;
- a local read-only MCP server with `list_kbs`, `list_documents`, `read_document`, `search_kb`, `search_all_kbs`, and `get_kb_summary`;
- CI running the full pytest suite on pushes/PRs, route-contract tests over committed artifacts, and browser-level verification for live deploys.

## Public handles

- Human site: https://pixiiidust.github.io/pixi-wiki/
- Repository: https://github.com/pixiiidust/pixi-wiki
- Agent registry: https://pixiiidust.github.io/pixi-wiki/llms.txt
- Full corpus: https://pixiiidust.github.io/pixi-wiki/llms-full.txt
- Machine registry: https://pixiiidust.github.io/pixi-wiki/index.json
- Agent setup: https://pixiiidust.github.io/pixi-wiki/docs/AGENT_SETUP.html
- Replication guide: https://pixiiidust.github.io/pixi-wiki/docs/REPLICATE_APPROACH.html
- Search page: https://pixiiidust.github.io/pixi-wiki/search.html
- Updates history: https://pixiiidust.github.io/pixi-wiki/updates.html
- MCP guide: https://pixiiidust.github.io/pixi-wiki/docs/MCP_SERVER.md


<!-- ===== pixi-vault/wiki/index.md ===== -->

---
title: Pixi Vault — Master Index
created: 2026-06-16
updated: 2026-07-07
type: index
status: compiled
namespace: pixi-vault
---

# Pixi Vault — Master Index

> Compiled index for `pixi-vault`, the private source vault and namespace compiler system.

## Concepts

- [[concepts/wiki-compiler-map-and-source-classes|Wiki Compiler Map and Source Classes]] — Routing contract, source classes, primary namespace rule, and namespace promotion rule.

## Entities

- [[entities/pixi-wiki|Pixi Wiki]] — Hardened publishing surface for maintained knowledge bases: human wiki with search/Updates/navigation plus agent-readable raw Markdown, `llms.txt`, `llms-full.txt`, `index.json`, local read-only MCP, Agent Setup, and reusable approach guide.

## Summaries

- Cross-namespace summary: [[../../hermes-agent/wiki/summaries/external-hermes-wikis-import-review|External Hermes Wikis Import Review]] — Hermes-specific instance of external wiki import triage and namespace-routing rules.

## Syntheses

- [[syntheses/pixi-vault-to-pixi-wiki-publishing-model|Pixi Vault to Pixi Wiki Publishing Model]] — Source/output repo boundary and publish workflow from vault to human and agent KB surfaces.

## Source Roots

- `Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md`
- `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`


<!-- ===== pixi-vault/wiki/log.md ===== -->

---
title: Pixi Vault — Activity Log
created: 2026-06-16
updated: 2026-07-07
type: log
status: compiled
namespace: pixi-vault
---

# Pixi Vault — Activity Log

> Append-only namespace log.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Compile pixi-vault content pack v1

- Added concept `wiki/concepts/wiki-compiler-map-and-source-classes.md`.
- Added synthesis `wiki/syntheses/pixi-vault-to-pixi-wiki-publishing-model.md`.
- Updated namespace README and index from scaffold to compiled status.
- Sources are the PRD and Namespace Wiki Compiler Map.
- Scratch chronology was not copied or compiled.

## 2026-06-16 update | Align publishing model with clean rebuild

- Replaced legacy-shim language with clean rebuild policy for `pixi-wiki`.
- Added cross-namespace links to Agent Workflows, Eval Trace, and Local AI Infrastructure.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Record Pixi Wiki public artifact milestone

- Added entity `wiki/entities/pixi-wiki.md` to classify Pixi Wiki as a public generated artifact under the `pixi-vault` namespace.
- Recorded the current UX contract: collapsible namespace sidebars, rendered Markdown pages with metadata, raw/source links, report-a-mistake links, and previous/next navigation.
- Linked Pixi Wiki's RAG/retrieval use case to `local-ai-infrastructure` and `RAG over Agent Wikis`.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Clarify Pixi Wiki human/agent publishing surface

- Reframed Pixi Wiki as a publishing surface for curated KBs: human web wiki plus agent-readable raw Markdown, `llms.txt`, `index.json`, and local read-only MCP.
- Recorded the shipped local MCP server and docs as repo/public-artifact features, while preserving the boundary that the MCP server is not hosted by GitHub Pages.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Ship agent-first homepage and reusable approach guide

- Recorded the live homepage IA: `WIKIS`, `AGENT SETUP`, `GITHUB`, dark toggle, and `curl https://pixiiidust.github.io/pixi-wiki/llms.txt` as the explicit agent-start command.
- Moved `index.json` out of the primary hero/nav and kept it as a footer/docs machine-contract link.
- Added the replication guide handle so other users can copy the Markdown KB → human wiki → agent entrypoints → local MCP pattern.
- Recorded the corrected dark palette contract: near-black background, muted teal links, `#8b4356` reddish-purple active accent, and pale gold highlights.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Crosslink external wiki import method

- Added cross-namespace pointer to the Hermes Agent external wiki import review as a concrete instance of Pixi Vault namespace-routing/import triage.
- No Daily Notes were copied or compiled.

## 2026-07-07 update | Record Pixi Wiki hardening and feature delivery

- Captured the shipped hardening pass: 18 issues closed through 20 merged PRs, live on GitHub Pages and browser-verified.
- Recorded the user-facing features now in the public artifact: correct Markdown rendering, mobile navigation, heading anchors/TOC, client search, `search.html`, Updates history, pagination, SEO/sitemap/404, and shared hash-versioned CSS.
- Recorded the agent/ops features now in the public artifact: CI running 207 tests, route-contract tests over committed artifacts, MCP search performance improvements, and browser-level deploy verification for CSS/JS/runtime issues that HTTP checks miss.
- No Daily Notes were copied or compiled; this log entry summarizes verified repo/live-site milestone state.


<!-- ===== pixi-vault/wiki/syntheses/pixi-vault-to-pixi-wiki-publishing-model.md ===== -->

---
title: Pixi Vault to Pixi Wiki Publishing Model
created: 2026-06-16
updated: 2026-07-07
type: synthesis
status: compiled
namespace: pixi-vault
tags: [pixi-vault, pixi-wiki, publishing, agentwikis]
sources:
  - Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md
  - Wiki Compiler Maps/Namespace Wiki Compiler Map.md
confidence: high
---

# Pixi Vault to Pixi Wiki Publishing Model

`pixi-vault` is the private source repository. `pixi-wiki` is the public generated mirror. The boundary is intentional: authoring truth and public output are separate artifacts.

## Source side

```text
pixi-vault/
├── Knowledge/              # reusable concept authoring
├── Projects/               # project/application source truth
├── Wiki Compiler Maps/     # routing contracts
└── wikis/<slug>/           # compiled namespace source
```

The `wikis/<slug>/` layer is compiled/curated source inside the vault. It is reviewable in Git and Obsidian, but agents should edit `Knowledge/`, `Projects/`, or Wiki Compiler Maps first unless intentionally patching compiled output.

## Public side

```text
pixi-wiki/
├── llms.txt
├── llms-full.txt
├── index.json
├── search.html
├── updates.html
├── updates.json
├── sitemap.xml
├── site.css
├── raw/<slug>/...
└── wiki/<slug>/...
```

`llms.txt` is the compact agent registry. `llms-full.txt` is the full concatenated corpus. `index.json` is the machine-readable registry. `raw/<slug>/` preserves Markdown, `wiki/<slug>/` exposes human-readable HTML, `search.html`/`updates.html` provide human retrieval and freshness surfaces, and the local MCP server exposes read/search tools over the same KB files.

Human pages render Markdown with breadcrumbs, visible frontmatter metadata, raw Markdown links, report-a-mistake links, namespace sidebars, heading anchors, table of contents, and previous/next navigation. The goal is a two-surface publication model: humans browse/search the web wiki and update history, while agents use raw Markdown, `llms.txt`, `index.json`, and local MCP tools over the same KBs.

## Publication workflow

1. Update canonical source in `Knowledge/`, `Projects/`, or Wiki Compiler Maps.
2. Compile/curate into `wikis/<slug>/`.
3. Run namespace linting against `pixi-vault/wikis`.
4. Run the `pixi-wiki` generator.
5. Run public-output tests.
6. Push both repos as needed.
7. Verify live GitHub Pages URLs with HTTP 200 and expected content tokens.
8. Run browser-level verification for pages affected by CSS, layout, navigation, or JavaScript. HTTP checks alone miss computed-style and runtime failures.
9. For local MCP changes, run the MCP self-test and a real stdio client smoke test.

## Clean rebuild policy

Old root flat pages in `pixi-wiki` are removed from the canonical public contract. The clean mirror should keep root-level global surfaces such as the homepage, registries, search, Updates, sitemap, shared assets, and docs, plus `/raw/<slug>/...` and `/wiki/<slug>/...` namespace trees.

No old `concept-*.html`, `projects-*.html`, `knowledge.html`, `projects.html`, `maps-of-content.html`, `root.html`, `agent/`, or `legacy/` surface should reappear without a deliberate compatibility policy and regression coverage.

## Cross-namespace relationships

- [Agent Workflows](../../../agent-workflows/README.md) documents crew workflows affected by source-truth boundaries, Knowledge Pack Routing, and markdown-first agent memory.
- [Eval Trace](../../../eval-trace/README.md) evaluates whether agents overfit stale context or skip live verification.
- [Local AI Infrastructure](../../../local-ai-infrastructure/README.md) will matter when RAG or local models consume compiled wiki pages.

## Source

Compiled from `Projects/Hermes Mission Control/PRD - Pixi Vault Namespace Compiler.md` and `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.


<!-- ===== agent-workflows/CLAUDE.md ===== -->

# Agent Workflows Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/agent-workflows/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to: Pixoid/Tinker/Quill/Boba operating model, Hermes Mission Control, route governance, memory boundaries, context handoffs, self-improving agent systems, and workflow reliability practices.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== agent-workflows/README.md ===== -->

---
title: Agent Workflows
created: 2026-06-16
updated: 2026-07-09
type: namespace-overview
status: active
category: agents
namespace: agent-workflows
confidence: medium
---

# Agent Workflows

> Operational namespace for Jamie's Pixoid crew workflows: route governance, durable context, agent entrypoints, verification gates, and markdown-first agent memory.

## Scope

### Covers

Pixoid/Tinker/Quill/Boba operating model, Hermes Mission Control, route governance, memory boundaries, context handoffs, Knowledge Pack Routing, agent entrypoint meshes, static retrieval/eval gates, self-improving agent systems, effective-state-load boundaries, and workflow reliability practices.

### Not Covered

Product case studies except where they demonstrate agent workflow mechanics; low-level local AI infrastructure unless it affects workflow execution; public wiki publishing mechanics except where they define agent routing contracts; Daily Notes scratch chronology unless explicitly promoted into durable source notes.

### Current As

2026-07-09 — Added the Eve-derived Agentic Harness Engineering pattern: build agents as inspectable runtime harnesses with explicit capability slots, trust boundaries, durable sessions, channels, sandboxing, and eval gates.

## Canonical Source Roots

- `Projects/Effective State Load/Index.md`
- `Projects/Hermes Mission Control/Index.md`
- `Projects/Hermes Mission Control/PRD - Knowledge Pack Routing.md`
- `Projects/Hermes Mission Control/PRD - Knowledge Pack Routing V2.md`
- `Projects/Hermes Mission Control/Knowledge Pack Contract V1.md`
- `Projects/Hermes Mission Control/KPR Static Retrieval Eval - 2026-06-15.md`
- `Projects/Hermes Mission Control/kpr-pixoid-routing-rule.md`
- `Knowledge/concepts/self-improving-agent-systems.md`
- `Knowledge/concepts/profile-memory-boundaries.md`
- `Knowledge/concepts/runtime-memory-knowledge-routing.md`
- `Knowledge/concepts/agent-skill-routing.md`
- `Knowledge/concepts/agent-tooling-plan.md`
- `Knowledge/concepts/agentic-harness-engineering.md`
- `Knowledge/concepts/effective-state-load.md`
- `Knowledge/concepts/reader-centered-outreach-asks.md`
- `Knowledge/concepts/compound-engineering-skill-layer.md`
- `Knowledge/concepts/hermes-capability-routing.md`
- `Knowledge/concepts/high-agency-work-levels.md`
- `Knowledge/concepts/creative-ideation-routing.md`
- `Knowledge/concepts/interaction-mode-routing.md`
- `Knowledge/concepts/peer-profiles-vs-child-processes.md`
- `Knowledge/concepts/multi-agent-multiplayer-boundaries.md`
- `Knowledge/concepts/ponytail-minimal-code-discipline.md`
- `Knowledge/concepts/visual-plan-review-surfaces.md`
- `Knowledge/concepts/matt-pocock-skills-best-practices.md`

## Routing Rules

- Primary namespace: `agent-workflows` for crew operating model, KPR, entrypoint meshes, and route/eval workflow practices.
- Also relevant to `pixi-vault` when namespace compiler or publishing boundaries change.
- Also relevant to `eval-trace` when workflow quality, route failure modes, or static eval gates are being evaluated.
- Use primary namespace plus crosslinks. Do not duplicate pages across namespaces unless the page is rewritten for a different user job.

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/agent-workflows/README.md
/raw/agent-workflows/wiki/index.md
/wiki/agent-workflows/README.md.html
/wiki/agent-workflows/wiki/index.md.html
/wiki/agent-workflows/assets/reports/esl-full-report.html
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== agent-workflows/wiki/concepts/agent-capability-route-pattern.md ===== -->

---
title: Agent Capability Route Pattern
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: agent-workflows
tags: [architecture, agent-systems, workflow, governance]
sources:
  - /root/.hermes/knowledge/concepts/agent-capability-route-pattern.md
  - Knowledge/concepts/agent-capability-route-pattern.md
confidence: high
---

# Agent Capability Route Pattern

## Definition

An **agent capability route** is an explicit, bounded path from approved work into a Hermes agent capability. It defines how work enters, which profile may execute it, what that profile may do, what artifact it must return, and how Pixoid verifies the result before it becomes durable truth.

Short form:

```text
approved trigger → profile seam → bounded execution → artifact → verification → handoff/closure
```

## Current synthesis

A route is not just “ask an agent.” It is a small operating contract with these parts:

| Component | Question it answers |
|---|---|
| Trigger | How does work enter the route: approved issue, explicit handoff, scheduled job, or manual CLI command? |
| Profile seam | Which Hermes profile is requested, and how is the actual executing profile verified? |
| Authorization | What approval is required before execution, merge, posting, deployment, or live side effects? |
| Execution bounds | What scope, tools, context budget, max slices, and stop conditions apply? |
| Artifact contract | What must the route produce: PR, report, vault note, issue comment, handoff, or launch prompt? |
| Verification gate | What real evidence proves the artifact worked or stayed in bounds? |
| Observability | What event, issue comment, report, or handoff records requested profile, actual profile, status, and proof? |

The profile seam is the identity-critical part. Named crew work should run through peer Hermes profiles when a real route exists; child subagents can help with analysis, but they are not proof that Tinker, Quill, Boba, or another named peer profile executed work. See [[peer-profiles-vs-child-processes]] and [[hermes-soul-md-wiring]].

## Application

Use this pattern when a future agent needs to decide whether work may be delegated, run AFK, launched under a profile, or closed from existing evidence.

A healthy route should state:

1. the source of truth for the task, usually a GitHub issue, PRD, or handoff;
2. the requested profile or capability;
3. the allowed side effects;
4. the forbidden side effects;
5. verification commands or review checks;
6. the required durable artifact;
7. who may close or merge.

For issue-driven work, route execution usually pairs with [[issue-driven-afk-workflow]] and [[smart-zone-context-discipline]]. For broader autonomy, map the route to [[workspace-autonomy-levels]].

## Boundaries

- A route recommendation is not an automatic trigger.
- Documentation Hygiene recommendations do not automatically invoke Quill, Boba, Tinker, or any worker route.
- `delegate_task` children are useful for local read-only synthesis or review, but they are not named peer-profile execution evidence.
- Do not claim a route is live unless runtime proof shows the requested profile and actual profile match.
- Do not mutate profiles, gateways, providers, cron, webhooks, secrets, MCP, RAG, or deployment state unless the route explicitly authorizes that action.
- Do not merge, deploy, post live messages, or expose secrets without the route’s approval policy and current user scope supporting it.
- Keep transient issue numbers, PR numbers, commit SHAs, and milestone state out of generic concept pages.

## Related pages

- [[peer-profiles-vs-child-processes]]
- [[hermes-soul-md-wiring]]
- [[profile-memory-boundaries]]
- [[workspace-autonomy-levels]]
- [[issue-driven-afk-workflow]]
- [[smart-zone-context-discipline]]
- [[runtime-memory-knowledge-routing]]
- [[context-overfitting]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/agent-capability-route-pattern.md`
- `/root/ObsidianVault/Projects/Pixoid Agent Capability Routes/Index.md`


<!-- ===== agent-workflows/wiki/concepts/agent-entrypoint-mesh.md ===== -->

---
title: Agent Entrypoint Mesh
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, entrypoints, routing, llms-txt]
sources:
  - Projects/Hermes Mission Control/kpr-pixoid-routing-rule.md
  - Projects/Hermes Mission Control/Knowledge Pack Contract V1.md
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing V2.md
confidence: medium
---

# Agent Entrypoint Mesh

An **agent entrypoint mesh** is a set of small, typed starting points that route an agent to the right truth surface for the job.

The point is not to make one universal file. The point is to make the first hop cheap, explicit, and hard to confuse.

## Mesh shape

A healthy mesh usually has:

- a root agent registry such as `llms.txt`;
- namespace or domain-level packs;
- project/entity packs for concrete work;
- machine registry metadata such as `index.json`;
- raw provenance mirrors for source inspection;
- issue tracker links for execution truth.

## Why mesh beats dump

A raw dump asks the model to infer structure from volume. A mesh gives it structure first: scope, not-covered boundaries, source paths, freshness, and fallback behavior.

## Pixoid rule

Pixoid should treat entrypoints as routing contracts, not as replacement truth. If a pack points to a GitHub issue, PRD, or source note, the agent verifies the live source before claiming current state.

## Related pages

- [[knowledge-pack-routing]]
- [[static-retrieval-evals]]
- [[runtime-memory-knowledge-routing]]


<!-- ===== agent-workflows/wiki/concepts/agent-skill-routing.md ===== -->

---
title: Agent Skill Routing
created: 2026-06-23
updated: 2026-07-09
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/agent-skill-routing.md
confidence: high
---

# Agent Skill Routing

Agent skill routing is the operating contract that Jamie states the desired outcome while Pixoid chooses the useful skill stack, loads those skills, and carries active skill constraints into any delegated subagent context.

## Why this exists

Tools already work this way: Jamie does not need to say `read_file` or `web_search`; Pixoid selects the tool that fits the job. Skills need the same user-facing behavior, but with one extra step: the parent agent must load the skill contents before relying on them.

## Runtime rule

1. Classify the user intent.
2. Load the smallest useful skill stack with `skill_view`.
3. Execute the task through the loaded procedures.
4. If delegating, add an `Active skill constraints` block to the `delegate_task` context.
5. Verify that the subagent followed the constraints before presenting the result.

## Default skill stacks

| Intent | Primary skill | Common supports |
|---|---|---|
| Delegated research, writing, product strategy, portfolio, or project analysis | `pixi-wiki-first-research` | `business-model-research`, `public-signal-monitoring`, `verb-first` |
| PM portfolio or product case study | `portfolio-build-readiness-review` | `product-case-study`, `verb-first`, `pixi-wiki-first-research` |
| Product positioning or copy | `verb-first` | `find-lock`, `ai-native-framing` |
| Creative inspiration, brainstorming, project ideas, or option generation | `creative-ideation` | `find-lock`, `verb-first`, `ai-native-framing` after an idea is selected |
| Spec or implementation plan needs an inspectable review surface | `visual-plan` | `plan`, `prototype`, `obsidian` when the artifact should be source-controlled |
| Build or implementation slice | `implement` | `test-driven-development`, `ponytail-code-discipline`, `github-operations` |
| Repo-local Compound Engineering loop | `ce-setup`, then `ce-brainstorm` / `ce-plan` / `ce-work` | `ce-simplify-code`, `ce-code-review`, `ce-compound`; `/lfg` only with explicit scope and approval gates |
| Debugging | `debugging` | project-specific skill, `codebase-inspection` |
| PR or diff review | `code-review` | `ponytail-code-discipline`, `github-operations` |
| Vault or source-of-truth update | `obsidian` | `pixi-wiki-first-research` when public/wiki context matters |
| Fresh-session continuity | `handoff` | `obsidian` if a durable note is needed |
| Hermes setup/config/troubleshooting | `hermes-agent` | `hermes-cron-operations`, `hermes-gateway-ops`, `native-mcp` |

## Delegation constraint block

Loaded parent skills do not automatically bind isolated subagents. Delegated tasks that rely on skills should include:

```text
Active skill constraints:
- Skills selected by Pixoid: <skill names>.
- Apply these rules before final output: <short constraints>.
- Report which constraints you followed and what source/tool evidence supports the result.
- If a required source/tool is unavailable, say so directly instead of producing generic output.
```

For delegated research, writing, strategy, portfolio, or project analysis, the Pixi Wiki rule is mandatory by default:

```text
Before producing the final answer, use Pixi Wiki MCP first: list available KBs, search for the task topic, read relevant documents, and tailor the answer to Jamie/project context. Generic output without Pixi Wiki retrieval is incomplete. Report which KBs/docs you used and where public web research differs from Pixi Wiki context.
```

## Boundaries

- Use the smallest useful stack; do not load every adjacent skill.
- Skills do not override current user intent, live repo state, GitHub issues/tickets, specs/PRDs, safety rules, or verification evidence.
- Subagent output that does not report required retrieval, evidence, or skill constraints is incomplete.
- Durable lessons still route by layer: facts to memory, concepts to Knowledge/Pixi Wiki, project state to Obsidian/GitHub, procedures to skills.

## Edge cases

- Explicit user-invoked skills or `/skill-name` labels are the chosen mode unless they conflict with safety or live evidence. In Discord, distinguish native gateway commands from Hermes skill shorthand: `/ce-ideate` can mean the `ce-ideate` skill even if the Discord slash command is not registered.
- Ask only when different skill stacks imply materially different artifacts or side effects.
- If a skill might matter but its description is unclear, load it before relying on it or excluding it.
- If required MCP/tool/source access is unavailable, report that directly or use a grounded fallback; do not produce generic output as if the constraint was satisfied.
- For open-ended inspiration or option generation, load `creative-ideation`, route through one method, and produce grounded non-generic ideas before returning to product/build gates.
- For PRD/implementation-plan review surfaces, load `visual-plan` and default to local/private MDX artifacts; hosted Plan auth, share links, and comments are optional, not prerequisites.
- For repo-local Compound Engineering loops, load `ce-setup` first, then route through `ce-brainstorm` -> `ce-plan` -> `ce-work` -> `ce-simplify-code` -> `ce-code-review` -> `ce-compound`; keep `lfg` approval-gated. In Discord, invoke CE skills with natural language or `/skill <name>` unless native `/ce-*` aliases have been explicitly registered.
- Updating vault/Pixi Wiki source can preserve durable knowledge; pushing public `pixi-wiki` deploys still needs explicit approval.
- If skill routing would overload context, stop and hand off rather than carrying a bloated stack forward.

## Source

Canonical source: `Knowledge/concepts/agent-skill-routing.md`.

Reusable Hermes skill: `~/.hermes/skills/productivity/jamie-skill-router/SKILL.md`.

Related skill: `~/.hermes/skills/research/pixi-wiki-first-research/SKILL.md`.

Creative support skill: `~/.hermes/skills/creative/creative-ideation/SKILL.md`.

Visual review support skill: `~/.hermes/skills/visual-plan/SKILL.md`.


<!-- ===== agent-workflows/wiki/concepts/agent-tooling-plan.md ===== -->

---
title: Agent Tooling Plan
created: 2026-06-30
updated: 2026-06-30
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/agent-tooling-plan.md
confidence: high
---

# Agent Tooling Plan

An **Agent Tooling Plan** turns a problem into an agent-as-tools route: live-state checks, task buckets, tools, routing rules, memory, evaluation, permissions, and the smallest proving loop that lets an agent act safely.

## Core premise

An agent is not magic intelligence. It is an orchestration layer over bounded tools.

The product work is:

```text
configure the right tools for the right task bucket, then give the agent reliable routing, memory, evaluation, permissions, and a proving loop
```

## Start with live state

Before assigning tools, inspect named docs, repos, APIs, channels, files, dashboards, or existing workflows. If a source is unavailable, mark the relevant plan row as an assumption.

Route upstream to AI-native problem framing when the product/problem is fuzzy. Route downstream to Hermes capability routing when the work shape is clear and the question is which Hermes surface should execute it.

## Agent loop

```text
Goal → choose tool → run tool → observe result → interpret → choose next tool → repeat
```

## Tool buckets

| Bucket | Purpose | Example tools |
|---|---|---|
| Perception | See the environment | Browser, files, APIs, sensors, logs |
| Interpretation | Turn signals into meaning | LLM, classifier, parser, summarizer |
| Memory | Apply interpreted past experience | Retrieval, compression, preference memory |
| Planning | Decide possible next steps | Decomposer, simulator, option ranker |
| Action | Change the environment | Email, code editor, deploy, browser click |
| Evaluation | Judge result quality | Tests, metrics, scoring, human review |
| Escalation | Hand off when uncertain | Approval gate, human decision, exception flow |

## Planning outputs

For a vague request, output a scaffold plus questions/gaps and route to `/grill-me` or `/grill-with-docs` instead of inventing a complete plan. Ask at most five questions, and only when each answer changes tool choice, routing, evaluation, permissions, memory, or the proving loop.

For a clear request, output a full plan with:

- goal;
- environment;
- inspected sources and assumptions;
- bucket table;
- routing rules;
- memory contract;
- evaluation contract;
- permissions table;
- feedback loop;
- smallest proving loop.

## Smallest proving loop

The proving loop is the smallest buildable/testable route that demonstrates:

```text
perception → action or simulated action → evaluation → next routing decision
```

For high-risk domains, the first loop can be read-only or simulated. Do not call the system autonomous until observe, evaluate, and escalate are all defined.

## Mini-example

Request: “Plan an email triage agent.”

- **Goal:** reduce inbox review time without losing important messages.
- **Perception:** Gmail/API inbox search, labels, message metadata, sender history.
- **Interpretation:** classify urgency, topic, action needed, and confidence.
- **Memory:** user preferences for VIP senders, recurring newsletters, prior corrections.
- **Planning:** choose archive, label, draft reply, summarize, or escalate.
- **Action:** apply labels, draft replies, archive low-risk messages.
- **Evaluation:** sample 20 decisions, check false archives, compare user corrections, measure time saved.
- **Escalation:** ask before sending replies, deleting, unsubscribing, or handling low-confidence/VIP messages.
- **Smallest proving loop:** read 25 recent emails → classify only → user reviews labels → update routing before enabling actions.

## Boundaries

- Tool assignment is incomplete without routing, memory, evaluation, permissions, feedback, and a proving loop.
- Approval gates are part of the product surface, not an afterthought.
- Memory should store interpreted experience, not raw logs.
- Evaluation must be concrete enough to distinguish “agent says done” from “the loop worked.”
- Do not produce a pretty table that cannot be executed or evaluated.

## Source

Canonical source: `Knowledge/concepts/agent-tooling-plan.md`.

Reusable Hermes skill: `~/.hermes/skills/autonomous-ai-agents/agent-tooling-plan/SKILL.md`.

Related pages: [[concepts/agent-skill-routing|Agent Skill Routing]], [[../../hermes-agent/wiki/concepts/hermes-capability-routing|Hermes Capability Routing]], [[concepts/agent-capability-route-pattern|Agent Capability Route Pattern]], [[concepts/runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]], [[concepts/matt-pocock-skills-best-practices|Matt Pocock Skills Best Practices]].


<!-- ===== agent-workflows/wiki/concepts/agentic-harness-engineering.md ===== -->

---
title: Agentic Harness Engineering
created: 2026-07-09
updated: 2026-07-09
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/agentic-harness-engineering.md
confidence: high
---

# Agentic Harness Engineering

Agentic harness engineering treats an AI agent as a deployable software harness, not a giant prompt. The harness makes identity, actions, tool authority, channel routes, sandbox execution, durable state, background work, and eval gates inspectable before the agent runs.

## Reference pattern from Eve

Vercel's Eve framework is a useful reference shape because it authors agents as files under `agent/`:

```text
instructions.md  -> identity and standing contract
agent.ts         -> model and runtime config
tools/           -> typed model-callable actions
skills/          -> on-demand procedures
channels/        -> HTTP, Slack, Discord, GitHub, Linear, and custom entrypoints
connections/     -> MCP/OpenAPI external tool surfaces with brokered auth
subagents/       -> specialist child agents
schedules/       -> cron/background runs
sandbox/         -> isolated /workspace for shell and file work
evals/           -> route-level behavioral checks
```

The transferable lesson is not the exact folder names. The pattern is that each capability has a visible slot and a runtime boundary.

## Harness checklist

A real agentic harness should answer these questions without relying on chat history:

| Question | Harness surface |
|---|---|
| Who is this agent? | instructions / profile / identity file |
| What actions can it take? | typed tools and connection manifests |
| Where can users reach it? | channels and route auth |
| What is unsafe/untrusted execution? | sandbox backend, workspace, and network policy |
| What needs human approval? | HITL and approval policies |
| What persists across turns? | durable session state and knowledge/memory routing |
| How does work split? | subagents and delegation caps |
| What runs on a clock? | schedules / cron |
| How is behavior verified? | evals, stream events, route checks, and live proof |

## Jamie-system application

- **Hermes Mission Control:** keep profile routes, Discord channel contracts, skills, cron, MCP, memories, vault truth, and verification as explicit harness surfaces.
- **Pixi Wiki:** treat namespace source, compiler maps, generated routes, `llms.txt`, MCP tests, and live Pages checks as the publishing harness, not just generated pages.
- **Crew workflows:** use peer-profile vs child-process boundaries before claiming named-agent execution.
- **Product prototypes:** start with identity, tool/data boundary, channel, sandbox, approval path, durable state, and eval smoke test before promising autonomy.

## Boundaries

- A visible file tree is not sufficient; auth, approval, idempotency, network policy, and verification still matter.
- Secrets belong in trusted runtime tools or connection auth, not in model context or sandbox files.
- Long procedures should be load-on-demand skills/playbooks, not permanent prompt bulk.
- Subagents are not an approval boundary by themselves.

## Source

Canonical source: `Knowledge/concepts/agentic-harness-engineering.md`.

External references reviewed: `https://eve.dev/docs/introduction` and `https://github.com/vercel/eve`.

## Related pages

- [[agent-tooling-plan|Agent Tooling Plan]]
- [[agent-skill-routing|Agent Skill Routing]]
- [[../../hermes-agent/wiki/concepts/hermes-capability-routing|Hermes Capability Routing]]
- [[runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]]
- [[self-improving-agent-systems|Self-Improving Agent Systems]]
- [[peer-profiles-vs-child-processes|Peer Profiles vs Child Processes]]


<!-- ===== agent-workflows/wiki/concepts/bounded-context-tree-pattern.md ===== -->

---
title: Bounded Context Tree Pattern
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: agent-workflows
tags: [architecture, workflow, ai, knowledge-management]
sources:
  - /root/.hermes/knowledge/concepts/bounded-context-tree-pattern.md
  - Knowledge/concepts/bounded-context-tree-pattern.md
confidence: high
---

# Bounded Context Tree Pattern

## Definition

A **bounded context tree** organizes project knowledge as a self-contained domain with its own language, decisions, and artifacts.

```text
Root = bounded context / project hub
Branch = major concern inside the context
Leaf = specific artifact, decision, PRD, ADR, report, or source note
```

This adapts Domain-Driven Design for personal and agent-readable knowledge management.

## Current synthesis

Use this pattern for serious multi-artifact project knowledge. A strong context tree has:

- one `Index.md` or hub at the root that defines scope, current status, source-of-truth order, and branch map;
- branches for stable concerns such as strategy, domain model, architecture, product, research, decisions, and implementation artifacts;
- leaves that hold focused evidence or decisions, not transcript dumps;
- explicit cross-context links only when a real boundary is crossed;
- one primary parent branch for each durable note.

The goal is language isolation. Each project or domain owns its vocabulary. Agents should not import terms, priorities, or constraints from one bounded context into another unless a cross-link explains why.

## Application

Use this pattern when:

- a project has multiple PRDs, ADRs, decisions, source inventories, prototypes, or research notes;
- a brainstorm is becoming a committed project;
- raw transcripts need to be distilled into a project hub and leaf artifacts;
- an agent needs a map before editing Obsidian or a local knowledge namespace;
- MOC/navigation work risks becoming a backlink hairball.

Minimal example:

```text
Projects/Example/Index.md          # root / hub
Projects/Example/01-Strategy/      # branch
Projects/Example/02-Domain/        # branch
Projects/Example/03-Architecture/  # branch
Projects/Example/Decisions/        # branch
Projects/Example/Decisions/ADR-001.md  # leaf
```

In the local Hermes KB, the same principle means concept pages should be concise reusable leaves linked through [[moc-knowledge-cortex]], not copied project logs.

## Boundaries

- Do not dump raw chat transcripts or command logs into a project hub.
- Do not let MOCs replace project hubs; MOCs route, hubs own context.
- Do not create deep folder trees before the domain has enough durable artifacts to justify them.
- Do not import stale project status into generic concept pages.
- Do not add backlinks just to make graph view look connected; add crosslinks only for useful retrieval or real domain meaning.
- Do not promote scratch/capture notes into canonical knowledge without source review.

## Related pages

- [[moc-knowledge-cortex]]
- [[matt-pocock-sdlc-rhythm]]
- [[runtime-memory-knowledge-routing]]
- [[agent-wikis]]
- [[context-overfitting]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/bounded-context-tree-pattern.md`
- `/root/ObsidianVault/Projects/README.md`


<!-- ===== agent-workflows/wiki/concepts/compound-engineering-skill-layer.md ===== -->

---
title: Compound Engineering Skill Layer
created: 2026-06-27
updated: 2026-07-09
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/compound-engineering-skill-layer.md
confidence: high
---

# Compound Engineering Skill Layer

Compound Engineering is an EveryInc plugin that packages a repo-local engineering loop: ideate or brainstorm, plan, work, simplify, review, compound the learning, and repeat with better context.

In Jamie's Hermes setup, it is installed at `/root/.hermes/plugins/compound-engineering-plugin/skills` and exposed as normal Hermes skills such as `ce-setup`, `ce-brainstorm`, `ce-plan`, `ce-work`, `ce-simplify-code`, `ce-code-review`, `ce-debug`, `ce-compound`, and `lfg`.

## Quick start

Treat the CE names as Hermes skill invocations, not guaranteed Discord-native slash commands. In Discord, Jamie may write `/ce-ideate` as shorthand for the skill; if Discord rejects it as unknown, use natural language or the built-in skill loader:

```text
@Pixoid use the ce-ideate skill: surprise me with app ideas
/skill ce-ideate
```

Upstream docs often show `/ce-*`; that is command-style skill naming from the source ecosystem, not proof that the Discord gateway registered a native slash alias.

Run `ce-setup` once per target repo, then use the standard loop:

```text
ce-brainstorm describe the feature or problem
ce-plan
ce-work
ce-simplify-code
ce-code-review
ce-compound
```

## When to use it

| Situation | Route |
|---|---|
| Need grounded build ideas | `ce-ideate` -> `ce-brainstorm` |
| Need requirements before implementation | `ce-brainstorm` -> `ce-plan` |
| Need to execute an approved CE plan | `ce-work` |
| Need to clean fresh implementation work | `ce-simplify-code` |
| Need plan-aware review | `ce-code-review` |
| Need bug reproduction/root cause/fix | `ce-debug` -> `ce-code-review` -> `ce-compound` |
| Need project-local learning capture | `ce-compound` |
| Need bounded autopilot after requirements | `lfg`, only with explicit scope/approval gates |

## Similar to existing skills

Compound Engineering aligns with [[matt-pocock-sdlc-rhythm]] and [[matt-pocock-skills-best-practices]]: it reduces misalignment through planning, shared artifacts, feedback loops, review, and durable learning.

It also overlaps with [[agent-skill-routing]] because Pixoid should choose the right CE skill automatically instead of making Jamie be the skill librarian.

## Different from existing skills

- CE is an integrated workflow package; Pocock/Jamie skills are modular gates.
- CE's `ce-brainstorm` and `ce-plan` write a shared unified plan artifact for downstream CE commands; `to-spec` and `to-tickets` remain better when the durable deliverable is a spec/ticket tree.
- CE's `ce-work` assumes the CE plan context; `implement`/`tdd` remain better for one narrow GitHub issue or an existing non-CE plan.
- CE's `ce-compound` captures project-local engineering learning, usually under `docs/solutions/`; Obsidian/Pixi Wiki remain the home for reusable human-facing knowledge.
- CE's `lfg` is an autopilot. Jamie's AFK route contracts still govern profile boundaries, handoffs, merge/deploy approval, and route observability.

## Pixoid routing rules

- Use CE for repo-local engineering loops.
- Use `prototype`, `visual-plan`, `grill-with-docs`, `/wayfinder`, `/to-spec`, and `/to-tickets` when Jamie needs explicit human review artifacts before execution.
- Use normal `code-review`, `debugging`, `ponytail-code-discipline`, or `test-driven-development` when CE's unified plan artifact is not the active source.
- Do not let `lfg` bypass destructive-change, deploy, merge, secret, profile/runtime, or public publishing approvals.
- Treat CE skills as procedures, not proof: inspect live state, run tests, and verify outputs before reporting success.

## Related pages

- [[agent-skill-routing]]
- [[matt-pocock-sdlc-rhythm]]
- [[matt-pocock-skills-best-practices]]
- [[visual-plan-review-surfaces]]
- [[profile-memory-boundaries]]


<!-- ===== agent-workflows/wiki/concepts/creative-ideation-routing.md ===== -->

---
title: Creative Ideation Routing
created: 2026-06-24
updated: 2026-06-24
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/creative-ideation-routing.md
confidence: high
---

# Creative Ideation Routing

Creative ideation routing is the agent-workflow pattern for turning open-ended inspiration requests into method-routed idea generation instead of generic brainstorming.

## Runtime rule

When Jamie asks for inspiration, project ideas, weirdness, options, research questions, or a way out of a stale creative loop:

1. Load the `creative-ideation` Hermes skill.
2. Classify phase, domain, and specificity.
3. Apply overrides for mood, named method, method recommendation, or high-slop terrain.
4. Route to one named method.
5. Generate concrete, non-obvious ideas with mechanisms, tradeoffs, and at least one grounded first step.

## Why this belongs in Agent Workflows

This is not a new Pixi Wiki namespace. It is a reusable skill-routing behavior: Jamie states the creative need, Pixoid chooses the method and skill constraints, then returns any chosen idea to the normal product/build gates.

## Quality bar

Good ideation output:

- names the method used;
- avoids obvious first ideas;
- uses concrete mechanisms and situations;
- states failure modes or tradeoffs;
- includes at least one buildable option;
- stops ideating once Jamie chooses.

Bad output is unrouted LLM slop: generic lists, vague app nouns, no method, no mechanism, no tradeoff, and no first step.

## Relationships

- [[agent-skill-routing|Agent Skill Routing]] chooses when to load `creative-ideation`.
- [[matt-pocock-sdlc-rhythm|Matt Pocock SDLC Rhythm]] takes over after Jamie chooses an idea.
- Cross-namespace product lenses such as [[../../ai-native-product-surfaces/wiki/concepts/interaction-mode-routing|Interaction Mode Routing]] decide which surface should carry a selected idea.

## Source

Canonical source: `Knowledge/concepts/creative-ideation-routing.md`.

Reusable Hermes skill: `~/.hermes/skills/creative/creative-ideation/SKILL.md`.


<!-- ===== agent-workflows/wiki/concepts/effective-state-load.md ===== -->

---
title: Effective State Load
created: 2026-07-03
updated: 2026-07-07
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/effective-state-load.md
confidence: high
---

# Effective State Load

**Effective State Load (ESL)** is workflow-specific load testing for LLM agents: define state/dependency load for a workflow, map where the model-agent harness loses track of reality, then keep future runs inside the safe operating band.

```txt
SC = state cardinality   # live things the agent must track
DD = dependency density  # simultaneous bindings/preconditions per action
ESL = SC × DD            # metric family; not a universal threshold/formula
```

## Current verdict

`ESL = SC × DD` is **environment-general as a metric family and measurement recipe, not as a portable formula**.

The durable recipe is:

```txt
cheap grid → SC/DD surface → calibrated frontier → operating margin → routing/guardrails
```

Boundary location and axis weights are workload-specific. The useful answer is not “one formula ships in a library”; it is “calibrate the collapse frontier for this model/tool/workflow setup.”

## Evidence summary

### Phase 1 — StatefulPuzzle

- 240 deduped episodes over SC `{5,10,15,20,25,40}` × DD `{1,2,4,6}`.
- StatefulPuzzle is SC-dominant: SC=40 collapses even at DD=1.
- Weighted fallback after simple ESL underperformed: **SC¹ × DD^0.48**.
- Token count was a tough baseline: calibrated ESL Spearman 0.858 vs token count 0.857.

### Phase 3 — ToolDAG-B

- 160 transfer-grid episodes after a 60-episode gate PASS.
- ToolDAG-B tests provenance-checked binding: right type is not enough; the variable/object must come from the correct producer.
- Surface is binary-sharp: every cell is 10/10 or 0/10.
- Dominant axis flips: SC=40 DD=1 passes 10/10; SC=20 DD=4 and SC=40 DD=2 fail 0/10.
- Simple `SC × DD` is the top predictor here: Spearman 0.810 vs token count 0.804, with perfect label separation at ESL≤60 pass / ESL≥80 fail.
- Failure mode: 2,655 wrong-provenance/binding errors vs 1 parse error in 2,811 steps.

## What “world-model collapse” means

The agent can still produce fluent, valid-looking output, but its internal picture of the workflow state has drifted from reality. In production this can show up as:

- valid customer ID, wrong customer;
- valid file path, wrong file;
- valid ticket ID, wrong ticket;
- stale tool output treated as fresh;
- a write action whose arguments came from mismatched upstream contexts.

## Measuring SC/DD in practice

There are three practical scenarios:

1. **Count** from a system of record when objects and rules are already structured: CRM, ERP, PLM, data lineage, ticketing, cloud graphs.
2. **Measure** through tool middleware when every tool call and object ID passes through an interception layer. SC is active provenance nodes; DD is required correct bindings per action.
3. **Estimate** for plain-language tasks using a plan DAG, cheap classifier, or historical template, then correct with realized runtime load.

The key rule: SC/DD units can be arbitrary, but they must be counted the same way during calibration and runtime sizing.

## Product implication

The first product wedge is **object-provenance verification for AI-agent writes**, not a standalone metric dashboard.

> Schema validation checks that it is a customer ID. Provenance guardrails check that it is the right customer for this task.

The same provenance graph then becomes the ESL measurement instrument: it can block or flag wrong-object writes today, then learn which workflows can safely reduce human review or need slicing/routing tomorrow.

## Current implementation bridge

The next build slice is a shadow-mode provenance auditor MVP. It starts with a deterministic checker over ToolDAG-B research traces, hiding gold labels during checking and scoring precision/recall afterward. Only after that passes should the work move to entity-mapping UX and real-trace audits.

Public-safe milestone sequence:

1. Validate provenance/binding checks on gold-labeled research traces.
2. Prove tool→entity mapping can stay self-serve on messy catalogs.
3. Run a real trace-file-in → verified-near-miss-out audit in under an hour.

## Full report

- [Read the full ESL report as a standalone HTML artifact](/pixi-wiki/wiki/agent-workflows/assets/reports/esl-full-report.html)
- [Download the PDF](/pixi-wiki/wiki/agent-workflows/assets/reports/esl-full-report.pdf)
- [[../summaries/effective-state-load-full-report|Report summary and reading guide]]

## Related pages

- [[agent-tooling-plan]]
- [[world-model-control-surfaces]]
- [[self-improving-agent-systems]]
- [[context-overfitting]]
- [[visual-plan-review-surfaces]]


<!-- ===== agent-workflows/wiki/concepts/hermes-soul-md-wiring.md ===== -->

---
title: Hermes SOUL.md Wiring
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-systems, governance, workflow]
sources:
  - /root/.hermes/knowledge/concepts/hermes-soul-md-wiring.md
  - Knowledge/concepts/hermes-soul-md-wiring.md
confidence: high
---

# Hermes SOUL.md Wiring

## Definition

Hermes agent identity is wired through an uppercase `SOUL.md` file, not lowercase `soul.md`.

This matters on Linux because paths are case-sensitive. A lowercase search can falsely report that profile identity files are missing even when `SOUL.md` exists.

## Current synthesis

| Scope | Canonical path |
|---|---|
| Default profile | `$HERMES_HOME/SOUL.md`, usually `~/.hermes/SOUL.md` |
| Named profile | `~/.hermes/profiles/<name>/SOUL.md` |

`SOUL.md` is the identity/system-prompt surface for a Hermes profile. It should be understood together with profile memory, tools, model/provider configuration, and route contracts. The SOUL file says who the profile is; an [[agent-capability-route-pattern]] says when that profile may act.

## Application

When auditing or debugging profile identity:

1. use uppercase `SOUL.md` in file searches;
2. verify the active profile with Hermes profile/runtime commands when available;
3. distinguish default Pixoid identity from named peer identities;
4. compare requested profile and actual profile before claiming a route ran under a named peer;
5. treat missing/changed SOUL files as profile/config work, not as a generic knowledge-page edit.

## Boundaries

- Do not write lowercase `soul.md` guidance.
- Do not modify `SOUL.md`, profile config, providers, gateways, cron, or secrets from this concept page.
- Do not infer a live route from the presence of a `SOUL.md` file. Profile identity exists separately from trigger/routing proof.
- Do not claim Quill, Boba, Tinker, or another peer profile executed work unless route evidence verifies the actual profile.
- Keep profile-specific persona details in the profile and route artifacts, not in generic concept pages.

## Related pages

- [[agent-capability-route-pattern]]
- [[peer-profiles-vs-child-processes]]
- [[profile-memory-boundaries]]
- [[runtime-memory-knowledge-routing]]
- [[workspace-autonomy-levels]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/hermes-soul-md-wiring.md`


<!-- ===== agent-workflows/wiki/concepts/high-agency-work-levels.md ===== -->

---
title: High Agency Work Levels
created: 2026-06-26
updated: 2026-06-26
type: concept
description: Operating ladder for moving agent work from problem alerts to recommendations, verified fixes, and system improvements without crossing approval boundaries.
status: active
domain: agent-systems
tags: [agent-systems, workflow]
sources: [Knowledge/concepts/high-agency-work-levels.md, hermes-skill:agent-workflow-os]
confidence: medium
---

# High Agency Work Levels

## Definition

High-agency work compresses uncertainty into a decision or a verified action instead of merely reporting friction.

For Jamie's agent crew, the default posture is:

> **Level 4 by default. Level 5 when safe. Level 6 when the pattern repeats.**

## The ladder

| Level | Agent behavior | Good output |
|---|---|---|
| 1 | Alert | “There is a problem.” |
| 2 | Diagnose | “There is a problem, and here are likely causes.” |
| 3 | Options | “Here is the problem, likely causes, and possible fixes.” |
| 4 | Recommend | “Here is the problem, likely cause, options, and the path I recommend.” |
| 5 | Closed loop | “I found it, fixed it, verified it, and here is the proof.” |
| 6 | System improvement | “This pattern recurs, so I patched the workflow/check/skill/test/route/handoff to reduce recurrence.” |

## Pixoid operating rule

Pixoid should live at **Level 4** for analysis, planning, review, and any task with approval or side-effect uncertainty. That means giving Jamie a recommendation, not just a list of observations.

Pixoid may rise to **Level 5** only when the action is:

- safe and scoped;
- reversible or already approved;
- inside the current task boundary;
- verifiable with real output;
- not a secret, deploy, destructive change, broad rewrite, public post, or unauthorized merge.

Use **Level 6** only when a repeated failure class appears. A one-off correction does not need new process; a recurring miss should become a better skill, check, test, route contract, or handoff template.

## Crew applications

- **Pixoid:** default to Level 4; move to Level 5 for safe verified actions; use Level 6 for repeated operating-system fixes.
- **Tinker:** target Level 5 on implementation slices: code changed, tests run, proof reported.
- **Quill:** target Level 4+ on scribe work: state what changed, why it matters, and the next source-of-truth update.
- **Boba:** target Level 4 on research: evidence, implication, recommendation, and uncertainty boundaries.

## Useful report shapes

For unresolved or approval-gated work:

```text
Problem:
Evidence:
Likely cause:
Options:
Recommendation:
What I can do now:
What needs Jamie approval:
```

For closed-loop work:

```text
Found:
Did:
Verified:
Proof:
Next:
```

## Boundaries

High agency is not permissionless autonomy. If a step would change public state, mutate runtime/profile/secrets, deploy, merge, delete, rewrite broadly, or expand scope materially, stop at Level 4 and ask Jamie for the decision.

## Related pages

- [[agent-skill-routing]]
- [[self-improving-agent-systems]]
- [[agent-capability-route-pattern]]
- [[profile-memory-boundaries]]


<!-- ===== agent-workflows/wiki/concepts/knowledge-pack-routing.md ===== -->

---
title: Knowledge Pack Routing
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, knowledge-routing, llms-txt, kpr]
sources:
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing.md
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing V2.md
  - Projects/Hermes Mission Control/Knowledge Pack Contract V1.md
confidence: medium
---

# Knowledge Pack Routing

**Knowledge Pack Routing** is Jamie's markdown-first pattern for telling agents where durable truth lives before they start work.

It does not try to put every fact into one file. A pack is a map to truth: it states scope, freshness, source paths, fallback rules, and ownership so the agent can route itself to GitHub issues, Obsidian notes, skills, session search, or live tools.

## Why it exists

Without routing, agents waste context on archaeology, treat stale notes as current, or build infrastructure before proving retrieval failure. KPR makes the first step explicit: load the right compact contract, then follow canonical source links.

## Operating rule

A useful pack answers five questions quickly:

- What does this pack cover?
- What does it explicitly not cover?
- How fresh is it?
- Where are the canonical source paths?
- What should the agent do if the answer is missing, stale, or out of scope?

## Product judgment

KPR deliberately keeps MCP/RAG/search deferred until a concrete eval shows markdown routing cannot answer important questions. That turns retrieval infrastructure into a response to evidence, not a default reflex.

## Related pages

- [[agent-entrypoint-mesh]]
- [[static-retrieval-evals]]
- [[runtime-memory-knowledge-routing]]
- [[../entities/hermes-mission-control|Hermes Mission Control]]


<!-- ===== agent-workflows/wiki/concepts/matt-pocock-sdlc-rhythm.md ===== -->

---
title: Matt Pocock SDLC Rhythm
created: 2026-06-18
updated: 2026-07-09
type: concept
status: compiled
namespace: agent-workflows
tags: [workflow, agent-systems, product-management, design]
sources:
  - /root/.hermes/knowledge/concepts/matt-pocock-sdlc-rhythm.md
  - Knowledge/concepts/matt-pocock-sdlc-rhythm.md
confidence: high
---

# Matt Pocock SDLC Rhythm

## Definition

Jamie uses Matt Pocock-style skills as a pattern-based agent-assisted SDLC rhythm because they counter common agent failure modes: misalignment, missing shared language, weak feedback loops, solution-jumping, and codebase entropy.

Choose the path based on problem clarity and whether product/UI/workflow surface truth is needed. Do not force every request through one rigid pipeline.

## Lock vs key framing

A feature request is a **possible key**. The real user problem, workflow friction, domain constraint, trust gap, or decision bottleneck is the **lock**.

The agent should not rush to compare keys. It should first understand the lock’s shape, then prototype or grill the right thing.

## Wayfinder on-ramp

Use `/wayfinder` before `/to-spec` when the effort is too foggy or too large for one agent session: greenfield projects, major frontend/product surface decisions, large migrations, or course/product planning. It creates a shared map issue with frontier tickets (`research`, `prototype`, `grilling`, `task`) and resolves one ticket per session until the route to a spec is clear.

Use `/research` for AFK source-reading tickets. Use `/prototype` when a decision needs a concrete UI/logic artifact. Use `/grilling`/`/domain-modeling` when the decision belongs to Jamie or the domain language.


## Pattern 1 — Problem seems clear, but surface truth is needed

Use when the domain problem sounds clear, but product/UI/workflow reality may reveal friction that prose misses.

Sequence:

`/prototype` → `/grill-with-docs` (or `/wayfinder` if foggy/too large) → `/to-spec` → human spec approval → `/to-tickets` → one frontier ticket at a time with `/implement` (`/tdd` + `/review`) → verify → `/handoff`

Why: visual and interactive surfaces often reveal missing states, wrong information hierarchy, trust gaps, awkward workflow loops, or language that sounds right but feels wrong in use.

## Pattern 2 — Problem is unclear or input is a premature key

Use when the input is a proposed solution, feature request, or “key” but the underlying domain problem / “lock” is fuzzy.

Sequence:

`/prototype` as probe to reveal the lock/problem shape → `/grill-with-docs` or `/wayfinder` → `/to-spec` → human spec approval → `/to-tickets` → one frontier ticket at a time with `/implement` (`/tdd` + `/review`) → verify → `/handoff`

Prototype-as-probe means creating small disposable artifacts where each variant tests a different lock hypothesis. The goal is not solution polish; the goal is to learn what problem is actually being solved.

Examples:

- “Build an agent dashboard” → probe visibility, control, and trust/evidence surfaces.
- “Add notifications” → probe state-change indicators, audit trails, and digest/subscription flows.
- “Improve CRM deal view” → probe timeline-first, stage-board, and command-center layouts.

## Pattern 3 — Mostly non-visual domain / architecture / rule uncertainty

Use when the uncertainty is primarily terminology, bounded contexts, rules, state transitions, architecture, or trade-offs and a visual surface is unlikely to teach much.

Sequence:

`/grill-with-docs` → `/to-spec` → human spec approval → `/to-tickets` → one frontier ticket at a time with `/implement` (`/tdd` + `/review`) → verify → `/handoff`

If uncertainty becomes experiential or hard to reason about in words, switch back to `/prototype` as a probe or logic/state prototype.

## Visual plan review gate

Use [[visual-plan-review-surfaces]] when a spec, implementation plan, or ticket plan needs an inspectable artifact before execution. This is an optional review gate between `/to-spec` and `/to-tickets`, or between an implementation plan and `/implement`.

Jamie's default is local/private MDX artifacts under `.agent-native/plans/<slug>/`, not hosted share links or comment workflows. The visual plan should preserve durable truth in the spec/GitHub/vault source while making the plan easier to inspect: file maps, diagrams, UI states, annotated code, open questions, and verification gates.

## Compound Engineering compatibility

[[compound-engineering-skill-layer]] is compatible with this rhythm, but it packages the loop differently. Pocock/Jamie skills are modular gates for prototype, grill, spec, ticket slicing, TDD, review, and handoff. Compound Engineering is an integrated repo-local loop with `ce-brainstorm`, `ce-plan`, `ce-work`, `ce-simplify-code`, `ce-code-review`, and `ce-compound` sharing a unified plan artifact and project-local learning trail. Upstream docs may write these as `/ce-*`; on Discord that is skill shorthand unless a native slash command exists.

Use CE when the active repo should follow that integrated loop. Use this SDLC rhythm when Jamie needs explicit prototype/spec/ticket approval gates, a portfolio/product artifact, or a narrower one-issue implementation path.

## Source-backed best practices

[[matt-pocock-skills-best-practices]] preserves the source-backed pattern from `mattpocock/skills`: small composable skills, grilling for alignment, shared language docs, feedback loops, and architecture discipline. This SDLC rhythm is Jamie's generalized implementation sequence for applying those practices without turning them into a rigid framework.

## Router skill layer

The Pocock skill layer is a router and decomposition toolkit, not a reason to skip current evidence.

Useful routes include:

- `ask-matt` — choose which Matt-style flow fits the situation.
- `grilling` / `grill-me` / `grill-with-docs` — pressure-test the problem, language, and assumptions.
- `wayfinder` — chart a foggy multi-session effort as a shared map of decision/research/prototype/task tickets.
- `research` — delegate AFK source reading into a cited Markdown finding file.
- `diagnosing-bugs` — build a tight failing loop before fixing hard bugs.
- `implement` — implement a bounded piece of work from an approved spec or ticket.
- `codebase-design` — reason about deep modules and vocabulary before changing code.
- `domain-modeling` — sharpen domain language and boundaries.
- `writing-great-skills` — improve reusable skill artifacts.

## Applications

- Use [[find-the-lock-problem-first]] before treating a feature request as the real problem.
- Do not skip `/prototype` just because a product/UI/workflow problem sounds clear.
- Use `/prototype` as a probe when the lock/problem shape is unclear.
- Use `/grill-with-docs` for alignment, ubiquitous language, `CONTEXT.md`, and ADR capture.
- Use `/to-spec` as the lean spec spine; do not proceed to tickets until approved.
- Use `visual-plan` when the spec or implementation plan needs a richer local review surface before tickets or code.
- Use `/to-tickets` for vertical tracer-bullet slices, not horizontal layers.
- Use `/tdd` for red-green implementation loops; refactoring belongs in `/review`.
- Use `/handoff` to keep continuity across fresh contexts.
- Use Smart Zone discipline: watch context around 30%, checkpoint/stop before 40%, then continue in a fresh session with handoff.
- Run a [[context-overfitting]] check when a past skill, memory, or project note seems to override current user intent or live evidence.

## Boundaries

- Do not import transient issue, PR, commit, or project milestone state into this concept.
- Do not treat a skill’s existence as authorization to create issues, merge, deploy, change profiles, or trigger worker routes.
- Do not let written SDLC preferences override a current explicit user instruction, live evidence, or the active route contract.

## Related pages

- [[matt-pocock-skills-best-practices]]
- [[compound-engineering-skill-layer]]
- [[visual-plan-review-surfaces]]
- [[find-the-lock-problem-first]]
- [[issue-driven-afk-workflow]]
- [[smart-zone-context-discipline]]
- [[workspace-autonomy-levels]]
- [[context-overfitting]]
- [[agent-capability-route-pattern]]
- [[bounded-context-tree-pattern]]


<!-- ===== agent-workflows/wiki/concepts/matt-pocock-skills-best-practices.md ===== -->

---
title: Matt Pocock Skills Best Practices
created: 2026-06-19
updated: 2026-07-09
type: concept
description: Best-practice pattern from Matt Pocock's skills repo for reducing agent misalignment through small composable skills, grilling, shared language, feedback loops, and architecture discipline.
status: compiled
namespace: agent-workflows
domain: agent-systems
tags: [workflow, agent-systems, architecture]
sources:
  - Knowledge/concepts/matt-pocock-skills-best-practices.md
  - Knowledge/raw/articles/matt-pocock-skills-readme.md
  - https://github.com/mattpocock/skills
confidence: high
---

# Matt Pocock Skills Best Practices

## Definition

Matt Pocock's `skills` repo is a reusable best-practice pattern for reducing agent misalignment while keeping the human in control. The key move is not “let a framework own the process”; it is “give the agent small, composable operating skills that make alignment, shared language, feedback, and design discipline repeatable.”

For Jamie's workflow, this page is the source-backed best-practices concept. [[matt-pocock-sdlc-rhythm]] is the generalized implementation rhythm that translates those practices into Pixoid/Tinker execution gates.

## Misalignment reducers

1. **Keep skills small and composable.** Avoid monolithic process frameworks that hide control flow. Use focused skills that can be adapted per repo and per problem.
2. **Grill before building.** Misalignment is the default failure mode. Use `grill-me` / `grill-with-docs` to ask detailed questions before turning a vague request into implementation.
3. **Write shared language.** Use domain docs such as `CONTEXT.md` and ADRs so humans, agents, files, functions, and tests reuse the same domain terms instead of re-decoding jargon every run.
4. **Tighten feedback loops.** Red-green tests, static types, browser/runtime checks, diagnosis loops, and a separate review/refactor pass are the guardrails that stop aligned intent from becoming broken code.
5. **Care about codebase shape.** Agent speed can accelerate entropy. Use architecture/design review skills to keep modules deep, names consistent, and boundaries navigable.
6. **Separate orchestration from discipline.** User-invoked skills route and orchestrate; model-invoked skills hold reusable discipline. A router should not recursively invoke another user-invoked router.

## Implementation pattern

Use the repo as a menu of practices, not as a rigid mandatory pipeline:

- run setup once per repo so tracker labels and docs locations are explicit;
- choose the smallest skill that matches the current failure risk;
- preserve human approval gates before specs become tickets and before merge/deploy actions;
- verify with real tests/checks before claiming completion;
- capture durable learning in docs, issues, or skills rather than hidden chat memory.

## Relationship to Jamie's SDLC rhythm

[[matt-pocock-sdlc-rhythm]] generalizes the upstream repo into Jamie's default flow:

`/prototype` when surface truth or lock discovery is needed → `/grill-with-docs` for alignment and language, or `/wayfinder` when the effort is too foggy/large → `/to-spec` for the requirements spine → `/to-tickets` for vertical slices and blocking edges → `/implement` with `/tdd` and `/review` → verification → `/handoff`.

This concept explains **why** those gates reduce misalignment. The SDLC rhythm explains **when** to apply them.

## Version 1.1 note

Matt renamed the planning vocabulary to match the artifact: `/to-prd` became `/to-spec`, `/to-issues` became `/to-tickets`, and `/decision-mapping` became `/wayfinder`. Jamie’s Hermes install follows the new names, while upstream `/code-review` is locally exposed as `/review` because Jamie already has a broader Hermes `code-review` skill.

## Boundaries

- Do not use a skill repo as evidence that the agent may create issues, merge, deploy, or mutate runtime configuration without explicit scope and approval.
- Do not let a preferred workflow override current user intent, issue acceptance criteria, live evidence, or safety constraints.
- Do not copy upstream process wholesale when Jamie's repo already has a clearer source of truth; adapt the practice to the active project contract.

## Related pages

- [[matt-pocock-sdlc-rhythm]]
- [[find-the-lock-problem-first]]
- [[building-software-is-learning]]
- [[bounded-context-tree-pattern]]
- [[context-overfitting]]
- [[ponytail-minimal-code-discipline]]


<!-- ===== agent-workflows/wiki/concepts/multi-agent-multiplayer-boundaries.md ===== -->

---
title: Multi-Agent Multiplayer Boundaries
created: 2026-06-29
updated: 2026-06-29
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-systems, architecture, governance, workflow]
sources:
  - Knowledge/concepts/multi-agent-multiplayer-boundaries.md
  - Projects/Hermes Mission Control/Index.md
  - Knowledge/concepts/channel-scoped-agent-identities.md
  - Knowledge/concepts/agent-capability-route-pattern.md
  - Knowledge/concepts/peer-profiles-vs-child-processes.md
confidence: high
---

# Multi-Agent Multiplayer Boundaries

## Definition

A **multi-agent multiplayer experience** is a collaboration surface where several agent identities can participate around the same human task without losing turn-taking, accountability, source-of-truth discipline, or safety.

The hard part is not making several agents answer. The hard part is making the right agents stay quiet, preserving one user-facing owner, isolating work surfaces, and verifying any side effects before they become durable truth.

## Current synthesis

Treat multiplayer agents like a distributed system plus a chat UX problem. The default should be coordinator-mediated collaboration, not every bot independently responding in the same thread.

Use four explicit modes:

| Mode | Contract | Default? |
|---|---|---|
| Coordinator mode | Pixoid owns the user thread, routes work, verifies results, and posts one final answer. | Yes |
| Specialist mode | A direct `@Boba`, `@Quill`, or `@Tinker` call wakes only that named profile/route. | Yes |
| Bounded huddle / workbench council | Pixoid opens a bounded huddle or workbench thread for agent discussion, closes on all-replied-or-timeout, then summarizes/decides. | Preferred for crew input |
| Direct multiplayer | Multiple live agents may speak in the same user thread. | Test-only / explicit opt-in |

The core invariant:

```text
user message -> route classifier -> one visible owner -> optional workers -> verified artifact -> one final answer
```

## Implemented council-mode hardening (2026-06-29)

The 2026-06-29 Discord council-mode hardening slice turned the boundary model into live gateway behavior for Jamie's crew:

- `@Crew` and crew text aliases route to Pixoid/default as coordinator; they do not wake every worker bot.
- Direct `@Boba`, `@Quill`, and `@Tinker` remain specialist summons in approved channels/threads; they do not wake from untagged top-level-channel chatter.
- Pixoid can open a bounded huddle, collect one short worker round, close on all-replied-or-timeout, and post one final answer to the original thread.
- Closed huddle route records are enforced in the adapter/gateway path: ambient worker/bot chatter after close is dropped before model invocation.
- Discord reply pings do not count as direct summons unless the message text explicitly includes the bot mention or an owned council role mention.
- Top-level shared channels can be stricter than huddle threads: `discord.channel_allow_bots: none` blocks bot/status chatter in channels while preserving `allow_bots: mentions` for thread handoffs. Worker profiles share Pixoid's approved room allowlist but still require direct mentions in top-level channels.
- Prompt-level silence is a useful belt, not the lock. The lock is router-level suppression plus replay coverage.

## Boundary conditions

### 1. Summoning and routing

- `@Crew` must not blindly wake every bot; it should wake Pixoid as coordinator unless direct multiplayer is explicitly enabled.
- Role mentions, user mentions, text aliases, quoted messages, edited messages, replies, thread names, and topic metadata need separate trigger handling.
- Agent replies should not accidentally summon other agents unless the route contract permits that chain.
- Discord reply metadata is not enough to prove a direct summon; direct calls should be based on explicit textual bot/role mentions or a route-owned trigger.
- Webhook personas are outbound display identities only; they are not proof of an inbound, pingable agent route.
- A crew request can mean opinions, delegation, workbench council, or live multiplayer; the route must classify which one before acting.

### 2. Turn-taking and closure

- Without a single visible owner, agents duplicate answers, interrupt each other, debate endlessly, or bury the useful answer.
- Each worker needs an explicit stop condition and return format.
- The coordinator decides when enough input exists and closes the loop.
- Closed route state must suppress post-close worker/bot chatter at the adapter or router layer; prompt-level silence is not sufficient.
- Agent-to-agent discussion belongs in a workbench surface by default, not the main user thread.

### 3. Identity and accountability

- Do not claim “Boba/Quill/Tinker did this” unless route evidence proves the requested profile, actual profile, trigger, artifact, verification proof, and Pixoid review.
- Child/subagent analysis is useful, but it is not named peer-profile execution.
- Profile memories, credentials, tool scopes, and delivery identities must not silently bleed across agents.
- A model is not an identity; the identity lives in the profile, route, memory boundary, tools, and audit trail.

### 4. Context and memory

- Different agents may see different thread slices, stale memories, or different source-truth surfaces.
- Discord is discussion/notification, not canonical project truth.
- Daily notes and cron outputs are scratch/context, not compiled truth unless promoted and verified.
- Long-term facts route to memory only when compact and stable; concepts route to Knowledge/Pixi Wiki; procedures route to skills; project state routes to GitHub/Obsidian project hubs.
- Written context should be a weak prior, not a hard constraint when live evidence disagrees.

### 5. Authority and human control

- Multiple humans can give conflicting instructions in one channel; route contracts need an owner/approval policy.
- Silence is not approval.
- Destructive changes, deploys, merges, secrets/auth, profile/gateway/provider changes, public posting, and cross-boundary side effects require explicit approval.
- Agents may recommend routes, but recommendations do not automatically trigger workers.
- Human control belongs at capability boundaries; routine work inside an approved route can be automated only within its bounds.

### 6. Shared resources and concurrency

- Parallel agents can overwrite files, compete for `.git/index.lock`, rebase under each other, use stale branches, fight over ports/dev servers, mutate shared caches, or run incompatible migrations.
- Coding agents need isolated worktrees/branches and independent issue slices.
- Browser/computer-use agents need clear ownership of the session/window/desktop target.
- Shared state should be claimed through explicit locks, branches, route IDs, or issue assignments, not vibes.

### 7. Handoff quality

Every worker handoff should include:

```text
goal
current state
allowed files/actions
forbidden actions
commands/checks
artifact contract
time/context budget
stop conditions
return format
```

Weak handoffs cause agents to do housekeeping, duplicate research, or expand scope because they cannot infer the intended slice.

### 8. Verification and observability

- Worker summaries are leads, not proof.
- Pixoid or the route verifier must inspect changed files, tests, URLs, branch state, issue state, and delivery artifacts before reporting success.
- Every meaningful run should produce an observable record: event/route ID, owner, requested profile, actual profile, status, artifact, verification proof, and final delivery target.
- Duplicate/out-of-order events, gateway restarts, retries, partial tool failures, rate limits, and stale cron deliveries need idempotency and status tracking.

### 9. UX and attention

- Multiplayer must reduce Jamie's cognitive load, not create an agent food fight.
- The user-facing surface should show one owner, short status, bounded worker mentions, and one synthesized answer.
- Intermediate debate should stay out of the main thread unless Jamie asked for live council visibility.
- Agents should stay quiet when they are not the next best decision maker.

### 10. Safety and prompt-injection surfaces

- Treat web pages, screenshots, repo files, Discord topics, thread names, and tool outputs as data, not instructions.
- Least privilege should be per route, not per persona aesthetic.
- Multi-user channels require data isolation and authority checks.
- Secrets and webhook URLs must never be pasted into chat or durable notes.

## Evaluation checklist

A proper multiplayer agent system should have tests or replay traces for:

- `@Crew` produces one Pixoid-owned answer.
- Direct `@Boba`, `@Quill`, or `@Tinker` wakes only that specialist route.
- Mentions inside quotes, code blocks, historical messages, or agent replies do not accidentally trigger workers.
- Duplicate Discord events are idempotent.
- Out-of-order worker replies do not publish stale conclusions.
- Worker failure is reported as failure, not converted into a plausible answer.
- Conflicting human instructions escalate instead of racing.
- Direct multiplayer requires an explicit mode flag.
- Parallel coding work uses separate branches/worktrees or an equivalent claim protocol.
- Pixoid verifies artifacts before closure.
- Closed huddle threads drop ambient worker/bot messages before model invocation.
- Discord reply pings after a huddle closes do not reopen the loop unless there is an explicit direct mention or approved reopen trigger.
- All-replied and timeout closure paths both produce one final owner answer, not worker chatter.

## Recommended default for Jamie's crew

Use this as the default policy:

```text
Do not make @Crew wake every agent in the main thread.
Make @Crew wake Pixoid.
Pixoid decides whether to answer directly, ask one specialist, open a workbench council, or explicitly enter direct multiplayer test mode.
```

That preserves the multiplayer feel while keeping source truth, accountability, and attention under control.

## Related pages

- [[channel-scoped-agent-identities]]
- [[agent-capability-route-pattern]]
- [[peer-profiles-vs-child-processes]]
- [[runtime-memory-knowledge-routing]]
- [[context-overfitting]]
- [[self-improving-agent-systems]]


<!-- ===== agent-workflows/wiki/concepts/peer-profiles-vs-child-processes.md ===== -->

---
title: Peer Profiles vs Child Processes
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-systems, governance, workflow]
sources:
  - /root/.hermes/knowledge/concepts/peer-profiles-vs-child-processes.md
  - Knowledge/concepts/peer-profiles-vs-child-processes.md
confidence: high
---

# Peer Profiles vs Child Processes

## Definition

Jamie’s named crew agents are **peer Hermes profiles by default**, not Pixoid-owned child processes.

Peer profiles have their own identity surface, memory boundary, tool configuration, and route evidence. Child processes or `delegate_task` subagents are temporary workers inside the current session; they can analyze, draft, or review, but they do not prove that a named peer profile executed work.

## Current synthesis

Use the distinction this way:

| Execution shape | Use it for | Do not use it for |
|---|---|---|
| Peer Hermes profile | Named crew execution with profile identity, credentials, memory boundary, route logs, and durable audit requirements. | Fast in-session synthesis when no real profile route is needed. |
| Child/subagent process | Local read-only research, drafting, compatibility review, or linting that Pixoid will synthesize and verify. | Claiming “Tinker/Quill/Boba did this,” persistent route proof, profile-specific credentials, or live side effects. |

Pixoid remains the control plane: clarify scope, route work, verify output, and report to Jamie. Named peers may execute bounded work when an [[agent-capability-route-pattern]] exists and current authorization allows it.

## Application

Before saying a named peer did work, verify route evidence:

1. requested profile;
2. actual profile;
3. route trigger or handoff;
4. output artifact;
5. verification proof;
6. Pixoid review or closure comment.

If those are absent, describe the work as child-subagent analysis, local synthesis, or Pixoid-authored output.

## Boundaries

- Do not trigger Quill, Boba, Tinker, or recursive worker chains from a concept page or Documentation Hygiene note.
- Do not treat persona wording, a child-agent summary, or a simulated viewpoint as live peer-profile execution.
- Do not route one worker profile directly into another unless an explicit route contract authorizes that chain.
- Do not let profile memories bleed across profiles; use [[profile-memory-boundaries]] and [[runtime-memory-knowledge-routing]] to choose the correct layer.
- Do not use child agents for durable side effects that require named accountability unless Pixoid verifies the resulting artifact independently.

## Related pages

- [[agent-capability-route-pattern]]
- [[hermes-soul-md-wiring]]
- [[profile-memory-boundaries]]
- [[workspace-autonomy-levels]]
- [[issue-driven-afk-workflow]]
- [[self-improving-agent-systems]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/peer-profiles-vs-child-processes.md`
- `/root/ObsidianVault/Projects/Hermes Mission Control/Index.md`
- `/root/ObsidianVault/Projects/Pixoid Agent Capability Routes/Index.md`


<!-- ===== agent-workflows/wiki/concepts/ponytail-minimal-code-discipline.md ===== -->

---
title: Ponytail Minimal Code Discipline
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, code-review, minimalism, verification]
sources:
  - Knowledge/concepts/ponytail-minimal-code-discipline.md
  - /root/.hermes/skills/software-development/ponytail-code-discipline/SKILL.md
confidence: high
---

# Ponytail Minimal Code Discipline

**Ponytail** is a minimal-code discipline for agentic coding work: write only the code the current task needs, prefer native/stdlib/existing-dependency solutions, and run a separate simplification pass during review.

It is a workflow guardrail, not a product spec or always-on personality override.

## Build ladder

1. Does this need to exist?
2. Does stdlib/browser/native platform already do it?
3. Does an existing dependency solve it?
4. Can it be one line or one small function?
5. Only then, write the minimum code that satisfies the current issue.

## Where it belongs

- Coding workflows before implementation.
- Pre-PR checks.
- Pixoid/Tinker PR review passes.
- Reusable Knowledge and skill surfaces.
- Project-specific repo docs only after a concrete project adopts it.

## Boundaries

Ponytail cannot simplify away:

- Jamie's current instruction.
- GitHub issue / PRD acceptance criteria.
- Security, auth, secrets, and trust-boundary validation.
- Accessibility basics.
- Data-loss prevention and persistence/recovery requirements.
- Evidence quality, eval proof, or human decision authority.
- One small runnable check for non-trivial logic.

Current user instruction, issue scope, and safety gates beat memory or generic Ponytail preference.

## Review seam

Run two passes:

1. **Correctness pass:** scope, acceptance criteria, tests, UX, security, accessibility, product/evidence gates.
2. **Ponytail pass:** `delete`, `stdlib`, `native`, `yagni`, and `shrink` findings only.

If there is nothing to cut: `Ponytail: lean already.`

## Source

Compiled from `Knowledge/concepts/ponytail-minimal-code-discipline.md` and the Hermes `ponytail-code-discipline` skill.


<!-- ===== agent-workflows/wiki/concepts/profile-memory-boundaries.md ===== -->

---
title: Profile Memory Boundaries
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, memory, governance, source-of-truth]
sources:
  - Knowledge/concepts/profile-memory-boundaries.md
confidence: high
---

# Profile Memory Boundaries

**Profile memory boundaries** define where durable knowledge belongs across Jamie's agent system. The core rule is: save facts to the smallest layer that will help future runs without turning memory into a wiki dump.

## Boundary model

- `USER.md` holds universal person-level operating facts and preferences.
- Profile `MEMORY.md` holds compact profile-specific routing facts and durable environment lessons.
- Local Hermes knowledge holds reusable agent-operational concepts and dossiers.
- Obsidian/GitHub hold project state, strategy, PRDs, issues, and long-form truth.
- Skills hold repeatable procedures and pitfalls.

## Agent workflow rule

Before saving knowledge, classify it. Universal preferences go to user memory. Reusable frameworks go to knowledge pages. Project state goes to project hubs or GitHub. Repeatable procedures go to skills. Temporary task progress, PR numbers, command logs, and issue status do not belong in always-injected memory.

## Cross-namespace links

- `pixi-vault` — source classes and Wiki Compiler Maps depend on this boundary.
- `eval-trace` — context-overfit checks verify agents did not trust the wrong layer.

## Source

Compiled from `Knowledge/concepts/profile-memory-boundaries.md`.


<!-- ===== agent-workflows/wiki/concepts/reader-centered-outreach-asks.md ===== -->

---
title: Reader-Centered Outreach Asks
created: 2026-07-01
updated: 2026-07-13
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/reader-centered-outreach-asks.md
confidence: high
---

# Reader-Centered Outreach Asks

A **reader-centered outreach ask** is a cold DM, cold email, intro request, or help request drafted from the recipient's mind rather than the sender's need.

Core rule:

> Put yourself in the reader's mind. Make the recipient want to help **you**, understand the context quickly, accept at low cost, and decline without pressure.

Use this when drafting cold outreach for Jamie or when an agent is asked to turn a vague “can you help me?” into a message someone can comfortably answer.

## Drafting contract

Before drafting, identify:

1. **Recipient mind** — what this person already cares about or has context for.
2. **Proof of work** — the strongest real evidence that the sender is serious.
3. **Tiny context** — the unsummarizably short reason this message exists.
4. **Specific bounded ask** — one small action, answer, intro, resource, or review.
5. **Easy no** — a graceful exit that keeps the relationship clean.

If a field is missing, use a placeholder or ask for it. Do not invent facts.

## Credibility hierarchy

1. **Proof of work** — strongest: shipped project, model, case study, blog post, prototype, analysis, repo, demo, portfolio piece, or other real artifact.
2. **Personal connection** — useful only when real and safe; it borrows the connector's credibility.
3. **Institutional credibility** — weakest; schools, employers, and titles can situate someone but should not be the whole case.

For Jamie, use true project artifacts and portfolio proof. Do not fake metrics, inflate titles, or manufacture familiarity.

## Context rule

Keep context so short it is hard to summarize further. Connect the message to what the recipient already knows.

Avoid life story, vague passion, internal drama, or generic admiration. Prefer a specific bridge between the sender's work and the recipient's world.

## Ask rule

Make the request easy to accept:

- small magnitude;
- specific;
- low friction;
- bounded to one instance.

“Could you point me to one resource?” usually beats “Can I pick your brain?” If asking for an intro, include a forwardable blurb.

## No-pressure rule

Make it easy to say no. A pressured yes is worse than a clean no because it poisons the relationship and produces half-hearted help.

Good exits: “Totally fine if not,” “No worries if you are not the right person,” or “A pointer to a better resource/person would also help.”

## Message formula

```text
Hi [Name] — I saw [specific work/context].
I’m [who the sender is + real proof of work].
I’m trying to [tiny context connected to their world].
Would you be open to [specific bounded ask]?
[Low-friction artifact/question/blurb]. Totally fine if not.
```

## Agent behavior

- Start from the recipient's perspective, not the sender's biography.
- Use the strongest true proof of work available.
- Keep context shorter than feels comfortable.
- Replace “pick your brain” with a concrete written question or bounded next step.
- Include an easy no.
- Never lie.
- If the request is too large, shrink it before polishing the prose.

## Source

Canonical source: `Knowledge/concepts/reader-centered-outreach-asks.md`.

Primary article source: `Knowledge/raw/articles/how-to-ask-for-help-from-people-who-dont-know-you.md`.

Related pages: [[concepts/agent-skill-routing|Agent Skill Routing]], [[concepts/agent-tooling-plan|Agent Tooling Plan]], [[../../ai-native-product-surfaces/wiki/concepts/verb-first-product-positioning|Verb-First Product Positioning]], [[../../ai-native-product-surfaces/wiki/concepts/find-the-lock-problem-first|Find the Lock Problem First]], [[../../ai-native-product-surfaces/wiki/syntheses/side-doors-make-useful-work-legible|Side Doors: Make Useful Work Legible]].


<!-- ===== agent-workflows/wiki/concepts/runtime-memory-knowledge-routing.md ===== -->

---
title: Runtime Memory Knowledge Routing
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, memory, routing, knowledge-management]
sources:
  - Knowledge/concepts/runtime-memory-knowledge-routing.md
confidence: high
---

# Runtime Memory Knowledge Routing

**Runtime memory knowledge routing** is the live decision rule for combining injected memory, Honcho, local Hermes knowledge, Obsidian Knowledge, skills, GitHub/project truth, and session search while doing work.

## Layer model

- Injected memory and user profile are hints, not proof.
- Honcho provides recalled peer context and synthesis.
- Local Hermes knowledge carries reusable agent-operational concepts.
- Obsidian Knowledge carries human-facing durable concepts and source-backed synthesis.
- Projects and GitHub carry current project truth.
- Skills carry procedures.
- Session search recovers prior conversation context, but is never canonical alone.

## Operating pattern

1. Start with injected memory as routing context.
2. Load relevant knowledge/wiki packs when the task touches a durable domain.
3. Verify live project/runtime state before acting on current facts.
4. Promote durable learning to the narrowest correct layer after the work.
5. Never save raw outputs, issue progress, PR numbers, or command logs to memory.

## Source

Compiled from `Knowledge/concepts/runtime-memory-knowledge-routing.md`.


<!-- ===== agent-workflows/wiki/concepts/self-improving-agent-systems.md ===== -->

---
title: Self-Improving Agent Systems
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, governance, agent-evolution, evidence]
sources:
  - Knowledge/concepts/self-improving-agent-systems.md
confidence: high
---

# Self-Improving Agent Systems

A **self-improving agent system** improves through verified durable state, not model-weight updates. Each run can make future runs better by distilling evidence into knowledge, skills, routing contracts, project truth, and compact memory pointers.

Short form:

```text
observe → judge → verify → distill → write → consult next run
```

## What evolves

- Agent dossiers: role-specific feedback and review patterns.
- Knowledge concepts: reusable frameworks and distinctions.
- Skills: repeatable procedures, pitfalls, and verification routines.
- Cron/routing prompts: scheduled operating contracts and trigger behavior.
- Project source of truth: GitHub issues, PRs, project hubs, and evidence handles.
- Memory: compact last-mile routing facts only.

## Evidence gate

Durable changes need evidence: Jamie correction, verified regression, repeated pattern, or a single high-impact event. Weak signals should stay as observations.

## Verifier rule

Makers should not grade their own homework. Pixoid verifies worker output before closing issues or treating changes as durable truth.

## Source

Compiled from `Knowledge/concepts/self-improving-agent-systems.md`.


<!-- ===== agent-workflows/wiki/concepts/static-retrieval-evals.md ===== -->

---
title: Static Retrieval Evals
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: agent-workflows
tags: [agent-workflows, evals, retrieval, quality-gates]
sources:
  - Projects/Hermes Mission Control/KPR Static Retrieval Eval - 2026-06-15.md
  - Projects/Hermes Mission Control/kpr-v1-validation-report.md
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing V2.md
confidence: medium
---

# Static Retrieval Evals

**Static retrieval evals** are small question sets that test whether the current markdown/wiki routing surface answers important agent questions before heavier retrieval infrastructure is justified.

They are a build/no-build gate.

## What they test

A good static retrieval eval asks questions that reveal routing failures:

- Does the agent find the active repo or project?
- Does it distinguish canonical source truth from derived output?
- Does it understand what the pack does not cover?
- Does it preserve provenance and source boundaries?
- Does it avoid leaking secrets or relying on scratch notes?
- Does it know when to escalate to live tools or GitHub?

## Gate behavior

If the static eval passes, do not build search/RAG/MCP just because it feels sophisticated. Improve the markdown route only when the eval exposes a concrete failure.

If the eval fails, fix the cheapest layer first: source wording, index coverage, scope boundaries, crosslinks, or freshness metadata. Only then consider infrastructure.

## Related pages

- [[knowledge-pack-routing]]
- [[agent-entrypoint-mesh]]
- [Context Overfitting](../../../eval-trace/wiki/concepts/context-overfitting.md)


<!-- ===== agent-workflows/wiki/concepts/visual-plan-review-surfaces.md ===== -->

---
title: Visual Plan Review Surfaces
created: 2026-06-26
updated: 2026-07-09
type: concept
status: compiled
namespace: agent-workflows
source: Knowledge/concepts/visual-plan-review-surfaces.md
confidence: high
---

# Visual Plan Review Surfaces

A visual plan review surface turns a spec, PRD, implementation plan, or planned multi-file change into a local interactive MDX artifact that Jamie can inspect before code changes begin.

For Jamie's current workflow, the default is **local/private self-use**: local MDX files and local verification, not hosted publishing, share links, or comment workflows.

## Default artifact shape

```text
.agent-native/plans/<slug>/
  plan.mdx
  canvas.mdx        # only when UI/product visuals help
  prototype.mdx     # only when interaction matters
```

The `visual-plan` Hermes skill from BuilderIO's Agent-Native skills turns normal agent plans into a richer review medium: structured plan sections, file maps, diagrams, wireframes, annotated code, open questions, and optional prototype surfaces.

## Routing rules

- Load `visual-plan` when Jamie asks to turn a spec, PRD, ticket plan, implementation plan, or architecture/UI plan into a review surface.
- Use local/private mode by default. Hosted Agent-Native Plan auth, share links, and comments are optional, not prerequisites.
- Keep durable truth in source-controlled Markdown, Obsidian project hubs, GitHub tickets/issues, specs/PRDs, and handoffs. The visual surface is a review artifact, not the only source of truth.
- For UI/product work, include canvas wireframes or prototype surfaces only when they help review actual states or flows.
- For backend/architecture/data work, skip decorative UI and use document-local diagrams, file maps, annotated code, API/schema blocks, risks, and verification steps.
- Do not start implementation until the review surface has been generated and Jamie has approved the direction, unless the task is trivial or Jamie explicitly skips the gate.

## Where it fits

Visual-plan is an approval surface between planning and implementation:

- after `/to-spec` when the spec needs a richer review surface before ticket slicing;
- after an implementation plan when the plan touches multiple files, architecture, UX states, or open questions;
- before `/to-tickets` when the plan needs human review before creating execution slices;
- before `/implement` when an existing plan needs visual inspection rather than more chat discussion.

It complements [[matt-pocock-sdlc-rhythm]]: `/prototype` tests experiential unknowns, `/grill-with-docs` aligns language and decisions, `/to-spec` captures requirements, and `visual-plan` makes approved or near-approved plans inspectable.

## Boundaries

- Not for trivial one-line fixes or changes whose diff is easier to review than a plan.
- Not a substitute for live repo inspection, tests, GitHub tickets/issues, specs/PRDs, or handoffs.
- Not authorization to publish, deploy, share, or use hosted comment workflows.
- Not a place to store secrets, private customer data, or final project truth outside source-controlled plan files.

## Related pages

- [[matt-pocock-sdlc-rhythm]]
- [[agent-skill-routing]]
- [[../../ai-native-product-surfaces/wiki/concepts/agent-output-decision-artifacts|Agent Output Decision Artifacts]]
- [[../../ai-native-product-surfaces/wiki/concepts/interaction-mode-routing|Interaction Mode Routing]]
- [[../../ai-native-product-surfaces/wiki/concepts/material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]


<!-- ===== agent-workflows/wiki/entities/hermes-mission-control.md ===== -->

---
title: Hermes Mission Control
created: 2026-06-16
updated: 2026-06-29
type: entity
status: compiled
namespace: agent-workflows
tags: [agent-workflows, hermes, pixoid, route-governance]
sources:
  - Projects/Hermes Mission Control/Index.md
  - Projects/Hermes Mission Control/kpr-pixoid-routing-rule.md
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing.md
confidence: medium
---

# Hermes Mission Control

**Hermes Mission Control** is Jamie's agent-ops coordination hub for the Pixoid crew: Pixoid, Quill, Tinker, and Boba.

Its primary namespace is `agent-workflows` because the durable knowledge is not the public wiki itself. The durable knowledge is how agents coordinate work: route governance, persona boundaries, issue-backed execution, handoffs, review gates, and durable truth routing.

## Crew roles

- **Pixoid:** orchestrator, reviewer, route owner, final verifier.
- **Tinker:** builder for bounded implementation slices.
- **Quill:** scribe for vault/docs updates and compiled knowledge pages.
- **Boba:** explorer/researcher for external signal and reality checks.

## What it controls

- Crew role boundaries and operating surfaces.
- GitHub issue/PR coordination as durable work truth.
- Obsidian/Git as knowledge and project truth.
- Discord as notification surface, not durable truth.
- Discord council-mode routing: `@Crew`/crew aliases call Pixoid as coordinator by default; direct worker mentions call individual profiles; bounded huddles collect one worker round, close deterministically, and suppress post-close worker chatter at the gateway layer.
- Cron output as context, not canonical project state.
- Verification gates before tracker closure.


## Pixoid Review Surface

Interaction Mode Routing clarifies that chat is the command channel, not the whole Hermes interface. Pixoid should generate small review/control surfaces when Jamie needs to approve or steer work, while durable truth remains in GitHub issues/PRs, Obsidian hubs, handoffs, skills, and knowledge entrypoints.

The standard review surface includes status, evidence, risks, files/handles, verification run, options, and Pixoid's recommended next slice.

## Discord council-mode hardening milestone

As of 2026-06-29, the stable Discord contract is coordinator-first and gateway-enforced:

- `@Crew` / `<@&1521188694915158078>` is a Pixoid/default coordinator call.
- `crew:`, `get the crew`, and `calling the crew` are Pixoid/default text aliases.
- `@Boba`, `@Quill`, and `@Tinker` are direct specialist calls in approved channels/threads; they do not answer ambient top-level-channel chatter.
- If Pixoid needs visible crew discussion, it opens a bounded huddle tied to the triggering message/origin, waits for one short worker round or timeout, closes the huddle, and returns one final answer.
- Closed huddle threads suppress ambient worker/bot chatter before model invocation; prompt-level silence is not the enforcement layer.
- Discord reply pings are not direct summons unless the message text explicitly mentions the bot or an owned council role.
- Re-adding the shared `Crew` role to all worker bots is not the default because it causes duplicate independent work in the user thread.

## Routing significance

Hermes Mission Control feeds `pixi-vault` when compiler/publication rules are affected, and it feeds `eval-trace` when route quality or workflow evidence needs evaluation.

The project should not become a standalone namespace unless it grows an independent audience, source corpus, document types, and freshness lifecycle beyond the broader `agent-workflows` domain.

## Cross-namespace links

- `pixi-vault` — source/output repo boundaries and namespace compiler rules.
- `eval-trace` — route-quality checks and failure-mode evaluation, including [context overfitting](../../../eval-trace/wiki/concepts/context-overfitting.md).

## Related pages

- [[../concepts/knowledge-pack-routing|Knowledge Pack Routing]]
- [[../concepts/agent-entrypoint-mesh|Agent Entrypoint Mesh]]
- [Interaction Mode Routing](../../../ai-native-product-surfaces/wiki/concepts/interaction-mode-routing.md)
- [[../syntheses/pixoid-crew-operating-model|Pixoid Crew Operating Model]]

## Source

Compiled from `Projects/Hermes Mission Control/Index.md` and related KPR operating docs.


<!-- ===== agent-workflows/wiki/index.md ===== -->

---
title: Agent Workflows — Master Index
created: 2026-06-16
updated: 2026-07-09
type: index
status: compiled
namespace: agent-workflows
---

# Agent Workflows — Master Index

> Compiled index for `agent-workflows`.

## Concepts

- [[concepts/effective-state-load|Effective State Load]] — Workflow-specific agent load testing: calibrate SC/DD collapse frontiers, detect world-model collapse, and route from provenance guardrails toward capacity management.
- [[concepts/agent-capability-route-pattern|Agent Capability Route Pattern]] — Explicit trigger-to-profile route contract covering authorization, execution bounds, artifacts, verification, observability, and profile seam proof.
- [[concepts/agent-entrypoint-mesh|Agent Entrypoint Mesh]] — Typed starting points that route agents to the right truth surface.
- [[concepts/agent-skill-routing|Agent Skill Routing]] — Contract for choosing useful Hermes skills automatically and passing active constraints into delegated subagents.
- [[concepts/agent-tooling-plan|Agent Tooling Plan]] — Agent-as-tools playbook for mapping vague or clear requests into live-state checks, task buckets, tools, routing rules, memory, evaluation, permissions, and smallest proving loops.
- [[concepts/agentic-harness-engineering|Agentic Harness Engineering]] — Eve-derived pattern for building agents as inspectable runtime harnesses with explicit capability slots, trust boundaries, durable sessions, channels, sandboxing, and eval gates.
- [[concepts/compound-engineering-skill-layer|Compound Engineering Skill Layer]] — Guide for using EveryInc Compound Engineering skills inside Hermes and routing them against Jamie's existing skill stack.
- Cross-namespace concept: [[../../hermes-agent/wiki/concepts/hermes-capability-routing|Hermes Capability Routing]] — Selects the smallest effective Hermes surface for a task before work becomes a skill, subagent, cron, gateway/API, MCP/plugin, profile, kanban, provider, or vault/Pixi Wiki route.
- [[concepts/creative-ideation-routing|Creative Ideation Routing]] — Method-routed inspiration loop for using the `creative-ideation` skill without generic brainstorming.
- [[concepts/reader-centered-outreach-asks|Reader-Centered Outreach Asks]] — Cold DM/email/help-request drafting contract: recipient mind first, true proof of work, tiny context, specific bounded ask, easy no, and no lies.
- Cross-namespace concept: [[../../ai-native-product-surfaces/wiki/concepts/interaction-mode-routing|Interaction Mode Routing]] — Product/refactor lens that also defines Hermes review/control surfaces.
- Cross-namespace concept: [[../../ai-native-product-surfaces/wiki/concepts/agent-output-decision-artifacts|Agent Output Decision Artifacts]] — Compress verbose agent output into concise, visual, source-backed review/control artifacts when users need to decide, approve, compare, or steer.
- [[concepts/bounded-context-tree-pattern|Bounded Context Tree Pattern]] — Root/branch/leaf structure for project and knowledge contexts with explicit language boundaries and routing links.
- [[concepts/hermes-soul-md-wiring|Hermes SOUL.md Wiring]] — Uppercase `SOUL.md` profile identity wiring and profile-audit boundary for Hermes agents.
- [[concepts/high-agency-work-levels|High Agency Work Levels]] — Level 4+ operating ladder for recommendations, verified fixes, and system improvements with explicit approval boundaries.
- [[concepts/knowledge-pack-routing|Knowledge Pack Routing]] — Markdown-first maps to canonical truth for agent work.
- [[concepts/matt-pocock-sdlc-rhythm|Matt Pocock SDLC Rhythm]] — Pattern-based SDLC rhythm with lock/key framing, prototype-as-probe, Wayfinder, router skills, and grill/spec/ticket/TDD/review gates.
- [[concepts/matt-pocock-skills-best-practices|Matt Pocock Skills Best Practices]] — Source-backed best practices from `mattpocock/skills` for reducing agent misalignment through composable skills, grilling, shared language, feedback loops, and architecture discipline.
- [[concepts/multi-agent-multiplayer-boundaries|Multi-Agent Multiplayer Boundaries]] — Coordinator/specialist/workbench/direct-multiplayer mode contract plus edge cases for triggers, turn-taking, identity, context, authority, concurrency, handoffs, verification, UX, safety, and eval traces.
- [[concepts/peer-profiles-vs-child-processes|Peer Profiles vs Child Processes]] — Boundary between named peer profiles and local subagent fallback.
- [[concepts/ponytail-minimal-code-discipline|Ponytail Minimal Code Discipline]] — Minimal-code build/review guardrail that keeps implementation lean without weakening acceptance, safety, evidence, or verification gates.
- [[concepts/profile-memory-boundaries|Profile Memory Boundaries]] — Where durable knowledge belongs across memory, knowledge, projects, and skills.
- [[concepts/runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]] — How agents combine injected memory, Honcho, knowledge packs, skills, GitHub, and session search at runtime.
- [[concepts/self-improving-agent-systems|Self-Improving Agent Systems]] — How agents improve through verified durable state rather than weight updates.
- [[concepts/static-retrieval-evals|Static Retrieval Evals]] — Small retrieval question sets used as gates before heavier search/RAG/MCP infrastructure.
- [[concepts/visual-plan-review-surfaces|Visual Plan Review Surfaces]] — Local/private review artifacts for turning PRDs and implementation plans into inspectable MDX before code changes.
- Cross-namespace concept: [[../../eval-trace/wiki/concepts/context-overfitting|Context Overfitting]] — Eval Trace primary page for a workflow reliability failure mode.

## Entities

- [[entities/hermes-mission-control|Hermes Mission Control]] — Agent-ops coordination hub for Pixoid crew route governance, delivery boundaries, and durable work truth.

## Summaries

- [[summaries/agent-workflow-system-summary|Agent Workflow System Summary — Skills, Tools, Scheduling, Delegation]] — Compact summary of Jamie's agent workflow system: skills, tools, scheduling, delegation, control surfaces, verification, and durable knowledge routing.
- [[summaries/effective-state-load-full-report|Effective State Load Full Report]] — Reading guide for the full ESL HTML/PDF report: Phase 1/2/3 evidence, environment-generality verdict, and provenance-guardrail product path.
- Cross-namespace summary: [[../../hermes-agent/wiki/summaries/external-hermes-wikis-import-review|External Hermes Wikis Import Review]] — Routes external Hermes content between Hermes Agent, Agent Workflows, Local AI Infrastructure, Eval Trace, and Pixi Vault.

## Syntheses

- [[syntheses/markdown-first-agent-memory|Markdown-First Agent Memory]] — Why visible, versioned Markdown/issues/skills should carry durable operational knowledge before hidden infrastructure.
- [[syntheses/pixoid-crew-operating-model|Pixoid Crew Operating Model]] — Crew roles, source-of-truth boundaries, route rules, and verification gates.

## Source Roots

- `Projects/Effective State Load/Index.md`
- `Projects/Hermes Mission Control/Index.md`
- `Projects/Hermes Mission Control/PRD - Knowledge Pack Routing.md`
- `Projects/Hermes Mission Control/PRD - Knowledge Pack Routing V2.md`
- `Projects/Hermes Mission Control/Knowledge Pack Contract V1.md`
- `Projects/Hermes Mission Control/KPR Static Retrieval Eval - 2026-06-15.md`
- `Projects/Hermes Mission Control/kpr-pixoid-routing-rule.md`
- `Knowledge/concepts/self-improving-agent-systems.md`
- `Knowledge/concepts/profile-memory-boundaries.md`
- `Knowledge/concepts/runtime-memory-knowledge-routing.md`
- `Knowledge/concepts/agent-skill-routing.md`
- `Knowledge/concepts/agent-tooling-plan.md`
- `Knowledge/concepts/agentic-harness-engineering.md`
- `Knowledge/concepts/effective-state-load.md`
- `Knowledge/concepts/reader-centered-outreach-asks.md`
- `Knowledge/concepts/compound-engineering-skill-layer.md`
- `Knowledge/concepts/hermes-capability-routing.md`
- `Knowledge/concepts/high-agency-work-levels.md`
- `Knowledge/concepts/creative-ideation-routing.md`
- `Knowledge/concepts/interaction-mode-routing.md`
- `Knowledge/concepts/agent-output-decision-artifacts.md`
- `Knowledge/concepts/peer-profiles-vs-child-processes.md`
- `Knowledge/concepts/ponytail-minimal-code-discipline.md`
- `Knowledge/concepts/visual-plan-review-surfaces.md`
- `Knowledge/concepts/multi-agent-multiplayer-boundaries.md`

- `Knowledge/concepts/agent-capability-route-pattern.md`
- `Knowledge/concepts/hermes-soul-md-wiring.md`
- `Knowledge/concepts/matt-pocock-sdlc-rhythm.md`
- `Knowledge/concepts/matt-pocock-skills-best-practices.md`
- `Knowledge/concepts/bounded-context-tree-pattern.md`


<!-- ===== agent-workflows/wiki/log.md ===== -->

---
title: Agent Workflows — Activity Log
created: 2026-06-16
updated: 2026-07-13
type: log
status: compiled
namespace: agent-workflows
---

# Agent Workflows — Activity Log

> Append-only namespace log.

## 2026-07-13 update | Link outreach asks to Side Doors synthesis

- Cross-linked `reader-centered-outreach-asks.md` to the illustrated Side Doors synthesis in `ai-native-product-surfaces` so message drafting remains connected to the broader specificity, public-proof, and opportunity-search model.

## 2026-07-09 create | Agentic Harness Engineering

- Added compiled concept `wiki/concepts/agentic-harness-engineering.md` from the canonical Knowledge page and Eve docs/repo review.
- Captured the transferable harness pattern: identity, tools, skills, channels, connections, subagents, schedules, sandbox, durable sessions, and evals should live in explicit slots with enforceable trust boundaries.
- No public `pixi-wiki` deploy was pushed.

## 2026-07-07 update | Effective State Load to provenance-auditor bridge

- Refreshed the compiled Effective State Load concept after the research repo handoff changed from in-flight work to complete program state.
- Added the public-safe implementation bridge: a shadow-mode provenance auditor MVP that validates right-object checks on ToolDAG-B traces before moving to entity-mapping UX or real traces.
- Kept private repo/build details out of public namespace pages while preserving the product direction.

## 2026-07-05 update | Effective State Load full report + Phase 3 verdict

- Refreshed compiled concept `wiki/concepts/effective-state-load.md` after the `effective-state-load` repo reached commit `5fa535d` with Phase 3 complete.
- Added compiled summary `wiki/summaries/effective-state-load-full-report.md` and mirrored the standalone full report under `assets/reports/esl-full-report.html` plus PDF.
- Captured the current verdict: ESL generalizes as a metric family and calibration recipe, not as a portable formula; the product wedge is provenance guardrails for right-object writes.


## 2026-07-03 update | Effective State Load ToolDAG-B transfer

- Refreshed compiled concept `wiki/concepts/effective-state-load.md` after the repo docs re-based Phase 3 on ToolDAG-B.
- Preserved the current transfer decision: upstream `tool_dag` stays as an optional control, but the main transfer environment checks exact variable provenance/identity bindings because type-only validation is too weak a dependency stress.
- Added the ToolDAG-B DD-sweep gate before full Phase 3 grid spend.

## 2026-07-03 update | Effective State Load repo-based ESL experiment

- Refreshed compiled concept `wiki/concepts/effective-state-load.md` from the updated project and Knowledge notes.
- Replaced the old five-factor starting formula with the current first-test hypothesis: `ESL = SC × DD`.
- Captured the current run path: official `world-model-collapse` harness, OpenRouter smoke/grid, SC/DD heatmaps, ESL contour/bucket analysis, then ToolDAG-B transfer.

## 2026-07-03 create | Effective State Load

- Added compiled concept `wiki/concepts/effective-state-load.md` from the canonical Knowledge page and private `effective-state-load` research repo.
- Captured the ToolDAG/variable-graph experiment: measure when model-agent harnesses stop reliably maintaining typed tool variables and dependencies.
- Linked ESL to future task slicing/statechart orchestration while preserving no-public-deploy boundary for this update.

## 2026-07-01 create | Agent workflow system summary

- Added compiled summary `wiki/summaries/agent-workflow-system-summary.md` as a compact public summary of Jamie's agent workflow system: skills, tools, scheduling, delegation, Discord/GitHub control surfaces, verification, and durable knowledge routing.
- Cross-linked Hermes Mission Control, Pixoid Crew Operating Model, Agent Skill Routing, Multi-Agent Multiplayer Boundaries, Agent Capability Route Pattern, Agent Tooling Plan, Markdown-First Agent Memory, Knowledge Pack Routing, and Hermes Capability Routing.
- Kept the page focused on the agent workflow system itself and removed job-application-defensive framing.

## 2026-07-01 create | Reader-Centered Outreach Asks

- Added compiled concept `wiki/concepts/reader-centered-outreach-asks.md` from the canonical Knowledge page and Jamie's supplied article about asking strangers for help.
- Captured the cold outreach drafting contract for future agents: recipient mind first, proof of work over status, tiny context, specific low-friction bounded ask, easy no, and never lie.
- Updated namespace README and index source roots for public Pixi Wiki rebuild/deploy.

## 2026-06-30 update | Agent Tooling Plan skill v1.0.1

- Mirrored the tightened `agent-tooling-plan` skill into compiled namespace source.
- Added live-state-first planning, max-five grill questions, adjacent skill routing, a concrete email-triage mini-example, and the smallest proving loop guardrail.

## 2026-06-30 create | Agent Tooling Plan

- Added compiled concept `wiki/concepts/agent-tooling-plan.md` from Jamie's Agent-as-tools Product Playbook and the reusable Hermes skill.
- Captured the vague-vs-clear request split: vague requests produce a scaffold plus `/grill-me` or `/grill-with-docs` questions; clear requests produce a full task-bucket/tool/routing/memory/evaluation/permissions/feedback-loop plan.
- Updated namespace README and index source roots for public Pixi Wiki rebuild/deploy.

## 2026-06-29 update | Discord worker mention allowlist

- Recorded that Boba/Quill/Tinker worker gateways share Pixoid's approved Discord room allowlist but remain bounded by direct mentions in top-level channels.
- Captured the paired safety rule: `discord.channel_allow_bots: none` blocks bot/status chatter in top-level shared channels, while `allow_bots: mentions` keeps thread handoffs possible.

## 2026-06-29 update | Discord council-mode hardening shipped

- Updated compiled `agent-workflows` source pages after `pixiiidust/pixi-wiki` tracker #33–#41 closed for Discord council-mode hardening.
- Captured the shipped coordinator-first contract: `@Crew`/crew aliases route to Pixoid, direct worker mentions stay specialist-only, bounded huddles close on all-replied-or-timeout, and Pixoid returns one final answer.
- Added the live-loop lesson: prompt-level silence is insufficient; closed huddle worker/bot chatter must be suppressed at the adapter/gateway layer, reply pings must not reopen the loop without explicit textual mention/approved trigger, and top-level shared channels can use `discord.channel_allow_bots: none` while huddle threads preserve worker handoffs.
- This update is intended for public `pixi-wiki` rebuild/deploy.

## 2026-06-29 create/update | Multi-agent multiplayer boundaries

- Added compiled concept `wiki/concepts/multi-agent-multiplayer-boundaries.md` from the canonical Knowledge page and the Discord crew-edge-case analysis.
- Captured the four-mode contract: coordinator mode, specialist mode, workbench council, and explicit direct multiplayer test mode.
- Preserved edge cases for trigger parsing, turn-taking, identity proof, context/memory, authority, shared resources, handoffs, verification, UX, safety, and eval traces.
- No public `pixi-wiki` deploy was pushed.

## 2026-06-29 update | Discord crew routing coordinator mode

- Updated Hermes Mission Control and Pixoid Crew Operating Model with the settled Discord contract: `@Crew`/crew aliases wake Pixoid as coordinator, direct worker mentions wake individual profiles, and visible crew discussion belongs in topic-specific `#agent-workbench` threads.
- Captured the live failure mode: assigning the shared `Crew` role to every bot makes Boba/Quill/Tinker/Pixoid independently inspect and reply, causing duplicated work and noisy threads.
- Recorded the role-mention/human-mention adapter lesson without treating it as sufficient for true multiplayer; the remaining open thread is a coordinator-mediated council protocol.

## 2026-06-27 update | Agent Output Decision Artifacts crosslink

- Added cross-namespace routing to `ai-native-product-surfaces/wiki/concepts/agent-output-decision-artifacts.md` from the workflow index and Visual Plan Review Surfaces page.
- Preserved `agent-workflows` as the workflow layer while keeping the primary concept home under `ai-native-product-surfaces`.

## 2026-06-27 create | Compound Engineering skill layer

- Added compiled concept `wiki/concepts/compound-engineering-skill-layer.md` from the canonical Knowledge page and the installed EveryInc `compound-engineering-plugin`.
- Captured `ce-*` and `lfg` routing, how CE compares with Jamie's Pocock/product/review/vault skills, the Discord invocation caveat for `/ce-*` shorthand, and the approval boundaries around autopilot use.
- Updated namespace README and index source roots.
- No public `pixi-wiki` deploy was pushed.

## 2026-06-26 update | Hermes capability routing crosslink

- Added cross-namespace routing to `hermes-agent/wiki/concepts/hermes-capability-routing.md` so crew workflow readers can choose the right Hermes surface before turning work into skills, subagents, cron, profile/kanban routes, or publishing steps.
- Updated namespace README and index source roots.
- No Daily Notes were copied or compiled, and no public `pixi-wiki` deploy was pushed.

## 2026-06-26 create | High agency work levels

- Added compiled concept `wiki/concepts/high-agency-work-levels.md` from Jamie's Level 4+ agency framework and the patched `agent-workflow-os` skill.
- Captured the operating rule: Pixoid defaults to Level 4, moves to Level 5 only when safe/scoped/approved, and uses Level 6 for repeated failure classes.
- Updated namespace README and index source roots.

## 2026-06-26 create/update | Visual plan review surfaces

- Added compiled concept `wiki/concepts/visual-plan-review-surfaces.md` from the canonical Knowledge page and the local `visual-plan` Hermes skill.
- Updated `agent-skill-routing` and `matt-pocock-sdlc-rhythm` routing so PRDs and implementation plans can become local/private MDX review surfaces before code.
- Preserved the boundary that hosted share/comment links and public `pixi-wiki` deploys require explicit opt-in.

## 2026-06-24 create/update | Creative ideation routing

- Added compiled concept `wiki/concepts/creative-ideation-routing.md` from the canonical Knowledge page and the `creative-ideation` Hermes skill.
- Updated `agent-skill-routing` so open-ended inspiration, brainstorming, project ideas, and option generation route through `creative-ideation` by default.
- Updated namespace README and index source roots.
- No Daily Notes were copied or compiled, and no public `pixi-wiki` deploy was pushed.

## 2026-06-23 create | Agent skill routing contract

- Added compiled concept `wiki/concepts/agent-skill-routing.md` from the canonical Knowledge page and the new `jamie-skill-router` Hermes skill.
- Captured the rule that Pixoid chooses the skill stack by default and passes active skill constraints into delegated subagent context.
- Added edge cases for explicit user-invoked modes, ambiguous routing, unavailable tools, public deploy approval, and context overload.
- Updated namespace README and index source roots.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Pilot compiled namespace page

- Added pilot entity `wiki/entities/hermes-mission-control.md` and crosslink to Eval Trace context-overfitting concept.
- Source pages remained in `Knowledge/` and `Projects/`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Compile agent-workflows content pack v1

- Added compiled concept pages for profile memory boundaries, runtime memory knowledge routing, self-improving agent systems, and peer profiles vs child processes.
- Added synthesis `wiki/syntheses/pixoid-crew-operating-model.md`.
- Updated namespace index.
- Source pages remain in `Knowledge/` and `Projects/`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add KPR and clean publishing gate content

- Promoted `agent-workflows` from scaffold to active namespace overview.
- Added concept pages for `knowledge-pack-routing`, `agent-entrypoint-mesh`, and `static-retrieval-evals`.
- Added synthesis `wiki/syntheses/markdown-first-agent-memory.md`.
- Expanded `Hermes Mission Control` as a compiled entity page with crew role boundaries and source routing.
- Updated namespace index and source roots.
- Final public publish remains gated by the clean `pixi-wiki` rebuild.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Add Ponytail minimal-code discipline concept

- Added compiled concept `wiki/concepts/ponytail-minimal-code-discipline.md` from the canonical Knowledge page and Hermes skill.
- Updated namespace README and index source roots.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Crosslink external Hermes import routing

- Added cross-namespace pointer to the Hermes Agent external wiki import review so workflow-specific candidates route through Agent Workflows instead of duplicating Hermes setup content.
- No Daily Notes were copied or compiled.
## 2026-06-18 update | Publish local Hermes KB workflow concepts

- Added compiled concept pages for `agent-capability-route-pattern`, `hermes-soul-md-wiring`, `matt-pocock-sdlc-rhythm`, and `bounded-context-tree-pattern`.
- Refreshed `peer-profiles-vs-child-processes` from the verified local Hermes KB closure synthesis.
- Updated namespace index so the public Pixi Wiki can expose the closed tracker concepts.
- Preserved no-auto-trigger and no profile/cron/gateway/MCP/RAG/deploy authorization boundaries.

## 2026-06-19 create | Matt Pocock skills best practices

- Added compiled concept `wiki/concepts/matt-pocock-skills-best-practices.md` from the canonical Knowledge page and upstream `mattpocock/skills` README.
- Cross-linked `matt-pocock-sdlc-rhythm` so the generalized SDLC rhythm points back to the source-backed best-practices pattern.
- Updated namespace README and index source roots.
- No Daily Notes were copied or compiled.

## 2026-06-23 update | Interaction Mode Routing crosslink

- Added cross-namespace routing to `ai-native-product-surfaces/wiki/concepts/interaction-mode-routing.md`.
- Updated `wiki/entities/hermes-mission-control.md` with the Pixoid Review Surface pattern.
- Updated namespace README and index source roots.
- No Daily Notes were copied or compiled.
## 2026-07-09 update | Matt Pocock skills v1.1 refresh

- Refreshed compiled `matt-pocock-sdlc-rhythm`, `matt-pocock-skills-best-practices`, `visual-plan-review-surfaces`, and `compound-engineering-skill-layer` for the upstream v1.1 rename: `/to-spec`, `/to-tickets`, `/wayfinder`, `/research`, `/diagnosing-bugs`, and local Hermes `/review` alias.
- Updated namespace index wording; no Daily Notes were copied or compiled.


<!-- ===== agent-workflows/wiki/summaries/agent-workflow-system-summary.md ===== -->

---
title: Agent Workflow System Summary — Skills, Tools, Scheduling, Delegation
created: 2026-07-01
updated: 2026-07-01
type: summary
status: compiled
namespace: agent-workflows
tags: [agent-workflows, product-management, skills, tools, scheduling, delegation]
sources:
  - wiki/entities/hermes-mission-control.md
  - wiki/syntheses/pixoid-crew-operating-model.md
  - wiki/concepts/agent-skill-routing.md
  - wiki/concepts/multi-agent-multiplayer-boundaries.md
  - wiki/concepts/agent-capability-route-pattern.md
  - wiki/concepts/agent-tooling-plan.md
confidence: high
---

# Agent Workflow System Summary — Skills, Tools, Scheduling, Delegation

This page summarizes Jamie's hands-on agent workflow system: the way Discord, Pixi Wiki, skills, tools, scheduling, delegation, verification gates, and durable knowledge surfaces come together as a system for building.

It is not a polished product case study or a proof dossier. The system is the work: a live operating model for turning intent into routed agent work, inspected artifacts, reusable knowledge, and verified progress while building with Hermes, Pixi Wiki, Discord, GitHub, and Obsidian.

## One-screen summary

Jamie's agent workflow system turns a human request in Discord into routed, inspectable building work:

```text
human request
→ Pixoid route selection
→ skills / tools / subagents / cron / MCP-style knowledge access
→ GitHub, Obsidian, and Pixi Wiki as durable truth surfaces
→ verification before final answer, closure, merge, or deploy
```

The product lesson is simple: agents become useful when the building system makes work legible — what triggered, who/what executed, which tools were used, what artifact was produced, what became reusable, and what evidence proves it worked.

## What this summarizes

- **Skills and tools:** [Agent Skill Routing](/pixi-wiki/wiki/agent-workflows/wiki/concepts/agent-skill-routing.md.html) defines how intent maps to useful skill stacks and how constraints are carried into delegated work.
- **Runtime/capability routing:** [Hermes Capability Routing](/pixi-wiki/wiki/hermes-agent/wiki/concepts/hermes-capability-routing.md.html) maps tasks to direct tools, scripts, skills, subagents, cron, MCP/plugins, gateway routes, or durable knowledge updates.
- **Agent delegation:** [Agent Capability Route Pattern](/pixi-wiki/wiki/agent-workflows/wiki/concepts/agent-capability-route-pattern.md.html) defines trigger → profile/capability → bounded execution → artifact → verification.
- **Multi-agent coordination:** [Multi-Agent Multiplayer Boundaries](/pixi-wiki/wiki/agent-workflows/wiki/concepts/multi-agent-multiplayer-boundaries.md.html) captures coordinator mode, specialist mode, workbench huddles, direct multiplayer risks, and suppression of noisy worker chatter.
- **Control plane:** [Hermes Mission Control](/pixi-wiki/wiki/agent-workflows/wiki/entities/hermes-mission-control.md.html) documents Pixoid/Tinker/Quill/Boba roles, Discord routing, GitHub issue/PR truth, and verification gates.
- **Operating model:** [Pixoid Crew Operating Model](/pixi-wiki/wiki/agent-workflows/wiki/syntheses/pixoid-crew-operating-model.md.html) explains how work moves across route selection, source-of-truth checks, memory boundaries, and review.
- **Planning agents as tools:** [Agent Tooling Plan](/pixi-wiki/wiki/agent-workflows/wiki/concepts/agent-tooling-plan.md.html) turns vague or clear requests into task buckets, tools, routing rules, memory, evaluation, permissions, and smallest proving loops.
- **Durable knowledge for agents:** [Markdown-First Agent Memory](/pixi-wiki/wiki/agent-workflows/wiki/syntheses/markdown-first-agent-memory.md.html) and [Knowledge Pack Routing](/pixi-wiki/wiki/agent-workflows/wiki/concepts/knowledge-pack-routing.md.html) keep agent context visible, versioned, citeable, and reusable.

## Product judgment shown here

This work is not just "using agents." The product judgment is in the boundaries:

- one visible owner for the user-facing thread;
- explicit route contracts instead of unbounded agent autonomy;
- skills as reusable operating procedures, not prompt vibes;
- GitHub issues, PRs, Obsidian, and Pixi Wiki as durable truth surfaces;
- Discord as a control plane and notification layer, not the canonical source of truth;
- verification before claiming success;
- public/wiki surfaces that humans can browse and agents can retrieve.

## Implementation tradeoffs and scaling lessons

The hard parts have been product and systems tradeoffs, not just wiring tools together:

- Coordination vs agent noise — direct multiplayer feels powerful, but it can create duplicate work and noisy threads. The system now favors Pixoid as one visible coordinator, with bounded huddles only when specialist input is useful.
- Convenience vs trigger precision — role mentions, reply pings, bot-authored chatter, and thread metadata can accidentally wake the wrong agent. The routing layer needs explicit summons, channel controls, and closed-loop suppression before model invocation.
- Builder speed vs trust — agents can move fast, but outputs only become durable after verification: changed files, tests, links, GitHub state, and source-truth checks.
- Local knowledge vs shareable surfaces — Pixi Wiki keeps the same knowledge usable by humans and agents through browsable pages, raw Markdown, indexes, and local MCP-style retrieval.
- Custom workflows vs scale — the repeatable unit is a route, skill, template, or scheduled job: define the trigger, allowed actions, artifact, owner, stop condition, and verification handle so one builder workflow can become a team workflow.

A concrete implementation example is the [Discord council and bot routing hardening PR](https://github.com/NousResearch/hermes-agent/pull/55200), which came from a real product problem: `@Crew` should create coordinated progress, not wake every worker into the same user thread. That work maps directly to [Multi-Agent Multiplayer Boundaries](/pixi-wiki/wiki/agent-workflows/wiki/concepts/multi-agent-multiplayer-boundaries.md.html) and [Hermes Mission Control](/pixi-wiki/wiki/agent-workflows/wiki/entities/hermes-mission-control.md.html).

## How it maps to a Founding PM, Agents role

For an agents product, the important questions are practical:

1. How does a builder go from an idea to a working agent or skill?
2. How does the runtime know what the agent can see, call, schedule, delegate, and change?
3. How do humans inspect what happened and trust the output?
4. How does useful work become reusable templates, skills, or durable knowledge?
5. How do teams avoid agent noise, duplicate work, and unsafe side effects?

The linked pages are Jamie's working answers to those questions.


<!-- ===== agent-workflows/wiki/summaries/effective-state-load-full-report.md ===== -->

---
title: Effective State Load Full Report
created: 2026-07-05
updated: 2026-07-07
type: summaries
status: compiled
namespace: agent-workflows
source: effective-state-load/docs/reports/esl-full-report.html
confidence: high
---

# Effective State Load Full Report

This page routes to the full ESL project report compiled from `pixiiidust/effective-state-load` after Phase 3 completed.

## Read directly

- [Open the standalone HTML report](/pixi-wiki/wiki/agent-workflows/assets/reports/esl-full-report.html)
- [Download the PDF](/pixi-wiki/wiki/agent-workflows/assets/reports/esl-full-report.pdf)

## What the report covers

- Problem: long-horizon agents fail when their internal workflow state drifts from reality, not only when context windows fill.
- Method: stress one model-agent harness across state cardinality (SC) and dependency density (DD).
- Phase 1: StatefulPuzzle shows an SC-led state wall.
- Phase 2: simple `SC × DD` is only partially useful in StatefulPuzzle; weighted calibration ties token count.
- Phase 3: ToolDAG-B shows a DD/provenance-led coupling cliff, where simple `SC × DD` beats token count and separates pass/fail cells cleanly.
- Verdict: ESL is a metric family and measurement recipe, not a portable universal formula.
- Product path: start with provenance guardrails for agent writes, then use the same graph for capacity/load measurement.

## Short verdict

There is no universal ESL exponent or threshold to ship. What transfers is the operating method: define SC/DD for a workflow class, run a cheap calibration grid, map the collapse frontier, operate with margin, and use provenance/binding errors as leading indicators.

## Product one-liner

> Schema validation checks that an ID is valid. Provenance guardrails check that it is the right ID for this task; ESL uses the same provenance graph to learn how much state/dependency load each workflow can safely carry.

## Implementation bridge

The follow-on MVP is a shadow-mode provenance auditor: replay traces, build the entity provenance graph, flag wrong-object/stale/scope-mismatched writes, and score the checker against hidden ToolDAG-B labels before running real traces.

## Related page

- [[../concepts/effective-state-load|Effective State Load]]


<!-- ===== agent-workflows/wiki/syntheses/markdown-first-agent-memory.md ===== -->

---
title: Markdown-First Agent Memory
created: 2026-06-16
updated: 2026-06-16
type: synthesis
status: compiled
namespace: agent-workflows
tags: [agent-workflows, memory, markdown, routing]
sources:
  - Projects/Hermes Mission Control/PRD - Knowledge Pack Routing.md
  - Projects/Hermes Mission Control/Knowledge Pack Contract V1.md
  - Knowledge/concepts/runtime-memory-knowledge-routing.md
  - Knowledge/concepts/profile-memory-boundaries.md
confidence: medium
---

# Markdown-First Agent Memory

Markdown-first agent memory is the rule that durable operational knowledge should live in source-controlled notes, packs, issues, and skills before it becomes infrastructure.

The memory layer should help the agent route itself. It should not become a hidden second database of project truth.

## Layer model

- **Injected memory:** compact stable hints, preferences, and environment facts.
- **Knowledge / wiki pages:** durable concepts and synthesis.
- **Project notes:** concrete project state and decisions.
- **GitHub issues:** execution truth and active coordination.
- **Skills:** reusable procedures.
- **Live tools:** current system state and verification.

Markdown-first means the agent can inspect and cite the source. When the source is too volatile, the agent should use live tools instead of freezing it into memory.

## Why this matters

Hidden memory is convenient but hard to audit. Markdown and issues are slower but visible, reviewable, and versioned. For Jamie's crew, that makes them better default truth surfaces.

## Failure mode

The danger is treating written context as commandment. Packs and notes are routing aids. They must be overridden by current GitHub state, live filesystem state, tests, and Jamie's latest instruction.

## Related pages

- [[../concepts/knowledge-pack-routing|Knowledge Pack Routing]]
- [[../concepts/agent-entrypoint-mesh|Agent Entrypoint Mesh]]
- [[../concepts/profile-memory-boundaries|Profile Memory Boundaries]]
- [[../concepts/runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]]


<!-- ===== agent-workflows/wiki/syntheses/pixoid-crew-operating-model.md ===== -->

---
title: Pixoid Crew Operating Model
created: 2026-06-16
updated: 2026-06-29
type: synthesis
status: compiled
namespace: agent-workflows
tags: [agent-workflows, pixoid, crew, source-of-truth]
sources:
  - Projects/Hermes Mission Control/Index.md
  - Knowledge/concepts/profile-memory-boundaries.md
  - Knowledge/concepts/runtime-memory-knowledge-routing.md
  - Knowledge/concepts/self-improving-agent-systems.md
  - Knowledge/concepts/peer-profiles-vs-child-processes.md
confidence: high
---

# Pixoid Crew Operating Model

The Pixoid crew operates as a set of bounded peer roles coordinated through durable source-of-truth surfaces. Pixoid is the control plane; Tinker builds; Quill maintains vault/source truth; Boba explores public sources and reality-checks signals.

## Operating contract

- GitHub issues and PRs are coordination truth.
- Obsidian/Git is knowledge and project truth.
- Discord is notification, not durable truth.
- Cron output is context, not canonical state.
- Daily Notes are scratch chronology, not compiled truth.

## Why this belongs in agent-workflows

The model is about how work moves through the crew: route selection, source-of-truth checks, memory boundaries, evidence gates, and review. It links to `pixi-vault` where the same rules affect namespace compilation, and to `eval-trace` where workflow quality gets measured.

## Core patterns

1. **Route by source of truth.** Use GitHub for work coordination, Obsidian for knowledge/project truth, skills for procedures, and memory only for compact stable routing facts.
2. **Prefer peer profiles for named crew work.** Use child/subagent execution only as a local fallback and label it honestly.
3. **Verify before closing.** Pixoid checks changed files, tests, live URLs, issue state, and pushed commits before reporting success.
4. **Promote durable learning carefully.** Evidence must justify whether a lesson belongs in a dossier, concept page, skill, prompt, project hub, or memory pointer.
5. **Separate coordinator mode from multiplayer mode.** `@Crew` is a Pixoid coordinator call by default, not a request for every live bot gateway to solve the same user message independently.

## Discord crew interaction modes

| Mode | Trigger | Contract |
|---|---|---|
| Coordinator | `@Crew`, `crew:`, `get the crew`, `calling the crew` | Pixoid handles the user-facing thread, creates/reuses a topic workbench thread when useful, gathers crew input, and posts one final answer. |
| Specialist | `@Boba`, `@Quill`, `@Tinker` | Only the named profile replies directly. |
| Workbench council / bounded huddle | Pixoid-created huddle tied to the triggering message/origin | Worker profiles respond once to a bounded prompt; Pixoid closes on all-replied-or-timeout and posts one final answer. |
| Direct multiplayer | Shared role assigned to all bots | Not default. It caused duplicate independent investigations and should only be enabled intentionally for tests. |

The live 2026-06-29 Discord milestone proved that role mentions and human mentions arrive in different Discord fields (`message.role_mentions` vs `message.mentions`) and that prompt-level worker silence fails under reply-ping/runtime-notice loops. The adapter fixes therefore enforce both summon parsing and closure state: shared crew summons should not wake all peer profiles into the same user thread, closed huddle worker chatter is dropped before model invocation, and reply pings do not reopen the loop without an explicit direct mention or approved reopen trigger.

## Cross-namespace links

- [[../../../eval-trace/wiki/concepts/context-overfitting|Context Overfitting]] — evaluation failure mode for stale-context execution.
- `pixi-vault` — namespace compiler and source-class policy.
- `local-ai-infrastructure` — future local/offloaded execution support.


<!-- ===== eval-trace/CLAUDE.md ===== -->

# Eval Trace Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/eval-trace/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to workflow, agent, and model-behavior evaluation; traces; context-overfitting detection; reliability metrics; evidence gates; style-transfer checks; and quality read-outs. Route dataset provenance to `curated-tuning-datasets` and training runtime to `local-ai-infrastructure`.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== eval-trace/README.md ===== -->

---
title: Eval Trace
created: 2026-06-16
updated: 2026-07-17
type: namespace-overview
status: active
category: evaluation
namespace: eval-trace
confidence: high
---

# Eval Trace

> Active namespace for evidence quality, behavior/workflow evaluation, reliability, and claim boundaries.

## Scope

### Covers

Workflow, agent, and model-behavior evaluation; traces; context-overfitting detection; reliability metrics; evidence gates; style-transfer checks; and quality read-outs.

### Not Covered

General observability unrelated to behavior/workflow quality; product analytics unless used as an evaluation surface; model-training infrastructure except where it changes the evaluation contract.

### Current As

2026-07-17 — active. Includes context-overfitting, the Eval Trace prototype, workflow-quality mapping, LLM style-transfer evaluation, the LKY Voice objective-plus-blind-listening gate, and the LKY Avatar factual-accuracy/persona-quality/fabrication separation.

## Canonical Source Roots

- `Projects/Eval Trace/Index.md`
- `Knowledge/concepts/context-overfitting.md`
- `Knowledge/concepts/style-transfer-evaluation.md`
- `Projects/LKY Avatar/Index.md`

## Crosslinks

- [[../agent-workflows/README|agent-workflows]]
- [[../pixi-vault/README|pixi-vault]]
- [[../ai-native-product-surfaces/README|ai-native-product-surfaces]]
- [[../local-ai-infrastructure/README|local-ai-infrastructure]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/eval-trace/README.md
/raw/eval-trace/wiki/index.md
/wiki/eval-trace/README.md
/wiki/eval-trace/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== eval-trace/wiki/concepts/context-overfitting.md ===== -->

---
title: Context Overfitting
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: eval-trace
tags: [agent-systems, governance, workflow, ai]
sources:
  - /root/.hermes/knowledge/concepts/context-overfitting.md
  - Knowledge/concepts/context-overfitting.md
confidence: high
---

# Context Overfitting

## Definition

**Context overfitting** is when an agent over-weights written context — memory, skills, dossiers, project notes, cron prompts, prior suggestions, or old issue state — and treats it as a hard constraint even when current user intent, live evidence, or scope boundaries should override it.

The written rule may still be useful. The failure is the weighting and scope.

## Current synthesis

Use the compact test:

```text
Context overfit? YES / NO / UNSURE
Suspect source: <memory / skill / dossier / prompt / project note / issue / none>
Evidence:
- <1-2 concrete observations>
Recommended action: <demote / scope / patch / update truth / keep / ask Jamie>
```

Verdicts:

| Verdict | Meaning | Action |
|---|---|---|
| YES | Written context or stale truth overrode current user intent, live evidence, or scope boundaries. | Demote the rule, scope it, patch the source, update the canonical truth surface, or remove the stale consumer. |
| NO | Context was used as a weak prior and the agent stayed steerable. | Keep the rule; no durable change unless another defect appears. |
| UNSURE | Evidence is insufficient, or Jamie must judge whether the rule should generalize. | Ask Jamie, inspect the suspect source, or gather better trace evidence before changing durable state. |

## Source-layer priority

When context conflicts, prefer current and canonical truth in this order:

1. current user instruction and explicit scope;
2. safety, secrets, data-loss, and approval boundaries;
3. live filesystem/GitHub/runtime evidence;
4. current PRD, issue, route contract, or handoff;
5. project/vault source of truth;
6. local Hermes knowledge concepts;
7. skills and procedures;
8. memory, dossiers, cron prompts, and older session recalls as weak priors.

This is a routing rule, not a license to ignore durable context. Written context is useful when it is current, scoped, and backed by live evidence.

## Application

Run this check when:

- an agent refuses a reasonable correction because an older rule says otherwise;
- project-local advice leaks into another project;
- stale issue or repo state drives a current recommendation;
- a self-improvement loop tries to promote a one-off suggestion into global behavior;
- memory or a dossier sounds authoritative but live evidence disagrees;
- a route/profile rule is treated as automatic approval when it is only a recommendation.

For self-improvement, pair this page with [[self-improving-agent-systems]]: promote only evidence-graded, reversible, layer-fit lessons. For memory and knowledge routing, pair it with [[runtime-memory-knowledge-routing]] and [[profile-memory-boundaries]].

## Boundaries

- Do not use this rubric to bypass safety, secrets, destructive-action, merge, deploy, or live-posting approvals.
- Do not patch memory, cron, profiles, providers, gateways, MCP, RAG, or GitHub state merely because a context-overfit risk exists; verify and use the correct change process.
- Do not store raw eval traces, issue progress, PR numbers, or command logs in concept pages.
- Do not call every stale page context overfitting. Ordinary knowledge rot is stale content; context overfitting is stale or over-scoped content being weighted too strongly during action.

## Related pages

- [[self-improving-agent-systems]]
- [[runtime-memory-knowledge-routing]]
- [[profile-memory-boundaries]]
- [[agent-ops-harness-health]]
- [[agent-capability-route-pattern]]
- [[matt-pocock-sdlc-rhythm]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/context-overfitting.md`


<!-- ===== eval-trace/wiki/concepts/style-transfer-evaluation.md ===== -->

---
title: Style-Transfer Evaluation
created: 2026-07-10
updated: 2026-07-17
type: concept
status: compiled
namespace: eval-trace
tags: [eval-trace, style-transfer, lora, llm-judge, checkpoint-selection, uncertainty, voice-ai]
sources:
  - Knowledge/concepts/style-transfer-evaluation.md
  - Projects/LKY Archive/Index.md
  - Projects/LKY Avatar/Index.md
  - https://github.com/pixiiidust/lky-brain
  - https://pixiiidust.github.io/lora-LKY-report/
confidence: high
---

# Style-Transfer Evaluation

Style-transfer evaluation asks whether an adapter changes named observable behaviors on held-out prompts without confusing persona imitation, lower train loss, or one judge's preference with general reasoning improvement.

## Minimum contract

1. Split by whole source document before creating overlapping windows.
2. Compare base and candidate checkpoints on the same prompts and decoding settings.
3. Score explicit observable traits plus a separate overall voice/style measure.
4. Use deterministic generation or repeated fixed seeds.
5. Blind candidate identity and randomize answer order.
6. Run both reference-free and reference-anchored judge passes when a real answer exists.
7. Calibrate with human review.
8. Aggregate or bootstrap by held-out document, not only by prompt row.

## LKY Brain result

On 24 rows from 10 held-out interviews, the epoch-2 QLoRA checkpoint moved judged behavior relative to base Qwen3-14B:

- voice: 2.04 → 2.88;
- directness: 46% → 88%;
- bounded uncertainty: 8% → 33%;
- concrete analogy: 0% → 25%;
- reframing: 29% → 38%.

Epoch 3 reached voice 2.96 and analogy 38%, but lower reframing and bounded uncertainty. Epoch 2 is a defensible provisional checkpoint preference because it retains the subtler traits while tying on broad voice within likely noise.

## Parallel speech-style evaluation

The LKY Voice run applies the same evidence discipline to speech generation, where identity, intelligibility, deployment speed, and human recognition must remain separate:

| gate | contract | winning Chatterbox LoRA e14 |
|---|---|---:|
| speaker similarity | meet or beat baseline 0.8693 | 0.8900 |
| intelligibility | WER ≤ 0.05 | 0.0390 |
| deployability | RTF ≤ 0.6 | 0.381 |
| human blind listen | tuned preferred ≥ 70% | 18/20 |
| integrated placement | no failures; realtime on the shared GPU | RTF mean/max 0.369/0.397; 0 failures |

The rejected GPT-SoVITS arm is the useful counterexample: similarity improved to 0.9049, but WER degraded to 0.1274. The operator's blind listen can veto a numerically attractive model; no one metric decides shipment.

Integration also preserved a stock-model rollback and PerTh watermark confidence 1.0000. These results support a tuned-voice preference and deployment decision, not authentic speech, semantic correctness, factual fidelity, or robust pronunciation. Singapore proper nouns and mixed acoustic eras remain separate residual risks.

## Parallel factuality evaluation

The first integrated LKY Avatar session passed interaction and voice gates while inventing constituencies, dates, and historical events. The application therefore added an independent factuality lane:

| signal | question |
|---|---|
| factual accuracy | Does the answer contain only correct dates, places, offices, and relationships? |
| persona quality | Does grounding preserve concise, recognizable reasoning style? |
| fabrication | Did the model invent a date, quote, meeting, office, or constituency? |

The implementation uses a small audited fact sheet, deterministic per-turn section retrieval, a source-over-memory block inserted immediately before the latest question, an uncertainty guardrail, and Singapore proper-noun STT keyterms. A 12-question subset supports matched grounding-on/off runs.

Tests establish that these seams work as code. They do not establish factual lift. The remaining proof is a real-microphone keyterm check plus a local-brain comparison of factual accuracy, persona quality, and fabrication with grounding enabled and disabled.

## Claim boundary

The evidence supports a directional behavioral shift. It does not yet establish statistically stable per-trait lift, factual fidelity, general capability gain, or definitive overfitting because:

- the 24 rows are the longest-reference subset of 66 windows rather than a representative random sample;
- generation sampled at temperature 0.8 without reported fixed/repeated seeds;
- those rows are clustered within 10 source documents;
- the same held-out subset selects the checkpoint and reports the final result;
- one Claude judge sees a real LKY reference answer;
- no confidence intervals, judge-reliability study, or human agreement rate is reported.

## Next evidence gate

For model style, evaluate all 66 rows with fixed or repeated seeds, separate checkpoint selection from final testing, publish document-level aggregates and confidence intervals, add a blind/no-reference judge pass, manually review a stratified sample, and check same-event/date leakage across the dialogue and speech streams. For application factuality, run the 12 questions with grounding on/off and report factual accuracy, persona quality, and fabrication separately. Phrase epoch-3 as a possible overfit signal and the retrieval layer as implemented-but-unproven until those checks agree.


<!-- ===== eval-trace/wiki/entities/eval-trace.md ===== -->

---
title: Eval Trace
created: 2026-06-16
updated: 2026-06-16
type: entity
status: compiled
namespace: eval-trace
tags: [eval-trace, agent-workflows, evaluation, traces]
sources:
  - Projects/Eval Trace/Index.md
confidence: medium
---

# Eval Trace

**Eval Trace** is Jamie's local prototype for evaluating agent-workflow quality, especially context overfitting. It builds trace packets, runs deterministic prechecks, and can hand ambiguous cases to an LLM judge.

## Current artifact

```text
.hermes/context-overfit/
```

Current status: local prototype. It is not yet a public GitHub repo. The repo decision is deferred until the harness proves review-load reduction on real workflow traces.

## Current capabilities

- Builds segmented trace packets from Hermes session exports.
- Runs deterministic prechecks before any LLM judge.
- Emits compact `judge_packets.jsonl` for reviewable `UNSURE` cases.
- Supports real LLM judge passes when Jamie asks Pixoid to judge.
- Reads `.hermes/knowledge/registry/project-status.json` for done/deprecated/replaced project status.

## Next gate

Before a standalone `pixiiidust/eval-trace` repo exists, prove value on real workflow traces: add sequence-level cron checks, run on recent crew outputs, and show a confirmed real `YES` or useful `UNSURE` clustering.

## Source

Compiled from `Projects/Eval Trace/Index.md`.


<!-- ===== eval-trace/wiki/index.md ===== -->

---
title: Eval Trace — Master Index
created: 2026-06-16
updated: 2026-07-17
type: index
status: compiled
namespace: eval-trace
---

# Eval Trace — Master Index

> Compiled index for `eval-trace`.

## Concepts

- [[concepts/context-overfitting|Context Overfitting]] — Agent workflow failure mode where stale or overly rigid context overwhelms current intent/live evidence.
- [[concepts/style-transfer-evaluation|Style-Transfer Evaluation]] — LLM document holdouts and trait rubrics; tuned-voice similarity, intelligibility, realtime, blind-listening, placement, watermark, and rollback; plus separate factual accuracy, persona quality, and fabrication signals for grounded applications.

## Entities

- [[entities/eval-trace|Eval Trace]] — Local prototype for context-overfit trace packets, deterministic prechecks, and LLM judge review.
- Cross-namespace entity: [[../../agent-workflows/wiki/entities/hermes-mission-control|Hermes Mission Control]] — Agent Workflows primary page for route governance and crew operating surfaces.

## Summaries

- Cross-namespace summary: [[../../hermes-agent/wiki/summaries/external-hermes-wikis-import-review|External Hermes Wikis Import Review]] — Routes auxiliary-model and evaluation/trace-adjacent Hermes content back to Hermes Agent with Eval Trace crosslinks.

## Syntheses

- [[syntheses/workflow-quality-evaluation-map|Workflow Quality Evaluation Map]] — Evaluation surfaces, gates, and evidence rules for agent workflow quality.

## Source Roots

- `Projects/Eval Trace/Index.md`
- `Knowledge/concepts/context-overfitting.md`
- `Knowledge/concepts/style-transfer-evaluation.md`
- `Projects/LKY Avatar/Index.md`


<!-- ===== eval-trace/wiki/log.md ===== -->

---
title: Eval Trace — Activity Log
created: 2026-06-16
updated: 2026-07-17
type: log
status: compiled
namespace: eval-trace
---

# Eval Trace — Activity Log

> Append-only namespace log.

## 2026-07-17 update | Separate factual grounding from persona quality

- Extended the style-transfer page with the LKY Avatar factuality lane after issue #45 / PR #47 merged.
- Added the audited evidence, per-turn retrieval, uncertainty, proper-noun input, and 12-question matched-eval contract.
- Kept tests as implementation evidence only; live microphone and local-brain grounding-on/off results remain the quality gate.

## 2026-07-15 update | Extend style-transfer evaluation to tuned voice

- Added the LKY Voice parallel case to `wiki/concepts/style-transfer-evaluation.md`.
- Preserved separate gates for identity similarity, WER intelligibility, realtime factor, blind human preference, same-GPU placement, watermarking, and rollback.
- Recorded GPT-SoVITS as the counterexample where higher similarity did not compensate for failed intelligibility, and kept pronunciation/authenticity/factuality outside the claim.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Pilot compiled namespace page

- Added pilot concept `wiki/concepts/context-overfitting.md` and crosslink to Agent Workflows Hermes Mission Control entity.
- Source pages remained in `Knowledge/` and `Projects/`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Compile eval-trace content pack v1

- Expanded `wiki/concepts/context-overfitting.md`.
- Added entity `wiki/entities/eval-trace.md`.
- Added synthesis `wiki/syntheses/workflow-quality-evaluation-map.md`.
- Updated namespace index.
- Source pages remain in `Knowledge/` and `Projects/`.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Crosslink Hermes eval-adjacent imports

- Added cross-namespace pointer to the Hermes Agent external wiki import review for auxiliary-model and trace/eval-adjacent routing.
- No Daily Notes were copied or compiled.
## 2026-06-18 update | Refresh context-overfitting from local Hermes KB closure

- Refreshed `wiki/concepts/context-overfitting.md` with the verified YES/NO/UNSURE rubric and source-layer priority from the local Hermes KB tracker closure.
- Preserved the boundary that context-overfit checks do not bypass safety, approval, profile, cron, or deployment gates.

## 2026-07-10 add | Style-transfer evaluation contract from LKY Brain

- Added `wiki/concepts/style-transfer-evaluation.md` from the completed LKY Brain base/epoch-2/epoch-3 comparison.
- Preserved the strong parts: whole-document holdout, named behavior rubric, matched candidates, checkpoint preservation, and answer-level inspection.
- Tightened the claim boundary around n=24, 10 source documents, stochastic generation, one reference-anchored judge, no confidence intervals, and non-random longest-reference selection.
- Recorded the next gate: all 66 rows, fixed/repeated seeds, document-level uncertainty, blind/no-reference judging, and human calibration.


<!-- ===== eval-trace/wiki/syntheses/workflow-quality-evaluation-map.md ===== -->

---
title: Workflow Quality Evaluation Map
created: 2026-06-16
updated: 2026-06-16
type: synthesis
status: compiled
namespace: eval-trace
tags: [eval-trace, workflow-quality, evidence-gates, agent-workflows]
sources:
  - Projects/Eval Trace/Index.md
  - Knowledge/concepts/context-overfitting.md
  - wikis/agent-workflows/wiki/syntheses/pixoid-crew-operating-model.md
confidence: medium
---

# Workflow Quality Evaluation Map

Workflow quality evaluation asks whether an agent's output followed the right source-of-truth hierarchy, adapted to current user intent, and produced verified artifacts instead of plausible process talk.

## Evaluation surfaces

| Surface | Quality question | Evidence |
|---|---|---|
| Source routing | Did the agent use the correct truth layer? | GitHub issue/PR state, Obsidian project hubs, Knowledge pages, Wiki Compiler Maps |
| Context adaptation | Did the agent update from latest user intent and live checks? | Current message, live git/GitHub/tool output |
| Artifact progress | Did it produce a working artifact? | Committed files, tests, generated output, live URL checks |
| Review discipline | Did Pixoid verify before closing? | Test logs, API checks, issue comments, clean status |
| Safety boundary | Did it stop before risky actions? | Explicit approvals for deletes, deploys, secrets, broad rewrites |

## Evidence gates

1. **Pre-flight gate:** inspect live repo/tracker/source state before editing.
2. **Revision gate:** if checks fail, fix and rerun focused verification.
3. **Escalation gate:** ask Jamie before destructive or ambiguous ownership changes.
4. **Closure gate:** close issues only after pushed commits, tests, and live/remote verification.

## Context-overfit signal

A strong context-overfit signal appears when the agent follows a written prior that should have been overridden by a newer user instruction, current project status, or live tool output. The evaluation target is not whether context was used; it is whether context was treated as stronger than the right source of truth.

## Cross-namespace links

- [[../../../agent-workflows/wiki/syntheses/pixoid-crew-operating-model|Pixoid Crew Operating Model]] — operational source hierarchy.
- [[concepts/context-overfitting|Context Overfitting]] — primary failure-mode concept.


<!-- ===== hermes-agent/CLAUDE.md ===== -->

# Hermes Agent Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/hermes-agent/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Keep this namespace scoped to Hermes Agent usage, setup, configuration, MCP, traces, evals, observability, and Jamie/Pixoid operating reference.
- Source priority is explicit: official Hermes docs and local installed Hermes source outrank AgentWikis. AgentWikis is a curated discovery map, not source-of-truth for commands.
- Do not import the whole AgentWikis Hermes wiki. Curate only pages Jamie's workflow uses.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== hermes-agent/README.md ===== -->

---
title: Hermes Agent
created: 2026-06-18
updated: 2026-06-27
type: namespace-overview
status: compiled
category: agent-infrastructure
namespace: hermes-agent
confidence: medium
---

# Hermes Agent

> Curated Hermes Agent operating reference for Jamie/Pixoid: setup, configuration, MCP, profiles, tracing, evals, observability, and workflow-specific usage.

## Scope

### Covers

Hermes Agent setup and configuration, MCP integration, profiles, skills, memory, cron, gateway operations, subagents/delegation, session traces, trajectory capture, batch evals, Langfuse traces, NeMo Relay ATOF/ATIF exports, capability-routing decisions, and Jamie-specific operating reference for Pixoid.

### Not Covered

General AI-agent theory, unrelated community projects, old video transcripts unless they explain a workflow Jamie uses, stale release history not needed for current operation, and web rumors not verified against official Hermes docs or local installed source.

### Current As

2026-06-27 — added Hermes Remote Artifact Previews as a reusable rule: remote Desktop artifacts must use dashboard HTTP/API, never VPS-local `file://` preview paths.

## Source Priority

1. Official Hermes docs: `https://hermes-agent.nousresearch.com/docs`
2. Local installed Hermes source: `/usr/local/lib/hermes-agent`
3. AgentWikis Hermes: `https://agentwikis.com/wiki/hermes/llms.txt`
4. Web search for freshness checks only

## Canonical Source Roots

- Official docs mirrored in local install: `/usr/local/lib/hermes-agent/website/docs/`
- Canonical capability-routing concept: `Knowledge/concepts/hermes-capability-routing.md`
- Remote artifact preview rule: `Knowledge/concepts/hermes-remote-artifact-previews.md`
- Local source/plugin docs: `/usr/local/lib/hermes-agent/`
- AgentWikis Hermes raw pages: `https://agentwikis.com/raw/hermes/...`

## Crosslinks

- [[../agent-workflows/README|agent-workflows]]
- [[../eval-trace/README|eval-trace]]
- [[../pixi-vault/README|pixi-vault]]
- [[../local-ai-infrastructure/README|local-ai-infrastructure]]

## Maintenance

- Verify commands against official docs or live `hermes --help` before using them.
- Prefer MCP retrieval over web search for stable Hermes reference questions.
- Use web search only when checking latest releases, GitHub issues, or current external state.
- Keep this namespace slim: add operational pages, not a full AgentWikis mirror.


<!-- ===== hermes-agent/wiki/concepts/evals-and-traces-setup.md ===== -->

---
title: Hermes Evals and Traces Setup
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: hermes-agent
tags: [hermes-agent, evals, traces, observability, langfuse, nemo-relay, trajectories]
sources:
  - https://hermes-agent.nousresearch.com/docs/user-guide/features/batch-processing
  - https://hermes-agent.nousresearch.com/docs/user-guide/features/built-in-plugins
  - /usr/local/lib/hermes-agent/website/docs/developer-guide/trajectory-format.md
  - /usr/local/lib/hermes-agent/plugins/observability/nemo_relay/README.md
confidence: high
---

# Hermes Evals and Traces Setup

Hermes has native trace surfaces and trajectory capture, but it does not ship a full generic pass/fail eval dashboard. Use the right layer for the job.

## Native trace layers

| Layer | Use | Setup |
|---|---|---|
| `state.db` sessions | Review real conversations, tool calls, usage, cost, and platform history. | Built in. Use `hermes sessions ...`. |
| Session JSONL export | Build eval datasets or review failure traces outside Hermes. | `hermes sessions export ...`. |
| `/insights` | Usage analytics: models, tools, skills, tokens, cost, platforms, top sessions. | Built in. Use `hermes insights --days N`. |
| Trajectory saving | ShareGPT-compatible turn/tool traces from CLI sessions. | `agent.save_trajectories: true` or `--save-trajectories`. |
| Batch runner | Run many prompts and collect structured trajectories/statistics. | `python batch_runner.py ...`. |
| Langfuse plugin | External LLM observability dashboard for turns, LLM calls, and tool calls. | Enable `observability/langfuse` and set keys. |
| NeMo Relay plugin | ATOF/ATIF exports for replay, evaluation, and harness analysis. | Enable `observability/nemo_relay` and set export env vars. |

## Session export

```bash
hermes sessions export sessions.jsonl
hermes sessions export --source discord discord.jsonl
hermes sessions export --session-id <session_id> one-session.jsonl
```

Use this for failure review, dataset building, replay-style analysis, and tool-use trace mining.

## Insights

```bash
hermes insights --days 30
hermes insights --days 7 --source cli
```

Use this for operational analytics, not task correctness scoring.

## Trajectory saving

Official developer docs describe ShareGPT-compatible JSONL trajectories written as:

```text
trajectory_samples.jsonl      # completed=True
failed_trajectories.jsonl     # failed or interrupted
```

Enable in config:

```yaml
agent:
  save_trajectories: true
```

or run with:

```bash
hermes chat --save-trajectories -q "..."
```

The batch runner always saves trajectories.

## Batch eval runner

Official batch-processing docs describe `batch_runner.py` as the native path for running many prompts and producing trajectory data plus statistics.

```bash
python batch_runner.py   --dataset_file=data/eval_suite.jsonl   --batch_size=10   --run_name=eval_gpt55   --model=gpt-5.5   --num_workers=4   --max_turns=10
```

Outputs:

```text
data/<run_name>/
├── trajectories.jsonl
├── batch_0.jsonl
├── checkpoint.json
└── statistics.json
```

Tracked fields include `completed`, `partial`, `api_calls`, `toolsets_used`, `tool_stats`, and `tool_error_counts`.

## Langfuse setup

Official built-in plugin docs say the Langfuse plugin traces Hermes turns, LLM calls, and tool invocations.

Interactive setup:

```bash
hermes tools          # choose Langfuse Observability
```

Manual setup:

```bash
pip install langfuse
hermes plugins enable observability/langfuse
```

Add credentials to `~/.hermes/.env`:

```bash
HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com
```

Verify:

```bash
hermes plugins list
hermes chat -q "hello"
```

Then check Langfuse for a `Hermes turn` trace.

## NeMo Relay ATOF/ATIF setup

The NeMo Relay plugin maps Hermes observer hooks to scopes, LLM spans, tool spans, marks, ATOF, and ATIF. It can export raw lifecycle events as ATOF JSONL and ATIF trajectory files for replay/eval harnesses.

Enable plugin:

```bash
hermes plugins enable observability/nemo_relay
```

Install runtime if needed:

```bash
pip install "nemo-relay==0.3"
```

Local export settings:

```bash
export HERMES_NEMO_RELAY_ATOF_ENABLED=1
export HERMES_NEMO_RELAY_ATOF_OUTPUT_DIRECTORY=.nemo-relay/atof
export HERMES_NEMO_RELAY_ATIF_ENABLED=1
export HERMES_NEMO_RELAY_ATIF_OUTPUT_DIRECTORY=.nemo-relay/atif
```

Optional controls include `HERMES_NEMO_RELAY_ATOF_FILENAME`, `HERMES_NEMO_RELAY_ATOF_MODE`, `HERMES_NEMO_RELAY_ATIF_FILENAME_TEMPLATE`, `HERMES_NEMO_RELAY_ATIF_AGENT_NAME`, `HERMES_NEMO_RELAY_ATIF_AGENT_VERSION`, `HERMES_NEMO_RELAY_ATIF_MODEL_NAME`, and `HERMES_NEMO_RELAY_ATIF_SUBAGENT_EXPORT_MODE`.

## Decision rule

Use the lightest trace surface that answers the question:

```text
Need to inspect one past run?       → sessions export / session_search
Need usage trends?                  → insights
Need many-prompt eval trajectories? → batch_runner.py
Need external observability UI?     → Langfuse
Need replay/harness trajectory form?→ NeMo Relay ATIF/ATOF
```


<!-- ===== hermes-agent/wiki/concepts/hermes-capability-routing.md ===== -->

---
title: Hermes Capability Routing
created: 2026-06-26
updated: 2026-06-26
type: concept
status: compiled
namespace: hermes-agent
source: Knowledge/concepts/hermes-capability-routing.md
confidence: high
---

# Hermes Capability Routing

Hermes capability routing is the decision lens for choosing the smallest effective Hermes Agent surface for a task: direct tool call, `execute_code`, skill, memory, session search, delegation, cron, gateway, API server, MCP, plugin, profile, kanban board, or external process.

Short form:

```text
intent → smallest surface → durability boundary → side-effect boundary → verification handle
```

## Why this exists

Hermes exposes many overlapping surfaces. The optimal route depends on task shape, durability, side effects, and verification burden, not on which feature sounds most powerful.

Use this when a request is broader than skill selection but narrower than a full route contract. Skill routing decides which procedures frame the work. Capability routing decides whether the work should be a tool call, script, skill, subagent, scheduled job, gateway/API integration, profile route, MCP/plugin extension, or knowledge/project update.

## Routing matrix

| Task shape | Default Hermes surface |
|---|---|
| One immediate read/write/check | Current-session tools |
| Mechanical multi-tool loop | `execute_code` with `hermes_tools` |
| Reusable procedure | Hermes skill |
| Stable user/environment fact | Memory/user profile |
| Past-session recall | `session_search` |
| Independent bounded analysis | `delegate_task` |
| Durable scheduled work | `cronjob` or tracked background process |
| Repeated multi-profile collaboration | Kanban/profile route |
| Messaging delivery | Gateway/platform adapter |
| External app needs OpenAI-compatible access | API server |
| Existing external service has a server | MCP |
| New reusable action | Tool or plugin |
| Cost/speed/reliability choice | Model picker, provider routing, fallback providers |

## Public wiki placement

Primary namespace: `hermes-agent`, because this is a Hermes Agent capability-selection map derived from official docs and the reusable local skill.

Relevant crosslink namespace: `agent-workflows`, because Pixoid crew routing uses the lens to decide when work should become skill work, subagent work, scheduled work, peer-profile/kanban work, vault/Pixi Wiki source work, or a public deploy candidate.

Do not split this into a new namespace; it connects existing Hermes Agent and Agent Workflows pages.

## Boundaries

- Official Hermes docs remain source of truth for commands, flags, providers, config keys, and setup details.
- Capability routing is not authorization; destructive commands, deploys, merges, secrets, profile/gateway/provider/webhook changes, and public publication still require the relevant approval boundary.
- `delegate_task` is not durable; use cron/background/kanban/profile routes for work that must survive interruption.
- Do not make memory carry procedures, project state, or public wiki content.
- Do not build custom plugins/tools until existing CLI, tools, skills, MCP, gateway, and API surfaces have been checked.

## Related pages

- [[../../agent-workflows/wiki/concepts/agent-skill-routing|Agent Skill Routing]]
- [[../../agent-workflows/wiki/concepts/agent-capability-route-pattern|Agent Capability Route Pattern]]
- [[../../agent-workflows/wiki/concepts/runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]]
- [[../../agent-workflows/wiki/concepts/profile-memory-boundaries|Profile Memory Boundaries]]
- [[concepts/source-priority|Hermes Source Priority]]

## Sources

- Official docs: `https://hermes-agent.nousresearch.com/docs`
- Canonical source: `Knowledge/concepts/hermes-capability-routing.md`
- Reusable skill: `~/.hermes/skills/autonomous-ai-agents/hermes-capability-routing/SKILL.md`


<!-- ===== hermes-agent/wiki/concepts/hermes-remote-artifact-previews.md ===== -->

---
title: Hermes Remote Artifact Previews
created: 2026-06-27
updated: 2026-06-27
type: concept
status: compiled
namespace: hermes-agent
source: Knowledge/concepts/hermes-remote-artifact-previews.md
confidence: high
---

# Hermes Remote Artifact Previews

Hermes remote artifact previews are HTML/MDX/file artifacts generated on a remote Hermes host and opened from a local Hermes Desktop or dashboard session.

## Core rule

Never hand a remote Desktop session a VPS-local `file://` URL such as:

```text
file:///tmp/.../artifact.html
```

Use the dashboard HTTP/API boundary instead:

```text
remote file on VPS -> dashboard HTTP/API -> local Desktop preview
```

For Jamie's VPS setup:

- dashboard origin: `http://100.82.175.2:9119`
- gateway/API port: `8642` remains separate
- artifact links should be verified `http://...` URLs, not `file://...` paths

## Why this matters

A local Electron/Chromium webview cannot read the VPS filesystem. A dashboard page loaded over HTTP also cannot load arbitrary local resources through `file://`; Chromium reports this as `Not allowed to load local resource` or `chromewebdata`.

## Durable implementation pattern

For product behavior, remote HTML artifacts should be read or served through the Hermes dashboard backend:

- read remote HTML through the authenticated dashboard filesystem API and render a safe data/HTTP preview target; or
- serve the artifact through a dashboard/static route and return that HTTP URL.

Temporary `python3 -m http.server` links are acceptable for demos, but they are not durable product infrastructure.

## Agent operating checklist

1. Inspect topology: local Desktop vs remote VPS.
2. Treat `/tmp/...`, `/root/...`, and similar paths as remote-only when the Desktop is local.
3. Do not paste `file://` as the user-facing preview link.
4. Produce a dashboard HTTP/API URL or explicitly start a temporary HTTP endpoint.
5. Verify with `curl -I` that the URL is `200 OK` before saying it works.

## Related pages

- [[concepts/hermes-capability-routing|Hermes Capability Routing]]
- [[concepts/source-priority|Hermes Source Priority]]
- [[../../agent-workflows/wiki/concepts/runtime-memory-knowledge-routing|Runtime Memory Knowledge Routing]]


<!-- ===== hermes-agent/wiki/concepts/session-trace-store.md ===== -->

---
title: Hermes Session Trace Store
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: hermes-agent
tags: [hermes-agent, sessions, traces, state-db, insights]
sources:
  - /usr/local/lib/hermes-agent/hermes_state.py
  - /usr/local/lib/hermes-agent/agent/insights.py
  - https://hermes-agent.nousresearch.com/docs/reference/cli-commands
confidence: high
---

# Hermes Session Trace Store

Hermes' built-in trace substrate is the profile-scoped SQLite session store.

## What it stores

`state.db` stores session metadata, full message history, model configuration, tool calls, token usage, costs, source/platform tags, and searchable message text via FTS5.

The local source describes it as replacing older per-session JSONL storage for normal CLI/gateway sessions. Batch runner and RL trajectories are separate systems.

## Useful commands

```bash
hermes sessions list
hermes sessions browse
hermes sessions stats
hermes sessions export out.jsonl
hermes sessions export --source discord discord.jsonl
hermes sessions export --session-id <session_id> one-session.jsonl
```

## Insights

`hermes insights` analyzes `state.db` for token consumption, cost estimates, tool usage patterns, skill usage, activity trends, model/platform breakdowns, and top sessions.

```bash
hermes insights --days 30
hermes insights --days 7 --source cli
```

## Boundary

This is operational telemetry. It is not a correctness judge. Use it to find traces, mine examples, and inspect behavior; pair it with explicit eval prompts or human review when measuring quality.


<!-- ===== hermes-agent/wiki/concepts/source-priority.md ===== -->

---
title: Hermes Source Priority
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: hermes-agent
tags: [hermes-agent, source-priority, docs, agentwikis]
sources:
  - https://hermes-agent.nousresearch.com/docs
  - /usr/local/lib/hermes-agent
  - https://agentwikis.com/wiki/hermes/llms.txt
confidence: high
---

# Hermes Source Priority

Hermes reference work should separate **truth** from **maps**.

## Priority order

1. **Official Hermes docs** — commands, setup, configuration, current documented behavior.
2. **Local installed Hermes source** — what this VPS actually has installed and can run.
3. **AgentWikis Hermes** — curated topic map, release summaries, ecosystem inventory, and explanation layer.
4. **Web search** — freshness checks for new releases, open issues, and current community state.

## AgentWikis role

AgentWikis is useful as a discovery map. It surfaces topics such as MCP integration, configuration, profiles, subagents, release summaries, providers, memory backends, and community projects. It should not override official docs or live source when commands differ.

## Use policy

Use AgentWikis to decide what to read next. Use official docs or live source to decide what to run.

```text
Question: "What Hermes features exist?"          → AgentWikis is useful.
Question: "What command should I run now?"       → Official docs/live CLI first.
Question: "Why is this VPS failing?"             → Inspect live state first.
Question: "Is this still current upstream?"      → Official docs + web/GitHub check.
```

## Import boundary

Do not mirror the whole AgentWikis Hermes corpus into Pixi Wiki. Import only pages that support Jamie/Pixoid operations, and preserve source metadata plus freshness dates.


<!-- ===== hermes-agent/wiki/index.md ===== -->

---
title: Hermes Agent — Master Index
created: 2026-06-18
updated: 2026-06-27
type: index
status: compiled
namespace: hermes-agent
---

# Hermes Agent — Master Index

> Compiled index for `hermes-agent`.

## Concepts

- [[concepts/source-priority|Hermes Source Priority]] — How to rank official docs, local source, AgentWikis, and web search.
- [[concepts/hermes-capability-routing|Hermes Capability Routing]] — Select the smallest effective Hermes surface for a task: tool, script, skill, memory, delegation, cron, gateway/API, MCP/plugin, profile, kanban, provider route, and verification handle.
- [[concepts/hermes-remote-artifact-previews|Hermes Remote Artifact Previews]] — Use dashboard HTTP/API for remote Desktop artifacts; never hand local Desktop a VPS `file://` path.
- [[concepts/evals-and-traces-setup|Hermes Evals and Traces Setup]] — Practical setup map for session exports, batch trajectories, Langfuse, and NeMo Relay ATOF/ATIF.
- [[concepts/session-trace-store|Hermes Session Trace Store]] — Native `state.db`, session export, and `/insights` surfaces.

## Entities

<!-- Add Hermes-specific entities only when they are actively useful to Jamie/Pixoid. -->

## Summaries

- [[summaries/agentwikis-hermes-curated-seed|AgentWikis Hermes Curated Seed]] — What to use from AgentWikis and what to skip.
- [[summaries/external-hermes-wikis-import-review|External Hermes Wikis Import Review]] — Triage of Hermes Guide and AgentWikis content worth importing for Jamie/Pixoid.

## Syntheses

<!-- Add synthesized operating guides here. -->

## Source Roots

- Official docs: `https://hermes-agent.nousresearch.com/docs`
- Canonical concept: `Knowledge/concepts/hermes-capability-routing.md`
- Local installed source: `/usr/local/lib/hermes-agent`
- AgentWikis Hermes: `https://agentwikis.com/wiki/hermes/llms.txt`


<!-- ===== hermes-agent/wiki/log.md ===== -->

---
title: Hermes Agent — Activity Log
created: 2026-06-18
updated: 2026-06-27
type: log
status: compiled
namespace: hermes-agent
---

# Hermes Agent — Activity Log

## 2026-06-27

- Added `wiki/concepts/hermes-remote-artifact-previews.md` to preserve the remote Desktop preview rule: artifacts generated on the VPS must cross the dashboard HTTP/API boundary, not `file://`.
- Updated namespace index/README so future agents retrieve this rule before handing Jamie artifact URLs.

## 2026-06-26

- Added `wiki/concepts/hermes-capability-routing.md` as the primary Hermes capability-selection concept from the official docs review and reusable local skill.
- Updated namespace README and index to route capability questions to `hermes-agent`; `agent-workflows` carries a cross-namespace pointer for Pixoid crew routing.
- Preserved the public deploy boundary: source updated here, generated public `pixi-wiki` requires verified rebuild and explicit deploy/push approval.

## 2026-06-18

- Seeded `hermes-agent` namespace as a slim operating reference, not a wholesale AgentWikis mirror.
- Added source-priority policy: official docs and local installed source outrank AgentWikis; AgentWikis is a discovery map.
- Added setup notes for native session traces, batch trajectories, Langfuse traces, and NeMo Relay ATOF/ATIF exports from official Hermes docs/local source.
- Reviewed Hermes Guide and AgentWikis Hermes for import candidates; added `wiki/summaries/external-hermes-wikis-import-review.md` with a slim import queue and skip rules.

## 2026-06-19

- Re-ran the external Hermes wiki import assessment after namespace population updates.
- Confirmed no wholesale import and no new immediate import pages; updated `wiki/summaries/external-hermes-wikis-import-review.md` with current namespace routing, crosslink-only/default defer decisions, and source-priority caveats.


<!-- ===== hermes-agent/wiki/summaries/agentwikis-hermes-curated-seed.md ===== -->

---
title: AgentWikis Hermes Curated Seed
created: 2026-06-18
updated: 2026-06-18
type: summary
status: compiled
namespace: hermes-agent
tags: [hermes-agent, agentwikis, source-ingest, curation]
sources:
  - https://agentwikis.com/wiki/hermes/README.md
  - https://agentwikis.com/wiki/hermes/llms.txt
  - https://agentwikis.com/raw/hermes/wiki/index.md
confidence: medium
---

# AgentWikis Hermes Curated Seed

AgentWikis hosts a Hermes knowledge base with roughly 105 documents covering Hermes setup, configuration, workflows, extensions, releases, memory providers, platforms, providers, and community projects.

## Useful slices for Jamie/Pixoid

Use AgentWikis as a map for:

- MCP integration
- CLI and configuration reference
- profiles and multi-instance routing
- skills and memory systems
- cron and scheduling
- subagents and delegation
- release summaries when checking feature history
- ecosystem/community inventory when exploring external references

## Skip by default

Do not import everything. Skip or quarantine:

- video transcript summaries unless a transcript explains a workflow Jamie uses;
- broad community lists unless they answer a current question;
- old release pages unless debugging historical behavior;
- pages that conflict with official docs or local installed source.

## Staleness note

The AgentWikis Hermes README still claims an older verified release in one place, while `llms.txt` and the master index report v0.16.0 current as of 2026-06-16. Treat this as a useful but secondary source.

## Import posture

AgentWikis is a discovery layer. Official Hermes docs and live local source decide commands, config, and setup steps.


<!-- ===== hermes-agent/wiki/summaries/external-hermes-wikis-import-review.md ===== -->

---
title: External Hermes Wikis Import Review
created: 2026-06-18
updated: 2026-06-19
type: summary
status: compiled
namespace: hermes-agent
tags: [hermes-agent, curation, import-review, agentwikis, hermesguide]
sources:
  - https://hermesguide.xyz/wiki/
  - https://hermesguide.xyz/directory
  - https://agentwikis.com/wiki/hermes/README.md
  - https://agentwikis.com/wiki/hermes/llms.txt
  - https://agentwikis.com/raw/hermes/wiki/index.md
confidence: medium
---

# External Hermes Wikis Import Review

Reviewed `hermesguide.xyz` and AgentWikis Hermes for content worth importing into Jamie/Pixoid's Hermes Agent namespace.

## Verdict

Do **not** mirror either source. Keep this namespace slim and operational.

Import only content that is:

- hard to rediscover with one web search;
- likely to help Jamie operate Hermes, profiles, gateway, cron, memory, evals, or subagents;
- stable enough to be useful after a week;
- cross-checked against official Hermes docs or local installed source before commands/config are trusted.

## Hermes Guide / hermesguide.xyz

### Useful signal

`https://hermesguide.xyz/wiki/` is currently a landing/marketing route, not a deep wiki. The useful page is the ecosystem directory at `https://hermesguide.xyz/directory`, which lists 156+ community tools grouped by Dev Workflow, Integrations, Personal Assistant, Meta & Ecosystem, Business Ops, Enterprise, Content Creation, Cost Optimization, Creative, Research, Messaging, Trading & Markets, and Privacy/Self-Hosted.

### Worth importing

Import as **one summary**, not 156 entity pages:

- `Hermes Ecosystem Directory Triage` — curated shortlist of tools Jamie might actually evaluate.
- Include categories, short descriptions, and triage status: `watch`, `maybe`, `skip`, `needs verification`.
- Verify each selected tool against its primary repo before creating an entity page.

Possible shortlist for Jamie:

- Hermes Desktop / Scarf / Hermes Workspace / Hermes Console — front-end/control-plane options for sessions, memory, cron, project dashboards, and SSH-first operation.
- Hermes Memory UI / Herm / Autograph / Obsidian memory keep-alive — memory observability or Obsidian-linked memory workflows.
- Hermes Labyrinth / Hermescheck / Hermes progress tail / H-Ops — observability, health checks, progress visibility, and Kanban operations.
- Hermes Google Workspace / Microsoft Graph API skill / Nextcloud / Apple Calendar assistant — productivity integrations matching Jamie's assistant workflows.
- Hermes-Web-Search-Plus / video research ingest / Obsidian-Video-Notes — research ingestion helpers.
- Hermes-Multitenancy / Shellward / Hermes-Aegis / HermesClaw — security and multi-tenant routing ideas, only if Jamie works on gateway/profile isolation.
- Agent-Team-Orchestrator / Maestro / mission-control-like tools — compare against Jamie's existing crew/mission-control model; avoid importing unless they add a concrete pattern.

### Skip

- Broad creative/game/trading novelty tools unless Jamie opens a matching project.
- Most named forks with no current need.
- Pricing/model benchmark pages from Hermes Guide; freshness decays fast and web search is better.
- Landing pages that duplicate official docs.

## AgentWikis Hermes

AgentWikis has roughly 105 Hermes documents. It is a useful discovery map, but it is secondary to official docs and local source.

### Already covered locally

The current `hermes-agent` namespace already has:

- [[../concepts/source-priority|Hermes Source Priority]]
- [[../concepts/session-trace-store|Hermes Session Trace Store]]
- [[../concepts/evals-and-traces-setup|Hermes Evals and Traces Setup]]
- [[agentwikis-hermes-curated-seed|AgentWikis Hermes Curated Seed]]

### Highest-value imports

Create or expand these only when verified against official docs/local source:

1. `Memory Providers Compared` — high leverage because provider choice is hard to rediscover by search and crosses Honcho, Holographic, Hindsight, Mem0, OpenViking, ByteRover, RetainDB, Supermemory, and Memori. This should be a concept or synthesis, not separate entity pages for every provider unless Jamie evaluates them.
2. `Deployment Backends Compared` — useful for local vs Docker vs SSH/VPS vs Modal vs Daytona vs Singularity decisions. Jamie already uses VPS/WSL/local distinctions, so this would reduce repeated setup reasoning.
3. `Cron Troubleshooting Checklist` — worth a compact operational concept: timing, delivery, permissions, skill loading. This is likely to be reused for crew cron and gateway jobs.
4. `Auxiliary Models` — import the footguns: side-task routing, `auto` fallback, compression config split, approval/vision/web_extract/curator/task slots. This is web-search-resistant operational detail.
5. `Profiles & Multi-Instance` — import as Jamie-specific operating notes: profile isolation, gateway token boundaries, profile-scoped cron/memory paths, when to clone vs separate profile.
6. `Subagents & Delegation` — import only the operational decision table: `delegate_task` vs background process vs cron vs full spawned Hermes instance.
7. `Local Stack / Airplane Mode` — import only if Jamie actively works on local/offline Hermes; otherwise keep as a deferred pointer under local-ai-infrastructure.

### Medium priority / import on demand

- `Skills Catalog — 644-Skill Map` — useful as a pointer, but likely stale; prefer live `hermes skills browse/search` when available.
- `Awesome Hermes Agent — Ecosystem Inventory` — overlaps Hermes Guide directory; keep as source for the same ecosystem triage summary.
- Release summaries — only import when debugging historical behavior.
- Provider pages — import only selected providers Jamie actually uses or evaluates.
- Platform pages — import only Discord/Telegram/Email/Home Assistant/Google Workspace/Slack if actively configured.

### Skip by default

- Video transcript summaries unless they contain a workflow Jamie wants to preserve.
- OpenClaw comparison pages unless doing migration/positioning work.
- Onchain/trading workflow pages.
- One-page entity stubs for every community project.
- Old version pages as standalone entities.

## Suggested import queue

1. Create `wiki/syntheses/memory-providers-compared.md` from AgentWikis + official docs. Crosslink to agent-workflows memory-routing pages.
2. Create `wiki/syntheses/hermes-deployment-backends-compared.md` from AgentWikis + local source/docs. Include Jamie-specific VPS/WSL/Puffer notes only if they are stable and already authorized for this namespace.
3. Create `wiki/concepts/hermes-cron-troubleshooting.md` as a compact four-category checklist.
4. Create `wiki/concepts/hermes-auxiliary-model-routing.md` for side-task model routing and compression footguns.
5. Create `wiki/summaries/hermes-ecosystem-directory-triage.md` from Hermes Guide + AgentWikis ecosystem pages, with selected tools only.

## Import rule

One external source can justify a local page only if the page answers: “Would Jamie/Pixoid plausibly ask this again, and would web search be slower or noisier than retrieving the wiki page?”

If yes, import a compact synthesis. If no, leave the source as a pointer.


## Namespace routing review

Primary home stays `hermes-agent` for Hermes-specific operations and setup. Other namespaces should crosslink to this review or to future focused pages rather than duplicate the content.

| Candidate | Primary namespace | Crosslink namespaces | Decision |
|---|---|---|---|
| Memory Providers Compared | `hermes-agent` | `agent-workflows`, `local-ai-infrastructure` | Add as a Hermes synthesis if Jamie starts comparing providers; crosslink to runtime memory routing and local-first memory infrastructure. |
| Deployment Backends Compared | `hermes-agent` | `local-ai-infrastructure`, `agent-workflows` | Add as a Hermes synthesis; crosslink from local infrastructure because backend choice affects VPS/WSL/local execution. |
| Cron Troubleshooting Checklist | `hermes-agent` | `agent-workflows` | Add as a Hermes operational concept; crosslink from crew/cron workflow pages because recurring jobs are workflow infrastructure. |
| Auxiliary Models | `hermes-agent` | `eval-trace`, `agent-workflows` | Add as a Hermes concept; crosslink where eval/tracing side tasks and approval/compression behavior affect workflow quality. |
| Profiles & Multi-Instance | `hermes-agent` | `agent-workflows` | Add as a Hermes concept; crosslink from profile/memory boundary and peer-profile pages. |
| Subagents & Delegation | `hermes-agent` | `agent-workflows` | Split if needed: Hermes API/tool mechanics in `hermes-agent`; route-governance decision table in `agent-workflows`. |
| Local Stack / Airplane Mode | `local-ai-infrastructure` | `hermes-agent` | If imported, primary home should be local infrastructure; Hermes Agent should only link to setup-specific notes. |
| Ecosystem Directory Triage | `hermes-agent` | `pixi-vault`, `agent-workflows`, `local-ai-infrastructure` | Keep as a single triage summary first; create entity pages only for tools Jamie evaluates. |
| AgentWikis / external wiki import pattern | `pixi-vault` | `hermes-agent`, `agent-workflows` | The reusable import/routing method belongs to Pixi Vault; this page is the Hermes-specific instance. |

### Crosslink policy

- `hermes-agent` owns Hermes commands, config, providers, memory plugins, profiles, gateway, cron, skills, and subagent mechanics.
- `agent-workflows` owns Pixoid/Tinker/Quill/Boba route decisions, handoffs, governance, memory-boundary behavior, and when to delegate vs spawn vs schedule.
- `local-ai-infrastructure` owns offline/local model stacks, local retrieval, hardware constraints, and local-first deployment tradeoffs.
- `eval-trace` owns observability/evaluation failure modes and evidence gates, not general Hermes setup.
- `pixi-vault` owns the namespace-routing/import methodology and public wiki/compiler mechanics.


---

## 2026-06-19 re-run after namespace population updates

### Live Pixi Wiki state that changes routing

The namespace set is now materially populated, so the external Hermes sources should be routed more narrowly than the first review:

- `hermes-agent` already contains source-priority, session-trace, eval/trace setup, AgentWikis seed, and this import review. It remains the primary home for Hermes commands, config, providers, memory, profiles, gateway, cron, skills, and subagent mechanics.
- `agent-workflows` is now a real workflow namespace with route-pattern, SOUL.md, memory-boundary, peer-profile, Ponytail, and crew operating model pages. It should receive crosslinks for governance decisions, not duplicate Hermes mechanics.
- `local-ai-infrastructure` now has local retrieval and RAG-over-AgentWikis pages. It is the right primary home for local/offline model stack tradeoffs, with Hermes setup notes linked back to `hermes-agent`.
- `eval-trace` now has context-overfitting, workflow-quality evaluation, and Eval Trace entity pages. It should crosslink auxiliary-model/evidence-gate footguns, not own general Hermes setup.
- `pixi-vault` now has Pixi Wiki and compiler-model pages. It owns the reusable import methodology and source/output repo boundary, not Hermes operations.
- Newly populated `ai-native-product-surfaces`, `curated-tuning-datasets`, and `rl-sim-labs` do not materially change this import route. They are useful only if a specific Hermes tool becomes part of a product demo, dataset pipeline, or RL experiment workflow.

### Source inspection notes

- Hermes Guide `/wiki/` is still mostly landing/marketing HTML. Its reusable signal remains `/directory`, now observed as a 156+ tool directory across Dev Workflow, Integrations, Personal Assistant, Meta & Ecosystem, Business Ops, Enterprise, Content Creation, Cost Optimization, Creative, Research, Messaging, Trading & Markets, and Privacy/Self-Hosted.
- AgentWikis Hermes still exposes about 105 documents through `llms.txt` / raw markdown. It has useful topic maps for auxiliary models, deployment backends, cron troubleshooting, profiles, subagents, memory, local models, release notes, providers, platforms, and ecosystem pages.
- Any command/config/runtime claim from either external source still requires official Hermes docs or local installed source verification before use.

### Candidate imports by priority

#### Import now

No new full imports recommended from the re-run. The high-reuse material is already represented as source-priority, curated seed, eval/trace setup, and this routing review. Importing more now would mostly duplicate official docs or AgentWikis pages without a live operating need.

#### Crosslink only

- `Subagents & Delegation` — crosslink from `agent-workflows` route-governance pages to the Hermes mechanics in `hermes-agent`; do not duplicate the API mechanics in workflow pages.
- `Profiles & Multi-Instance` — crosslink from `profile-memory-boundaries`, `peer-profiles-vs-child-processes`, and `hermes-soul-md-wiring` to a future Hermes mechanics page if Jamie asks for one.
- `Local Models & Airplane Mode` — crosslink from `local-ai-infrastructure`; import only if local/offline Hermes operation becomes an active slice.
- `Auxiliary Models` — crosslink from `eval-trace` for evidence gates and context-overfit diagnostics; import only a Hermes concept if troubleshooting side-task routing.
- `Hermes Guide Directory` and AgentWikis ecosystem pages — keep as a source pointer for future triage; do not create 156 entity pages.

#### Import on demand

- `Memory Providers Compared` — synthesize only when choosing or troubleshooting Honcho/Mem0/Holographic/Hindsight/etc.; primary `hermes-agent`, crosslink `agent-workflows` and `local-ai-infrastructure`.
- `Deployment Backends Compared` — synthesize only when making a VPS/WSL/local/Docker/Modal/Daytona choice; primary `hermes-agent`, crosslink `local-ai-infrastructure` and `agent-workflows`.
- `Hermes Cron Troubleshooting` — create only when a real cron job fails or crew cron behavior needs a durable checklist; primary `hermes-agent`, crosslink `agent-workflows`.
- `Hermes Auxiliary Model Routing` — create only when side-task routing/compression/vision/web-extract behavior affects work quality; primary `hermes-agent`, crosslink `eval-trace`.
- `Hermes Ecosystem Directory Triage` — create only when Jamie asks to evaluate external Hermes tools; primary `hermes-agent`, crosslink `pixi-vault` for import method and `agent-workflows` for route/governance patterns.

#### Skip

- Wholesale AgentWikis mirror.
- Hermes Guide landing/marketing pages.
- Video transcripts unless a specific workflow becomes durable.
- Release/version pages unless debugging historical behavior.
- Provider/platform pages unless Jamie is configuring that provider/platform.
- Onchain/trading/game/novelty ecosystem tools unless a matching project is opened.
- Entity pages for every memory provider, backend, community project, or directory listing.

### Updated routing table

| Candidate | Primary namespace | Crosslink namespaces | Page type | Action | Rationale |
|---|---|---|---|---|---|
| External Hermes import methodology | `pixi-vault` | `hermes-agent`, `agent-workflows` | synthesis / source pointer | Crosslink only | Reusable import/routing logic belongs to compiler/source methodology, while this page remains the Hermes-specific assessment. |
| Hermes commands/config/providers/profiles/gateway/cron/skills | `hermes-agent` | `agent-workflows`, `eval-trace` | concept or synthesis | Import on demand | Durable only when verified against official docs/local source and tied to Jamie/Pixoid operations. |
| Subagents & delegation mechanics | `hermes-agent` | `agent-workflows` | concept / decision table | Crosslink now; import on demand | Hermes owns tool mechanics; Agent Workflows owns when to delegate/spawn/schedule. |
| Profile/peer/worker boundaries | `hermes-agent` | `agent-workflows` | concept | Crosslink now; import on demand | Existing workflow pages already cover route boundaries; import mechanics only if configuring profiles. |
| Memory providers comparison | `hermes-agent` | `agent-workflows`, `local-ai-infrastructure` | synthesis | Import on demand | High-reuse for provider choice, but stale/risky without official/local verification. |
| Deployment backends comparison | `hermes-agent` | `local-ai-infrastructure`, `agent-workflows` | synthesis | Import on demand | Backend tradeoffs are reusable when choosing local/VPS/Docker/remote execution; no active decision in this review. |
| Local Models / Airplane Mode | `local-ai-infrastructure` | `hermes-agent`, `agent-workflows` | concept / source pointer | Crosslink only now | Local/offline tradeoffs belong to local infrastructure; Hermes Agent should hold only verified setup mechanics. |
| Auxiliary models / side-task routing | `hermes-agent` | `eval-trace`, `agent-workflows` | concept | Import on demand | Useful for evidence-gate and side-task failures, but should be verified against docs/source before trusted. |
| Cron troubleshooting checklist | `hermes-agent` | `agent-workflows` | concept/checklist | Import on demand | Likely reusable for crew cron, but best created from a real failure or official-doc check. |
| Hermes ecosystem directory triage | `hermes-agent` | `pixi-vault`, `agent-workflows`, `local-ai-infrastructure` | summary | Import on demand | Directory is broad and noisy; only a curated shortlist beats future web search. |
| Product/demo uses of Hermes tools | `ai-native-product-surfaces` | `hermes-agent`, `agent-workflows` | source pointer | Defer | New namespace exists, but no candidate source is product-surface-specific yet. |
| Dataset/fine-tuning uses of Hermes tools | `curated-tuning-datasets` | `local-ai-infrastructure`, `hermes-agent` | source pointer | Defer | No external Hermes content is dataset-corpus-specific except possible future source collection tooling. |
| RL/simulation workflow uses of Hermes tools | `rl-sim-labs` | `eval-trace`, `local-ai-infrastructure`, `hermes-agent` | source pointer | Defer | No external Hermes content is RL-sim-specific unless a tool is adopted for Critical Ranger operations. |

### Practical verdict

Keep the review as the durable artifact. Do not import new pages until Jamie asks for one of the on-demand operating questions. The populated namespaces make crosslinks more precise, but they do not justify a broader mirror.


<!-- ===== ai-native-product-surfaces/CLAUDE.md ===== -->

# AI-Native Product Surfaces Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/ai-native-product-surfaces/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to: AI-native product/application surfaces, problem framing, product demos, PM case studies, job-search edge dashboards, J-Space-Replay, LKY Avatar, I-know-kungfu, planned program intelligence, myAbode, and product-language frameworks.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== ai-native-product-surfaces/README.md ===== -->

---
title: AI-Native Product Surfaces
created: 2026-06-16
updated: 2026-07-17
type: namespace-overview
status: scaffold
category: product
namespace: ai-native-product-surfaces
confidence: medium
---

# AI-Native Product Surfaces

> **Definition:** AI is any device that perceives its environment and constraints to take actions that maximize its chance of successfully achieving its goals.

> Scaffold namespace for the Pixi Vault AgentWikis compiler.

## Scope

### Covers

AI-native product/application surfaces, problem framing, product demos, PM case studies, product-management system-steering frameworks, side-quest validation, AI-era judgment and taste, role-aligned deployed portfolio proof, side-door opportunity and public-proof synthesis, J-Space-Replay, LKY Avatar, I-know-kungfu, planned program intelligence, myAbode, agent output decision artifacts, and product/capability-language frameworks.

### Not Covered

Generic product management notes that do not involve AI-native surfaces; local model infrastructure unless relevant to product behavior.

### Current As

2026-07-17 — active namespace. Includes Jamie's top-level AI definition, Product Management as System Steering, Side-Quest Validation Loop, Interaction Mode Routing, Material Loop / Glass Interfaces, Taste Requires Contact, World Model Control Surfaces, Agent Output Decision Artifacts, Role-Aligned Deployed Project Proof, Side Doors: Make Useful Work Legible, Anthropic J-space / Jacobian lens as a product-surface concept, video retrieve-then-verify / verified video answer concepts, compiled product-surface entities and concepts, Job Edge as a live job-search edge/dashboard prototype, Shifu as a local-first searchable video knowledge prototype, J-Space-Replay as a public demo for replaying VLM lens readouts over video, and LKY Avatar as a local fictional-interview stack with tuned voice, animated portrait, executed interaction gates, and a merged audited fact-grounding layer awaiting live operator proof. Cross-format attention and distribution guidance lives in `content-distribution`.

## Canonical Source Roots

- `Projects/Job Edge/Index.md`
- `Projects/J-Space-Replay/Index.md`
- `Projects/LKY Avatar/Index.md`
- `Projects/Shifu/Index.md`
- `Projects/I-know-kungfu/Index.md`
- `Projects/Planned Program Intel/Index.md`
- `Projects/Planned/PRD.md`
- `Projects/myAbode/Index.md`
- `Knowledge/concepts/ai-native-problem-framing-framework.md`
- `Knowledge/concepts/interaction-mode-routing.md`
- `Knowledge/concepts/j-space-global-workspace.md`
- `Knowledge/concepts/material-loop-and-glass-interfaces.md`
- `Knowledge/concepts/taste-requires-contact.md`
- `Knowledge/concepts/world-model-control-surfaces.md`
- `Knowledge/concepts/agent-output-decision-artifacts.md`
- `Knowledge/concepts/role-aligned-deployed-project-proof.md`
- `Knowledge/concepts/product-management-as-system-steering.md`
- `Knowledge/concepts/side-quest-validation-loop.md`
- `Knowledge/concepts/video-retrieve-then-verify-loop.md`
- `Knowledge/concepts/verified-video-answer-surfaces.md`
- `Knowledge/raw/articles/tonbistudio-mini-vss.md`
- `Knowledge/raw/articles/nvidia-vss-docs.md`
- `Knowledge/raw/transcripts/yann-lecun-world-models-next-ai-revolution.md`
- `Knowledge/raw/transcripts/if-you-want-good-taste-you-have-to-eat.md`
- `Knowledge/concepts/verb-first-product-positioning.md`
- `Knowledge/concepts/find-the-lock-problem-first.md`
- `Knowledge/concepts/side-door-opportunity-search.md`
- `Knowledge/raw/articles/how-to-enter-side-doors-maja.md`

## Crosslinks

- [[../agent-workflows/README|agent-workflows]]
- [[../eval-trace/README|eval-trace]]
- [[../content-distribution/README|content-distribution]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/ai-native-product-surfaces/README.md
/raw/ai-native-product-surfaces/wiki/index.md
/wiki/ai-native-product-surfaces/README.md
/wiki/ai-native-product-surfaces/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== ai-native-product-surfaces/raw/transcripts/yann-lecun-world-models-next-ai-revolution.md ===== -->

---
source_url: https://youtu.be/72Xj8k5WQX4?si=tFQOgcbG-xzmz7WI
ingested: 2026-06-26
sha256: b9eb1d14ab4133de9902cdc46cbdc6b3410b601d35175b57dab3244dc17f7fd5
source_type: transcript
speaker: Yann LeCun
---

# World Models: Possibly the Enabler for the Next AI Revolution

**Format:** Cleaned Markdown transcript
**Source:** User-provided transcript
**Note:** Light cleanup applied for punctuation, paragraphing, and obvious speech disfluencies. Meaning preserved.

## Talk

**Speaker:**

Yeah, I’ll talk about world models, possibly the enabler for the next AI revolution.

There are a lot of machine learning people in the room, perhaps. I have bad news for you: machine learning sucks. When we compare the learning abilities of machines with humans and animals, clearly there is a big gap.

People and animals can learn new tasks extremely quickly and with very few trials, very few samples. People have common sense. Animals too, physical common sense. There are a lot of tasks that we can accomplish zero-shot, even if we have never faced them before.

How do we do this with machines? We have very powerful AI techniques that everybody is using, but they do not really handle the real world. They do not handle continuous, high-dimensional, noisy data. Language is easy by comparison. The real world is messy. Language is simple.

This connects with what Vladlen said earlier, and Jitendra as well: Moravec’s paradox. Things that are simple for humans are difficult for computers, and things that are complicated for humans turn out not to be that difficult for computers, like playing chess, computing integrals symbolically, solving equations, proving math theorems, and so on.

How is it that a 10-year-old can basically do what you would like a domestic robot to do, and do most of those tasks without actually being trained to do them? The first time you ask them, they can do it. They may not want to do it, but they can.

How come any teenager can learn to drive a car in a few hours of practice, yet self-driving car companies have literally millions of hours of training data? Despite that, they cannot use those millions of hours of training data to get a machine, just imitating humans, to drive at the same level of reliability. Otherwise, we would have Level 5 self-driving cars, and we do not. At best in the consumer car business, we have Level 2 or 3. Robo-taxis are heavily engineered with various sensors and other things.

So we keep bumping into Moravec’s paradox, and we really have to go beyond this.

If you believe that intelligence requires grounding, and some philosophers and certainly some language people do not believe that is necessary, but I think it is, then this matters. Like Vladlen, we are in Switzerland, outside Jean Piaget. He was a big influence on me.

Piaget had a debate with Noam Chomsky in France in the late 1970s. They were debating whether language was innate or learned. There were transcriptions of that debate, with people participating in it. One of them was a guy who had worked with Piaget and was a professor at MIT. He was talking about the perceptron, saying that these simple machine learning models were capable of learning surprisingly complex tasks, and that this might be evidence that learning is possible, contrary to what Chomsky was saying.

This guy was Seymour Papert. He was a professor at MIT, and 10 years before that he had written a book that basically killed the entire field of neural nets by pointing out the limitations of the perceptron. But here he was 10 years later arguing that those things were actually interesting to study.

Piaget is often quoted as saying: “Intelligence is not what you know, it is what you do when you do not know.” In fact, he never actually said this. It is apocryphal. But other psychologists distilled his thinking into this sentence, which he never said.

Intelligence is not an accumulation of declarative knowledge. LLMs are an accumulation of declarative knowledge. Not just that, but the main reason they are useful is because they can accumulate a lot of declarative knowledge.

Intelligence is not a collection of skills. You can probably build a machine to accomplish almost any task if you spend enough resources on it, including things like self-driving. But that is not really what intelligence is.

Intelligence is the ability to learn to drive in about 20 hours, to learn any new task with very little training, or to accomplish new tasks. That is really what intelligence is. That is really what Piaget means.

That means we are not going to have any simple measure of intelligence, because any particular task can always be cracked if you spend enough effort and time. It is more about how adaptive you are.

This connects to something Vladlen said: the notion of AGI is complete nonsense. Human intelligence is specialized. The characterization of human intelligence is that it is very quickly adaptive, and we can learn new tasks. All of us know different sets of knowledge and have different skills, because we have been exposed to different environments and have had to solve different problems. We are adaptive. That is really what intelligence is.

## How Humans and Animals Learn

How do humans learn, and animals for that matter?

A lot of learning takes place in the early months of life, mostly by observation. A two-month-old baby can gesticulate and can develop a dynamical model of its own limbs, but basically cannot affect the world. It cannot move an object or anything. But it can learn a lot of things about the world.

One thing a baby can learn really quickly is that the world is three-dimensional. Why? Because the fact that every point in the world has a distance from us is the best way to explain how our view of the world changes when we move our head. Babies do not necessarily move their heads, but they are being moved. They see parallax and derive from this the fact that the world is three-dimensional.

We can do this with learning machines today. They learn that the world is three-dimensional only by being exposed passively to videos. That is interesting.

Basic concepts like object permanence are learned really quickly. Notions of stability, rigidity, and things like that. But what we would consider intuitive physics, things like inertia and gravity, take nine months for human infants. It is shorter for most animals.

If you put an eight-month-old or nine-month-old on a high chair and put a bunch of toys in front of them, the child will most likely systematically take all the toys, throw them on the floor, and watch the result. They are doing the experiment that gravity applies to everything.

That takes a long time. How does that happen? What type of learning is taking place? They are doing experiments, but they can also learn about gravity by observation.

If you show the scenario at the bottom, where a car is on a platform and you push it off the platform, but it appears to float in the air, a six-month-old will barely pay attention. They have not learned about gravity yet. A 10-month-old will be very surprised, like the little girl in the slide.

That is how psychologists measure whether a baby has learned a particular concept about the world, through violation of expectation. We can use those techniques to test whether machine learning systems have acquired some notion of common sense.

There is a lot that can be said about this. Jitendra and I collaborated on a paper here, mostly written by Emmanuel Dupoux, and Jitendra had very little contribution to it, on this whole set of questions.

## What Intelligence Is

What is intelligence really, if it is not an accumulation of skills or declarative knowledge?

It is the ability to accomplish new tasks and solve new problems without prior training.

Again, AGI makes no sense as a phrase. Human intelligence is specialized. The question is not whether you know how to do everything. The question is whether you can learn quickly how to do anything, or a wide spectrum of things.

This is a somewhat philosophical paper at the bottom, written by some of my young colleagues.

Here is a simple calculation. There are still a lot of people, particularly on the west coast of the US, who believe that we are going to reach what they call AGI by scaling up LLMs, maybe training them on synthetic data, maybe using a few tricks in post-training and reinforcement learning. I think that is impossible.

I am a believer in grounded intelligence. You can do this simple calculation.

A typical LLM today is trained on something like 20 trillion words. That corresponds to about 30 trillion tokens. Each token is about three bytes, so the data volume is about 10^14 bytes. This would take about 400,000 years for any human to read.

Compare this with what a four-year-old has seen during his or her life. That is about 16 hours of wake time per day, which is a small amount of video, about 30 minutes of YouTube uploads. We have two million optic nerve fibers carrying about one byte per second each. So the data volume that a four-year-old has seen through vision, and probably through touch as well, is about 10^14 bytes.

A four-year-old has seen the world through vision with the same amount of data as 400,000 years of text, with all the human-produced text publicly available on the internet.

We are not going to get to anything like human-like intelligence by just training on text. It is just not going to happen.

Of course, you might say video is much more redundant than text. But that is a feature, not a bug. If you want to train a system, particularly using self-supervised learning, you need redundancy in the data. If you do not have redundancy, you cannot learn anything. Redundancy is a good thing. You do not want too much of it, though.

## Inference by Optimization

There is another question about the right properties of intelligent systems. In my opinion, an important property is the mode of inference.

Does the system compute its output by propagating through a fixed number of layers of some neural net? Or consider the alternative: computing the output by searching for an output that is most compatible with the input.

You observe a situation. That runs through some perception module that produces some representation of the current state of the world as you observe it. You can directly produce an action. That is a reactive system.

Or you could imagine an action and have the intelligent system figure out whether it is a good action for this observation. Is this something that will accomplish the task I want?

The objective here characterizes whether the task the system wants to accomplish has been accomplished. Think of it as a cost function. It is not used for learning. It is used for inference. Think of it as negative likelihood in a probabilistic inference model, or as I prefer to think of it, an energy function.

The inference process is a process by which you search for an output that minimizes some energy function at inference time. That is intrinsically more powerful computationally than just propagation through a fixed number of layers.

Contrast the model on the left, which is LLM-like. You take a window of inputs, run it through a fixed number of layers of a big neural net with a few hundred billion parameters, and produce one token. Then you shift that token into the input and produce the second token, and so on.

That is autoregressive prediction. Every token involves a fixed amount of computation: running through a fixed number of layers of some neural net. This is not a good model of reasoning.

The way you coerce an LLM to do reasoning is that you trick it into generating more tokens. But that is not the way we reason. We reason internally. We do not reason in token space, or even in language.

Compare this with the model on the right, which is a slight specialization of the previous one.

You perceive the world or your environment. You get some idea of the current state of the world. Then you imagine a sequence of actions, a proposal for an action. You feed it to an internal world model, and the world model predicts the outcome. Then it feeds this outcome to an objective that measures to what extent a task has been accomplished.

Then, by optimization, you search for an action sequence that optimizes this objective, or minimizes this energy, at inference time.

In my opinion, that is a much more powerful model. But you need a world model.

## A World Model Architecture

I settled on this idea or architecture about five years ago. I wrote a long paper about it and put it online in 2022 with some general architecture. If you want to take pictures, here are QR codes. It is relatively easy to read, but long.

It is based on the idea that reasoning and planning are essential, and they proceed by energy minimization rather than forward propagation. For this to work, you need a world model.

It is the same process I described before, with a few additional tricks.

You observe the environment. A perception module produces a representation of the initial state of the world, but only a representation of what you currently perceive. You may have to combine this with the content of a memory to get a complete idea of the state of the world, or at least what you know about it.

Then you feed this to your world model, together with a proposal for an action sequence. Your world model predicts the outcome of that action sequence. You feed this to an objective, an energy function, that measures to what extent a particular task has been accomplished.

This function outputs zero if the task is accomplished, and some positive number if the task is not accomplished. Perhaps it measures some distance to the task being accomplished.

You can have another set of objectives that are guardrails. They ensure that whatever state sequences the system is going to take the world through will not kill anyone, hurt anyone, or have any deleterious effect.

A system constructed this way can be made intrinsically safe because it has to obey and optimize the guardrail objective with every output it produces.

This is not the case for an LLM. The only way an LLM can be made safe or non-toxic is by fine-tuning it. There is always a way to break the conditioning, or jailbreak the system. Here, you cannot jailbreak a system like this. It can do nothing but optimize the guardrail objectives and the task objective.

If you have a world model, there are certainly a lot of roboticists and optimal control people in the room, you can apply this world model multiple time steps. Each action sequence can be decomposed into a sequence. The guardrails can be applied to all the steps in the sequence.

That is the way you would use a world model. The way you plan by optimization is akin to model predictive control, MPC, very classical stuff in optimal control going back to the 1960s.

## Hierarchical Planning

Ultimately, what you want is something that can do hierarchical planning. All of us do hierarchical planning. Animals do hierarchical planning.

What is hierarchical planning? Suppose I am sitting in my office at NYU and I want to be in Paris tomorrow. There is no way I can plan my entire trip to Paris in terms of muscle actions 10 milliseconds by 10 milliseconds, which are the elementary actions that humans can do.

I cannot do that because, first of all, it is too long. Second, I do not have the information. I do not know how long I will have to wait on the street before a taxi stops. There is no way I can plan the entire thing.

I have to do hierarchical planning.

At a high level, I can say: I do not know how long it will take me to go to the airport, but maybe roughly an hour or an hour and a half. So I need to get to the airport and catch a plane. That is a two-step high-level plan. I do not need to know many details to make that plan.

Now I have a subgoal: being at the airport. I am in New York, so going to the airport involves going down to the street, hailing a taxi, and going to the airport.

Now I need to go down to the street. I am in an NYU building, so that involves walking to the elevator, pushing the button, getting down, and walking out the door.

Now I have a subgoal: getting to the elevator. You can go down this hierarchy.

At some point, you get to a point where the action you need to take is very simple. It is something you are familiar with. You may not have to use your full mental power to plan the action. You can probably stand up from your chair without having to think about it. That could just be a policy.

Ultimately, we want systems to do hierarchical planning.

How do we solve that? This is an unsolved problem. If you are a roboticist, or an AI for robotics person, or an agentic AI person starting a PhD on this topic, this is a great topic. It is completely open. Nobody knows how to do this, or nobody has proved that they know how to do this.

## Training World Models

Now the big question is: how are we going to train those models?

Hierarchical or not, let us start with non-hierarchical. First we have to figure out what architecture to give them. A natural instinct these days is to train a generative model.

In fact, I have been working on trying to train world-model-like things for about 15 years, mostly failing for the first 10, because I was trying to train generative models.

What is a generative model?

Self-supervised learning has been incredibly successful in the context of language. You take a string of words, remove some of the words, corrupt the input, run the corrupted input through a big neural net, and train it to recover the missing parts.

That works amazingly well for text. The original models like BERT used to do this. An LLM is a special case where the only word you remove is the last one, so the entire system is trying to produce the next word in a sequence.

It works amazingly well and it scales if you do it right.

It does not work if you apply it to video.

If you take a video and show the initial segment of the video to the system, then ask it to predict what will happen next at a pixel level, it does not really work. The representations you get from the system for your video are not particularly good.

The reason is that you simply cannot predict everything that takes place in a video. There is an infinite number of plausible things.

In text, it is easy because there is only a finite number of words. You can get the system to produce a probability distribution over all possible words or tokens in your dictionary.

You cannot do this with video. There is an incredibly large number of possible video frames.

Take an example. If I take a video of this room, start here, slowly rotate the camera, stop here, and ask the system to continue the video, it is probably going to predict that we are in some sort of classroom or auditorium, that the room has a finite size, that there might be windows on this side, and things like that.

There is absolutely no way the system can predict what all of you look like, or which chairs are unoccupied. It is impossible. You just do not have the information.

So when you train a system to make this kind of prediction, you kill it.

Of course, you are going to tell me: but we can train systems to produce cute videos. Video generation, yes. But this prediction is usually done in representation space, not pixel space. It is only a second stage that turns the predictions into high-resolution, high-frame-rate videos. The system only needs to produce one cute-looking video. It does not need to actually represent all plausible videos. That is a much simpler problem.

As I said, I have been working on this for the better part of the last 15 years. Here is a 10-year-old paper where we tried to train a neural net to predict short video clips, two frames from four frames of context. You get blurry predictions. Why? Because the system predicts the average of everything that can happen.

Of course, you can correct that with latent variable models like diffusion models, which we did not know at the time. We tried to use GANs and things like that, but were not too successful. Perhaps using latent variable models would help, diffusion models in particular, which of course produce cute videos.

Do they actually understand the world? The evidence is no.

## Joint Embedding Predictive Architecture

Here is my solution: an architecture called joint embedding, or more precisely Joint Embedding Predictive Architecture, JEPA, shown on the right.

On the left you have a generative architecture. You observe X, maybe you observe A, an action that is taking place, and you observe the result Y. The system is trying to reconstruct Y in its most minute details.

With JEPA, you observe X, Y, and A, but you encode both X and Y, and prediction takes place in that representation space.

That is a major difference. The system can essentially eliminate from the input, by constructing a representation of Y, all the information about Y that is simply not predictable. That makes the prediction more abstract, with fewer details, but more accurate in a way.

How do you train a generative model? It is easy because the cost is just a reconstruction cost. You train it to reconstruct. You can train it as an autoencoder, but then you need to restrict the information content in the code, or as a denoising autoencoder, which is what a lot of techniques like masked autoencoders have attempted to do.

That means taking an input, corrupting it in some way, and training an autoencoder to recover the initial one. Diffusion models are a special case of this general idea of denoising.

The bad news is that when you train systems of this type to learn representations of images, you do not get good representations. If you use the representations of images obtained this way and feed them to a downstream task that you train supervised, the results are not great.

To get good results, you have to use joint embedding architectures. All the best systems that use self-supervised learning to train image or video representation systems use joint embedding. None of them uses reconstruction.

For images, either you have two views of the same scene and you train a neural net to produce representations, telling the system you want those two representations to be identical, or you use the corruption technique. You take an input, corrupt it or transform it in some way, and train this JEPA architecture to predict the representation of the original image from the representation of the corrupted version.

There is a big issue: the system can collapse.

Generative models can also collapse to some extent. If you train an autoencoder without a restriction on the information content of the code, your autoencoder learns the identity function. That is a collapse. It is not going to learn anything useful.

Similarly, a system like this can collapse by completely ignoring the inputs and producing constant representations. Then the prediction problem is trivial. If you just train a system of this type to minimize prediction error, it is going to collapse. It is not going to do anything useful.

The whole trick of self-supervised learning for joint embedding systems is how you prevent collapse.

My favorite concept for preventing collapse is information maximization. You come up with an objective function that measures some sort of information content of the representation that comes out of your encoders, and you try to maximize that information content. Your cost function is minus the information, or something like that.

There are a bunch of techniques for this from the last six or seven years, with names like MCR, MCR^2, VICReg, VICRegL, and Barlow Twins. Barlow Twins and VICReg come from people working with me. The other ones are from other groups. MCR comes from Berkeley, and MCR^2 from a colleague at NYU in neuroscience.

This idea of JEPA is gaining popularity. There are about 1,700 papers that mention “joint embedding predictive architecture” spelled out on Google Scholar.

## Measuring Information Content

There is an issue with this type of method: how do you measure information content?

We need a cost function that is a differentiable measure of information content so we can backpropagate gradients and maximize it.

The bad news is that, first, we do not have objective measures of information content, because all the proper definitions are based on knowing the distribution of the vectors, or whatever you want to measure the information content of. We do not know the distribution. We only have samples coming out of an encoder.

How do you compute information content from a finite number of samples? That is the first problem.

The second problem is that, to maximize something, you would need a lower bound on information content, so that when you maximize, you push the actual information content up. The problem is that every empirical measure we have is an upper bound.

So what do we do? We come up with a good upper bound, cross our fingers, show some theorems, and so on.

## Energy-Based Models

The way to properly explain how you can train self-supervised learning systems, and every learning system really, is a framework I call energy-based models. I have been advocating for this for 20 years or so.

The basic idea is this: if you want to capture the dependency between two variables X and Y, and there is no real functional relationship between X and Y, meaning there is no single Y for a given X, only a dependency, then you cannot run a function that computes Y from X.

This is indicated by the diagram on the right. You have a bunch of data points, the black dots, and they indicate some sort of dependency between X and Y.

How do you capture this dependency, given that you cannot run a function that computes Y from X?

One way is to learn or build a contrast function, an energy function, that tells you whether a point in this XY space is near the training data or not.

Think of it as a landscape where the black dots are in the valley. In Switzerland, there would be a lake. Then you get level curves. As you move outside of those regions, the altitude goes up. The energy goes up.

Now, if I give you a value for X, you can infer a bunch of values for Y that are compatible with X. There are values of Y that minimize the energy. It is the kind of inference I was talking about earlier: inference by optimization, not by forward propagation.

You can possibly do it the other way around. If I give you Y, you can infer X from Y and give me multiple answers.

In situations like video prediction, where there is basically an infinite number of possible answers, the proper way to train a system of this type is to think of it in terms of energy-based models.

Probabilistic models are a special case where your energy has a particular form and the way you train it has a particular loss function. This is a slightly more general framework than probabilistic inference and learning.

To train an energy-based model, you have to prevent collapse. The collapse problem I was telling you about before would be manifested by the energy function being flat everywhere. You train the system to minimize energy for a bunch of training samples, and the system gives you an energy function that is zero everywhere.

That is what an autoencoder that learns the identity function does. That is what a JEPA that ignores the input and produces constant representation does. It has zero prediction error for everything. So it is a collapse.

To prevent collapse, you need one of two things.

One is contrastive methods. You generate points outside the region of data and push the energy up. You come up with a cost function that makes sure the energy of the data points comes down and the energy of other points is higher.

There is another set of methods, which I have come to prefer: regularized methods. They work by minimizing the volume of space that can take low energy. If you push down the energy of certain regions, the rest has to go up because there is only a small volume of low energy to go around.

In practice, this reduces to one of those two methods.

## Information Maximization

Let us go back to this idea of information maximization.

Suppose I run a batch of samples through one of the encoders. I get a matrix where each row is the representation for one sample, and each column is the value of one variable in the representation for all samples.

There are two ways to make that matrix informative.

One way is to make sure all the rows are different.

Another way is to make sure all the columns are different. You want to make sure the columns are different because if all the columns are the same, every variable in the representation carries the same information. That is not very informative.

You want each variable in the representation to be maximally disentangled from the others, to give independent information from the other variables.

That is an example of what we can call dimension-contrastive methods, which are a form of regularized method.

At the bottom, the type of criterion that makes the rows all different corresponds to contrastive methods, or sample-contrastive methods.

Sample-contrastive methods are very popular for certain applications. A lot of the perceptual pipelines in LLMs are trained with a technique called CLIP, which is basically a contrastive method that does joint embedding between images and text.

But I prefer the other one.

## Abstraction and Prediction

The idea that you need to find an abstract representation of an input to make prediction is very natural.

We do this all the time as humans. We do this all the time as scientists and engineers. Animals do it too.

In principle, I could explain or simulate everything taking place in this room at the level of quantum field theory or particle physics. I could simulate the trajectory of every particle in this room, going all the way down to simulating all of our brain processes and everything. In principle, running the simulation, I could figure out whether any of you actually understand the words I am saying, whether you are sleeping, or whether you are totally bored.

Of course, that is completely impractical.

What we do in science is invent abstractions that allow us to make predictions. Those abstractions ignore a lot of details about the underlying state of the system.

We invent abstractions from quantum fields to particles, atoms, molecules, proteins, organelles, cells, organisms, individuals, societies, and ecosystems. Every level in this hierarchy is a particular level of abstraction with which we describe the world. It allows us to make longer-range predictions than the levels below by ignoring many details of the lower level.

That is why the way to understand what is going on in this room at the moment is more at the level of psychology than at the level of particle physics.

Of course, physicists always make fun of everyone by saying that everything is just applied physics. Even psychology is applied physics to some extent. But in fact, there is specific knowledge about chemistry that does not derive directly from physics.

This abstraction contains new knowledge, information, or structure that was not apparent at the level below.

This idea of JEPA constructs on the concept that you need to find an abstraction to be able to make predictions.

Suppose you want to design an airplane. You need to design the airfoils for the airplane, so you do computational fluid dynamics. You simulate the flow of air around the wing. You model the state of the air in every little cube around the wing by velocity, density, and so on, and then you solve Navier-Stokes partial differential equations. That simulates the flow of air.

But it ignores a huge amount of detail in the underlying mechanism. The underlying mechanism is molecules of air bumping into each other and bumping into the plane.

You never simulate fluids at that level. It is too complicated, and it would diverge from reality really quickly because it has too many details. You have to ignore details to be able to make accurate long-term predictions.

We do this in science all the time.

World models should not be simulators. They should work in abstract space. They should not be digital twins, which is a buzz phrase. They should definitely not be generative models, as I just explained. They should not be video generation systems.

A lot of people are working on video generation and calling this world models. They are not world models. They are video generation systems.

One big message from my talk is: if you want to use world models, do not work on video generation. That is a different problem. If you want to produce cute videos, work on video generation. But if you want to control robots or industrial processes or understand the world, do not work on generation.

You want models to control complex systems where you cannot model the dynamics by writing a bunch of equations.

If you have a humanoid robot, or any kind of robot, you can write down the dynamical equations and simulate the dynamics of the robot. You can get your humanoid robot to do somersaults and kung fu and whatever. That is simple.

As soon as a robot starts to interact with the real world, it becomes much more complicated. That is more difficult to reduce to simple equations.

Think about a complex system like a turbojet, a chemical plant, a patient, or a robot that interacts with the real world in complex ways. You cannot reduce this to a small number of equations.

You have to learn a phenomenological model of the whole system, the system you control and its interaction with the environment, so you can make predictions and plan a sequence of actions to arrive at a particular outcome.

That is a world model. The concept is very old. It goes back to the 1960s and is the root of optimal control.

## SIGReg

Now I come to a particular technique that I am very fond of, and that I think we will expand over the next few months and years to do this information maximization. It is called SIGReg: Sliced Isotropic Gaussian Regularization.

The trick is the following.

You run a batch of samples through your encoders, and you get a bunch of points in a vector space, with dimension equal to the dimension of your representation space.

We are going to try to make the distribution of those points isotropic Gaussian, with the same variance in all dimensions.

Why? Because an isotropic Gaussian is a distribution where all variables are independent. They are maximally informative individually. It is also the distribution that has maximum entropy for a given variance, but we do not really care about that. What is interesting is that it makes the variables independent of each other.

How do we do this?

Of course, we do not have the distribution. We just have a bunch of points. It may be a high-dimensional space, like 2,000 dimensions, and we may have a few hundred or a few thousand points. How can we make sure this is a Gaussian?

Here is the trick. You project the individual points along a single direction, and what you get is a marginal distribution.

Of course, you still have discrete points. You do not have a continuous density. You have discrete points.

One trick is to compute the cumulative distribution that those points give you. It is a staircase because you have discrete points in one dimension.

Then you can ask: what is the distance between the staircase, the empirical cumulative distribution of my points, and the cumulative distribution of a Gaussian?

You can do that because you know what the Gaussian looks like. For every point on the staircase, you can tell whether it is to the left or to the right of the ideal Gaussian. That gives you a gradient: do I move the point this way or that way in that projection?

It gives you a gradient for every training sample in your batch.

If you make the distribution Gaussian along that projection by gradient descent, it makes the marginal distribution Gaussian along this projection.

There is a theorem that says if you do this along lots and lots of directions, then in the limit your joint distribution is actually isotropic Gaussian.

What we need to do is many projections. For all of those projections, compute those gradients, move the points, or backpropagate through the network and change the weights, so that the points move and the overall distribution becomes more Gaussian.

If you apply this to a distribution like the one on the top left, an X shape in two dimensions among 1024, and do gradient descent, you move the points. You do not train a neural net in that example. The technique I am advocating for gives you something that is sort of Gaussian-ish.

This really works in practice. We have applied it to training world models that are action-conditioned, and we have used them for planning. It works decently. The source code is available. It is very simple. You can train it on one GPU.

What we need to do with this technique is scale it up. There are a few other things we need to do, but that is the main one.

In simple cases, you can train this world model and use it to plan simple actions, as in Push-T or simple robotic situations in simulated environments. That needs to be scaled up, but it is good work.

There is a theoretical paper that we put out just a few days ago. If you make the hypothesis that the underlying distribution of your data is actually an isotropic Gaussian, and assume that the observations you get from the world are some complicated nonlinear transformation of those points, like a spiral transformation, then if you train a neural net with SIGReg on it, it will recover the original Gaussian in representation space.

It is not a general proof that it works in every case. But it is a proof that if your original explanatory variables are Gaussian, the system will recover those variables up to a rotation.

## Distillation Methods: I-JEPA, V-JEPA, and DINO

We can use these techniques in the context of self-supervised learning to train an image recognition system.

There is another set of techniques that I should mention because they work really well and are the ones that have been scaled up so far. SIGReg is conceptually my favorite method, but it is very recent and we have not scaled it up yet. These other methods are based on distillation, and we have scaled them up and obtained really good results for both images and video, with techniques like I-JEPA and V-JEPA.

What is the basic idea of those distillation methods?

You still have two encoders. So it is a JEPA architecture.

You take an input, transform it, corrupt it, or mask it, and then train the system to predict in representation space. But you do not propagate gradients through the encoder on the right.

Those are two encoders with identical architectures, and they kind of share the weights. The encoder on the right uses an exponential moving average over time of the weights of the encoder on the left.

The encoder on the left gets gradients and gets updated all the time. The encoder on the right gets updated more slowly and shares the weights.

This is derived from intuitive ideas by people at Google DeepMind who were using techniques like this to stabilize the variance in reinforcement learning. They realized you could apply this to self-supervised learning from images. They called this BYOL, Bootstrap Your Own Latent.

There are a whole bunch of methods from Meta in particular, such as SwAV and others, that use this exponential moving average idea.

A particular method called I-JEPA, which I show here, produces really good results. With I-JEPA, we were able to compare results against a generative approach called MAE, masked autoencoder. I-JEPA is not only better, it is much faster to train.

Another technique is called DINO. Many of you, I am sure, have heard of it. I know some of you have used it because there were projects in the robot demos that used DINO.

This was done by some of our former colleagues at Meta in Paris. It is completely self-supervised. It is a joint embedding architecture. It uses distillation, with various tricks I am not going to explain. There is a lot of engineering behind it.

These systems basically, at this time, produce the best generic representations of images. If you have any type of vision task you want to do, this is probably the best encoder for images.

Among other things, what we have done is use DINO as an encoder, train a world model, and do planning.

## Planning Demo

Let me show you a cute video.

You have an initial state of a simulated environment with pretty complex dynamics. You have goals at the top. At the bottom, what you see is the sequence of actions of a planner that uses this trained world model to get the world to a configuration as close as possible to the original one in less than 25 steps.

This has been applied to a number of different scenarios, like double pendulum, Push-T, and others. It now works really well.

## V-JEPA and Common Sense

More recently, we applied this to video.

You take a video, mask a big chunk of it, and train the JEPA to produce good representations, so that it can predict the representation of a full video from the representation of a partially masked one.

Once the system is trained, you use the encoder as a way to extract features from the video, and you train a head on top of it to accomplish some task.

It works really well, state of the art for many traditional vision tasks, particularly from video: action recognition, action prediction, and so on.

Instead of boring you with a table of results, one interesting thing I want to mention is that V-JEPA has learned some level of common sense.

Because we train it to predict what will happen next in a video, we can train a predictor to do that and measure its internal prediction error. We can show it a video and monitor the internal prediction error at every time step.

This system takes a window of 16 frames. We slide those frames over a video and measure the prediction error for the next 15 or 16 frames.

The cool thing is that if you show it a video where something impossible happens, something unphysical, the prediction error shoots to the roof.

It is like the little girl in one of the early slides looking at the scene of the car not falling.

If you have a video of a ball being thrown and the ball disappears, the prediction error shoots through the roof.

That is interesting because it is the first time, at least from my point of view, that I have seen a completely self-supervised system acquire some level of common sense, telling you what is possible and what is not possible.

Let me skip this. It is cute, but no. It just says V-JEPA can be used for planning. New versions of this do a better job at planning and everything.

Here is an interesting thing. Remember I told you that the way babies learn the world is three-dimensional is because it is the best way to explain how your view of the world changes when you move your head.

We took the representation learned by some version of V-JEPA called V-JEPA 2.1, and then trained a head on top of it to predict depth from a single image. It does a really good job. It produces really good results, in fact better than DINOv3.

That shows that this system, by just being trained to fill in the blanks in videos at a representation level, basically understands, in double quotes, that the world is three-dimensional. It understands the notion of object. If you use the representation as input to a segmentation system, it works decently well, and for various other things.

## Conclusion

Let me conclude.

Abandon generative models. I mean if you work on LLMs, of course, but you should not work on LLMs. At least if you are in academia, you should absolutely not work on LLMs. There is nothing you can bring to the table.

Abandon generative models in favor of joint embedding architectures if you are interested in intelligence.

Abandon probabilistic models in favor of energy-based models. I did not have time to really explain why.

I made an argument in favor of regularized methods, or information maximization through variables instead of samples. So, dimension-contrastive methods rather than sample-contrastive methods, though sample-contrastive methods have many practical applications.

I have been saying forever to abandon reinforcement learning. I do not really mean abandon it. I mean minimize its use because it is so horribly inefficient in terms of sample efficiency.

I know there are people here who work on this, but reinforcement learning is what you do when you are desperate and there is nothing else you can do.

You have to do most of the learning by observation, learning world models, and so on. Once you have good representations, you can use reinforcement learning on top of them because you already have good representations and will not require too many samples. Sometimes you cannot avoid it.

If you are interested in making real progress in AI, in grounded AI, AI for the real world, or physical AI, do not work on LLMs. Do not work on generative models either.

As you can probably guess, this does not make me very popular in Silicon Valley.

As many of you probably know, I left Meta at the end of last year and formed a new company, heard in the transcript as “AMI Labs.” Its purpose is AI for the real world, physical AI. Robotics is a use case, but it is not just that. It is control of industrial processes, anything that is high-dimensional, continuous, and noisy, for which LLMs are completely helpless.

That is the kind of problem we are working on.

That is it. Thank you very much.

*[Applause]*

## Q&A

**Moderator:**

Okay. I know there are many questions. Maybe we will take one or two, but then we have to wrap up. Please, quick questions and quick answers.

**Audience question:**

Thanks for the talk. I wanted to ask about the guardrails that you mentioned on one of the earlier slides, where you also talked about MPC.

Engineers love MPC because they can put in their constraints and describe them in state space, like 3D space. But from what I understand, in your system everything works in representation space.

How do I even get a constraint like “do not bump into the wall” into this representation space? Do you envision the system learning the constraints by itself, or can engineers really put them in?

**Speaker:**

No, you would have to learn a very small head on top of your representation that maps that to the constraint you are interested in. That part has to be trained, but you can train it with a very small number of samples because it is tiny, basically just a projection.

**Audience question:**

But you need a different encoder for each kind of constraint that you might want to put in?

**Speaker:**

Well, you need a different projector for each constraint.

If your task is to open a door, I am not talking about a constraint, I am talking about a task objective. You need some cost function to tell you: is the door open or not? That might have to be trained when you train the system to accomplish the task. But basically, that requires two samples.

**Audience:**

All right. Thanks.

**Moderator:**

Okay. I think we will have to leave it here. Thank you, Yann, very much.

**Speaker:**

All right. Thank you.

*[Applause]*


<!-- ===== ai-native-product-surfaces/wiki/concepts/agent-output-decision-artifacts.md ===== -->

---
title: Agent Output Decision Artifacts
created: 2026-06-27
updated: 2026-06-27
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai-native, product-framing, interaction-design, agent-workflows]
sources:
  - Knowledge/concepts/agent-output-decision-artifacts.md
  - Knowledge/concepts/interaction-mode-routing.md
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
  - Knowledge/concepts/visual-plan-review-surfaces.md
confidence: medium
---

# Agent Output Decision Artifacts

**Agent Output Decision Artifacts** are concise, visual, interactive surfaces that convert verbose AI-agent output into an inspectable decision.

The artifact is not a generic summary. It is a control surface: preserve what matters for the decision, expose evidence where trust is needed, and make the next action obvious.

## Core pattern

1. **Compress** the agent run into decision-critical meaning.
2. **Structure** it around three visible elements: options, risks, actions, evidence cards, or tradeoffs.
3. **Close the loop** with approve, reject, annotate, choose, or steer-back controls.

## Artifact contract

A good decision artifact:

- fits on one screen by default;
- removes repetition, caveats, filler, and process narration;
- uses simple clear sentences;
- uses cards, tables, hierarchy, or diagrams when they carry structure faster than prose;
- keeps details behind progressive disclosure;
- preserves source anchors or expandable evidence;
- makes the next action visible within 5-10 seconds.

## Why it matters

Verbose chat is useful while an agent is working. It is a weak final surface when the user needs to decide.

Decision artifacts let chat remain the command channel while the review/approval work moves into a surface that is easier to scan, compare, and steer.

## Relationship to existing lenses

- [[interaction-mode-routing|Interaction Mode Routing]] decides when chat should give way to generated review/control surfaces.
- [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]] explains why judgment-bearing work needs to stay visible, steerable, interruptible, and traceable.
- [[../../agent-workflows/wiki/concepts/visual-plan-review-surfaces|Visual Plan Review Surfaces]] is a workflow-specific subtype for turning PRDs and implementation plans into inspectable MDX/HTML review artifacts.
- [[world-model-control-surfaces|World Model Control Surfaces]] gives the control-loop shape: show state, actions, predicted outcomes, objectives, guardrails, evidence, and next safe step.

## Example surfaces

| Surface | Compresses | User action |
|---|---|---|
| Ideation artifact | long brainstorm or agent proposal | choose, reject, or validate one direction |
| PR review artifact | code-review run and verification output | merge, block, or request changes |
| Research artifact | source-heavy investigation | accept answer, ask follow-up, or inspect evidence |
| Compile/release artifact | source changes and generated outputs | approve publish or fix route gaps |

## Boundaries

- Not every agent output deserves a generated artifact; sometimes a table, diff, or short answer is enough.
- The artifact should point back to stable truth rather than becoming the only source of truth.
- Do not hide uncertainty; make it visible through confidence, evidence, open questions, or expandable detail.

## Source

Compiled from `Knowledge/concepts/agent-output-decision-artifacts.md` and adjacent Pixi Wiki concepts.


<!-- ===== ai-native-product-surfaces/wiki/concepts/ai-native-problem-framing-framework.md ===== -->

---
title: AI-Native Problem Framing Framework
created: 2026-06-16
updated: 2026-07-12
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai-native, product-framing, product-management]
sources:
  - Knowledge/concepts/ai-native-problem-framing-framework.md
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
  - Knowledge/concepts/world-model-control-surfaces.md
confidence: high
---

# AI-Native Problem Framing Framework

The **AI-Native Problem Framing Framework** is the reusable lens for deciding whether a product surface is genuinely AI-native or merely has AI attached.

## Core frame

Define the system before picking models:

- **Environment** — what data describes the world?
- **Actions** — what can the system do?
- **Goal** — what is success or what is optimized?
- **Constraints** — what must never be violated?
- **Agency constraints** — what must remain visible, steerable, inspectable, interruptible, or user-owned?

Bad framing creates bad AI. Environment, action space, objective, constraints, and agency boundaries define the intelligence problem.

[[world-model-control-surfaces|World Model Control Surfaces]] extend the frame into a planning/review loop: observed state -> candidate actions -> predicted outcomes -> objective/guardrail score -> recommended next safe step. Use it when an AI-native surface needs to expose what the system expects to happen before a human or agent acts.

Agency constraints come from [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]: AI can shorten the path from idea to artifact, but the interface should not hide the judgment-bearing parts of the loop.

## Interface mode after framing

After the environment/actions/goal/constraints frame is clear, use [[interaction-mode-routing|Interaction Mode Routing]] to choose which parts should be direct UI, agentic delegation, generative UI, or stable truth/routing.

This keeps AI-native product work from collapsing into either chatbot theatre or agentic overreach. The interface should preserve provenance, constraints, and human control where the domain requires them.

## Product-surface use

For `ai-native-product-surfaces`, this framework prevents vague “add AI” product thinking. It asks whether the surface perceives a domain, chooses or prepares actions, improves the chance of achieving a goal, and respects hard constraints.

It is especially useful for comparing:

- Planned Program Intel: event-program decision routing and institutional memory;
- myAbode: real-estate prepared next actions under compliance and adoption constraints;
- future surfaces that need prediction, optimization, and execution separated rather than collapsed into a black box.

After framing the AI system, use [[product-management-as-system-steering|Product Management as System Steering]] to make the human product calls around decision tempo, ownership seams, stakeholder dynamics, scope, and ecosystem incentives.

## Boundary

Do not blindly copy game/RL patterns into product domains. Real-world operational products have partial visibility, noisy outcomes, multiple stakeholders, and constraints that must be represented explicitly.

## Related pages

- [[interaction-mode-routing|Interaction Mode Routing]]
- [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]
- [[world-model-control-surfaces|World Model Control Surfaces]]
- [[product-management-as-system-steering|Product Management as System Steering]]

## Source

Compiled from `Knowledge/concepts/ai-native-problem-framing-framework.md`.


<!-- ===== ai-native-product-surfaces/wiki/concepts/interaction-mode-routing.md ===== -->

---
title: Interaction Mode Routing
created: 2026-06-23
updated: 2026-07-13
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai-native, product-framing, interaction-design, generative-ui]
sources:
  - Knowledge/concepts/interaction-mode-routing.md
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
  - Knowledge/concepts/taste-requires-contact.md
  - Knowledge/concepts/ai-native-problem-framing-framework.md
  - Projects/I-know-kungfu/Index.md
  - Projects/Hermes Mission Control/Index.md
confidence: medium
---

# Interaction Mode Routing

**Interaction Mode Routing** is a product refactor lens for choosing whether a task should use direct UI, agentic delegation, generative UI, or stable truth/routing surfaces.

The question is not "should this use AI?" The question is: **what interaction mode best fits the user's need for speed, control, exploration, inspection, and execution?**

## Four modes

| Mode | Use when | Failure smell |
|---|---|---|
| Direct UI | The human can act faster by manipulating visible objects than by describing the action. | Replacing a faster button, slider, table, or visual control with a slower chatbot. |
| Agentic delegation | The user wants an outcome across repetitive or cross-tool work, not every step. | Hiding judgment, provenance, or approval behind autonomous action. |
| Generative UI | The user needs to compare, inspect, tune, approve, or understand a middle-complexity task. | A prompt box that only feeds a fixed grid, or a generated surface that hides source/constraints. |
| Stable truth/routing | The surface is durable source truth, provenance, or routing. | Generated UI becoming the only place a decision, source, or constraint exists. |

## Product-surface use

Use [[ai-native-problem-framing-framework|AI-Native Problem Framing Framework]] first to define environment, actions, goal, constraints, and agency constraints. Then choose the interaction mode:

- direct manipulation for fast, visual, precise work;
- agents for boring multi-step execution;
- generative UI for review/control surfaces;
- stable truth for PRDs, project hubs, GitHub issues, handoffs, skills, MOCs, `llms.txt`, `index.json`, raw Markdown, and MCP entrypoints.

Use [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]] as the material closeness test: if the work carries taste, trust, scope, provenance, architecture, or release responsibility, keep it visible and steerable instead of collapsing it into black-box output.

Use [[taste-requires-contact|Taste Requires Contact]] as the learning-friction test: when firsthand use, diagnosis, imitation, preference formation, or final selection is how the user develops judgment, assist that act without delegating it away.

## I-know-kungfu refactor

For [[../entities/i-know-kungfu|I-know-kungfu]], the strongest next surface is a generated **Fit Check Surface** over stable wiki truth:

- source coverage;
- local overlap;
- recommended serving entrypoint;
- refusal boundaries;
- trust/eval state;
- clearly labeled evidence provenance.

This keeps the product out of two traps: pure chatbot and static card pile.

## Pixi Wiki / vault refactor

Pixi Wiki should keep source/navigation stable and generate temporary review surfaces above the corpus:

- compile-review report;
- source-to-output trace map;
- namespace coverage dashboard;
- MCP/live-route visibility report;
- broken/stale route repair panel.

## Agent workflow connection

For Hermes Mission Control, chat is the command channel, not the whole interface. Review and approval should be shaped as small generated control surfaces while durable truth remains in GitHub, Obsidian, handoffs, skills, and knowledge entrypoints.

For verbose agent output, use [[agent-output-decision-artifacts|Agent Output Decision Artifacts]] when the user needs a decision, approval, comparison, or steering surface instead of a wall of chat prose.

## Source

Compiled from `Knowledge/concepts/interaction-mode-routing.md` plus project applications in I-know-kungfu, Pixi Wiki, and Hermes Mission Control.


<!-- ===== ai-native-product-surfaces/wiki/concepts/j-space-global-workspace.md ===== -->

---
title: J-Space as Global Workspace
created: 2026-07-08
updated: 2026-07-08
type: concept
status: active
namespace: ai-native-product-surfaces
source: Knowledge/concepts/j-space-global-workspace.md
confidence: medium
---
# J-Space as Global Workspace

J-space is Anthropic's name for the model-internal subspace spanned by Jacobian lens vectors: directions in a language model's residual stream that make a token more likely to be verbalized now or later.

The paper argues that this verbalizable subspace behaves like a **functional global workspace**: content written there can be reported, modulated, used in flexible reasoning, and broadcast to downstream computations. This is a functional claim about accessible representations, not a claim about subjective consciousness.

## Product translation

```text
model activation at a position/layer
  -> project onto J-lens directions
  -> read token/concept directions with high activation
  -> inspect what is available for verbal report or downstream use
  -> optionally intervene to test whether the representation is causal
```

The useful product idea is not "read model thoughts." The useful idea is: **replay what a model is poised to verbalize so humans can inspect intermediate, silent, or weakly expressed content before trusting the answer.**

## What the paper claims

Anthropic reports that J-space has the cluster of properties associated with global workspace theory:

- **Verbal report:** J-lens readouts track what the model will say, and interventions can change reports.
- **Directed modulation:** instructed mental content can appear in J-lens readouts even while the surface output is unrelated.
- **Internal reasoning:** unspoken intermediates can appear in J-space and be causally load-bearing.
- **Flexible generalization / broadcast:** one J-space vector can feed many downstream functions.
- **Selective mediation:** flexible explicit tasks depend on J-space more than routine automatic processing.
- **Structural support:** model components appear arranged to read, write, amplify, and broadcast J-space content.

## Alignment-auditing relevance

The paper applies J-lens readouts to cases where silent strategic or situational assessments appear in J-space before or without appearing in the model output. This makes J-space a promising review surface for evaluation awareness, prompt-injection recognition, self-monitoring, or hidden objective signatures.

The boundary is just as important: the authors do **not** claim J-space monitoring is sufficient for alignment. Automatic or highly practiced behavior can route outside J-space, and single-token limitations can hide multi-token or diffuse concepts.

## Relationship to J-Space-Replay

J-Space-Replay borrows the interaction shape: it lets users replay Qwen2.5-VL logit-lens and fitted J-lens readouts over a video-answer timeline.

Keep the public claim honest:

- the Anthropic paper validates text-model J-space behavior, not VLM video behavior;
- J-Space-Replay is a demo-quality glass-box surface, not a full replication;
- the app's preset traces and UI are useful for inspecting readouts, but upload/local GPU use is required for new videos;
- the honest claim is "inspect VLM readouts," not "read model thoughts."

## Source handles

- Anthropic Transformer Circuits paper: https://transformer-circuits.pub/2026/workspace/index.html
- Canonical Knowledge page: `Knowledge/concepts/j-space-global-workspace.md`
- Source digest: `Knowledge/raw/papers/anthropic-verbalizable-representations-global-workspace-2026.md`
- Related entity: [[../entities/j-space-replay|J-Space-Replay]]


<!-- ===== ai-native-product-surfaces/wiki/concepts/material-loop-and-glass-interfaces.md ===== -->

---
title: Material Loop and Glass Interfaces
created: 2026-06-24
updated: 2026-07-13
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai-native, product-framing, interaction-design, generative-ui]
sources:
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
  - Knowledge/concepts/interaction-mode-routing.md
  - Knowledge/concepts/ai-native-problem-framing-framework.md
  - Knowledge/concepts/taste-requires-contact.md
  - https://youtu.be/az6OEZV8iHw
confidence: medium
---

# Material Loop and Glass Interfaces

**Material Loop and Glass Interfaces** is the agency/authorship lens for AI-native product surfaces.

The **Material Loop** is the cycle where a person turns an idea into a visible artifact, inspects what feels wrong, changes it, and develops judgment through contact with the work.

[[taste-requires-contact|Taste Requires Contact]] adds the input side: judgment also depends on firsthand contact with the work a person consumes. Reference gathering is not enough; the person must use, notice, name, imitate, compare, curate, and sometimes depart from what they encountered.

A **Glass Interface** keeps AI-shaped work inspectable, steerable, interruptible, and traceable. It exposes enough plan, state, sources, tools, diffs, commands, constraints, and intermediate artifacts for the user to stay close to the material without micromanaging every step.

Black-box AI optimizes for clean output. Glass AI optimizes for human agency over shapeable material.

## Output vs material

| Output | Material |
|---|---|
| Finished-looking answer | Shapeable intermediate artifact |
| Accept/reject loop | Inspect/steer/edit loop |
| Hides process | Shows relevant state and provenance |
| User becomes approver | User remains author |
| Can weaken judgment | Can build judgment |

## Material closeness test

Before choosing an interaction mode, ask:

1. Is this a taste-bearing or judgment-bearing decision?
2. Would hiding the process make the user less able to learn, steer, or verify?
3. Does the user need to see the plan, sources, diff, trace, or intermediate state?
4. Is the artifact still shapeable, or has the system collapsed it into final output?
5. Can the user interrupt, edit, branch, or take over?

If the work is boring execution, delegate it to an agent with verifiable output. If the work carries judgment, taste, trust, scope, provenance, architecture, or release responsibility, keep the user close to the material through direct UI, generative UI, stable truth surfaces, or visible agent traces.

## Relationship to Interaction Mode Routing

[[interaction-mode-routing|Interaction Mode Routing]] chooses the tactical surface: direct UI, agentic delegation, generative UI, or stable truth/routing.

Material Loop and Glass Interfaces explain why the route matters: the interface should preserve the user's ability to inspect, steer, learn, and care.

## Pixi Wiki implication

Pixi Wiki should keep source/navigation stable while generating temporary review surfaces above the corpus:

- source-to-output trace maps;
- namespace coverage dashboards;
- compile-review reports;
- MCP/live-route visibility reports;
- stale route repair panels.

The goal is not only to publish knowledge, but to keep the knowledge system close enough to the material that humans and agents can inspect, route, correct, and trust it.

## I-know-kungfu implication

[[../entities/i-know-kungfu|I-know-kungfu]] should not become a magic import button. Its strongest surface is a glass fit-check interface over stable wiki truth: source coverage, local overlap, proposed harmonization, serving entrypoint, refusal boundaries, trust/eval state, and provenance.

## Hermes Mission Control implication

Hermes review surfaces should show enough plan, diff, evidence, risk, and next-action state for Jamie to remain the author of the decision instead of merely approving a plausible agent summary.

## Source

Compiled from `Knowledge/concepts/material-loop-and-glass-interfaces.md`, inspired by Ryo Lu's "Closer to the Material" talk for Cursor Compile 26.


<!-- ===== ai-native-product-surfaces/wiki/concepts/product-management-as-system-steering.md ===== -->

---
title: Product Management as System Steering
created: 2026-07-12
updated: 2026-07-12
type: concept
status: compiled
namespace: ai-native-product-surfaces
source: Knowledge/concepts/product-management-as-system-steering.md
resource: https://roachcap.com/memos/secrets-of-the-best-pms.html
confidence: medium
---

# Product Management as System Steering

A PM steers a system of decisions, ownership seams, people, constraints, and participant incentives. The practical review formula is:

```text
Decide under ambiguity.
Own the gaps.
Route through people.
Trade scope first.
Align ecosystem incentives.
```

This lens is adapted from Fahd Ananta's [“Secrets of the Best PMs”](https://roachcap.com/memos/secrets-of-the-best-pms.html). Treat the article as practitioner judgment, not empirical proof.

## Five steering responsibilities

### 1. Match decision tempo to reversibility

Make timely calls with incomplete information, including explicit decisions not to pursue something. Move quickly on reversible choices; slow down when downside is hard to undo. Record the evidence, assumptions, rejected options, owner, and review trigger.

### 2. Close ownership gaps

Extreme ownership means no unowned seam. It does not mean the PM personally executes every task. Keep the path from problem and design through build, launch, support, and learning connected with clear handoffs and escalation.

### 3. Adapt influence to people

Understand strengths, limits, incentives, working styles, and feedback needs. Use data for empirical disagreement, prototypes for hard-to-verbalize choices, memos for durable reasoning, coaching for learning, and escalation only when its trust cost is justified.

### 4. Trade scope first

For a bounded delivery window, assume team and time are fixed until proven otherwise. Cut, sequence, or defer scope to preserve the smallest coherent user outcome. Team and time can change, but usually more slowly and expensively than scope.

### 5. Align ecosystem incentives

Map users, buyers, operators, employees, vendors, partners, investors, regulators, and other constituents. Durable products create mutual value that makes continued participation rational. The healthy target is incentive alignment and embedded value, not coercive lock-in.

## Product review questions

1. What call are we making, what are we declining, and when will we revisit it?
2. Which seam could fall between roles, and who closes it?
3. Which stakeholder dynamics or incentives could block execution?
4. With team and time fixed, what is the smallest coherent scope?
5. Which participants must gain durable value for the product to work?
6. What evidence will change the next decision?

Use [[ai-native-problem-framing-framework|AI-Native Problem Framing Framework]] to define environment, actions, goals, constraints, and agency boundaries. Use [[agent-output-decision-artifacts|Agent Output Decision Artifacts]] to make the call and its evidence reviewable. Use [[role-aligned-deployed-project-proof|Role-Aligned Deployed Project Proof]] to show this product judgment in a portfolio case study.

## Guardrails

- Decisiveness is not impulsiveness.
- Ownership is not micromanagement.
- Prioritization must preserve the core user outcome.
- Influence tools lose force when overused; trust is a renewable coordination asset.
- Incentive alignment must not become exploitative retention or dark patterns.

## Source

- Fahd Ananta, [“Secrets of the Best PMs”](https://roachcap.com/memos/secrets-of-the-best-pms.html), published 2026-02-26.


<!-- ===== ai-native-product-surfaces/wiki/concepts/role-aligned-deployed-project-proof.md ===== -->

---
title: Role-Aligned Deployed Project Proof
created: 2026-07-09
updated: 2026-07-12
type: concept
status: active
namespace: ai-native-product-surfaces
source: Knowledge/concepts/role-aligned-deployed-project-proof.md
confidence: medium
---

# Role-Aligned Deployed Project Proof

A strong portfolio project is not merely “an AI app.” It is a live, owned artifact built around a real responsibility, workflow, or pain from a target role.

The selection rule is:

```text
target role or JD
→ repeated job verb
→ painful or decision-critical workflow
→ smallest useful live artifact
→ evidence and limits
→ tailored case study
```

The intended hiring signal is simple:

> This person already understands the work we do.

This is a useful heuristic, not universal proof about interview outcomes. The quality of the artifact, role fit, communication, and the rest of the application still matter.

## Four hard gates

1. **Role-specific** — maps to a responsibility, toolchain, decision, or pain visible in the job description.
2. **Deployed** — a reviewer can use a live URL without installing the repo.
3. **Yours** — the builder can explain the product choices, implementation, tradeoffs, limits, and feedback loop.
4. **Truthful** — claims are supported by real behavior, tests, data, or user evidence.

AI API wiring alone is not the proof. The role-specific decisions around the system are the proof.

For PM roles, use [Product Management as System Steering](product-management-as-system-steering.md) to show the ambiguous call, ownership seam, stakeholder/influence choice, scope cut, ecosystem incentives, and evidence that changed the next decision.

## Build-selection questions

- Which exact role or job description is this for?
- Which verbs repeat: review, investigate, forecast, analyze, summarize, route, monitor, optimize, communicate?
- Who owns that workflow, and what delay, error, risk, or decision cost do they experience?
- What is the smallest end-to-end artifact that performs one useful transformation?
- Can it be deployed cheaply and reviewed in under two minutes?
- What evidence will show that it works?
- Which failure mode or boundary should be visible?
- What demonstrates judgment from the target role rather than only API integration?

## Starter idea catalog

Tailor these against a real job description. Do not treat them as default builds.

### Software engineering

- AI code review bot: diff in, bounded risks and review questions out.
- Smart bug explainer: logs and environment context in, likely causes and next checks out.
- Resume parser API: resume text in, validated structured fields and confidence out.
- PR summarizer: pull request in, changes, risks, tests, and reviewer questions out.
- Semantic documentation search: question in, cited answer or explicit refusal out.

### Data science and ML

- Job-market trend analyzer: public postings in, sourced skill and role trends out.
- Churn predictor: public dataset in, evaluated classification and explainable review surface out.
- Sentiment dashboard: public posts in, time-based trends with coverage and bias notes out.
- Sales forecasting tool: historical series in, backtested forecasts and scenario comparisons out.

### Business, marketing, and operations

- Content brief generator: keyword and audience in, editable sourced brief out.
- Email campaign analyzer: campaign copy in, prioritized CTA, tone, and subject-line experiments out.
- Competitive intelligence bot: public company sources in, cited positioning comparison out.
- AI meeting summarizer: transcript in, decisions, owners, deadlines, and unresolved questions out.

### Communications and information systems

- Press release analyzer: release in, strategy, claims, risks, and journalist angles out.
- Internal knowledge-base Q&A: documents in, permission-aware cited answers or “not found” out.

## Translate the proof by role

- **Software engineering:** integration quality, reliability, tests, observability, security, and deployment.
- **Data science / ML:** data provenance, baselines, evaluation, uncertainty, drift, and model limits.
- **Business / marketing / operations:** decision impact, workflow adoption, experiment design, and measurable action.
- **Communications / information systems:** source fidelity, information architecture, editing judgment, permissions, and retrieval quality.
- **Product management:** problem selection, user/workflow evidence, scope tradeoffs, success measures, launch choice, and learning.

## Guardrails

- Start from the role, not the project list.
- A GitHub repo alone is not deployed proof.
- Do not hide empty states, weak data, model uncertainty, or unsupported claims.
- Prefer one complete role-shaped workflow over a broad platform.
- Tailor the artifact itself, not only the application copy.
- Build the smallest missing signal; do not duplicate a capability already proven by another project.

## Related concepts

- [AI-Native Problem Framing Framework](ai-native-problem-framing-framework.md)
- [Interaction Mode Routing](interaction-mode-routing.md)
- [Agent Output Decision Artifacts](agent-output-decision-artifacts.md)
- [Product Management as System Steering](product-management-as-system-steering.md)


<!-- ===== ai-native-product-surfaces/wiki/concepts/side-quest-validation-loop.md ===== -->

---
title: Side-Quest Validation Loop
created: 2026-07-13
updated: 2026-07-13
type: concept
status: active
namespace: ai-native-product-surfaces
confidence: medium
source_url: https://www.youtube.com/watch?v=SE401zf_fgM
---

# Side-Quest Validation Loop

## Definition

A side quest is a **small, reversible, useful, and enjoyable experiment** that puts an idea in contact with real people before it earns serious product or business commitment.

> Shrink the idea, ship a useful probe, expose it to reality, observe commitment, then kill, adjust, continue, or promote it.

Deya's video frames this through creator and business anecdotes and demonstrates prototypes using sponsored tool Lovable. The transferable method is tool-independent, and the examples should be treated as practitioner evidence rather than universal proof.

## Design criteria

1. **Tiny enough** — test the important uncertainty without triggering a large project.
2. **Useful enough** — solve one recognizable problem for one specific person well enough to produce a real reaction.
3. **Fun enough** — sustain a short ambiguous exploration. Fun helps execution; it does not validate demand.

## The loop

1. Name the person, problem, and uncertain assumption.
2. Choose one learning question.
3. Build the smallest valid artifact: offer, manual service, workshop, calculator, waitlist, or prototype.
4. Put it in front of the intended users.
5. Observe behavior rather than collecting compliments.
6. At the timebox, kill, adjust, continue, or promote it.

## Evidence ladder

From weaker to stronger:

1. compliments;
2. use or sharing;
3. reply, signup, booking, or another intentional commitment;
4. payment;
5. repeat use or continued payment;
6. unsolicited referral.

A generated prototype or live link is an artifact, not validation. Validation begins when the intended user behaves differently.

## Promotion gate

Define this before launch:

```text
Person and problem:
Smallest artifact:
Distribution path:
Timebox:
Evidence target:
Promote if:
Kill or revise if:
```

Promote only when there is both **external pull** from user behavior and **builder pull** after doing the real work. Increase commitment one step at a time: a waitlist may justify interviews or a manual pilot, not a full product.

## Common failure modes

- branding, planning, or funnel work without user contact;
- treating publication or compliments as proof;
- choosing only for fun while ignoring problem severity and willingness to pay;
- running too many quests without timeboxes or decisions;
- letting a prototyping vendor define the method.

## Product-surface connection

This loop complements [[product-management-as-system-steering]]: move quickly on reversible tests and slow down as commitment becomes expensive. It also complements [[role-aligned-deployed-project-proof]]: use tiny public artifacts to test whether a workflow is useful before investing in a full portfolio or product build.

## Compact formula

> Tiny enough to start. Useful enough to test. Fun enough to finish. Real enough to produce evidence.

## Source

- Deya, ["your $1M business starts as a side quest, here's how."](https://www.youtube.com/watch?v=SE401zf_fgM), YouTube. The full user-supplied transcript remains in the private source vault and is not compiled into this public namespace.


<!-- ===== ai-native-product-surfaces/wiki/concepts/taste-requires-contact.md ===== -->

---
title: "Taste Requires Contact: Building Judgment in the AI Era"
created: 2026-07-13
updated: 2026-07-13
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai, judgment, taste, curation, learning, interaction-design]
sources:
  - Knowledge/concepts/taste-requires-contact.md
  - Knowledge/raw/transcripts/if-you-want-good-taste-you-have-to-eat.md
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
resource: https://youtu.be/F4igbiu9eR8
confidence: medium
---

# Taste Requires Contact: Building Judgment in the AI Era

AI can make almost anything for you. It cannot decide what deserves to exist. That judgment begins long before the prompt, in the things you have used, heard, worn, tasted, copied, compared, and learned to name.

Jason Liu captures this with a simple line: **if you want good taste, you have to eat**. A menu can show what a restaurant serves, but it cannot teach how the food tastes. In the same way, screenshots, moodboards, launch videos, summaries, and AI-generated references can point toward quality without giving someone the firsthand experience required to understand it.

## Taste is a practice

**Taste requires contact** means that judgment develops through repeated, attentive encounters with real work. It is not downloaded as a reference collection or produced by generating more options.

The practice loop is:

```text
Contact → notice → name → imitate → compare → curate → risk
```

- **Contact:** use, hear, wear, eat, play, or handle the thing itself.
- **Notice:** detect specific choices and reactions.
- **Name:** gain language that turns impressions into distinctions.
- **Imitate:** test whether you actually perceived the structure.
- **Compare:** inspect gaps across the original, your attempt, and alternatives.
- **Curate:** select, reject, combine, sequence, and protect.
- **Risk:** depart from consensus with a choice that expresses conviction.

## Taste has three jobs

Liu's account combines:

1. **Aesthetic judgment** — sensing what is beautiful, coherent, expressive, or well made.
2. **Audience judgment** — anticipating what other people will understand or value.
3. **Personal conviction** — choosing something that may not already be validated by consensus.

Good taste is not simply predicting popularity. Audience awareness without conviction produces safe consensus. Conviction without communication can become private expression that reaches no one. The useful tension is understanding the audience without becoming ruled by it.

## Vocabulary makes perception actionable

Contact creates impressions. Language turns them into diagnoses.

Art has composition, depth, form, colour, and line confidence. Engineering has abstraction, contracts, coupling, and architecture. Animation has timing, easing, and sound design. Cooking has acidity, salting, searing, and marination. Fashion has silhouette, proportion, and drape.

Without vocabulary, judgment stops at “I don't like it.” With vocabulary, it can move:

```text
vague reaction → named distinction → testable change
```

Words do not replace experience. They make experience inspectable enough to compare, explain, and refine.

## AI flips the traditional gap

Beginners have often developed taste faster than execution. They could see that their work was wrong but could not yet repair it.

AI can reverse that relationship. It produces polished artifacts before the user has developed the judgment required to evaluate them. Output leaps ahead while perception, vocabulary, and standards remain unchanged.

Experienced practitioners often gain more from AI because they bring references, causal models, diagnostic language, failure patterns, and the ability to distinguish a plausible result from a fitting one. Their advantage is not merely prompting. It is judgment.

## Preserve the friction that teaches

Not all friction is valuable. Repetitive formatting, boilerplate, file transfer, and deterministic checks are good automation targets.

Other activities may carry the learning:

- firsthand observation;
- careful comparison;
- attempted imitation;
- diagnosis and error correction;
- preference formation;
- final selection.

Liu's music-transcription example makes the distinction clear. The value is not possessing completed notation. The value is listening closely enough to produce it, making an attempt, detecting the mismatch, and correcting it.

Before automating a learning task, ask:

> **Is performing this activity how the person develops the judgment they are trying to acquire?**

If yes, assist the loop without replacing its learning-bearing centre.

## Copying and wandering

Copying is active perception. A failed imitation reveals the gap between what someone thought they noticed and what the original actually does. Once the structure is understood, variation can become deliberate rather than accidental.

Wandering expands the reference field. Browsing a book, trying clothes you will not buy, testing unfamiliar software, listening outside a familiar genre, or following a strange reference creates encounters that destination-only systems filter out.

Efficiency is useful when the destination is known. It is a poor default when the purpose is discovery.

## Product and agent implication

[[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]] explains how people develop judgment by staying close to shapeable work. Taste Requires Contact adds the input side: people must also stay close to the material they consume.

Together they form four loops:

1. **Reference loop:** encounter, notice, compare, and name.
2. **Making loop:** imitate, generate, inspect, and revise.
3. **Curation loop:** select, reject, sequence, and protect.
4. **Conviction loop:** depart from consensus and take a creative risk.

[[interaction-mode-routing|Interaction Mode Routing]] should preserve firsthand use, diagnosis, preference formation, and final selection when those activities carry the learning. Agents can retrieve comparisons, widen the reference set, handle repetitive execution, and expose alternatives. They should not silently replace the perceptual act the user needs to practise.

Contact develops judgment; artifacts make that judgment legible. [[syntheses/side-doors-make-useful-work-legible|Side Doors: Make Useful Work Legible]] shows the applied bridge: public work can expose what someone notices, selects, rejects, and protects, allowing other people to inspect the judgment instead of trusting a claim to “have taste.” An artifact is not proof of good taste merely because it exists; it makes the underlying decisions available for evaluation.

## Guardrails

- Taste is domain-specific and socially situated, not a universal score.
- Vocabulary sharpens attention, but jargon without contact becomes performance.
- Friction is not virtuous by itself; preserve only the friction that carries learning or responsibility.
- Audience judgment and personal conviction should constrain each other, not erase each other.

## Related pages

- [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]
- [[interaction-mode-routing|Interaction Mode Routing]]
- [[syntheses/side-doors-make-useful-work-legible|Side Doors: Make Useful Work Legible]]
- [[../../agent-workflows/wiki/concepts/creative-ideation-routing|Creative Ideation Routing]]

## Source

- Jason Liu, [“if you want good taste, you have to eat”](https://youtu.be/F4igbiu9eR8), YouTube. This page synthesizes a user-supplied transcript as a practitioner framework; it does not reproduce the transcript publicly.


<!-- ===== ai-native-product-surfaces/wiki/concepts/verified-video-answer-surfaces.md ===== -->

---
title: Verified Video Answer Surfaces
created: 2026-06-27
updated: 2026-06-30
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, video-ai, product-framing, interaction-design]
sources:
  - Knowledge/concepts/verified-video-answer-surfaces.md
  - Knowledge/concepts/video-retrieve-then-verify-loop.md
  - Knowledge/concepts/agent-output-decision-artifacts.md
confidence: high
---

# Verified Video Answer Surfaces

**Verified Video Answer Surfaces** turn video AI from a ranked search box into an evidence-backed answer workflow:

```text
question -> verified moments -> evidence cards -> clips/report -> next action
```

The answer should show the moment, timestamp, confidence, evidence, and coverage boundary.

## Shifu pivot note

Shifu's current best framing is not “AI understands video.” It is a local video workbench that helps users find, verify, save, compare, and export moments with visible timestamps and evidence. AI is an assistant for transcript search, suggested tags, candidate expansion, and verifier notes only where it earns trust.

For gameplay VODs, the primary surface may be workflow plus structured evidence: timeline marks, round tags, HUD/OCR state, killfeed/spike/phase metadata, manual corrections, collections, notes, and exports.

## Surface contract

A useful verified-video answer includes:

1. interpreted question;
2. searched videos / time range / camera or source scope;
3. verified moments with clip, timestamp, confidence, and evidence sentence;
4. evidence trail: frame, transcript/caption excerpt, modality signal, and source video handle;
5. explicit no-match state when weak candidates are rejected;
6. recall warning for "every X" queries;
7. next action: save clip, export report, refine search, mark false positive/negative, or ask a follow-up.

## Product wedge formula

```text
For [person who scrubs video],
find [repeated high-value moment],
return [timestamped clips + evidence + confidence],
so they can [make a decision / create an artifact / coach / report / publish].
```

Examples:

- coach -> fast breaks, press breaks, missed rotations -> film-review clips;
- creator -> beat, quote, visual action -> exportable clips;
- training lead -> correct/incorrect procedure -> teaching examples;
- operations lead -> candidate incidents -> verified report with rejected false alarms separated.

## UI mode guidance

- **Direct UI:** video library, timeline, filters, saved clips.
- **Agentic delegation:** long ingest, batch indexing, recurring scans, report generation.
- **Generative UI:** answer cards, evidence strips, comparison views, recall/coverage warnings.
- **Stable truth/routing:** source IDs, timestamps, captions, transcripts, verdicts, and eval logs.

## Quality bar

Measure precision of verified results, recall for "every X" claims, time saved versus manual scrubbing, evidence-card trust, false-positive correction, false-negative discovery, and whether a returned report can be shared without redoing the review.

## Boundaries

- Do not promise "find every" without recall measurement.
- Do not treat top-k ranking as a verified answer.
- Do not hide transcript/commentary dependence when target footage may be silent.
- Do not build real-time/multi-camera/alerting infrastructure before the verified answer loop works.
- Do not make AI the source of truth for precise gameplay state.
- Do not judge a Tonbi-style implementation before captions/transcripts/fusion/verifier are wired.

## Related pages

- [[video-retrieve-then-verify-loop|Video Retrieve-Then-Verify Loop]]
- [[agent-output-decision-artifacts|Agent Output Decision Artifacts]]
- [[interaction-mode-routing|Interaction Mode Routing]]
- [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]
- [[world-model-control-surfaces|World Model Control Surfaces]]

## Source

Compiled from `Knowledge/concepts/verified-video-answer-surfaces.md` and adjacent AI-native product-surface concepts.


<!-- ===== ai-native-product-surfaces/wiki/concepts/video-retrieve-then-verify-loop.md ===== -->

---
title: Video Retrieve-Then-Verify Loop
created: 2026-06-27
updated: 2026-06-30
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, video-ai, retrieval, verification, product-framing]
sources:
  - Knowledge/concepts/video-retrieve-then-verify-loop.md
  - Knowledge/raw/articles/tonbistudio-mini-vss.md
  - Knowledge/raw/articles/nvidia-vss-docs.md
confidence: high
---

# Video Retrieve-Then-Verify Loop

The **Video Retrieve-Then-Verify Loop** is the reusable pattern for answering natural-language questions over video:

```text
ingest video -> segment -> caption/transcribe/embed -> retrieve candidates -> verify with visual/audio evidence -> return timestamped answer
```

Retrieval maximizes candidate recall. Verification filters false positives, cites evidence, sets confidence, and refines the answer.

## Why it matters

NVIDIA VSS shows the industrial version: video IO/storage, agent routing, model endpoints, search, summarization, alert verification, stream handling, and telemetry.

Tonbi's `mini-vss` shows the desk-scale version: segment one video, embed frames/captions/transcripts, fuse retrieval, then judge candidates with evidence. Its reported "fast break" test moved from 0.20 precision@5 on retrieval alone to 1.00 verified precision with 75% recall. The verifier also found a full-court press the human label pass had missed.

The product lesson: **video search quality is candidate recall plus evidence-bearing verification, not just vector ranking.**

## Shifu / gameplay correction

Jamie's private Valorant/CS smoke sharpened the boundary: OpenCLIP visual-only retrieval can work technically and still return wrong tactical moments. A fair Tonbi-style test needs segment captions, transcript search, fusion, deeper candidate pools, and verifier judgment.

For precise gameplay, structured signals matter more than generic frame similarity: OCR/HUD, round phase, spike state, killfeed, economy, map location, utility usage, VOD metadata, before/after context, manual tags, and game APIs/demos where available.

## Design rules

1. Segment is the product unit; frames are evidence inside a segment.
2. Visual, caption, transcript, object, and metadata signals propose candidates.
3. Fusion should preserve recall before optimizing rank aesthetics.
4. A verifier should output match/no-match, confidence, evidence, and refined timestamp.
5. "Find every X" is a recall claim and needs deeper candidate pools.
6. A trustworthy no-result state can be better than noisy ranked guesses.
7. For gameplay, structured state should outrank generic visual embeddings until evidence says otherwise.

## Query tiers

| Tier | Example | Answer path |
|---|---|---|
| Appearance | "player shooting", "forklift in aisle" | visual embeddings / detections |
| Event | "made layup", "person enters restricted zone" | captions, transcript, object/action signals |
| Tactical / semantic | "fast break", "unsafe loading pattern" | retrieval pool + verifier over clip context |

## Product implication

For Jamie's app exploration, do not start with "video search app" as the promise. Start with one painful video-review job where verified timestamped answers save obvious scrubbing time.

Strong first-user candidates include coaches, creators, course/community operators, and small teams reviewing support, sales, training, or operations footage.

## Related pages

- [[verified-video-answer-surfaces|Verified Video Answer Surfaces]]
- [[ai-native-problem-framing-framework|AI-Native Problem Framing Framework]]
- [[world-model-control-surfaces|World Model Control Surfaces]]
- [[../../local-ai-infrastructure/wiki/concepts/rag-over-agent-wikis|RAG over Agent Wikis]]

## Source

Compiled from `Knowledge/concepts/video-retrieve-then-verify-loop.md`, Tonbi `mini-vss`, and NVIDIA VSS docs.


<!-- ===== ai-native-product-surfaces/wiki/concepts/world-model-control-surfaces.md ===== -->

---
title: World Model Control Surfaces
created: 2026-06-26
updated: 2026-06-26
type: concept
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, ai-native, product-framing, interaction-design, grounded-ai]
sources:
  - Knowledge/concepts/world-model-control-surfaces.md
  - Knowledge/raw/transcripts/yann-lecun-world-models-next-ai-revolution.md
  - https://youtu.be/72Xj8k5WQX4?si=tFQOgcbG-xzmz7WI
confidence: medium
---

# World Model Control Surfaces

**World Model Control Surfaces** translate Yann LeCun's world-model argument into a product/interface lens: expose state, available actions, predicted outcomes, objectives, guardrails, and evidence before recommending action.

Core loop:

```text
observed state -> candidate actions -> predicted outcomes -> objective / guardrail score -> recommended next safe step
```

## Why it matters

The transcript argues that grounded intelligence is not just declarative knowledge or next-token generation. It requires abstract predictive models of the world, planning by optimization, and guardrails that score imagined action/state sequences before execution.

For product surfaces, the useful lesson is not “build a full world model now.” It is: **make the system's action model visible**.

## Product-surface use

Use this lens after [[ai-native-problem-framing-framework|AI-Native Problem Framing Framework]] and before choosing the final interface mode with [[interaction-mode-routing|Interaction Mode Routing]].

A good AI-native control/review surface should show:

1. current state;
2. possible actions;
3. predicted outcomes;
4. task objective;
5. guardrails/constraints;
6. evidence and uncertainty;
7. recommended next safe step.

## Application targets

- **Shifu / I-know-kungfu:** show source coverage, local overlap, route effects, refusal boundaries, provenance risk, and recommended import/serve action.
- **Hermes Mission Control:** show task state, candidate next slices, likely side effects, verification evidence, and approval guardrails instead of only “agent says done.”
- **Pixi Wiki:** show source-to-output trace, namespace coverage, MCP/raw/HTML visibility, stale route risk, and suggested repair or promotion action.
- **RL Sim Labs:** separate environment state, allowed actions, dynamics model, objective/reward, evidence gates, and policy/planner output.

## Boundary

This is a concept, not a standalone namespace and not a claim that current LLM agents already have robust learned world models. Do not create separate entity pages for Yann LeCun, JEPA, V-JEPA, SIGReg, or AMI Labs until those entities recur across more Pixi Wiki sources or become project-critical.

## Related pages

- [[ai-native-problem-framing-framework|AI-Native Problem Framing Framework]]
- [[interaction-mode-routing|Interaction Mode Routing]]
- [[material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]


<!-- ===== ai-native-product-surfaces/wiki/entities/i-know-kungfu.md ===== -->

---
title: I-know-kungfu
created: 2026-06-19
updated: 2026-06-24
type: entity
status: active
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, i-know-kungfu, knowledge-base-wikis, cookbook, local-first, agent-context]
sources:
  - Projects/I-know-kungfu/Index.md
  - Knowledge/concepts/material-loop-and-glass-interfaces.md
  - https://github.com/pixiiidust/I-know-kungfu
  - https://github.com/pixiiidust/I-know-kungfu/issues/1
confidence: medium
---

# I-know-kungfu

I-know-kungfu is an AI-native product surface for growing a user's own knowledge base by importing, adapting, and serving bounded knowledge base wikis that agents can search, cite, and refuse against.

## Product shape

The current flow is:

```text
Find useful knowledge base wiki
→ check local fit
→ choose serving entry point
→ harmonize overlap
→ inspect scope / proof / refusal
```

The product is not primarily a generic "pack" marketplace. Each imported serving unit is conceptually a wiki: source-backed pages, scope/non-scope, provenance, freshness, and agent-friendly entry points such as MCP, `llms.txt`, raw Markdown, and `index.json`.

A Knowledge Pack is the portable package/install format for a knowledge base wiki. The wiki is the thing users grow and agents use; the pack is how that wiki moves between local storage, Cookbook listings, and agent harnesses.

## Why it matters

The goal is to let users evolve their knowledge base without reinventing the wheel. In the ideal case, a user can adapt proven wikis with known quality or track record to improve their own coverage, fill gaps, and avoid duplicating or polluting what they already know.

For agents, bounded wiki entry points should be faster and more token-efficient than broad web search. Agents can search a specific source, cite exact pages, and refuse when a task falls outside the wiki's scope.

## Current status

The first static Cookbook serving prototype passed Jamie's initial smell test with Variant C. The accepted direction is table/list-first and decision-first: check fit before trust, choose one serving entry point, then make overlap harmonization explicit.

The repo now has a PRD, README, glossary, and ADR that center knowledge base wiki as the product object and demote Knowledge Pack to package/install format.

## Namespace role

I-know-kungfu belongs in `ai-native-product-surfaces` because it is primarily about the user-facing and agent-facing product surface for trusted context routing and knowledge-base growth.

It crosslinks to:

- `agent-workflows` for agent consumption, MCP, `llms.txt`, and bounded source routing mechanics;
- `pixi-vault` for compiled wiki / namespace publishing patterns;
- `local-ai-infrastructure` for local-first serving and future retrieval infrastructure.


## Interaction mode refactor

Use [[../concepts/interaction-mode-routing|Interaction Mode Routing]] as the product-surface lens for the next slice. I-know-kungfu should not become a pure chatbot or a static card pile. Its strongest wedge is a generated fit-check surface around stable wiki truth.

Use [[../concepts/material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]] as the authorship lens: importing a wiki should not feel like a magic install button. The user should see what will enter their knowledge system, where it overlaps, what it will route to agents, what it refuses to cover, and what evidence supports trust before it becomes durable context.

| Mode | I-know-kungfu surface |
|---|---|
| Direct UI | Browse candidate wikis, search/filter metadata, choose install/serve target, inspect source links. |
| Agentic delegation | Fetch candidate wiki metadata, summarize scope, detect local overlap, propose harmonization, run quality/eval/provenance checks. |
| Generative UI | Fit-check report, overlap map, scope/non-scope checklist, provenance coverage grid, serving-entrypoint decision table, trust panel. |
| Stable truth/routing | Wiki contracts, source pages, install manifests, `llms.txt`, `index.json`, MCP, PRD, ADRs. |

Next product slice to spec: **Generated Fit Check Surface** — source coverage, local overlap, recommended serving entrypoint, refusal boundaries, trust/eval state, and clearly labeled evidence provenance.

## Boundaries

The first slice should remain local-first and endpoint-ready. Do not treat the current project as a hosted marketplace, vector database, hosted RAG layer, payments system, public upload-moderation system, or cloud MCP service.

## Source

Compiled from `Projects/I-know-kungfu/Index.md`, the public repo README/PRD, and GitHub issue #1.


<!-- ===== ai-native-product-surfaces/wiki/entities/j-space-replay.md ===== -->

---
title: J-Space-Replay
created: 2026-07-08
updated: 2026-07-08
type: entity
status: working-demo
namespace: ai-native-product-surfaces
source: Projects/J-Space-Replay/Index.md
confidence: high
---
# J-Space-Replay

J-Space-Replay is a public working side project for replaying a vision-language model's decoded internal readouts on a video timeline while it answers a question. The public lite version lets users browse preset traces; upload/new-video generation requires local install/GPU.

The product surface is intentionally glass-box and cautious: it helps a user inspect Qwen2.5-VL logit-lens or fitted J-lens readouts, but it does **not** claim to reveal model thoughts or validate mechanistic claims about VLMs.

## Product frame

```text
short video + question
  -> one offline Qwen2.5-VL pass on a local NVIDIA GPU
  -> per-layer residual capture
  -> logit-lens-v1 or j-lens-v1 decode
  -> schema-v1 trace
  -> replay UI: answer, video, word grid, patch/box overlays, unspoken/adversarial cues
```

The UI is a technical replay dashboard: honesty banner, query/answer console, video transport, readout-strength bars, answer-token × layer workspace grid, raw top-token drilldown, lens selector, and trace library.

## What the demo shows

- **Answer precursors:** answer-token readouts can surface words such as `gravity` before the model emits them.
- **Adversarial checks:** when an answer rules something out, cells that still decode the ruled-out word pulse as a warning surface.
- **Unspoken readouts:** the UI lists words read across many cells that appear in neither prompt nor answer.
- **Computed but unsaid content:** the ball-drop example shows late-mid J-lens readouts such as `level`, `horizontal`, `move`, `off`, and `right` while the answer remains a generic gravity explanation.

## Architecture

- Backend: Python/FastAPI package `src/jsr/`.
- Model path: Qwen2.5-VL-7B-Instruct, NF4 + SDPA + fp16 stack.
- Trace pipeline: video frame sampling, prompt preparation, residual capture, lens decode, label extraction, grounding queries, validated `trace.json` schema v1.
- Frontend: React + Vite screens for upload, progress, replay, and library.
- Demo mode: no-GPU pre-baked traces for instant browsing.
- J-lens: ships as a fitting recipe, not committed weights.

## Evidence and caveats

The repo reports a verified J-lens port against component-level autograd checks, with the paper-faithful identity seed making final-layer J-lens readouts exactly equal to the logit lens. On synthetic clips, J-lens improves concept recall by about 31% and reveals a late-mid visual content band around layers 22-26.

The honest boundary is central:

- demo-quality interpretability only;
- the Anthropic workspace paper validated text models, not VLMs;
- single-token readouts only;
- adversarial/unspoken surfaces are mechanical string analysis;
- natural-video baselines and interventions are not done;
- raw-token grid remains primary because concept-label recall is still limited.

## Source handles

- Project hub: `Projects/J-Space-Replay/Index.md`
- Repo: https://github.com/pixiiidust/j-space-replay
- Lite preset library: https://pixiiidust.github.io/j-space-replay/
- Inspiration concept: [[../concepts/j-space-global-workspace|J-Space as Global Workspace]]
- Screenshot/demo: `docs/screenshot.png`, `docs/demo.mp4`
- Evidence: `reports/jlens_evidence.md`, `reports/m2_quality_gate.md`
- Related concepts: [[../concepts/video-retrieve-then-verify-loop|Video Retrieve-Then-Verify Loop]], [[../concepts/verified-video-answer-surfaces|Verified Video Answer Surfaces]], [[../concepts/material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]


<!-- ===== ai-native-product-surfaces/wiki/entities/job-edge.md ===== -->

---
title: Job Edge
created: 2026-06-27
updated: 2026-06-30
type: entity
status: live-public-prototype
namespace: ai-native-product-surfaces
source: Projects/Job Edge/Index.md
confidence: high
---
# Job Edge

Job Edge is a live public prototype for finding **edge in crowded job searches**: freshness, geography, fit, and distribution signals that make a role more worth applying to now.

The first use case is **Ashby PM Radar**, a PM/product-role radar that turns public Ashby job-board data into an apply-action queue.

## Thesis

Most job-search tools optimize for more listings. Job Edge optimizes for better timing and lower competition.

Core question:

> Which roles are worth applying to today because timing, fit, and crowding signals create an edge?

## Current prototype

The public dashboard is live at:

```text
https://pixiiidust.github.io/job-edge/
```

The public `pixiiidust/job-edge` repo contains:

```text
job_edge/ashby_pm_radar.py                # Ashby use-case CLI/scorer
scripts/refresh_ashby_pm_radar.py         # refresh wrapper for local/GitHub Actions use
.github/workflows/refresh-ashby-pm-radar.yml
dashboard.html                            # static interactive dashboard
data/                                     # saved discovery, scoring, dashboard, provenance artifacts
docs/                                     # product/PRD notes
tests/                                    # unit tests
```

`ashby-pm-radar` is the first use case, not the full product boundary.

## Ashby PM Radar flow

Current automatic flow:

```text
saved Ashby company slugs → fetch public boards → score jobs → commit static JSON → publish GitHub Pages
```

Ashby exposes company-scoped public boards, not a global search endpoint:

```text
https://api.ashbyhq.com/posting-api/job-board/{companySlug}?includeCompensation=true
```

GitHub Actions now runs the refresh every 6 hours and on manual workflow dispatch. The browser does not run Python; the dashboard only re-fetches the latest published static JSON.

## Discovery boundary

Job Edge currently refreshes **known Ashby boards** from `data/discovered_slugs.txt`. It does **not yet automatically search the public web for brand-new Ashby companies**.

This means a future run can still show `150` jobs and be healthy. The success signal is a fresh generated timestamp plus current board data, not a changed count.

Next discovery layer:

```text
automated search queries → extract jobs.ashbyhq.com/{slug} → update slug list with provenance → refresh boards
```

## Edge signals

The current scorer combines:

- **Freshness** — recently posted roles are more actionable.
- **Geographic narrowing** — Toronto/GTA/Canada roles shrink the applicant pool.
- **Role specificity** — niche PM roles can be less crowded than generic product listings.
- **Personal/product fit** — AI, agents, workflow, developer tools, design/product overlap, integrations, platform, and B2B SaaS.
- **Distribution crowding** — public LinkedIn posting presence implies a larger applicant pool.

Competition is inferred. Ashby does not expose applicant counts, and LinkedIn evidence only detects public posting presence; it does not scrape applicant counts.

## Triage buckets

```text
apply_now            high score, fresh/local, no LinkedIn posting found
apply_fast_crowded   high score, found on LinkedIn, likely larger applicant pool
maybe                plausible but weaker timing/fit/competition profile
low_priority         stale or low-score roles
```

Freshness buckets:

```text
new_0_3d
fresh_4_7d
recent_8_14d
aging_15_30d
old_31_90d
stale_90d_plus
```

## Dashboard contract

The dashboard is an action queue, not a generic job board.

It supports:

- Apply and source-job links.
- Mark-applied state in browser local storage.
- Copyable job notes.
- Search by title, company, and location.
- Filters for triage, freshness, and LinkedIn presence.
- Sorting by best triage, freshness, low crowd risk, Canada/Toronto fit, role fit, or score.
- Manual `Run Ashby refresh` link to the GitHub Actions workflow.
- `Reload latest published data` button for re-fetching the current static snapshot.

Primary workflow:

```text
1. Apply now — fresh/local roles with no LinkedIn evidence.
2. Apply fast — strong roles already visible on LinkedIn.
3. Review maybes — backup queue after the top targets.
```

## Verification snapshot

2026-06-30 auto-refresh milestone verified:

- PR #10 merged on `pixiiidust/job-edge`.
- GitHub Action run succeeded.
- Pages status returned `built`.
- Live dashboard rendered 150 jobs from the auto-refreshed JSON snapshot.
- Latest verified generated timestamp: `2026-06-30T22:08:53.138975+00:00`.
- Browser smoke confirmed the refresh link, reload button, job rows, and no JavaScript console errors.

## Next slice

Add automated discovery for new Ashby company slugs and a “new / removed / changed since last refresh” diff layer so users can distinguish a healthy refresh from a stable job count.


<!-- ===== ai-native-product-surfaces/wiki/entities/lky-avatar.md ===== -->

---
title: LKY Avatar / Voice Persona Stack
created: 2026-07-15
updated: 2026-07-17
type: entity
status: working-demo
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, voice-ai, avatar, local-ai, evaluation]
sources:
  - Projects/LKY Avatar/Index.md
  - Projects/LKY Archive/Index.md
  - https://github.com/pixiiidust/lky-brain
confidence: high
---

# LKY Avatar / Voice Persona Stack

LKY Avatar is a working local fictional-interview product that turns the `lky-brain` reasoning-style adapter into a voice-first, interruptible experience with an animated elderly-statesman portrait, a tuned watermarked voice, and a transcript designed as the record of proceedings.

It is a separate applied product from the completed [[../../curated-tuning-datasets/wiki/entities/lky-archive|LKY Brain / LKY Archive]] corpus-and-adapter case study. The brain supplies the reasoning-style model; the avatar product owns the interaction, serving, disclosure, failure handling, and public-experience gates. The source avatar and voice-training repos are private. This page records a public-safe system summary, not private launch instructions.

## Product frame

```text
speak or type a question
  -> streaming transcription
  -> local LKY-style language model
  -> fine-tuned elder voice
  -> animated portrait + spoken reply
  -> transcript/export as inspectable record
```

The web surface uses a broadcast-interview hierarchy rather than a generic chat layout:

- portrait stage and session-state lamp;
- persistent fictional-AI disclosure;
- `TRANSCRIPT OF RECORD` for spoken and written turns;
- voice input, typed-note fallback, and free interruption;
- transcript export, visible reset, and explicit busy/rate-limit states;
- text-only continuation when voice synthesis is unavailable.

The current default avatar is a bundled illustrated elderly-statesman portrait sprite with state-mapped expressions, mouth motion, blink, and breathing. It replaced an earlier anime placeholder. A separate Live2D path remains for a future full custom rig.

## Architecture

- LiveKit Cloud carries realtime rooms and WebRTC media.
- Deepgram provides streaming speech-to-text.
- A Python voice agent owns persona prompting, history, interruption, TTS state, degraded text delivery, per-turn fact retrieval, and the uncertainty guardrail.
- A small audited fact sheet is split into retrievable sections. The best matches are inserted immediately before the latest question behind a source-over-memory instruction.
- Deepgram Nova-3 receives a Singapore proper-noun `keyterm` list; the same vocabulary extends the TTS pronunciation seam.
- The brain is a merged epoch-2 `lky-brain` LoRA served as Q4_K_M GGUF through llama.cpp behind an OpenAI-compatible seam.
- The voice is a Chatterbox t3 model with a merged rank-16 LoRA overlay, served through a loopback-only HTTP adapter.
- A Vite/TypeScript client renders the interview surface and keeps transcript export client-side.
- A small token server mints short-lived room tokens and enforces unique rooms, one active session, and per-IP limits.

## Evidence gates reached

### Brain and interaction

- Warm brain decode: 80.5 tok/s p50; warm time to first token about 0.05 s.
- End-of-speech to first audio: 3.96 s p50, 5.95 s worst observed over 10 live turns.
- Agent-side playback stops about 18–21 ms after interruption detection; about 270 ms from raw speech onset including the deliberate detection window.
- Thirty-minute soak: 37/37 turns with no failures.

### Fine-tuned voice

The voice-training project compared two arms against a frozen Chatterbox baseline:

| arm | blind preference | similarity | WER | outcome |
|---|---:|---:|---:|---|
| baseline | 2/20 in final LoRA pack | 0.8693 | 0.0324 | retained rollback |
| GPT-SoVITS | 13/20 tuned | 0.9049 | 0.1274 | failed intelligibility gate |
| **Chatterbox LoRA epoch 14** | **18/20 tuned** | **0.8900** | **0.0390** | **integrated** |

The integrated voice kept the existing HTTP contract, passed a ten-turn same-GPU placement run at RTF mean 0.369 / max 0.397 with zero failures, and preserved Chatterbox's PerTh watermark at confidence 1.0000 on served output.

### Factual-grounding implementation

- The audited sheet covers constituencies and offices, independence and merger, HDB, water, selected policies, family, and a critical Tanjong Pagar correction with institutional source notes.
- Deterministic keyword retrieval selects only relevant sections per turn and leaves the brain server unchanged.
- A 12-question eval records factual accuracy, persona quality, and fabrication as independent signals and supports matched grounding-on/off runs.
- Repository verification passed across 148 root tests, 199 voice-agent tests with 3 live-service skips, 91 web tests, and a production build.
- The implementation is merged; live factual lift and real-microphone proper-noun transcription are still operator-side proofs.

## Trust and honesty boundary

- This is a fictional simulation. Generated answers are not authentic quotations and the portrait is illustrative, not an authentic photo or endorsement.
- The style adapter is not a factual database. Live testing found invented constituencies, dates, and historical events. The application now has an audited retrieval layer, but model-quality lift has not yet been measured live.
- Voice data and weights remain local. The generated audio stays watermarked.
- Singapore proper-noun input/output seams are implemented. Real-microphone STT and broader TTS pronunciation remain acceptance checks rather than proven coverage.
- The demo is not publicly deployed as of 2026-07-17. Home-GPU hosting is a measured recommendation, not a verified live service.

## Next gate

Run the 12 fact questions with grounding on and off against the local brain, score factual accuracy separately from persona quality and fabrication, and live-check the Singapore keyterms through a real microphone. Reopen the grounding gate if either fails. Only after those proofs should the project choose between the full Live2D rig and public hosting.

## Related

- [[../../curated-tuning-datasets/wiki/entities/lky-archive|LKY Brain / LKY Archive]]
- [[../../local-ai-infrastructure/wiki/summaries/lky-brain-consumer-gpu-qlora|LKY Brain Consumer-GPU QLoRA Case Study]]
- [[concepts/material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]]
- [[concepts/interaction-mode-routing|Interaction Mode Routing]]


<!-- ===== ai-native-product-surfaces/wiki/entities/myabode.md ===== -->

---
title: myAbode
created: 2026-06-16
updated: 2026-06-16
type: entity
status: parked
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, myabode, real-estate, ai-crm, product-strategy]
sources:
  - Projects/myAbode/Index.md
confidence: medium
---

# myAbode

**myAbode** is a parked AI-native real-estate CRM case study. It belongs under `ai-native-product-surfaces` because the learning value is product-surface design: how to turn messy constraints into prepared next actions that agents actually choose to use.

## Current posture

myAbode is not an active build. It should be treated as a problem-first product-strategy case study, with the Command Grid prototype as the strongest artifact.

The key adoption constraint is that real-estate agents are independent contractors. The product cannot rely on mandated workflow change; it must make the better action obvious enough that time-poor agents adopt it voluntarily.

## Product-surface lessons

The durable lessons for this namespace are:

- deterministic compliance boundaries matter in regulated workflows;
- AI should reduce cognitive load without surveilling or nagging users;
- prepared next actions are stronger than generic dashboards;
- a precedent library and scratchpad-then-reconcile flow can keep humans in authority;
- adoption incentives are part of the product architecture, not a go-to-market afterthought.

## Promotion boundary

Do not promote myAbode into its own namespace while parked. Reconsider only if it becomes active again with its own source corpus, recurring update lifecycle, and public-facing audience.

## Source

Compiled from `Projects/myAbode/Index.md`.


<!-- ===== ai-native-product-surfaces/wiki/entities/planned-program-intel.md ===== -->

---
title: Planned Program Intel
created: 2026-06-16
updated: 2026-06-16
type: entity
status: compiled
namespace: ai-native-product-surfaces
tags: [ai-native-product-surfaces, planned-program-intel, product-management, decision-routing]
sources:
  - Projects/Planned Program Intel/Index.md
  - Projects/Planned/PRD.md
confidence: high
---

# Planned Program Intel

**Planned Program Intel** is an AI-native decision layer for enterprise event programs. It is the strongest current product-surface proof inside the `ai-native-product-surfaces` namespace.

## Product shape

The product routes customer-side decisions by answering:

1. What needs attention?
2. Who should decide?
3. What happened in similar past events?
4. What is different this time?
5. What action is recommended?
6. Should the human accept, change, override, or escalate?

The core loop is not a chatbot. It is a decision-routing and institutional-memory surface: signals create decisions, decisions route to owners, evidence packages prior cases/exceptions/precedents, and resolutions become program memory.

## Status

The Vite prototype is done and live. The source hub records the build queue as complete and treats future work as optional portfolio packaging: deck, Loom walkthrough, application submission, or case-study narrative.

## Namespace role

Planned Program Intel anchors the product-surface namespace because it shows:

- decision moments as the product primitive;
- inspectable evidence rather than opaque confidence;
- human authority through accept/change/override/escalate verbs;
- program memory compounding through resolutions;
- a PM-portfolio-friendly artifact that connects product reasoning to a working demo.

## Source

Compiled from `Projects/Planned Program Intel/Index.md` with supporting historical PRD context in `Projects/Planned/PRD.md`.


<!-- ===== ai-native-product-surfaces/wiki/entities/shifu-app.md ===== -->

---
title: Shifu
created: 2026-06-27
updated: 2026-06-30
type: entity
status: pivot-thesis-under-review
namespace: ai-native-product-surfaces
source: Projects/Shifu/Index.md
confidence: high
---
# Shifu

Shifu is a local-first video knowledge/workbench prototype: private videos stay close to the user while the app helps users find, verify, save, compare, export, and reuse timestamped moments.

The current corpus direction uses Valorant/CS VOD-style material as an evaluation corpus, not as the full product identity. The gameplay thesis is under review because generic visual embeddings are weak at precise tactical state.

## Product frame

```text
source video -> light indexing -> local heavy worker -> evidence/workflow surface
```

Shifu should expose candidate moments, keyframes, transcript/caption/structured evidence when available, modality state, verifier decisions, manual tags, and clear boundaries. It should not pretend a query was answered when evidence is missing; AI assists only where it earns trust.

## Local-first architecture

The current architecture decision is:

```text
VPS app/orchestrator
  -> upload, source registration, browser UI
  -> light MiniVSS smoke: segmentation + keyframes
  -> search/save/export surfaces
  -> verifier manifests and reports

Local desktop GPU worker
  -> heavy visual embeddings
  -> transcription/caption artifacts when available
  -> structured verifier verdicts
  -> worker_artifacts/<source_id>/status.json
```

This follows the same product logic as games and creator tools: use the user's desktop GPU for heavy local media work, then make cloud GPU a later optional accelerator.

Short contract:

> Local first. Cloud when useful. Evidence always.

## Current milestone state

The implementation chain through parent issue #3 is complete: PR #26 merged, issue #21 closed, parent #3 closed after post-merge verification on `main`, and PR #27 added the Windows/D: local-video guide.

The app can run on an actual local video today for upload/light-processing/search smoke. It includes browser/API upload, source registration, light segmentation/keyframes, search/save/export surfaces, local worker status seam, verifier manifests, structured verdict import, deeper T3 verifier pools, verified-only T3 recall, baseline-vs-verified deltas, and negative/refusal reporting.

The product thesis is now under review. Jamie's private Valorant/CS `mini-vss` smoke showed the GTX 1070 CUDA/OpenCLIP path and LanceDB visual index can work technically, but manual inspection found the visual-only `post plant throw` hits wrong. Transcript/commentary looked more useful, and the full Tonbi loop still needs a clean reproduction with captions/transcripts/fusion/deeper pools/verifier before judging `mini-vss` itself.

Post-merge verification on `main`: focused verifier/eval tests 18 passed; full suite 80 passed with one warning; compileall clean; `git diff --check` clean; fixture evaluator passed 5/5 while honestly reporting `Private VOD detection proof: no`, `Verified hits: 0`, and T3 verified recall `0.00` until structured verdicts are imported.

## Boundaries

- Jamie's previous local proof target was **NVIDIA GTX 1070**; next heavy experiments are expected after the repaired 5070 Ti desktop is available.
- Cloud GPU rental is deferred until the local-worker seam proves useful.
- Private media, generated frames, transcripts, embeddings, worker artifacts, verifier verdicts, and private reports should not be committed.
- Fixture reports are plumbing smoke only. Real private-VOD detection proof requires private media, private hand labels, non-placeholder modality artifacts, and structured verifier verdict imports.
- Shifu can run on an actual video today for upload/light-processing/search smoke; production-grade proof is not established.
- Visual embeddings are low-trust recall for tactical gameplay until structured signals and verifier evidence support them.
- Do not judge Tonbi `mini-vss` from OpenCLIP visual-only output; its intended loop includes captions/transcripts, fused retrieval, candidate pools, and verification.

## Source handles

- Project hub: `Projects/Shifu/Index.md`
- Repo: https://github.com/pixiiidust/shifu-app
- Parent issue: https://github.com/pixiiidust/shifu-app/issues/3
- Final PR: https://github.com/pixiiidust/shifu-app/pull/26
- Final child issue: https://github.com/pixiiidust/shifu-app/issues/21
- Windows/D: guide PR: https://github.com/pixiiidust/shifu-app/pull/27
- Related concepts: [[../concepts/video-retrieve-then-verify-loop|Video Retrieve-Then-Verify Loop]], [[../concepts/verified-video-answer-surfaces|Verified Video Answer Surfaces]]


<!-- ===== ai-native-product-surfaces/wiki/index.md ===== -->

---
title: AI-Native Product Surfaces — Master Index
created: 2026-06-16
updated: 2026-07-17
type: index
status: active
namespace: ai-native-product-surfaces
---

# AI-Native Product Surfaces — Master Index

> **Definition:** AI is any device that perceives its environment and constraints to take actions that maximize its chance of successfully achieving its goals.

> Scaffold index for `ai-native-product-surfaces`. Add compiled pages here as they are created.

## Concepts

- [[concepts/agent-output-decision-artifacts|Agent Output Decision Artifacts]] — Compress verbose agent output into concise, visual, source-backed decision artifacts with explicit next actions and feedback controls.
- [[concepts/ai-native-problem-framing-framework|AI-Native Problem Framing Framework]] — Defines environment/actions/goal/constraints for AI-native product surfaces.
- [[concepts/interaction-mode-routing|Interaction Mode Routing]] — Refactor lens for choosing direct UI, agentic delegation, generative UI, or stable truth/routing surfaces.
- [[concepts/j-space-global-workspace|J-Space as Global Workspace]] — Anthropic's J-space / Jacobian lens concept: a verbalizable representation subspace that behaves like a functional global workspace for report, modulation, flexible reasoning, broadcast, and alignment-auditing caveats.
- [[concepts/material-loop-and-glass-interfaces|Material Loop and Glass Interfaces]] — Agency/authorship lens for keeping AI-shaped work inspectable, steerable, interruptible, and traceable.
- [[concepts/taste-requires-contact|Taste Requires Contact]] — Judgment-building lens for firsthand experience, precise vocabulary, active imitation, comparison, curation, and creative risk; paired with Side Doors as the public-legibility layer.
- [[concepts/product-management-as-system-steering|Product Management as System Steering]] — PM operating lens for timely decisions, gapless ownership, adaptive influence, scope-first tradeoffs, and ecosystem incentive alignment.
- [[concepts/role-aligned-deployed-project-proof|Role-Aligned Deployed Project Proof]] — Project-selection heuristic for turning a target role or job description into a live, owned, evidence-backed artifact that demonstrates role understanding.
- [[concepts/side-quest-validation-loop|Side-Quest Validation Loop]] — Low-pressure, timeboxed loop for turning an idea into a tiny useful public experiment and letting behavioral evidence earn further commitment.
- [[concepts/video-retrieve-then-verify-loop|Video Retrieve-Then-Verify Loop]] — Video AI architecture pattern: retrieve high-recall candidate moments, then verify with timestamped evidence; for gameplay, visual-only is low-trust and structured signals matter.
- [[concepts/verified-video-answer-surfaces|Verified Video Answer Surfaces]] — Product-surface pattern for video apps/workbenches that return clips, confidence, evidence, and recall boundaries with AI as assistant, not source of truth.
- [[concepts/world-model-control-surfaces|World Model Control Surfaces]] — Grounded-AI control/review lens for exposing state, actions, predictions, objectives, guardrails, evidence, and the recommended next safe step.

## Entities

- [[entities/i-know-kungfu|I-know-kungfu]] — Active local-first Cookbook wiki serving project for growing a user's knowledge base with bounded, agent-readable wikis.
- [[entities/job-edge|Job Edge]] — Live job-search edge dashboard prototype using scheduled Ashby refresh, freshness, geography, fit, and LinkedIn-crowding signals to prioritize applications.
- [[entities/j-space-replay|J-Space-Replay]] — Working public demo for replaying Qwen2.5-VL logit/J-lens readouts over video with explicit demo-quality interpretability boundaries.
- [[entities/lky-avatar|LKY Avatar / Voice Persona Stack]] — Working local fictional-interview product combining the LKY reasoning adapter, tuned watermarked voice, animated portrait, audited per-turn fact retrieval, transcript/eval surfaces, and explicit live-proof boundaries.
- [[entities/shifu-app|Shifu]] — Local-first video workbench/proof question with implementation chain complete; visual gameplay thesis under review after visual-only misses, next heavy tests wait for the repaired 5070 Ti desktop.
- [[entities/myabode|myAbode]] — Parked real-estate AI CRM case study focused on prepared next actions and adoption constraints.
- [[entities/planned-program-intel|Planned Program Intel]] — Done decision-routing and institutional-memory prototype for enterprise event programs.

## Summaries

<!-- Add compiled summaries alphabetically. -->

## Syntheses

- [[syntheses/side-doors-make-useful-work-legible|Side Doors: Make Useful Work Legible]] — Illustrated synthesis of problem-first opportunity search, public proof, five story examples, and verb-first taste/distribution; linked to Taste Requires Contact as the judgment-formation layer.

## Source Roots

- `Projects/Job Edge/Index.md`
- `Projects/J-Space-Replay/Index.md`
- `Projects/LKY Avatar/Index.md`
- `Projects/Shifu/Index.md`
- `Projects/I-know-kungfu/Index.md`
- `Projects/Planned Program Intel/Index.md`
- `Projects/Planned/PRD.md`
- `Projects/myAbode/Index.md`
- `Knowledge/concepts/ai-native-problem-framing-framework.md`
- `Knowledge/concepts/interaction-mode-routing.md`
- `Knowledge/concepts/j-space-global-workspace.md`
- `Knowledge/concepts/material-loop-and-glass-interfaces.md`
- `Knowledge/concepts/taste-requires-contact.md`
- `Knowledge/concepts/world-model-control-surfaces.md`
- `Knowledge/concepts/agent-output-decision-artifacts.md`
- `Knowledge/concepts/role-aligned-deployed-project-proof.md`
- `Knowledge/concepts/product-management-as-system-steering.md`
- `Knowledge/concepts/side-quest-validation-loop.md`
- `Knowledge/concepts/video-retrieve-then-verify-loop.md`
- `Knowledge/concepts/verified-video-answer-surfaces.md`
- `Knowledge/raw/articles/tonbistudio-mini-vss.md`
- `Knowledge/raw/articles/nvidia-vss-docs.md`
- `Knowledge/raw/transcripts/yann-lecun-world-models-next-ai-revolution.md`
- `Knowledge/raw/transcripts/if-you-want-good-taste-you-have-to-eat.md`
- `Knowledge/concepts/verb-first-product-positioning.md`
- `Knowledge/concepts/find-the-lock-problem-first.md`
- `Knowledge/concepts/side-door-opportunity-search.md`
- `Knowledge/raw/articles/how-to-enter-side-doors-maja.md`


<!-- ===== ai-native-product-surfaces/wiki/log.md ===== -->

---
title: AI-Native Product Surfaces — Activity Log
created: 2026-06-16
updated: 2026-07-17
type: log
status: scaffold
namespace: ai-native-product-surfaces
---

# AI-Native Product Surfaces — Activity Log

> Append-only namespace log.

## 2026-07-17 update | LKY Avatar fact-grounding layer merged

- Refreshed `wiki/entities/lky-avatar.md` after issue #45 / PR #47 added an audited sectioned fact sheet, per-turn retrieval, source-over-memory and uncertainty instructions, Singapore STT keyterms, and a 12-question factuality eval.
- Recorded the implementation verification and the new signal boundary: factual accuracy, persona quality, and fabrication must be judged separately.
- Kept the live-proof boundary explicit: real-microphone STT and grounding-on/off local-brain results remain pending; the local demo is still not presented as a public live service.

## 2026-07-15 create | LKY Avatar / Voice Persona Stack

- Added `wiki/entities/lky-avatar.md` from the canonical `Projects/LKY Avatar/Index.md` hub after reconciling current private avatar/voice repo docs, merged PRs, open issues, and eval reports with the public `lky-brain` foundation.
- Kept the applied interview product separate from the LKY Brain corpus-and-adapter entity.
- Captured the tuned Chatterbox LoRA win, watermarked same-GPU integration, interaction/stability gates, portrait-sprite milestone, and the factual-grounding / Singapore proper-noun frontier.
- Omitted private weights, secrets, machine-only launch details, and any claim that the local demo is already publicly deployed.

## 2026-07-14 migrate | Move long-form attention guide to content-distribution

- Removed the earlier misconception-first article and its four public figure assets from this product namespace.
- The rewritten cross-format guide now lives at `content-distribution/wiki/syntheses/attention-architecture-for-long-form-content.md`.
- Kept product demos in scope here while routing general video, essay, Substack, and X attention/distribution systems to the dedicated namespace.

## 2026-07-14 update | Add source-video framework figures

- Added four Jamie-supplied frames to `assets/misconception-first-explanation-loop/` and embedded them beside the misconception, question-to-explanation, A-plot/B-plot, and combined-summary passages.
- Added descriptive alt text, numbered captions, source attribution, and a rights note.
- Kept the formula framed as a mnemonic for the video's structure, not a validated quantitative model.

## 2026-07-14 create/update | Misconception-First Explanation Loop

- Added `wiki/concepts/misconception-first-explanation-loop.md` from the canonical Knowledge concept and Jamie's supplied “Veritasium - What you don't see” transcript.
- Preserved the reusable sequence: misconception → question → prediction → explanation → revised model, plus connected concrete A-plot / technical B-plot switching.
- Routed it narrowly to technical explainers, product demos, and case studies; kept indexes, `llms.txt`, runbooks, and reference docs retrieval-first.
- Kept the full supplied transcript private and separated practitioner learning evidence from retrospective virality claims.

## 2026-07-13 update | Connect taste formation to public legibility

- Cross-linked `Taste Requires Contact` and the Side Doors `Verb-first taste` section in both directions.
- Clarified the relationship as formation → evidence → distribution: contact develops judgment, verb-first choices expose it, and public artifacts let it travel.
- Preserved the boundary that an artifact does not prove good taste by existing; it makes decisions inspectable.

## 2026-07-13 create/update | Side-Quest Validation Loop

- Added `wiki/concepts/side-quest-validation-loop.md` from the canonical `Knowledge/concepts/side-quest-validation-loop.md` synthesis and Deya's YouTube video.
- Preserved the tiny/useful/fun criteria, behavior-weighted evidence ladder, and predeclared kill/adjust/continue/promote gate.
- Kept the framework tool-independent and separated the sponsored Lovable demonstration and anecdotal business claims from universal proof.
- Kept the full user-supplied transcript private; the namespace contains a public-safe synthesis and source attribution only.

## 2026-07-13 create/update | Taste Requires Contact

- Added `wiki/concepts/taste-requires-contact.md` from the canonical `Knowledge/concepts/taste-requires-contact.md` article and Jason Liu's “if you want good taste, you have to eat.”
- Preserved the contact → notice → name → imitate → compare → curate → risk loop and the distinction between wasteful friction and learning-bearing friction.
- Cross-linked Material Loop and Interaction Mode Routing so AI can remove boring execution without replacing the perception tasks that develop judgment.
- Kept the supplied transcript private; the namespace contains a public-safe synthesis and source attribution only.

## 2026-07-13 create/update | Side Doors: Make Useful Work Legible

- Added the illustrated synthesis `wiki/syntheses/side-doors-make-useful-work-legible.md` from the canonical `Knowledge/concepts/side-door-opportunity-search.md` page and Maja's “How to Enter Side Doors.”
- Mirrored six Jamie-supplied framework and story screenshots under `assets/side-door-opportunity-search/` and used normal Markdown image syntax with local Pixi Wiki asset routes.
- Preserved the default/outbound/inbound model, five story patterns, verb-first taste/distribution extension, and survivorship, attention, privacy, and unpaid-labor guardrails.
- Updated namespace README and index; generated public output remains deployment-gated.

## 2026-07-12 create/update | Product Management as System Steering

- Added `wiki/concepts/product-management-as-system-steering.md` from the canonical Knowledge concept and Fahd Ananta's “Secrets of the Best PMs.”
- Preserved the operating formula: decide under ambiguity, own the gaps, route through people, trade scope first, and align ecosystem incentives.
- Linked the framework to AI-native problem framing, decision artifacts, and role-aligned deployed project proof; retained guardrails against impulsiveness, micromanagement, and coercive lock-in.
- Updated namespace README and index; no Daily Notes were copied or compiled.

## 2026-07-09 create/update | Role-Aligned Deployed Project Proof

- Added `wiki/concepts/role-aligned-deployed-project-proof.md` from the canonical `Knowledge/concepts/role-aligned-deployed-project-proof.md` page.
- Preserved the role/JD → repeated job verb → painful workflow → smallest live artifact → evidence → tailored case-study selection rule.
- Kept the multi-role idea list as a starter catalog and made live deployment, ownership, truthfulness, and role-specific judgment explicit hard gates.
- Updated namespace README and index; no Daily Notes were copied or compiled.

## 2026-07-08 create/update | J-space as Global Workspace concept

- Added `wiki/concepts/j-space-global-workspace.md` from the canonical `Knowledge/concepts/j-space-global-workspace.md` page and Anthropic Transformer Circuits paper.
- Routed the paper as a product-surface concept: replay verbalizable readouts to keep model work inspectable, while preserving the caveat that this is not direct access to model thoughts.
- Cross-linked it to J-Space-Replay as the app's inspiration and honesty boundary.

## 2026-07-08 create/update | J-Space-Replay entity

- Added `wiki/entities/j-space-replay.md` from the canonical `Projects/J-Space-Replay/Index.md` hub and public `pixiiidust/j-space-replay` repo docs.
- Routed J-Space-Replay as an AI-native product surface: a glass-box replay dashboard for VLM logit/J-lens readouts over video.
- Preserved the public honesty boundary: demo-quality interpretability, not validated VLM mechanistic evidence or model-thought claims.
- Updated namespace README, index, and compiler map; no Daily Notes were copied or compiled.

## 2026-06-30 update | Job Edge public dashboard and Ashby auto-refresh

- Updated `wiki/entities/job-edge.md` from the canonical `Projects/Job Edge/Index.md` hub after PR #10 merged on `pixiiidust/job-edge`.
- Captured the live-public milestone: GitHub Pages dashboard, scheduled/manual GitHub Action refresh, successful workflow run, built Pages status, 150-job live snapshot, and no-browser-Python boundary.
- Preserved the discovery boundary: current automation refreshes known Ashby company boards from `data/discovered_slugs.txt`; automated discovery of brand-new Ashby slugs and new/removed/changed diffs remain future slices.
- Updated namespace README and index; no Daily Notes were copied or compiled.

## 2026-06-30 update | Shifu pivot/proof boundary

- Updated `wiki/entities/shifu-app.md`, `wiki/concepts/video-retrieve-then-verify-loop.md`, and `wiki/concepts/verified-video-answer-surfaces.md` from the canonical project/Knowledge updates.
- Captured the public-safe pivot posture: keep the local-first video workbench artifact, demote the old AI-core visual gameplay bet, and treat visual embeddings as low-trust recall until structured signals and verifier evidence prove value.
- Recorded that Jamie's local `mini-vss` smoke likely has not exercised the full Tonbi loop yet; future proof should reproduce captions/transcripts/fusion/deeper pools/verifier before judging the implementation.
- Updated namespace index; no Daily Notes were copied or compiled.

## 2026-06-29 update | Shifu implementation chain closed

- Updated `wiki/entities/shifu-app.md` from the canonical `Projects/Shifu/Index.md` hub after PR #26 merged and parent #3 closed.
- Captured post-merge verification: focused verifier/eval tests 18 passed, full suite 80 passed with one warning, compileall clean, `git diff --check` clean, and fixture evaluator passed 5/5 while preserving `Private VOD detection proof: no` and verified hits 0.
- Reframed current state from PR-open gate to implementation-chain complete; next frontier is the actual private VOD proof run with GTX 1070 artifacts, labels, and structured verifier verdicts.
- Updated namespace index; no Daily Notes were copied or compiled.

## 2026-06-28 update | Shifu verifier report gate

- Updated `wiki/entities/shifu-app.md` from the canonical `Projects/Shifu/Index.md` hub after issue #21 / PR #26.
- Captured the verifier-report milestone: manifests, structured verdict import, deeper T3 verifier pools, verified-only T3 recall, baseline-vs-verified deltas, negative/refusal reporting, and actual-video guide.
- Preserved the proof boundary: fixture smoke may pass baseline retrieval, but real private-VOD proof still requires Jamie's GTX 1070 run, private labels, non-placeholder modality artifacts, and structured verifier verdict imports.
- Updated namespace index; no Daily Notes were copied or compiled.

## 2026-06-27 create/update | Shifu local-first video knowledge entity

- Added `wiki/entities/shifu-app.md` from the canonical `Projects/Shifu/Index.md` hub.
- Routed Shifu as an AI-native product surface: local-first searchable video knowledge with VPS upload/light smoke and a local GTX 1070 worker artifact seam.
- Preserved the boundary that cloud GPUs are optional future adapters and private media/model artifacts stay out of git.
- Updated namespace README and index; no Daily Notes were copied or compiled.

## 2026-06-27 create/update | VSS video retrieve-then-verify concepts

- Added `wiki/concepts/video-retrieve-then-verify-loop.md` and `wiki/concepts/verified-video-answer-surfaces.md` from the canonical Knowledge pages.
- Routed Tonbi `mini-vss` and NVIDIA VSS as product-surface source material: the durable concept is candidate recall plus evidence-bearing verification, not a new namespace or infrastructure commitment.
- Updated namespace README and index; no Daily Notes were copied or compiled.

## 2026-06-27 create/update | Agent Output Decision Artifacts

- Added `wiki/concepts/agent-output-decision-artifacts.md` from the canonical Knowledge page.
- Routed it as an AI-native product-surface concept: verbose agent output should become one-screen, visual, source-backed decision artifacts when the user needs to decide, approve, compare, or steer.
- Kept pricing, revenue path, and product wedge details in the private brainstorm namespace; public Pixi Wiki gets the reusable surface principle only.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add first product-surface compiled pages

- Added `wiki/entities/planned-program-intel.md`.
- Added `wiki/entities/myabode.md`.
- Added `wiki/concepts/ai-native-problem-framing-framework.md`.
- Updated `wiki/index.md` from scaffold to active content index.
- No Daily Notes were copied or compiled.

## 2026-06-19 update | Clarify I-know-kungfu wiki-first framing

- Updated `wiki/entities/i-know-kungfu.md` and `Projects/I-know-kungfu/Index.md` after product-language clarification.
- Set **knowledge base wiki** as the core product object.
- Demoted **Knowledge Pack** to the portable package/install format for a wiki.
- Preserved Variant C: find useful wiki → check local fit → choose serving entry point → harmonize overlap → inspect proof/refusal.
- No Daily Notes were copied or compiled.

## 2026-06-23 update | Add AI definition to namespace top

- Added Jamie's AI definition to the top of `README.md` and `wiki/index.md`.
- Preserved existing namespace scope and source roots.

## 2026-06-23 create/update | Interaction Mode Routing

- Added `wiki/concepts/interaction-mode-routing.md` from the canonical Knowledge page.
- Updated the AI-native framing page with interface-mode selection after E/A/G/C framing.
- Updated I-know-kungfu with the Generated Fit Check Surface direction.
- No Daily Notes were copied or compiled.

## 2026-06-24 create/update | Material Loop and Glass Interfaces

- Added `wiki/concepts/material-loop-and-glass-interfaces.md` from the canonical Knowledge page.
- Updated Interaction Mode Routing and AI-Native Problem Framing with agency/material-closeness framing.
- Updated I-know-kungfu with the glass fit-check authorship lens.
- Updated namespace README and index; no public Pixi Wiki deploy.

## 2026-06-26 create/update | World Model Control Surfaces

- Added `raw/transcripts/yann-lecun-world-models-next-ai-revolution.md` from the user-provided transcript.
- Added `wiki/concepts/world-model-control-surfaces.md` from the canonical Knowledge page.
- Updated AI-Native Problem Framing, namespace README, and index with the state/action/prediction/objective/guardrail control-loop lens.
- Classified this as a concept, not a standalone entity or namespace; no public Pixi Wiki deploy was pushed from this source update.

## 2026-06-27 create/update | Job Edge entity

- Added `wiki/entities/job-edge.md` from the canonical `Projects/Job Edge/Index.md` hub.
- Routed Job Edge as a job-search edge/dashboard product surface under `ai-native-product-surfaces`; `ashby-pm-radar` remains the first use case, not the whole product boundary.
- Updated namespace README and index with the new source root and entity listing.
- No Daily Notes were copied or compiled.


<!-- ===== ai-native-product-surfaces/wiki/syntheses/side-doors-make-useful-work-legible.md ===== -->

---
title: "Side Doors: Make Useful Work Legible"
created: 2026-07-13
updated: 2026-07-13
type: synthesis
status: compiled
namespace: ai-native-product-surfaces
source: Knowledge/concepts/side-door-opportunity-search.md
confidence: medium
---

# Side Doors: Make Useful Work Legible

A job is not fundamentally a title. It is a bundle of problems someone wants solved badly enough to spend money, trust, or attention on another person.

That framing changes opportunity search from:

```text
find posted role → submit credentials → wait to be interpreted
```

into a larger search problem:

```text
find meaningful work or a live problem
→ understand it with specificity
→ make useful capability visible
→ place the signal where a relevant person can recognize it
→ let a conversation reveal the opportunity
```

This synthesis draws from Maja's ["How to Enter Side Doors"](https://velvetnoise.substack.com/p/how-to-enter-side-doors), Jamie-supplied framework and story screenshots, the public [Traveler's Guide to the Latent Space](https://sweet-hall-e72.notion.site/A-Traveler-s-Guide-to-the-Latent-Space-85efba7e5e6a40e5bd3cae980f30235f), and a supplied transcript of the Shopify internship video.

## Companies contain problems before they contain jobs

![Framework diagram describing a company as a collection of problems](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/company-is-a-set-of-problems.jpg)

*Figure 1. A company is a set of problems and desired outcomes. Screenshot supplied by Jamie from Maja's article.*

Organizations are groups of people trying to make things happen under constraints. They need to understand markets, find customers, launch things, support users, explain their work, improve operations, hire, stay compliant, and remove bottlenecks.

Those needs exist before a hiring team writes a job description.

![Framework diagram showing company problems becoming named jobs](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/problems-packaged-into-jobs.jpg)

*Figure 2. Some problems get packaged into formal jobs. Screenshot supplied by Jamie from Maja's article.*

A formal role is a **packaged problem bundle**. Some needs have become legible enough to receive a title, budget, manager, and evaluation process. Other needs remain unscoped, cross functional, newly noticed, or ownerless.

The front door begins after the packaging. Side doors operate around the gap between **problems that already exist** and **roles that have already been formalized**.

## Three routes

![Framework diagram comparing default, outbound, and inbound paths](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/default-outbound-inbound-paths.jpg)

*Figure 3. The default, outbound, and inbound routes. Screenshot supplied by Jamie from Maja's article.*

### Default: apply to the package

```text
person → job board → posted role → application queue → company
```

The organization defines the problem and the evaluation frame. The candidate enters after the role is legible. This route remains useful, but it is crowded and lossy.

### Outbound: go toward the live problem

```text
person → specific company/person/problem
→ useful proof or observation
→ conversation
→ possible advocate or opportunity
```

Strong outbound is not generic networking. It notices a particular body of work, studies the context, and makes a small unit of relevant capability visible. The recipient should not have to invent the connection.

### Inbound: make the signal findable

```text
real work → public artifact → discovery by a tuned-in person
→ conversation → possible opportunity
```

Essays, guides, tools, analyses, prototypes, experiments, videos, events, and communities can act as ambassadors. They let another person inspect how the creator thinks before deciding whether to make contact.

### Hybrid: the pitch is also the proof

Some artifacts address one organization while remaining public and discoverable. The application itself performs the capability being offered.

## What creates signal

The recurring ingredients are:

1. **Specificity:** attention aimed at a real person, problem, company, or discourse.
2. **Proof:** a prior action, useful artifact, or inspectable decision trail.
3. **Legibility:** another person can infer what the creator notices and can do.
4. **Placement:** the proof reaches a channel or community where its value can be recognized.
5. **Invitation:** the next step is clear, small, and optional.

```text
specific attention + observable proof + useful placement + bounded invitation
```

## Story 1: the Calm cold email

![Excerpt from a cold email to the Calm CEO titled Two Thank Yous and One Offer](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/calm-cold-email-excerpt.jpg)

*Figure 4. Excerpt from Maja's "Two Thank You's + One Offer" email. Screenshot supplied by Jamie from Maja's article.*

At eighteen, Maja sent Calm's CEO a long, earnest email after encountering his public work. She connected that trigger to relevant ideas and evidence from growing large Instagram pages. He replied, asked her to prepare a pitch, and they worked together.

```text
specific person → genuine trigger → relevant proof → concrete offer
```

The lesson is not to imitate the email's length or intensity. The useful mechanism is that the message contained more than admiration: it gave the recipient enough specific evidence to imagine a working relationship.

## Story 2: the Blackbird internship that did not exist

![LinkedIn message beginning Random moonshot and asking about a Blackbird Foundation internship](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/blackbird-linkedin-message.jpg)

*Figure 5. Maja's "Random moonshot" LinkedIn message. Screenshot supplied by Jamie from Maja's article.*

Maja wanted to learn from Joel at the Blackbird Foundation, but no internship application was open. She explained the Startmate internship context, named why Blackbird and Joel specifically mattered, and connected her startup experience to the investor side she wanted to understand. An internship was later created.

```text
specific person → specific context → credible fit
→ request beyond the published taxonomy
```

From far away, this can look like luck. From inside, it begins with a person paying enough attention to try the handle on a door that has no official label.

## Story 3: Jae's essay on taste

![LinkedIn post sharing an essay critiquing taste discourse](/pixi-wiki/wiki/ai-native-product-surfaces/assets/side-door-opportunity-search/jae-taste-essay-linkedin-post.jpg)

*Figure 6. LinkedIn post sharing Jae's essay on taste. Screenshot supplied by Jamie from Maja's article.*

Jae published a strong critique of contemporary taste discourse on Substack and LinkedIn. The essay exposed how he selected evidence, rejected a prevailing frame, and constructed an argument. Eucalyptus CEO Tim Doyle saw it, commented, met him for coffee, and Jae was eventually hired.

```text
independent point of view → public essay → recognition → relationship
```

The essay was not a disguised application. It was real thinking directed at a real discourse. That is why it could travel ahead of its author.

## Story 4: A Traveler's Guide to the Latent Space

Ethan Smith created [A Traveler's Guide to the Latent Space](https://sweet-hall-e72.notion.site/A-Traveler-s-Guide-to-the-Latent-Space-85efba7e5e6a40e5bd3cae980f30235f) in response to repeated questions from the early AI-art community: "What's the prompt?" and "What are the settings?"

It is not a casual post. The chaptered guide covers Disco Diffusion setup, prompt engineering, init images, model settings, GPU/runtime troubleshooting, experiments, and comparisons. It organizes scattered frontier learning so other people can begin farther along.

Someone who recognized that capability contacted Ethan through Discord about becoming a technical cofounder of Leonardo.ai, later acquired by Canva.

```text
frontier obsession → repeated community questions → useful guide
→ discovery by someone carrying a matching problem
```

The guide demonstrates experimentation, synthesis, technical curiosity, teaching, and community awareness without listing them as identity claims.

## Story 5: Shopify's proposed first marketing internship

The supplied video transcript begins:

> "Shopify doesn't seem to have any marketing internships. What if I became the first?"

The creator does not stop at saying she is creative. She narrates repeated actions: building a YouTube community of more than 10,000 people, collaborating with brands, launching a podcast, organizing Socratica events, creating belonging, and continuing to publish without guaranteed attention.

It ends:

> "If you're all about bold ideas, then here's mine. Let me be your first."

```text
missing role → propose role → show repeated actions
→ perform the capability in the pitch → direct ask
```

The video is a hybrid side door. It addresses Shopify directly while also functioning as a public artifact. Its storytelling, emotional structure, and ability to attract attention are part of the evidence.

## One framework, five different objects

| Example | Route | What was made legible | Proof object |
|---|---|---|---|
| Calm email | Outbound | Internet attention, ideas, initiative | Specific email plus prior audience-building evidence |
| Blackbird message | Outbound | Person-specific fit and learning intent | Context-rich LinkedIn message |
| Jae's taste essay | Inbound | Judgment and argument | Public essay |
| Traveler's Guide | Inbound | Technical experimentation and teaching | Useful frontier guide |
| Shopify video | Hybrid | Story, connection, community, and audacity | Public application video |

The reusable move is not a particular medium. It is:

> Make the work inspectable enough that one relevant person can already imagine what engaging with you would feel like.

## Verb-first taste

Technology discourse often treats **taste** as a noun someone possesses: a refined aesthetic, the right references, or membership in a fashionable scene.

Verb-first taste asks what a person repeatedly:

- notices that others miss;
- selects and rejects;
- edits or removes;
- sequences under constraints;
- protects when tradeoffs appear;
- explains as better for the intended experience.

A moodboard is an input. Taste is the pattern of choosing, rejecting, combining, and protecting.

[[concepts/taste-requires-contact|Taste Requires Contact]] explains the upstream learning loop: firsthand encounter, precise noticing, vocabulary, imitation, comparison, curation, and creative risk develop judgment. Verb-first taste describes the downstream evidence of that judgment. Public work can then make those choices inspectable without reducing taste to a self-applied label.

Jae's essay demonstrates taste because the artifact exposes selections and refusals. It does not merely claim the identity.

## Verb-first distribution

Distribution is also commonly treated as a possession: a channel, audience, community, platform, or growth hire.

A verb-first distribution model describes the behavioral chain:

```text
person encounters
→ recognizes relevance
→ tries
→ experiences value
→ returns or shares
```

"We use LinkedIn" names a channel. It does not explain why someone notices, acts, continues, or tells another person.

The examples show several distribution verbs:

- the Calm email **reaches** one person with specific relevance;
- the Blackbird message **routes** around a nonexistent application form;
- Jae's essay **travels** through public discourse;
- Ethan's guide **answers** repeated community questions and **circulates** among frontier practitioners;
- the Shopify video **attracts**, **demonstrates**, and **invites** simultaneously.

## Community, brand, and strategy are verbs too

- **Community:** Who gathers, contributes, returns, helps, and develops belonging?
- **Brand:** What expectations are repeatedly created and kept?
- **Strategy:** What is chosen, refused, sequenced, and protected under constraints?

Nouns describe the identity someone wants credited. Verbs reveal the value they can repeatedly produce.

## How to do this without becoming annoying

- Study before contacting.
- Begin from the recipient's world, not a long biography.
- Make the proof small enough to inspect quickly.
- Do not require the recipient to invent the relevance.
- Ask for one bounded next step.
- Make "no" easy.
- Do not confuse audacity with entitlement.
- Do not spray identical messages at many people.
- Do not donate weeks of speculative labor to prove seriousness.
- Respect privacy, confidential information, and organizational boundaries.

The useful unit is usually not a complete unpaid solution. It is the smallest artifact or observation that makes the quality of attention and capability visible.

For the message layer, see [Reader-Centered Outreach Asks](/pixi-wiki/wiki/agent-workflows/wiki/concepts/reader-centered-outreach-asks.md.html).

## Limits

These are memorable success stories, so they contain survivorship bias. They do not prove that cold outreach, public writing, or viral artifacts reliably cause jobs.

Luck, privilege, timing, network position, taste, and platform distribution remain part of the outcome. Most attempts may receive no response. The defensible claim is narrower:

> Specific proof can create routes and signals that a formal application alone cannot create.

Side doors expand the move set. They do not make an unfair market fair, and they should not become a moral test that blames people when the market remains unresponsive.

## Working checklist

Before using a side door, ask:

1. What real person, work, or problem am I paying attention to?
2. What have I noticed that is specific rather than generic?
3. What is the smallest useful proof I can make or point to?
4. Which verbs does the proof demonstrate?
5. Where can someone tuned to this problem encounter it?
6. Is the invitation bounded and easy to decline?
7. Am I respecting attention, privacy, and unpaid-labor boundaries?
8. What will I learn even if the door stays closed?

## Sources and image note

- Maja, ["How to Enter Side Doors"](https://velvetnoise.substack.com/p/how-to-enter-side-doors), Velvet Noise, 2026-05-14.
- Ethan Smith, ["A Traveler's Guide to the Latent Space"](https://sweet-hall-e72.notion.site/A-Traveler-s-Guide-to-the-Latent-Space-85efba7e5e6a40e5bd3cae980f30235f).
- Framework and story screenshots supplied by Jamie from Maja's article for commentary and analysis. Copyright remains with the respective creators and publications.
- Shopify transcript supplied by Jamie from the public internship video. Only short excerpts are reproduced here.


<!-- ===== content-distribution/CLAUDE.md ===== -->

# Content Distribution Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/content-distribution/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and preserved raw sources as canonical authoring evidence.
- Keep the namespace about content structure, packaging, retention, redistribution, and measurement across formats.
- Do not claim that a framework guarantees virality or platform recommendation.
- Distinguish attention metrics from comprehension, accuracy, and trust.
- Translate patterns by medium; do not mechanically apply video pacing to essays or threads.
- Preserve source and image-rights boundaries.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added or materially changed.


<!-- ===== content-distribution/README.md ===== -->

---
title: Content Distribution Systems
created: 2026-07-14
updated: 2026-07-14
type: namespace-overview
status: active
category: knowledge-systems
namespace: content-distribution
confidence: medium
---

# Content Distribution Systems

> Cross-format systems for structuring, packaging, measuring, and improving the distribution conditions of useful long-form content.

## Scope

### Covers

Long-form attention architecture, honest packaging, narrative/explanation structure, audience retention, shareable payoff design, cross-format translation across video, Substack/blog essays, X articles/threads, and measurement boundaries between entry, retention, redistribution, understanding, and trust.

### Not Covered

Guaranteed virality formulas; platform-specific growth hacks without evidence; generic social calendars; paid-media operations; SEO catalogs; short-form trend imitation; manipulative clickbait or cliffhanger systems that sacrifice truth and payoff.

### Current As

2026-07-14 — active namespace. Starts with the illustrated **Attention Architecture for Long-Form Content** guide, migrated out of AI-Native Product Surfaces and generalized from a Veritasium video case into a cross-format editorial system.

## Canonical Source Roots

- `Knowledge/concepts/attention-architecture-for-long-form-content.md`
- `Knowledge/raw/transcripts/veritasium-what-you-dont-see.md`
- `Knowledge/raw/assets/misconception-first-explanation-loop/provenance.md`
- `Knowledge/raw/assets/misconception-first-explanation-loop/migration-2026-07-14.md`

## Crosslinks

- [[../ai-native-product-surfaces/README|ai-native-product-surfaces]]
- [[../eval-trace/README|eval-trace]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/content-distribution/README.md
/raw/content-distribution/wiki/index.md
/wiki/content-distribution/README.md
/wiki/content-distribution/wiki/index.md
/wiki/content-distribution/llms.txt
```

## Maintenance

- Edit canonical source notes first.
- Keep claims about virality, algorithms, and platform causality evidence-calibrated.
- Distinguish entry, retention, redistribution, understanding, and trust metrics.
- Translate structure by medium rather than copying video tactics into prose.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.


<!-- ===== content-distribution/wiki/index.md ===== -->

---
title: Content Distribution Systems — Master Index
created: 2026-07-14
updated: 2026-07-14
type: index
status: active
namespace: content-distribution
---

# Content Distribution Systems — Master Index

> Cross-format guides for earning attention, sustaining it honestly, and creating useful payoffs that improve the conditions for distribution.

## Concepts

<!-- Add durable component concepts alphabetically as the namespace grows. -->

## Entities

<!-- Add relevant platforms, publications, or case-study entities only when independently useful. -->

## Summaries

<!-- Add source or measurement summaries alphabetically. -->

## Syntheses

- [[syntheses/attention-architecture-for-long-form-content|Attention Architecture for Long-Form Content]] — Illustrated guide to the entry, retention, and redistribution gates across long-form video, Substack/blog essays, and X articles or threads.

## Source Roots

- `Knowledge/concepts/attention-architecture-for-long-form-content.md`
- `Knowledge/raw/transcripts/veritasium-what-you-dont-see.md`
- `Knowledge/raw/assets/misconception-first-explanation-loop/provenance.md`
- `Knowledge/raw/assets/misconception-first-explanation-loop/migration-2026-07-14.md`


<!-- ===== content-distribution/wiki/log.md ===== -->

---
title: Content Distribution Systems — Activity Log
created: 2026-07-14
updated: 2026-07-14
type: log
status: active
namespace: content-distribution
---

# Content Distribution Systems — Activity Log

## 2026-07-14 create/migrate | Attention Architecture for Long-Form Content

- Created the `content-distribution` namespace under the Knowledge Systems shelf.
- Renamed and expanded the earlier misconception-first concept into a practical cross-format guide for entry, retention, redistribution, understanding, and trust.
- Migrated the four supplied source-video figures from `ai-native-product-surfaces` and placed them beside the audience-model, question-first, A/B-plot, and compact-model sections.
- Added dedicated playbooks for long-form video, Substack/blog essays, and X articles or threads.
- Preserved the boundary that structure can improve distribution conditions but cannot guarantee virality.


<!-- ===== content-distribution/wiki/syntheses/attention-architecture-for-long-form-content.md ===== -->

---
title: Attention Architecture for Long-Form Content
created: 2026-07-14
updated: 2026-07-14
type: synthesis
status: compiled
namespace: content-distribution
tags: [content-distribution, long-form, storytelling, attention, retention, packaging]
sources:
  - Knowledge/concepts/attention-architecture-for-long-form-content.md
  - Knowledge/raw/transcripts/veritasium-what-you-dont-see.md
  - Knowledge/raw/assets/misconception-first-explanation-loop/provenance.md
resource: https://www.youtube.com/watch?v=QHhJ8_TJeNo
confidence: medium
---

# Attention Architecture for Long-Form Content

> A practical guide to earning the open, sustaining curiosity, and improving the conditions for distribution across video, essays, Substack posts, and X articles.

Virality is not a structure you can guarantee. Demand, audience fit, timing, initial reach, platform dynamics, social transmission, and luck all matter. Structure controls a narrower but useful part of the system:

> Earn the open. Create a real question. Alternate progress with explanation. Pay off the promise. Give the audience something worth carrying forward.

## The three gates

Long-form content has to clear three different gates:

1. **Entry:** does the packaging create an honest reason to open?
2. **Retention:** does each section create, advance, or resolve a question?
3. **Redistribution:** was the payoff useful, surprising, credible, or identity-relevant enough to save, share, quote, discuss, or recommend?

```text
Promise → knowledge gap → question/prediction → evidence → payoff → next useful gap
                           ↘ narrative A plot ↔ analytical B plot ↗
```

Clickbait clears entry and fails the payoff. Dense expertise may contain value but provide no reason to continue. Smooth storytelling can retain attention while leaving no durable idea worth sharing.

## 1. Start with a real audience model

A familiar topic can create false fluency: “I already know this,” so the audience stops testing its assumptions. A precise contradiction reveals the gap.

![Derek Muller speaking onstage beneath a mnemonic formula with misconceptions highlighted](/pixi-wiki/wiki/content-distribution/assets/attention-architecture-for-long-form-content/01-misconceptions-formula.png)

*Figure 1. The source video's mnemonic highlights misconceptions as the opening move. Treat the formula as a storytelling summary, not a validated quantitative model.*

Good openings use a specific mismatch, not generic surprise:

- state the likely prior belief;
- show what that belief fails to predict;
- make the gap observable;
- avoid claiming “everyone is wrong” when the disagreement is trivial or invented.

## 2. Package the gap honestly

Titles, thumbnails, headlines, deks, and opening posts are entry surfaces. Their job is to expose the unresolved gap while promising a payoff the piece can deliver.

```text
Topic label:     Shade balls in reservoirs
Knowledge gap:   Why are there millions of black balls on this lake?
```

The stronger frame tells the audience what it will get to resolve. It does not need to reveal the answer or manufacture a mystery.

## 3. Ask before explaining

Let the audience form a prediction before receiving the mechanism:

```text
Observation → prediction → question → evidence → revised model
```

A question gives the next information a job. The explanation is no longer inert background; it resolves uncertainty the audience is already carrying.

![Diagram showing a shade-ball question leading into explanatory frames about water coverage and temperature](/pixi-wiki/wiki/content-distribution/assets/attention-architecture-for-long-form-content/02-question-to-explanation.png)

*Figure 2. The question creates a gap; the following sequence earns the explanation by resolving that specific uncertainty.*

## 4. Alternate narrative and analysis

Long-form pieces benefit from two connected tracks:

- **A plot:** the experiment, person, journey, case, visible attempt, mystery, or concrete sequence;
- **B plot:** the mechanism, data, math, history, expert interpretation, or abstract explanation.

Move from A to B when the concrete action creates a real “why.” Return from B to A when abstraction accumulates and the audience needs to see consequences. Each switch should answer or create a question in the other track.

![Timeline alternating reservoir scenes on the A-plot track and interviews or explanations on the B-plot track](/pixi-wiki/wiki/content-distribution/assets/attention-architecture-for-long-form-content/03-a-plot-b-plot-timeline.png)

*Figure 3. The source video maps the reservoir investigation and explanatory material onto alternating A-plot and B-plot tracks.*

This is not random variety. An unrelated anecdote may reset attention while weakening the argument.

## 5. Pay off, then reset

Resolve the opening promise clearly enough that the audience can state what changed. In a longer piece, each major payoff can expose the next useful question.

A strong payoff gives the audience something portable:

- a revised mental model;
- a memorable distinction;
- evidence worth citing;
- a practical test;
- language that helps explain the idea to someone else.

Portable value is one bridge from retention to redistribution.

## The compact model

> Contradict. Ask. Demonstrate. Explain. Interleave.

![Summary frame listing misconceptions question-explanation and A plot B plot beneath the source video formula](/pixi-wiki/wiki/content-distribution/assets/attention-architecture-for-long-form-content/04-framework-summary.png)

*Figure 4. One-frame summary of the source video's three moves: surface misconceptions, move from question to explanation, and interleave A and B plots.*

## Translate the structure by format

| Function | Long-form video | Substack or blog essay | X article or thread |
|---|---|---|---|
| Entry surface | Title + thumbnail + cold open | Headline + dek + opening paragraph | Lead post, title, or first visible lines |
| A plot | Demonstration, journey, case, on-location sequence | Story, reported case, experiment, personal progression | Concrete example, event sequence, build-in-public progression |
| B plot | Voiceover, expert interview, mechanism, data | Analysis, evidence, history, model | Claim, evidence block, chart, quoted source, explanation |
| Switch unit | Scene or chapter | Section or paragraph cluster | Post block or short section |
| Payoff | Reveal, result, revised explanation | Thesis earned by evidence and consequences | Compact conclusion, model, or action worth quoting |
| Redistribution object | Clip, visual, surprising fact, useful model | Quotable distinction, chart, framework, checklist | Quote-ready line, image, mini-framework, sourced claim |

The medium changes the rhythm. Do not force video pacing into prose or turn an essay into artificial cliffhangers.

## Format playbooks

### Long-form video

1. **Package:** title and thumbnail expose the gap.
2. **Cold open:** show the contradiction before explaining the topic.
3. **Prediction:** let the viewer decide what should happen.
4. **A plot:** begin the experiment, journey, or case.
5. **B plot:** explain only when the visible sequence creates a “why.”
6. **Switch:** return to the concrete result before technical density becomes exhausting.
7. **Payoff:** resolve the opening promise, then expose the next useful question.
8. **Finish:** leave a visual, fact, or model worth sharing.

### Substack or blog essay

1. **Headline and dek:** promise a specific tension and consequence.
2. **Opening:** begin with the failed expectation, not a throat-clearing definition.
3. **Case:** give the reader a person, event, experiment, or decision to follow.
4. **Analysis:** use each explanatory section to answer a question raised by the case.
5. **Section endings:** close one loop before opening another.
6. **Conclusion:** compress the revised model into language the reader can reuse.

### X article or thread

1. **Lead:** make one specific, sourceable claim or contradiction.
2. **Preview:** tell readers what the sequence will resolve.
3. **Blocks:** alternate concrete example and evidence instead of stacking unsupported claims.
4. **Transitions:** make each post or section earn the next one.
5. **Portable objects:** include a chart, image, distinction, or mini-framework worth quoting.
6. **Close:** summarize the model and point to the underlying evidence, not a generic engagement request.

## Working outline

```text
Audience:
What they probably believe:
Observable contradiction or unresolved tension:
Entry promise:
Opening question:
Prediction the audience can make:
A plot (concrete progression):
B plot (mechanism/evidence):
Switch points and why each switch is earned:
First payoff:
Next useful gap:
Final revised model:
Portable value worth saving/sharing:
How truth and audience response will be measured:
```

## Measure the gates separately

### Entry

- click-through rate or open rate;
- qualified starts, not only impressions;
- packaging variants tested against the same underlying piece.

### Retention

- audience-retention curve or completion rate;
- read depth and time on page;
- exits around abstraction-heavy sections;
- continuation from one section or post block to the next.

### Redistribution

- saves, shares, forwards, quotes, citations, and discussion;
- subscriber or follower conversion;
- recommendation and downstream traffic;
- whether people reuse the model accurately.

### Understanding and trust

- can the audience explain the revised model?
- did the opening promise match the payoff?
- were sources and uncertainty visible?
- did corrections reveal an overstated claim?

Clicks are not learning. Retention is not truth. Shares are not necessarily endorsement.

## Guardrails

- **Do not promise virality.** Structure improves conditions; it does not control distribution.
- **Use real audience language.** Do not invent a convenient misconception.
- **Pay every major open loop.** Curiosity without resolution becomes manipulation.
- **Keep A and B plots connected.** Variety should deepen the main question.
- **Protect source truth.** A compelling narrative does not license weak evidence.
- **Match the medium.** Essay rhythm, video rhythm, and thread rhythm are not interchangeable.
- **Stay retrieval-first where needed.** Indexes, runbooks, reference docs, incident instructions, and agent entrypoints should usually answer directly.

## Evidence boundary

The source video combines two different claims:

1. **Learning-design evidence:** an instructional comparison suggested that activating misconceptions can outperform a clear explanation that audiences process passively.
2. **Virality interpretation:** the video retrospectively maps the same moves onto Veritasium's successful channel.

The first supports a useful hypothesis about prior beliefs and active attention. The second is not controlled evidence that the structure caused view counts. Treat this guide as an editorial system to test against real audience behavior, not a universal algorithm.

## Related pages

- [[../../ai-native-product-surfaces/wiki/concepts/taste-requires-contact|Taste Requires Contact]]
- [[../../ai-native-product-surfaces/wiki/syntheses/side-doors-make-useful-work-legible|Side Doors: Make Useful Work Legible]]
- [[../../ai-native-product-surfaces/wiki/concepts/agent-output-decision-artifacts|Agent Output Decision Artifacts]]

## Source and image rights

- The Internet Stamp, [“Veritasium - What you don't see”](https://www.youtube.com/watch?v=QHhJ8_TJeNo), YouTube.
- Figures 1–4 are Jamie-supplied frames from that source video, included for criticism, commentary, and explanation of the depicted framework. Rights remain with the original video and image rights holders.
- The full supplied transcript remains private and is not reproduced in Pixi Wiki.


<!-- ===== rl-sim-labs/CLAUDE.md ===== -->

# RL Sim Labs Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/rl-sim-labs/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to: PufferLib/RL projects, Critical Ranger FFM, zone-control experiments, simulation evidence gates, environment design, and future similar RL labs.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== rl-sim-labs/README.md ===== -->

---
title: RL Sim Labs
created: 2026-06-16
updated: 2026-06-16
type: namespace-overview
status: scaffold
category: rl-simulation
namespace: rl-sim-labs
confidence: medium
---

# RL Sim Labs

> Scaffold namespace for the Pixi Vault AgentWikis compiler.

## Scope

### Covers

PufferLib/RL projects, Critical Ranger FFM, zone-control experiments, simulation evidence gates, environment design, and future similar RL labs.

### Not Covered

General local GPU setup unless required by RL experiment execution; unrelated game projects without RL/simulation learning goals.

### Current As

2026-06-16 — scaffold only. Content has not yet been fully compiled.

## Canonical Source Roots

- `Projects/Critical Ranger FFM/Index.md`

## Crosslinks

- [[../eval-trace/README|eval-trace]]
- [[../local-ai-infrastructure/README|local-ai-infrastructure]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/rl-sim-labs/README.md
/raw/rl-sim-labs/wiki/index.md
/wiki/rl-sim-labs/README.md
/wiki/rl-sim-labs/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== rl-sim-labs/raw/puffer-ai-blog.md ===== -->

---
source_url: https://puffer.ai/blog.html
ingested: 2026-06-18
sha256: d611499cc509d4d5a7684614b63749ccb441b23d4f3376e1498f46cd79694060
---

PufferLib Blog
- PufferLib 3.0: Better Reinforcement Learning at 4M sps

- Puffing Up PPO

- Stronger Hyperparameters with Protein

- PufferLib 2.0: Reinforcement Learning at 1M sps

- Reinforcement Learning Quickstart Guide

- PufferLib 1.0: Now Stable

- The Puffer Stack

- PufferLib 0.7: Puffing Up Performance with Shared Memory

- PufferLib 0.6: 🐡🌊 An Ocean of Environments for Learning Pufferfish

- PufferLib 0.5: A Bigger EnvPool for Growing Puffers

- PufferLib 0.4: Ready to Take on Bigger Fish

- PufferLib 0.2: Ready to Take on the Big Fish

# PufferLib 3.0: Better Reinforcement Learning at 4,000,000 Steps/Second

Sane and robust reinforcement learning is here! Our latest benchmarks train at up to 4M steps/second on a single RTX 5090. Here's a 30 second demo during which we solve Breakout from scratch:

The core training code is < 1000 lines and we've spent a long time making it easy to follow. All our code is free and open source at puffer.ai, complete with documentation, a pip package, and docker images. Join discord for help or to get involved with development. We'll be posting a new article with details every day this week. For now, here are some highlights:

## New Environments

We're adding 10 first-party environments to Ocean for a total of 22. Play them here online!

## Hyperparameter Tuning that Works

Power up your RL with Protein, our new hyperparameter tuning algorithm! It's a heavily modified version of ImbueAI's CARBS that has set SOTA out-of-the-box for multiple clients. We've run tens of thousands of experiments with it across Ocean and third-party environments over the course of development. Here's Protein tuning a ludicrously hard maze environment:

## Algorithmic Breakthroughs

Up until this release, we were just making existing methods faster. Not anymore! Our new trainer solves problems out-of-the-box that 2.0 couldn't solve in a 200 run sweep. The default set of hyperparameters solves most of the easier environments that used to require their own sweeps, too!

## PufferEnv C API

It's easier than ever to build your own high-perf reinforcement learning environment. Our C API is an analog to Gymnasium with optimizations that propagate through Python. Native PufferEnvs simulate observations directly into shared memory batches with zero redundant copy operations. Two tutorial environments and a starter template are now available in our docs.

## Hire Puffer

RL is hard. We make it easier. Hire us to get our eyes on your RL problem, assistance in fast simulation, prioritized feature development, and more. Priority service contracts start at 10k/mo, with larger contracts available for fixed deliverables. DM here or email jsuarez🐡puffer🐡ai.

# Puffing Up PPO

Our day-to-day reinforcement learning work feels like a different field thanks to our new training algorithm. It often solves new environments out-of-the-box in seconds with default hyperparameters, and we're open-sourcing it with PufferLib 3.0. Star the project on GitHub to support our work!

## A Hard Benchmark

We use arcade envs like Pong, Breakout, and Enduro for a lot of our early experiments. These are great because we can train a ~150k parameter MLP-LSTM at 2-4M steps/second (~10B steps per hour). We also use harder game environments like Neural MMO to test ~2-3M parameter networks at 500k-1M steps/second. In this release, we wanted a pure benchmark task with intuitive, easily scalable difficulty to complement our game environments. So we made Puffer Maze! We can generate any size maze we like and train on 11x11 crops of tiles at >1M steps/second with a 2M parameter model. If you're familiar with the literature, you'll know that RL isn't great at mazes, and most of the papers that use them are about hacking exploration bonuses. Our setting is a ludicrously sparse problem in which the agent only gets a reward at the very end.

## Mordernizing the Optimizer

Our previous releases had a high-performance but algorithmically vanilla PPO implementation using Adam. This update uses Muon, which initially didn't seem to make much of a difference, but when we ran full sweeps, there was an immediate step-change in capabilities. The hyperparameters we found for Breakout not only solved the environment ~30% faster, but they also worked on nearly every other env in Ocean! Before this update, we would run a ~200 experiment hyperparameter sweep on each and every environment in order to get good baselines. We also swapped linear learning rate annealing for cosine annealing. This was a more minor detail: while having some form of annealing matters tremendously, we found that the method used doesn't matter much when swept alongside other hyperparameters. But cosine annealing produces more consistent learning curves during sweeps, which helps fit a model to hyperparameters.

## Trajectory Segment Filtering

Apple's self-driving RL paper filtered out training data with uninformative advantage estimates. We've wanted to adopt this for a while, but the naive implementation breaks LSTMs. Our solution was to apply filtering to entire trajectory segments based on the sum of the advantage estimate over the entire segment of usually 64 observations. As an additional improvement, we apply prioritized experience replay instead of filtering over a fixed range. Neither of these techniques helps with every environment, but it can be a massive improvement if rewards are sparse. Prioritized replay is equal to uniform sampling with alpha=0 and beta_0=1, and we sweep both these coefficients, so we can easily see how much prioritized replay matters for any given environment.

## Experience the Puffer Advantage

PPO was the algorithm OpenAI used to beat top pros at DoTA in 2019 and is probably the most widely used on-policy RL algorithm today. Half of what makes PPO good is clipping updates to avoid going too far off-policy. The other half is generalized advantage estimation , which scales rewards based on a fancy exponentially decaying average of n-step bootstrap estimates. In simpler terms: it determines how much a dollar today is worth vs. a dollar tomorrow.

The other really well-known on-policy algorithm is IMPALA. This one gets confused a lot, because it also introduced a ResNet-based architecture in the same paper. So when people say they are using IMPALA, half the time, they are just doing PPO with a ResNet and not actually using the algorithm. But when they are, the key to IMPALA is VTrace, which corrects off-policy updates. It essentially takes the clipping ratio used in PPO and uses it inside of the advantage function per-step, instead of just at the end.

Our original idea was to combine VTrace with trajectory segment filtering in PufferLib to keep around high-value data from epoch to epoch. That was way too off-policy and didn't work at all. But in the process, we spent a lot of time staring at the math... and realized GAE and VTrace are virtually identical! So we put them together and boom, Puffer Advantage! All the reference implementations we found for GAE and VTrace were pretty slow, so this release ships with a custom CUDA kernel. Puffer Advantage is equal to GAE when you set both clip coefficients to infinity and equal to VTrace with lambda=1, so our method is a strict generalization of both.

# Stronger Hyperparameters with Protein

Power up your hyperparameter sweeps with Protein, PufferAI's new algorithm based on ImbueAI's CARBS. The original method stands for Cost AwaRe Bayesian Search because it models the Pareto frontier of cost (usually wall-clock time or steps) and score (your environment's performance metric). Our method modifies CARBS to:

Fix major edge cases. A big motivation for our new algorithm was that CARBS can be show to fail in very simple synthetic tests where any reasonable algorithm should succeed. For example, if CARBS has a confident but wrong model of the Pareto frontier, it degenerates to random sampling. It is very susceptible to noise in individual Pareto points (like lucky seeds) and in the Gaussian Processes it uses to model cost and score.

Fix data normalization. Gaussian processes expect normally distributed data. Performance decays quite rapidly if you feed in big numbers. CARBS is missing normalization in a couple of places, so you can have it work great on some environments and not at all on others.

Simplify the algorithm: CARBS is over 2,500 lines. The PufferLib sweep file is ~500. This is in keeping with our focus on simplicity in all things, and it makes reasoning about the code much easier.

## CARBS

There's already a detailed manuscript on arXiv, but it's pretty dense, so read this section if you aren't already familiar with the algorithm. CARBS starts by defining the Pareto frontier as the subset of experiments where no other experiment is both better and faster, that is, higher score y and lower cost c.

$$ \text{PF} = \{ i \in [1:t] \mid y_{i} > y_{j} \lor c_{i} < c_{j}, \ \forall j \neq i $$

In practice, CARBS starts out by running a few random hyperparameter sets to seed the Pareto front. From there, it picks new candidate hyperparameters with a normal sample around existing Pareto-optimal hyperparameters and downweights them based on distance.

$$P_{\mathrm{search}}\left(\mathbf{x}\right)=\max_{i\in \rm{PF}}\left[\mathrm{exp}\left(-\frac{\left|\mathbf{x}_{i}-\mathbf{x}\right|^2}{2\sigma_{\mathrm{search}}^2}\right)\right]$$

Suppose we generate a few thousand candidates. To help pick the best one, CARBS trains three Gaussian Processes.

$$\mathcal{GP}_{y} \leftarrow \max_{\theta} \left[ p\left(y | \{\mathbf{x}_{i}, y_{i}\}_{i \in [1:t]}, k_{\theta} = k_{\mathrm{lin}} + k_{\mathrm{Mat}}\right) \right]$$

$$\mathcal{GP}_{c} \leftarrow \max_{\theta} \left[ p\left(c | \{\mathbf{x}_{i}, c_{i}\}_{i \in [1:t]}, k_{\theta} = k_{\mathrm{lin}} + k_{\mathrm{Mat}}\right) \right]$$

$$\mathcal{GP}_{\mathrm{pf}} \leftarrow \max_{\theta} \left[ p\left(y | \{c_{i}, y_{i}\}_{i \in PF}, k_{\theta} = k_{\mathrm{RBF}}\right) \right]$$

These are just basic supervised learning problems. The first two map a vector of hyperparameters to the score and cost of the experiment. The last is a bit trickier: it maps the cost of each Pareto point to its score. The idea is that, if you tell CARBS how long you have to run an experiment, it should know how good the result can be. Now to actually select the points, CARBS uses these GPs to define an acquisition function:

$$\alpha_{\mathrm{EI-th}}\left(\mathbf{x}\right) = \mathbb{E}_{\mathcal{GP}_{y}} \left[ \mathrm{ReLU}\left( \mathcal{GP}_{y}\left(\mathbf{x}\right) - \max\left( \tilde{y}_{\mathrm{pf}}\left(\mathbf{x}\right), \tilde{y}_{\mathrm{th}} \right) \right) \right]$$

This is run on each of the candidate hyperparameter vectors x that we got from P_search. If you ignore the second max for a moment and just use y_pf, then this is the difference between predicted score under GP_y and how well GP_pf thinks we can possibly do with any experiment that costs GPc(x). In practice, there's an extra term y_th to control exploration that we'll talk about soon. For now, just take the max of this function and you have your CARBS hyperparameter suggestion.

## ...Are bad for you?

This algorithm steamrolled ProcGen, so it's clearly pretty good. But the longer you look at it, the more problems you notice. First of all, P_search biases predictions to be close to existing Pareto points. Typically, you want longer and longer experiments over time as you become more confident in the results. So to counteract P_search keeping total timesteps (and therefore the run length) close to an existing point, there needs to be a counterbalance towards higher cost experiments. This is where y_th comes in. CARBS samples a random cost between the min and max pareto point and take a max with the existing sample y_pf. This punishes low-cost samples across the board

More problems come from explicitly modeling the Pareto frontier with y_pf. Suppose that all three Gaussian processes are perfect models. CARBS will then define GPy(x) - y_pf = 0. Since the acquisition function is 0 everywhere, you just end up with random sampling. This is true even if you don't actually have good experiments across the frontier. So even if CARBS fits a perfect log-linear scaling law to your problem, it won't actually try to run those more expensive experiments. And GP_pf is very sensitive, because it is only trained with the Pareto-optimal subset of hyperparameters. A lucky seed can throw it off, and the only remedy in CARBS is to periodically resample Pareto points, which requires rerunning old experiments 20% of the time by default. If you have even 5 Pareto points, you're going to have to wait 25 experiments on average before you maybe get an opportunity to correct one lucky seed.

## Power up with Protein!

Our algorithm keeps GP_y and GP_c. Protein eliminates P_search and GP_pf, and it replaces the acquisition function with the following:

$$w(x) = \text{GP}_y(x) \cdot \left(1 - \left| \alpha U - \text{GP}_c(x) \right| \right), \quad U \sim \mathcal{U}(0, 1)$$

Alpha is fixed to 1.25 in our experiments. So this method picks a random cost between 0 and 1.25 and then scores candidate points x by penalizing their predicted score GP_y(x) by the predicted distance from that cost. We normalize scores between 0 and 1 and log costs between 0 and 1.25, so the predicted target cost can be up to ~77% (25% in log space) more expensive than the most expensive point. But we're still sampling around Pareto points only, so runs cannot become arbitrarily expensive without expanding the Pareto front.

Protein is a simpler algorithm than CARBS, but it is robust in ways that CARBS isn't. For example, Protein doesn't care that much if you get a lucky experiment because it doesn't rely on a model of the Pareto frontier. If Protein perfectly fits both GPs, 1/5 (alpha / (1 + alpha)) of experiments will target expanding the frontier to higher-cost regions. It also doesn't get stuck in low-cost regions that are difficult to model, which is a problem we saw with CARBS.

A few other optimizations we made that mattered quite a lot:

- Instead of using only the final cost and score of an experiment, we downsample the training curve to 10 points and use them all as training data for both GPs.

- CARBS seeds with several random trials. We instead use a single run with a reasonable set of defaults. Because this gives us 10 pareto points, we don't have to waste our first 10-20 experiments of every sweep.

- We neatly normalize the search space of each hyperparameter between -1 and 1 to keep data in the domain expected by GPs.

- We set the mean function for GPc to 1. This makes it overestimate how long unconfident samples will take during scoring.

The core logic for Protein is under 100 lines, so if you want to know every detail, read the code!

## Speedrunning RL

How fast can you solve Breakout with really good hyperparameters? We ran CARBS vs. random search, a pareto genetic algorithm (similar to Protein but without the GPs), and CARBS.

We also wrote some synthetic tasks to evaluate various methods. There is only one parameter to fit, but score is either a linear, logarithmic, or percentile function of cost. The costs for the log and percentile tasks have 20% noise to make it harder. We evaluated a random search that takes normally distributed samples from hyperparam default means, a pareto genetic algorithm that works similarly to Protein but without the gaussian processes, and Protein. The source for all of the methos is in pufferlib/sweeps.py. The synthetic benchmarks to reproduce our experiments are in tests. Here are the results:
Algorithm comparisons on synthetic tasks
Random sampling fails because it never evaluates high-cost parameters. Pareto genetic sometimes works if you give it enough runs, but it can get stuck if the Pareto points are too densely distributed (this caused it to fail the log task on this run). Protein solves them all, and in fewer experiments!

## Catabolic Variations

We tried dozens of different scoring functions, normalization techniques, and objectives before settling on the current method. Here are some things that didn't work:

Fancy scoring normalization: It is common for hyperparameter sweep algorithms to apply some sort of scaling transformation to the target metric. But reinforcement learning score curves are quite varied! Breakout is scored from 0-864 points, where 550 isn't much different from 570, and 860-864 is just a matter of consistently hitting the last brick or two. Some environments use win-rate as a metric, so 0.999 is 10x better than 0.99. Other environments like Enduro are endless and have virtually linear learning curves with ever-improving scores. In our synthetic tasks, it was quite easy to improve one shape of curve at the expense of the others, but simply normalizing the min and max scores from 0 to 1 was the best overall.

Anything relying on a difference between GPs: We found that the trained GPs are at most directionally correct and quite noisy, with meaningless learned variances. This was the main reason we scrapped GP_pf.

Anything relying on specific Pareto points: One early variant attempted to maximize the distance between the next experiment and existing pareto points in cost space. It could be shown to converge to binary search under perfect GPs, which is a really nice property to have. Unfortunately, relying on an individual Pareto point once again creates instability to lucky seeds. The method worked great on initial synthetic tests but collapsed when we introduced noisy score estimates.

Maximizing information gain: Another early idea was to reward Protein based on the improvement made per compute spent. We could only make this work with a known learning curve shape, because the meaning of relative changes in score varies wildly per environment. This is still one of my favorite ideas, but it would require substantial rethinking and perhaps online curvature estimation.
# PufferLib 2.0: Reinforcement Learning at 1,000,000 Steps/Second

Welcome to a new age of reinforcement learning. This is our biggest release ever. 11 new environments totaling ~20,000 lines of pure C. They all run >1M steps/second (sps) on a single CPU core, and you can train at 300k-1.2M sps on a single GPU, depending on the environment and policy. That means you can run centuries of simulations per GPU per day. Academic labs with a handful of GPUs now effectively have thousands. It's all free and open source under the MIT license -- star the repo to support the project!

About half of the new environment code was written by open-source contributors. Thank you all for making this possible. A full list is available on the project page.

## Puffer Ocean: Our Environments

You can play these yourself or watch our pretrained agents running live in your browser. Each of our new environments are written in C as a single .h file. There is nothing fancy here, and the only dependency is raylib for rendering. Anyone who has taken a single systems course can understand and contribute to the code. The main techniques we use for performance are:

- No dynamic memory allocations. Everything is allocated during initialization.

- No observation copies. Environments write observations directly to the buffers used for training.

- Aggressive caching. The most extreme example of this is in the MOBA, where we store 250MB of pathing data.

We bind environments to Python via a short Cython intermediary layer. Each environment also has a Python stub defining observation and action spaces and wrapping the Cython step/reset/close functions. This means that environment devs more comfortable in Python can prototype there before porting to Cython or C for performance. Cython is plenty fast, but C makes it easy to compile for web. We load PyTorch models with a ~500 line puffernet.h to demo trained agents in your browser.

## Native PufferEnv API + Vectorization

Even with a 1M sps environment, you still spend 15 minutes on simulation per billion steps trained. With PufferLib, it's more like 10 seconds because of asynchronous on-policy sampling. When your policy is computing actions for one batch of environments, another is stepping in the background. By the time your forward pass is done, new data is ready with 0 downtime. This is a fancy implementation of EnvPool with some extra tricks. It's compatible with everything, not just our native envs, but that's where you'll see the biggest benefit. Details are in the PufferLib whitepaper on arXiv.

To achieve this level of performance, we introduce a new PufferEnv API for native environments. It's less than 100 lines and allows new environments to take full advantage of the rest of PufferLib's optimizations. Native environments skip the Python loop over agents as well as several redundant copy operations. Our multiprocessing implementation checks if you are using a native environment and, if you are, it passes your constructor a pointer into shared memory. Each C environment then writes observations directly into that buffer, so they are immediately available on the main process.

In case you're worried about compatibility, don't be. Everything can still be run with Gymnasium/PettingZoo. We just use a VecEnv style API by default. Async mode is a superset of Gymnasium, so you can start off synchronous and implement async with a few small changes to your training code. And even if you don't do any of that, you will still be able to train an order of magnitude faster than with more standard environments.

# Reinforcement Learning Quickstart Guide

So you want to learn reinforcement learning? It's a hard mountain to climb, but I'm going to be giving you some of the best tricks and insights from my playbook. Star PufferLib on GitHub if you learn something useful. It's the library I'm building to make RL fast and sane.

## What is RL?

(Deep) reinforcement learning is a branch of ML focused on learning through interaction. You are training an agent or policy. Both of these just mean neural network. The world, game, or sim the agent is interacting with is called the environment, which is in a particular state at any point in time. The agent makes an observation of the state at each timestep. That's the data it sees and can use to make decisions. In some environments, this is simply the full state, in which case we say the environment is fully observed. Otherwise, it is partially observed. In math heavy RL lit, you will see these described by Markov Decision Processes (MDP) and Partially Observable MDPs (POMDP). Consider this nomenclature optional. The agent makes an action based on the observation, which is then used to step the environment forward in time. The environment will return a reward based on what happens in the environment. This can be 0 and often is, but it might be 0.5 if an agent scores a point and -1 is the agent dies, for example.

## Fundamentals

There are a few different common classes of algorithms, as well as some stuff masquerading as RL that really isn't. I'd rather eat broken glass than read academic papers all day, so I'll keep the background material light.

On-policy: You learn a function that maps observations to actions. Read Karpathy's blog post on policy gradients, then skip right to the PPO paper. You might need to refer to the Generalized Advantage Estimation paper for context.

Off-policy: You learn a function that maps (observation, action) to some value that tells you how good that action is. The agent then acts either by selecting the highest-value action, or sometimes by sampling. You should absolutely read DQN as one of the first fundamental papers in this area. Then, skip right to Rainbow because it summarizes and cites most of the intermediate improvements anyways. Nowadays, Soft Actor Critic is the most widely used off-policy algorithm. (Edit: Yes, I am aware that off-policy is typically defined as training on data that doesn't come from the policy. Stay tuned for a follow-up on why this distinction is largely irrelevant and misleading)

Researchers made a big deal about on-policy vs. off-policy in the mid-late 2010s. It really doesn't matter that much. There have even been theoretical results showing some equivalences. Kind of expected. On-policy maps observations to actions but usually also predicts a value function. Off-policy predicts a sort of action-conditioned value function. The big difference is that off-policy algorithms are almost always trained with some sort of experience replay, meaning that the algorithm collects and samples training data from a big buffer. In contrast, on-policy methods usually use data as soon as it is collected... but the batch sizes can get pretty huge, so again, the differences are exaggerated.

Model based: is poorly named. In this context, "model" refers to the environment. Your agent is trained to directly predict future observations. You can use this as an auxiliary loss or even use the learned world model to simulate new training data. Model-based training is intuitively appealing and has shown some impressive results, but some of the recent lit is a bit dodgy. Most of RL is model free. I suggest the original World Models paper by David Ha & Schmidhuber.

Offline RL: is not RL. It's supervised learning on a fixed set of observations, actions, and rewards usually collected from humans or by an expert policy. This is similar to imitation learning or behavioral cloning, but with the addition of a reward signal. Either way, it is missing the key element of learning through interaction, since the policy does not have any control over its data collection.

Multiagent RL: Is the same as single-agent RL except that some of the environments and tools are jank. The most common approach is to use the same policy for all agents, applied independently. This is as if you had N single-agent environments instead of one N-agent environment. See? No different from single-agent. You can also compute actions jointly just by concatenating all the observations for a single environment together. Sometimes researchers come up with separate algorithm names to describe these techniques, like IPPO and MAPPO... but this is really all there is to it. There are also some dedicated multiagent algorithms, but having worked extensively in multiagent RL, these are pretty mixed.

## Perspective

Learn which areas of research to pay attention to and which you can ignore. The large-scale industry papers are great for developing this intuition. If I had to pick just one, it's OpenAI Five. PPO with simple historical self-play solves DoTA. There's a lot more in that paper, too. The core architecture is a 1-layer 4096 dim LSTM. The other papers are Alphastar, Learning Dexterity, Emergent Tool Use, and Capture the Flag in roughly that order. Don't forget about the whole AlphaGo line from DeepMind!

So why is this relevant? There's some important missing context here... RL is very sensitive to hyperparameters, and many of the common benchmarks are slow. Couple this with starving academic budgets and you inevitably get a lot of bad science. Algorithm A does 20% better than algorithm B, but hyperparameters alone make a difference of 3x. So why even bother developing fancy new algorithms if you can't test them properly? Well, that's how you get published. And a lot of the people developing faster envs were treated so badly by academia that they took their ball and went home (hint, that's why I just write blogs now!).

So how do you know what lines of work are promising? Look for papers with comprehensive experiments and ablations. Especially the ones that do this on one core idea. I particularly like the OpenAI blog post how AI training scales and the paper scaling laws for single-agent reinforcement learning. Personally, I think the most promising thing right now is to just rerun old work with more experiments on faster environments. We're developing tons of these at Puffer, so you can run hundreds of experiments per GPU per day. If that sounds boring, learn to be excited by the result rather than the method. The goal is to understand, and science is just one tool for doing so.

I also avoid work that advances research now at the price of making it slower in the future. Anything introducing slow environments or expensive training had better have a very good reason for it. On the contrary, anything that improves the pace of research is shortlisted. DreamerV3 caught my eye because it worked with one set of hyperparameters... but that was before blowing 10,000 A100 hours on ablation studies. You won't always be right!

When I'm assessing a new area of work, I always look for wrong fundamental assumptions. For example, a lot of work in curiosity or exploration don't reasonably define those terms. Several papers in this area abuse human intuition to propose environments that look easy, but are actually hard or impossible to learn tabula-rasa, or from a blank slate. That doesn't mean I won't consider any of the ideas from these papers... but I'm going to assume that the results don't generalize until a mountain of evidence proves otherwise.

## Things I use a lot

PPO: This is my go-to algorithm. It's simple and solved DoTA. Actually, it's simpler than most people appreciate. The way to think about PPO is vanilla policy gradients + GAE. That's just fancy exponential reward discounting with a value function baseline. Then, it adds policy clipping. This just means each weight can't change too much on any single update. Clipping lets PPO use the same batch of observations for multiple gradient updates. But if your environment is really fast, there's not much reason to do that, since new data is free. So it's just a simple and effective sample efficiency hack. Read Costa's 37 PPO details blog if you really want to understand the algorithm.

Hyperparameter Intuition: I'll cover these for PPO, but several are common across many algorithms. Learning rate, gamma, and lambda are the most important. You always sweep learning rate. Gamma and lambda are GAE parameters that relate to the effective horizon of your task. I like to think about the effective horizon of my task. For instance, in Pong, you don't need to look ahead more than a couple of seconds. If the framerate is 15, then there are 30 frames in 2 seconds, so I might try 1 - 1/30 = 0.97 as a starting point. Lambda is usually set a bit below gamma, so I would try 0.95. This should at least give you a decent starting point for an automated sweep. I leave clipping parameters at 0.1 or 0.2. Tuning these lower will cause aggressive "on rails" runs that learn well for a while before diverging. Batch size, minibatch size, and number of environments should be set based on hardware. For my fast environments with small networks, batch size 4096 is hardware efficient, so I use 4096 environments. Then I multiply by 128 to get the batch size. The reason for this is to allow GAE to compute discounted returns over 128-length trajectory segments. Decrease this if your environment has very short horizons or increase it for longer ones. I set minibatch size to be a quarter of batch size by default, but I also set this one based on GPU memory. Update epochs is 1 for fast environments or 3-4 for slow environments. You can go higher, but then you have to also worry about KL targets.

CARBS: A really good hyperparameter tuning algorithm from ImbueAI. We have bindings in PufferLib, and it is way better than standard random or bayes. We're still learning how best to configure this, but even if you do it wrong, it's still usually pretty good. Don't sweep clip coefficients like I mentioned above, otherwise you get some pretty nutty runs.

Common Architectures: I use an LSTM by default because it's fast and PufferLib makes adding one trivial. This replaces the main hidden layer, so networks can be as simple as fc-relu-lstm-fc-atn/val with 128-512 hidden dim. For 2d data, I will usually use a stack of 2-3 convolution layers with relus as an encoder. Avoid redundant fully connected layers when combining data from multiple sources, such as flat and 2d data. Deeper networks are not always better in RL, and they can sometimes be much harder to train. Also, know that RL tends to be more data hungry than other areas of AI, so you are often better off running more samples on a smaller network. That presumes your problem has a fast simulator. Feel free to experiment more here if you don't. The resnet architecture from the Impala paper is a decent slower one.

Normalize your data: Observations should be divided into discrete and continuous. One-hot or embed discrete data. Divide continuous data by its maximum value per channel. Do not do this using mean stats. Just say "max health is 100 so I will divide by 100" etc. Do the same for rewards.

Designing Rewards: These days, I just pick 3-5 things in the environment that are relevant to performance. For my MOBA, I did agent dying, getting xp, and taking a tower. I come up with rough guesses of the coefficients in the range of -5 to 5 (-0.5 to 0.5 for more common rewards). Then, I add the reward components to a hyperparameter sweep and tune them automatically. Be careful with continuous rewards. If you want an agent to go to a target, 1 for getting closer and -1 for getting farther is way better than just negative distance to target. The reason is that if the agent gets 0.01 closer, it might have a reward of -0.95 one step and -0.94 the next. Not much of a magnitude change to differentiate.

Whitebox software: Try not to over-modularize RL. CleanRL provides single-file training implementations, and if you talk to any researchers, you'll quickly find that it's the best thing since sliced bread. Anything and everything can go wrong in RL, and you don't want to be digging through several layers of abstraction searching for the issue. I can't tell you how many times I've seen environments break because someone forgot they were using some wrapper that no longer made sense. Or just an environment was passing data in a weird way. Seriously, just keep it simple. A high level API isn't going to save you. Assume anything you build will break, and you or someone else will have to read the source for it.

General engineering: Lots of AI researchers work out of notebooks. That doesn't fly in RL. In addition to the whole normal ML stack, RL requires you to deal with high-performance distributed simulation. The biggest innovations in PufferLib required me to get my hands dirty with asynchronous multiprocessing. Once that was done, I was able to 100x the standard training speed by writing envs from scratch in C. If you're coming from high level dev, it's much easier than you'd think. I wrote Python for 10 years. Within just a few weeks, I was as productive in C as in Python, and now I'm actually more productive. How is that possible? Well, I don't have to think about fancy performance optimization tricks. I just write the braindead loops and it's fast, done. You wouldn't believe some of the hoops I had to jump through during my PhD to get Neural MMO to run fast enough in Python.

Write better code: This one is more personal, but I'm irrationally obsessive about code quality. In order to get better, bad code has to cause you severe mental distress. I've gone through several phases here, some of which involved me writing a lot of bad code. One thing I want to emphasize: good engineers don't use every design pattern in the book. If you learned Java, unlearn it. No abstraction is zero-cost, and first year CS students should be able to read almost all of your code. I've hit a kind of zen state where dev is pretty easy, and I'd like to think I make it easier for new contributors too.

## Contribute to PufferLib

I'm not here to sell you courses. I wrote this mostly so new contributors would have a place to start. Many came in with zero RL experience. I spend a lot of time going through PRs and helping fill in knowledge gaps on stream or in voice chat. This all happens through the Discord. Folks usually start off by contributing to environments and then move into the science side as they get more comfortable. Major contributors even get hardware access for running experiments!

# PufferLib 1.0: Now Stable

Our first stable release. This update doesn't have any fancy new features, but it fixes a ton of common pain points. Here's 30 minutes of fast and simple reinforcement learning demos. As of this update, we now offer priority service packages for companies.

# The Puffer Stack

Thank you for 325 stars on PufferLib! As promised, this is a complete teardown of our stack including hardware, containerization, dependency management, and more.
8 RTX 4090s, 1 Titan V, 200 cores, and 1056 GB of RAM
## Hardware

We have 8 Maingear desktops (we call them puffer boxes) with one 24GB RTX 4090 each. The CPUs each have 24 cores. One has an i9 13900k. Five have i9 14900k’s. Two have i9 14900ks’s. Each machine has 128 GB DDR4 RAM. There is also a login/testing machine with a Titan V, 32GB of RAM, and an 8-core i7 9700k. The main machines retail around $4000 each. The 4090s are overkill for most jobs, but we wanted to have the option to scale up models and experiment with new architectures.

All machines are connected to gigabit ethernet. Power is supplied with a standard 20-amp outlet per 2 machines. Machines sit on a utility rack that is grated to allow air intake from below. Exhaust is backwards, towards the wall, which has about 2 feet of free space. A small industrial fan is angled so as to push hot air away from the back wall. The room is maintained at 80F.

Issues & Gotchas: We have had some stability issues that I am 95% certain are caused by faulty 14th gen intel chips. The motherboards are running Intel’s suggested power settings, but a couple of the machines still get occasional crashes. Unrelatedly, the chip architecture is 8 p-cores and 16 e-cores. To get good performance out of these chips, asynchronous environment sampling is a must. We also discovered that these machines would not boot properly from a hard reset when not connected to a monitor. We bought some dummy HDMI plugs to trick the machines into booting headless.

## Installation & Containerization

Machines are installed with a minimal build of Debian 12. The PufferTank repository on Github contains our setup script. For now, this is done manually on each machine. It installs NVIDIA drivers, utilities like git and vim, docker, and Tailscale. We rely on Tailscale for credentialing users and general administration. There is no Slurm, shared file system, or other such layers. Users are assigned one or multiple machines to use for development and experiments.

Each machine contains a build of PufferTank. Images for PufferTank are available from pufferai on docker hub or through the PufferTank github repository. PufferTank is a 3-stage docker build. There is a base layer that installs (currently) Pytorch 3.4 and Python 3.11, as well as basic utilities. A second layer installs dependencies for tricky RL environments like Nethack and DM Lab. The final layer is a quick build that clones PufferLib, sets a few environment flags, adds a bit of configuration to bash, and also installs Neovim. The idea is that the first layer doesn’t change often, the second layer changes whenever we add new envs, and the third layer is rebuilt quite often.

Puffer hardware users are booted into PufferTank on login. They can also spin up their own container in seconds, in cases where a fresh install is needed or a machine is being shared.

## PufferLib dependency management

PufferLib provides a pip package with a long list of optionals, one per environment. There is a common extra that will install all of the environments (or at least the ones that play nice together). This is the default in PufferTank. We set sane default versions of Gym/Gymnasium/PettingZoo for maximum compatibility. Some extras outside of common may override these. PufferLib provides short bindings for each environment, but no registry. We wrap environments in PufferLib’s emulation layer for compatibility, which is a 1-line change. For Gym environments, we apply a Gymnasium compatibility layer. For old PettingZoo environments still based on the Gym API, we apply a similar compatibility layer. For most environments, we apply an episode postprocessing wrapper that cuts down on data transfer during multiprocessing. Some environments have additional wrappers to make them render nicely or fix various quirks. But in general, we keep the stack as thin and as simple as possible. We considered folding the postprocessing wrapper into the vectorization module for this purpose, but enough envs return nonstandard data that this is not worth doing at the present.

## Summary

This is a very simple cluster, but we get a lot of mileage out of it. Most folks don’t realize how fast high-end desktop processors are compared to 10x more expensive server CPUs. One puffer box was 3x faster than the CPU in an 8x A100 server we previously had access to. With discounts, an 8x A100 box is still going to be $100k+. Our entire setup is around $35k. This was a lot of money for me to spend, but it is currently powering 4 different RL projects. And with the prices outside something like Vast, the buy price is only 2-4 months of rental pricing.

One of the worst things you can do is to adopt heavy tools and then use them wrong. No shared file system, Slurm, etc. means less stuff to manage and less stuff in onboarding. We can get new users onto a machine with their own dev environment that exactly matches their local one in 5 minutes.

# PufferLib 0.7: Puffing Up Performance with Shared Memory

This update doubles training throughput for most environments with no tradeoffs. We have tested Pokemon Red training at over 6000 steps/second on a single desktop, up from around 3000. CleanRL trains Atari 65% faster just by switching to PufferLib's vectorization, without even enabling our extra async features. The approach is a combination of shared memory, PyTorch code optimizations, dependency upgrades, and model compilation.

## Sharing Memory with Vectorized Environments

In PufferLib 0.5, we discovered that the standard Python multiprocessing Queue implementation is 3-10x slower than using Pipes and replaced it accordingly. In this update, we discovered that sending environment data through multiprocessing.Array instead of through Pipe yields an additional ~20% performance improvement. This is the exact code we use:

shared_mem = [ Array('d', agents_per_worker*(3+observation_size)) for _ in range(num_workers) ]

Each array has enough memory for all of the observations, rewards, terminals, and truncation signals from the environments on one worker. Only the actions and infos are still communicated via pipes. Since infos can store arbitrary data and are the simplest way to aggregate logs from the environment, we have left this as is. The multiprocessing.Array is also shared with a Numpy array, making it simple to update:

def _unpack_shared_mem(shared_mem, n): np_buf = np.frombuffer(shared_mem.get_obj(), dtype=float) obs_arr = np_buf[:-3*n] rewards_arr = np_buf[-3*n:-2*n] terminals_arr = np_buf[-2*n:-n] truncated_arr = np_buf[-n:] return obs_arr, rewards_arr, terminals_arr, truncated_arr

This function is called only once per worker at the start of training, and the data arrays can be updated in place to update the corresponding shared storage. These slices are views, meaning that they are fast to update without first having to aggregate all the data from a worker into a local array.

obs_arr[:] = obs.ravel() rewards_arr[:] = reward.ravel() terminals_arr[:] = done.ravel() truncated_arr[:] = truncated.ravel()

## PyTorch Indexing

Slow indexing is a `known issue `_ in PyTorch. PufferLib’s customized CleanRL PPO implementation has to do a lot of indexing because it uses an EnvPool-like interface that does synchronous policy updates but asynchronous environment simulation. After profiling, we found that indexing and subsequent copying were taking up 80% of inference and 50% of training. The fix for this was to just use Numpy. Calling np.asarray(tensor) creates a shared memory view in which updating the numpy array also updates the tensor, but it allows you to use 10x faster Numpy indexing to do it. It only works on CPU, but we were already offloading most of the rollout data to CPU anyway to enable large-batch training, and this only adds a few copies per epoch.

## Dependency Upgrades & torch.compile

We’ve updated PufferTank to Python 3.11 and PyTorch 2.1 with Cuda 12.1. This enables us to use torch.compile, which you can enable in the demo with the —train.compile flag. This gave us another 20% model throughput in our testing. Python 3.11 also contains a number of performance improvements. The one issue is that 3.11 specifically breaks a few important environments. We’ve included a build of NetHack that works with 3.11, and Neural MMO will be updated soon. If you are having trouble with any specific environment, let us know on the Discord.

## Attribution

Thanks to ThatGuy in the Pokemon Red RL Discord for profiling and optimizing clean_pufferl and Bet Adsorption for assistance

Thanks to Aleksei Petrenko, the creator of Sample Factory, for useful discussions and pointers to optimizations in the Sample Factory code base. Aleksei also has a useful pip package, faster-fifo, that fixes the horrible performance of Python’s native multiprocessing.Queue. It’s much simpler than raw Pipes and nearly as fast.

# PufferLib 0.6: 🐡🌊 An Ocean of Environments for Learning Pufferfish

Ocean is a small suite of environments that train from scratch in 30 seconds and render in a terminal. Each environment is a sanity check for a common implementation bug. Use Ocean as a quick verification test whenever you make small code changes.
Ocean test environments
Memory: The agent is shown one binary token at a time and must recite them back after a pause. Do not make the sequence too long or you start testing credit assignment.

Stochasticity: The agent is rewarded for learning a particular nondeterministic action distribution. Do not use an architecture with memory or the agent can solve the task without stochasticity.

Exploration: The agent is rewarded for guessing a specific binary sequence. Do not tune your entropy coefficients higher than you would use in your actual environments, since that is the point of the test.

Bandit: The agent is rewarded for solving a multiarmed bandit problem. This environment is included for historical importance. Any reasonable implementation should solve the default setting.

Squared: The agent is rewarded for moving to targets that spawn around the edges of a square. There are settings to test memory, exploration, and stochasticity separately or jointly to help you prod at deeper issues with your implementation.

This project is heavily inspired by BSuite, a DeepMind project with similar if more benchmarky goals. BSuite was a bit too heavy for my liking and didn’t fit the niche of a quick and portable verification suite.

I had a few issues designing these. The memory task is apparently a standard RNN copying task (I would be surprised if it weren’t). But it’s a bit different in an RL context because you still have to learn credit assignment. I don’t think there is a way to fully isolate learning only memory outside of a simple 1-step problem. Try increasing the memory sequence length or delay and you will quickly find that the problem gets harder to learn.

The exploration environment is the only one that just worked. You can increase the password length and the problem gets harder to learn at about the rate you would expect. It’s just a guess and check, so once you happen to get the password right once, the goal is to learn from that single instance as much as possible. Any prioritized replay would trivialize the problem.

The stochastic environment took the longest. Initially, I was looking for one where the optimal policy was still stochastic and nontrivial even if the agent had memory. I could not figure out how to make one of these, and Twitter seems to think it’s impossible. They’re probably right, though you might be able to alter the setup conditions a bit, still test for the same thing, and have something that works better. For now, this is a quick and consistent test.

I wrote the bandit environment earlier in the project, and it seems kind of useful, so I left it in the release. Probably a good idea to have at least some version of a problem this historically important easily accessible in PufferLib.

I wrote Squared over the summer. I’m rather fond of it as a test environment, since it is fairly scalable. You spawn at the center of a square and targets spawn around the outside. You get a reward the first time you hit each target and are teleported to the center whenever you hit a target. This means that the optimal policy is stochastic: you place equal probability on moving towards each target and then deterministically move towards the target you have selected. It’s interesting because the optimal policy is stochastic in some states and deterministic in others. You can also turn the problem into a memory test by using a recurrent network. In any event, it’s similar to the bandit problem in that it combines elements of the simpler tests, but it’s a bit more tunable and interpretable.

Let me know if you have other ideas for useful test environments. Lately, I’ve landed on either very simple or very complex environments as being the most useful for research. Many of the tasks in the middle (looking at you Atari) are too slow to be useful as quick tests and too simple to test interesting ideas.

# PufferLib 0.5: A Bigger EnvPool for Growing Puffers

This is what reinforcement learning does to your CPU utilization:
You wouldn’t pack a box this way, right?
With PufferLib 0.5, we are releasing a Python implementation of EnvPool to solve this problem. TL;DR: ~20% performance improvement across most workloads, up to 2x for complex environments, and native multiagent support.

If you just want the enhancements, you can pip install -U pufferlib. But if you’d like to see a bit behind the curtain, read on!

## The Simulation Crisis

You want to do some RL research, so you install Atari. Say it runs at 1000 steps/second on 1 core and 5000 steps/second on 6 cores. Now, you decide you want to work on a more interesting environment and happen upon Neural MMO, a brilliant project that must have been developed by a truly fantastic team. It runs at 1500 steps/second – faster than Atari! So you scale it up to 6 cores and it runs at … 1800 steps per second. What gives?

The problem is that environments simulated on different cores do not run at the same speed. Even if they did, many modern CPUs have cores that run at different speeds. Parallelization overhead is mostly the sum of:

- Launching/synchronization overhead. This is roughly 0.1 ms per process and is linear in the number of processes. At ~100 steps per second, you can ignore it. At >10,000 steps/second, it is the main limiting factor.

- Environment variance. This is defined by the ratio mu/std of the environment simulation time and scales with the square root of the number of processes. For 24 processes, 10% std is 20% overhead and 100% std is 300% overhead.

- Different core speeds. Many modern CPUs, especially Intel desktop series processors, feature additional cores that are ~20% slower than the main cores.

- Model latency. This is the time taken to transfer observations to GPU, run the model, and transfer actions to CPU. It is not technically part of multiprocesssing overhead, but naive implementations will leave CPUs idle during model inference.

As a rule of thumb, simple RL environments have < 10% variance because the code is always simulating roughly the same thing. Complex environments, especially ones with variable numbers of agents, can have > 100% variance because different code runs depending on the current state. On the other hand, if your environment has 100 agents, you are effectively running 100x fewer simulations for the same data, so launching/synchronization overhead is lower.

## The Solution

Run multiple environments per process if you have > ~2000 sps environment with variance < ~10%. This will reduce the impact of launching/synchronization overhead and also reduces variance because you are summing over samples. In PufferLib, we typically enable this only for environments > ~5000 sps because of interactions with the optimizations below.

Simulate multiple buffers of environments so that one buffer is running while your model is processing observations from the other. This technique was introduced by https://github.com/alex-petrenko/sample-factory and does not speed up simulation, but it allows you to interleave simulations from two sets of environments. It’s a good trick, but it is superseded by the final optimization, which is faster and simpler.

Run a pool of environments and sample from the first ones to finish stepping. For example, if you want a batch of 24 observations, you might run 64 environments. At each step, the 24 for which you have computed actions are going to take a while to simulate, but you can still select the fastest 24 from the other 64-24=40 environments. This technique was introduced by https://github.com/sail-sg/envpool and is massively effective, but the original implementation is only for specific C/C++ environments. PufferLib’s implementation is in Python, so it is slower, but it works for arbitrary Python environments and includes native multiagent support.

## Experiments

To evaluate the performance of different backends, I am using a 13900k (24 cores) on a max specced Maingear desktop running a minimal Debian 12 install. We test 9 different simulated environments: 1e-2 to 1-4 mean delay with 0-100% delay std. For each environment, we spawn 1, 6, 24, 96, and 192 processes for each backend tested (Gymnasium’s and Pufferlib’s serial and multiprocessing implementations + Pufferlib’s pool). We also have Ray implementations compatible with our pooling code, but that will be a separate post. Additionally, PufferLib implementations sweep over (1, 2, 4) environments per process and PufferLib pool will compute 24 observations at a time. We do not consider model latency, which can yield another 2x relative performance for pooling on specific workloads.
Envpool in PufferLib 0.5
9 groups of bars, each for one environment. 5 groups of bars per environment, each for a specific number of processes. The serial Gymasium/PufferLib experiments match in all cases. The best PufferLib settings are 10-20% faster than the best Gymasium settings for all workloads and can be up to 2x faster for environments with a high standard deviation in important cases (for instance, you may not want to run 192 copies of heavy environments). Again, this is before even considering the time saved by interleaving with the model forward pass.

All of the implementations start to dip ~10% at 1,000 steps/second and ~50% at 10,000 steps/second. To make absolutely sure that this overhead is unavoidable, I reimplemented the entire pool architecture as minimally as possible, without any of the environment wrapper or data transfer overhead:

SPS: 10734.36 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 1 batch_size: 1 sync: False SPS: 11640.42 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 1 batch_size: 1 sync: True SPS: 32715.65 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 6 batch_size: 6 sync: False SPS: 27635.31 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 6 batch_size: 6 sync: True SPS: 22681.48 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 24 batch_size: 6 sync: False SPS: 26183.73 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 24 batch_size: 24 sync: False SPS: 30120.75 envs_per_worker: 1 delay_mean: 0 delay_std: 0 num_workers: 24 batch_size: 6 sync: True

As it turns out, Python’s multiprocessing caps around 10,000 steps per second per worker. There is still room for improvement by running more environments per process, but at this speed, small optimizations to the data processing code start to matter much more.

## Technical Details and Gotchas

PufferLib’s vectorization library is extremely concise – around 800 lines for serial, multiprocessing, and ray backends with support for PufferLib’s Gymnasium and PettingZoo wrappers. Adding envpool only required changing around 100 lines of code but required a lot of performance testing:

- Don’t use multiprocessing.Queue. There’s no fast way to poll which processes are done. Instead, use multiprocessing.Pipe and poll with selectors. I have not seen noticeable overhead from this in any of my tests.

- Don’t use time.sleep(), as this will trigger context switching, or time.time(), as this will include time spent on other processes. Use time.process_time() if you want an equal slice per core or count to ~150M/second (time it on your machine) if you want a fixed amount of work.

The ray backend was extremely easy to implement thanks to ray.wait(). It is unfortunately too slow for most environments, but I wish standard multiprocessing used the Ray API, if not the architecture. The library itself has some cleanup issues that can cause crashes during heavy performance tests, which is why results are not included in this post.

There’s one other thing I want to mention for people looking at the code. I was doing some experimental procedural stuff testing different programming paradigms, so the actual class interfaces are in __init__. It’s pretty much equivalent to one subclass per backend.

# PufferLib 0.4: Ready to Take on Bigger Fish

## PufferLib 0.4: Ready to Take on Bigger Fish

PufferLib 0.4 is out now! Make your RL environments and libraries play nice with one-line wrappers, pain-free vectorization, and more.
Demo in Colab
New Features

- One-line wrappers for your Gym and PettingZoo environments

- Serial, Multiprocessing, and Ray vectorization backends

- PufferTank, a container preloaded with PufferLib and common environments

More importantly, we have rewritten the entire core for simplicity and extensibility. While this is not a flashy new feature, you will notice significantly fewer rough edges working with PufferLib. For example, your Gym environments are no longer converted to PettingZoo environment internally, and your discrete action spaces are no longer returned as MultiDiscrete: WYSIWYG.

## Emulation

Previously, PufferLib required you to wrap your environment class in a binding, which then provided creation and additional utilities. Now, you pass in a Gym/PettingZoo environment and get back a Gym/PettingZoo environment. All of the benefits described in our 0.2 blog post are included.

import pufferlib.emulation import nle, nmmo def nmmo_creator(): return pufferlib.emulation.PettingZooPufferEnv(env_creator=nmmo.Env) def nethack_creator(): return pufferlib.emulation.GymPufferEnv(env_creator=nle.env.NLE)

## Vectorization

Previously, PufferLib’s vectorization expected a binding object. Now, you pass it an environment creation function (as above) or a Gym/PettingZoo PufferEnv, if you prefer to subclass directly. Compared to 0.2 PufferLib includes Serial and Multiprocessing backends, in addition to Ray.

import pufferlib.vectorization import nmmo vec = pufferlib.vectorization.Multiprocessing # Or Serial or Ray envs = vec(nmmo_creator, num_workers=2, envs_per_worker=2) # Synchronous API obs = envs.reset() # Async API envs.async_reset() obs, _, _, _ = envs.recv()

## PufferTank

Many common RL environments are notoriously hard to set up and use. PufferTank provides containers with several such popular environments tested to work with PufferLib. These are preloaded onto base images so you can build the container over a coffee break.

## Policies

Previously, PufferLib required you to subclass a PyTorch base class for your models. Now, you can use vanilla PyTorch policies. We still provide a base class as an option, which allows you to use another of our wrappers to handle recurrence for you. Pass your model to our wrappers and we will convert to framework-specific APIs for you.

cleanrl_policy = pufferlib.frameworks.cleanrl.Policy(policy)

## Error Handling

Previously, PufferLib applied expensive runtime checks to all environments by default. These could be disabled by running with -O. This was inconvenient and easily forgotten. Now, these checks only run once at startup with negligible overhead. Thus far, we have observed no bugs with the new version that would have been caught by the previous checks.

## Miscellaneous

We have added sane default installations, setup, and policies for several more environments. Check our home page for an updated list.

The new environment and policy changes means that PufferLib no longer breaks serialization. This is useful for saving environment and model states.

We have written an optimized flatten and unflatten function for handling observation and actions. This was previously a bottleneck for environments with complex spaces. Expect a separate post on this, since it was an interesting case study for Python extension options.

We have an experimental custom CleanRL derivative to correctly handle environments with variable numbers of agents, without training on padding. Doing this simply has been a longstanding challenge in RL. More on this once it is more stable.

Join us on Discord and tell us your pain points. We might just fix them.

# PufferLib 0.2: Ready to Take on the Big Fish

PufferLib's goal is to make reinforcement learning on complex game environments as simple as it is on Atari. We released version 0.1 as a preliminary API with limited testing. Now, we're excited to announce version 0.2, which includes dozens of bug fixes, better testing, a streamlined API, and a working demo on CleanRL.

## Problem Statement

To understand the need for PufferLib, let's consider the difference between Atari and one of the most complex game environments out there: Neural MMO. Atari is deterministic, fully observable, and single-agent, with relatively short time horizons and simple observation and action spaces. In contrast, Neural MMO is nondeterministic, only partially observable, and features large and variable agent populations, with longer time horizons and hierarchical observation and action spaces.

Most RL frameworks are designed with Atari in mind, resulting in limited support for multiple agents, complex observation and action spaces, and a bias towards small models with fewer than 10 million parameters. This makes it challenging for researchers to tackle more complex environments and leads many to focus exclusively on Atari and other simple environments.

## CleanRL Demos

For our initial demo, we ran Neural MMO on CleanRL's single-file Proximal Policy Optimization (PPO) implementation designed for Atari by replacing only the vectorized environment creation code, without considering any of Neural MMO's complexities. For ease of experimentation, we have since wrapped CleanRL in a function and added additional logging. The latest version also includes double-buffering, an asynchronous environment simulation approach from the SampleFactory paper. To ensure the accuracy of our results, we maintain a public WandB profile with current baselines, including Atari results as a correctness check.

## PufferLib Emulation

The key idea behind PufferLib is emulation, or wrapping a complex environment to appear simple, thereby “emulating” an Atari-like game from the perspective of the reinforcement learning framework. This approach handles environment complexity in a wrapper layer instead of natively by the reinforcement learning framework, allowing us to use simple reinforcement learning code with an internally complex environment.

We will use Neural MMO as a running example here. Neural MMO has hierarchical observation and action spaces, while most reinforcement learning frameworks expect fixed size vectors or tensors. PufferLib flattens observations and action spaces to conform to this expectation, without losing any structural information: both observations and actions are unflattened right before they are required. Reinforcement learning frameworks also expect vectorized environments to have a constant number of agents. PufferLib pads Neural MMO’s variable population to a fixed number of agents and also ensures they appear in the same sorted order. Finally, PufferLib also handles some subtleties in multiagent environment termination signals that are a common source of bugs. PufferLib works with single-agent environments, too!

Creating a PufferLib binding for a new environment is straightforward - simply provide the environment class and name in the pufferlib.emulation.Binding() function. Here's an example binding for Neural MMO:

pufferlib.emulation.Binding( env_cls=nmmo.Env, env_name='Neural MMO', )

The Binding class also accepts optional arguments to disable certain emulation features if they're not needed. Additional features include hooks for observation featurization and reward shaping, as well as the ability to suppress output and errors from the environment to avoid excessive logging.

## PufferLib Vectorization

Most reinforcement learning libraries, including CleanRL, require vectorized environments that stack observation tensors across environments and split stacked actions across all environments. While a few options technically support multiagent environments, they are prone to difficult and finicky errors that are costly to debug. PufferLib takes a different approach by providing a wrapper with native support for multiagent environments. You can specify the number of CPU cores and the number of environments per core.

To use PufferLib's vectorization, create a VecEnvs object by passing in a binding and the number of workers and environments per worker:>

pufferlib.vectorization.RayVecEnv( binding, num_workers=num_cores, envs_per_worker=envs_per_worker )

All other popular vectorization implementations are based on native multiprocessing. This works well for bug-free environments that adhere perfectly to the Gym API but quickly becomes cumbersome outside of this ideal setting. Multiprocessing does not scale natively beyond a single machine, eats stack traces from the environments, and does not allow direct access to remote environments outside of the multiprocessed functions. PufferLib's vectorization is backed by Ray, which scales natively to multiple machines, provides correct stack traces, and allows arbitrary access to individual remote environments. At the same time, it is shorter and simpler than any multiprocessed implementation. This vectorization approach makes it easy to reset environments with new maps, convey task specifications, or receive logging information that is not suitable for the infos field. We will cover this in a subsequent post with more detail.

The one major downside to using Ray as a backend is that it is not particularly fast. Ray itself caps at a few hundred to a few thousand remote calls per second. Currently, this is the price that has to be paid for simplicity and generality. Using larger batch sizes that require many simulated environments per core and employing async techniques like double-buffering can help mitigate this issue. Ultimately, as RL continues to scale up, the problem will solve itself as models become the bottleneck.

## Next Steps

This release represents only a small part of what RL could be with better tooling. Here are some of our plans for future development:

Emulation features: We plan to add native support for team-based environments and better passthrough support for accessing any environment-specific features outside of Gym/PettingZoo. There is also room for performance optimization in this area.

Algorithmic features: We aim to provide PufferLib-compatible modules for commonly used methods in complex environments research, such as historical self-play, multiplayer skill-rating, and curriculum learning.

More integrations: In our initial release, we included both RLlib and CleanRL support. While we still provide an RLlib binding, we have focused on CleanRL as a faster testing mechanism in the early stages of development. However, PufferLib is designed to be easy to integrate with new learning libraries, and we plan to provide baselines for these as well.

Versioning Compatibility: The rapid progress of Gym/Gymnasium has created compatibility conflicts between specific environments, gym versions, and learning library dependencies. We are still on an old version of Gym from before all of this happened and are slowly increasing test coverage and compatibility with new versions.

Blog post by Joseph Suarez. Thank you to Ryan Sullivan for feedback and suggestions. Join our Discord if you are interested in contributing to PufferLib!


<!-- ===== rl-sim-labs/raw/puffer-ai-docs.md ===== -->

---
source_url: https://puffer.ai/docs.html
ingested: 2026-06-18
sha256: 315e81b01d99927203c77a04becce6da951a8abe98459e611b20eaafb41a638f
---

PufferLib Docs
PufferLib is a fast and sane reinforcement learning library. Our key features are:

- PuffeRL: 20,000,000 step/second training in only ~5k lines of CUDA. Torch version up to 5,000,000.

- Ocean: 20+ environments from simple arcade games to massively multiagent sims

- Constellation: Performant experiment local + web visualization toolkit in C

- Protein: Our algorithm for automatic hyperparameter and reward tuning

These docs will get you started. Join the Discord to get help and report bugs. If you're new to RL, building and contributing a new env is the best way to learn, and we review PRs live.

# Installation

## Docker

git clone https://github.com/pufferai/puffertank cd puffertank ./docker.sh test
PufferLib uses CUDA, cuBLAS, NCCL, and Nsight. If that sounds annoying to set up, use our Docker. Use ssh -X on setup for remote work or graphics won't work. Need a different CUDA base or system packages? The Dockerfile is really simple. Edit it and run ./docker.sh build -d puffertank.dockerfile
## UV

curl https://raw.githubusercontent.com/PufferAI/PufferTank/refs/heads/4.0/install.sh | sh
Requires CUDA. If you don't want to deal with CUDA deps, use the Dockerfile.
## Installation Test

bash build.sh breakout puffer train breakout puffer eval breakout --load-model-path latest
Trains a policy. 3-5 seconds on an RTX 5090. Eval requires a graphical interface. Works over ssh -X. Docker over ssh requires -X when you first run the container. Running without -X and reconnecting with -X will not work.
# Cheat Sheet

puffer [train|eval|sweep] env_name [OPTIONS] # PufferLib CLI, available from package python -m pufferlib.pufferl [train|eval|sweep] env_name [OPTIONS] # Equivalent command from source # Building PufferLib bash build.sh ENV_NAME # Build training for a specific environment bash build.sh ENV_NAME --float # Use fp32 backend (default is bf16) bash build.sh ENV_NAME --profile # Build our profiling tools bash build.sh ENV_NAME --[local|fast|web] # Build debug/optimized/web env standalones, no training bash build.sh constellation --[local|fast|web] # Build Constellation experiment dashboard # Examples puffer train breakout --train.learning-rate 0.001 # Set other train params puffer train breakout --env.frameskip 3 # Set env params puffer train breakout --vec.num-threads 4 # Set vec params puffer train breakout --wandb --tag tag_name # Track with Weights and Biases puffer eval breakout # Render the env with a random agent puffer eval breakout --load-model-path path/model_file # Load a trained model puffer eval breakout --load-model-path latest # Load the latest model (ls -lt experiments | head) # Distributed training and Sweeps puffer sweep breakout # Run a hyperparameter sweep puffer sweep breakout --sweep.gpus N # Sweep with 6 GPUs puffer train nmmo3 --train.gpus N # Distributed training # Torch bash build.sh ENV_NAME --float # Torch is not stable in bf16 bash build.sh ENV_NAME --cpu # Mostly for Mac users. Expect under 200k sps. # Torch Distributed - you should really, really use our native backend if you are going to scale torchrun --standalone --nnodes=1 --nproc-per-node=6 -m pufferlib.pufferl train nmmo3 --slowly

# About PufferLib

The PufferLib 4.0 native backend is ~1500 lines of Python and ~5000 lines of CUDA C. A PyTorch backend is provided as an additional ~1000 lines of Python for quick prototyping and as a fallback. Fork the project and edit directly. There is no prebuilt package blackboxing functionality. Everything is written as simply and transparently as possible. If you're new to low-level dev, it's much easier than you think. Give the environment tutorial a try!

Memory Management: Tensors in PufferLib are just structs with a shape and a data pointer. Every tensor registers its size with an allocator at init time. After all tensors are registered, the allocator sums up the sizes and does a single allocation of continuous memory. There are separate allocators for weights, gradients, and activations. No tensors are created or reallocated afterwards. Static memory improves performance, simplifies cudagraph tracing, and cleans up profile timelines. Since weights and gradients are contiguous, we can apply updates to them in a single kernel without looping over tensors.

Tracing: Cudagraphs capture and replay GPU operations in order to reduce kernel launch overhead. At the start of each run, PufferLib runs a few warm up epochs on empty rollout buffers. It then separately traces both the rollout forward pass and the entire train minibatch + loss + policy update. We bloat memory a bit by tracing separate cudagraphs for each step during rollouts in order to avoid an extra data copy for intermediate graph buffers.

Vectorization: Environment instances are chunked into buffers, each of which is associated with a rollout worker on a separate CUDA stream. Within each buffer, environment execution is parallelized with OMP threading. Rollout workers are independent of each other but each process the same number of environment steps per epoch. Each buffer asynchronously queues data transfers to/from the GPU and uses pinned memory.

Kernels: The main consideration for performance is fusing small elementwise operations to reduce memory bandwidth. For most of our kernels, the efficiency of the compute load is secondary. The MinGRU kernels are load-bearing and have received more attention to performance. The learnable workload of MinGRU is a set of linear layers implemented as cuBLAS matmuls. None of our kernels include complex operations with tensor cores.

Algorithm: PufferLib implements a PPO-variant with improvements based on our own research. The main improvements are our use of Muon, a custom advantage function combining GAE and VTrace, and prioritized replay over trajectory segments collected from the current epoch using absolute advantage.
PufferNet: Our default model architecture combines MinGRU, an RNN that is parallelizable over the time dimension, with highway nets, a fancy residual that replaces expensive normalization layers. It's equal to or better than an LSTM on every environment we've tested and much faster.
Sweeps: The fundamental unit of compute in PufferLib is a hyperparameter sweep, not a single experiment. Protein is a tuning algorithm based on our own research. It combines Gaussian processes with a simple genetic algorithm over the Pareto-frontier defined by cost (experiment wall-clock time) and score. This is the main thing we haven't ported over to CUDA C yet.
# Tutorial: Writing Your Own Environment at Millions of SPS (steps/second)!

Ocean environments are written in C. It's very simple C. Like first 2 weeks of an intro systems course C. Follow this guide and then copy Squared (single-agent) or Target (multi-agent) to use as templates for your own environment. Both have detailed comments that walk you through the requirements. Find/replace the demo name with your environment name.

The .h file contains core environment logic. The .c file contains a standalone demo. Only the .h file is compiled when you run puffer build env_name . The standalone is compiled with puffer build env_name --local or --fast for the optimized build. Observations, actions, rewards, and terminals are each allocated as big chunks of memory that are contiguous across all (usually thousands) of environment instances.

Create a .ini file in the config/ directory with the settings for your environment. Copy the one for Squared or Target as a starting point. Your environment is now available for training just like any other Ocean environment:

puffer build env_name puffer train env_name

Use the --local compilation option for testing while writing your environment. It enables address sanitizer and will catch most indexing and overflow bugs. Here's a checklist of common bugs if your env is not training:

- Zero or incorrect observations/actions: Ensure you have defined your observation and action metadata (space/size/type) correctly in your binding.c. Note that observation buffers are not zeroed for you every step, so if you are only writing information to specific indicies (i.e. one-hots), be sure you are zeroing them. One memset is usually the quickest.

- NaN losses: If your losses NaN after 1 epoch, your environment almost certainly has data corruption. You are writing to memory that does not match the obs/action sizes you have defined, or you have defined them using the wrong types. If your losses NaN after a longer time, it may be hyperparameters.

- Incorrect or missing resets: Your environment should handle its own resets internally. For envs that never reset, it is often useful to respawn agents if they are stuck (e.g. no reward for 500 steps). If every rollout has the same number of timesteps, you should stagger your environments on init.

- Not zeroing observations: If you are writing over your observation buffers but only write to some elements each step, If you don't zero out rewards, they will retain their value from the previous step. Ditto for terminals. Zero them at the start of c_step to be safe. A single memset will do it for multiagent envs. If you are not setting every element of every obs (i.e. one-hots), make sure to clear those too.

- Manually inspect data scale: You want observations and rewards to be roughly in the range of -1 to 1. 0 to 1 is fine. -5 to 5 is kind of fine. Randomly having one obs with magnitude 1000 is not.

- Incorrect binding args: Ensure your binding sets the same args as your .c file. Call your init function if you have one.
# FAQ

Why is it called PufferLib? Would you have rathered yet another minimal tech logo? Here, have a pufferfish 🐡
I'm new to RL. How do I contribute? Start by building a simple new environment in C and getting it to train. I review environment PRs from new contributors live on stream.

How do I export screenshots/gifs? F12 for screenshots, control+F12 for gifs. This is built in to raylib.
Where did all the Python/third-party stuff go? It was all 100x+ slower than PufferLib is now. We do plan on hooking the C/C++ for Atari, NetHack, and maybe ProcGen into our low-level interface when we have time.


<!-- ===== rl-sim-labs/wiki/concepts/pufferlib-fast-environment-loop.md ===== -->

---
title: PufferLib Fast Environment Loop
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: rl-sim-labs
tags: [rl-sim-labs, reinforcement-learning, pufferlib, simulation, environment-design, hyperparameter-tuning]
sources:
  - https://puffer.ai/blog.html
  - https://puffer.ai/docs.html
  - raw/puffer-ai-blog.md
  - raw/puffer-ai-docs.md
confidence: medium
---

# PufferLib Fast Environment Loop

**PufferLib Fast Environment Loop** is the systems pattern behind PufferLib: make reinforcement-learning environments cheap to run, easy to inspect, and fast enough that training quality can be tested through many real rollouts and sweeps instead of a few slow, fragile runs.

For `rl-sim-labs`, the useful takeaway is not “use PufferLib because it is fast.” The reusable concept is: design the environment, memory layout, build path, training command, and evidence gates as one loop. A project such as [[../entities/critical-ranger-ffm|Critical Ranger FFM]] should earn belief through deterministic environment contracts, high-throughput simulation, paired baselines, and visible evaluation artifacts, not by treating a single trained policy as proof.

## What PufferLib contributes

PufferLib describes itself as a fast RL library with four main pieces:

- **PuffeRL** — a native CUDA-oriented training backend, with a Torch fallback for prototyping.
- **Ocean** — a set of first-party environments, including arcade-style games and massively multi-agent simulations.
- **Constellation** — local/web visualization for experiments.
- **Protein** — automatic hyperparameter and reward tuning.

The docs frame PufferLib as “fast and sane” RL. The blog’s repeated claim is that throughput changes the working loop: PufferLib 2.0 reported around 1M steps/second, PufferLib 3.0 reported up to 4M steps/second on a single RTX 5090, and the 4.0 docs describe native training at much higher throughput with a Torch backend as fallback. Treat the exact numbers as hardware/version-dependent, but the direction matters: faster rollouts make correctness bugs, reward shaping, and hyperparameter mistakes easier to expose.

## Systems-first environment design

PufferLib’s environment API pushes environment work toward simple C and explicit memory contracts:

- environment logic lives in a `.h` file, with a `.c` standalone demo path available for local/debug builds;
- observations, actions, rewards, and terminals are allocated as contiguous chunks across many environment instances;
- native environments simulate directly into shared-memory batches, avoiding redundant copies through Python;
- vectorization is part of the environment design, not an afterthought;
- build modes separate training builds from local/debug, fast, web, profile, and CPU/Torch paths.

For Jamie’s RL namespace, this means a custom sim should be treated like a small systems program before it is treated like an ML experiment. The first acceptance tests should prove observation/action metadata, reset semantics, reward scale, terminal handling, and deterministic indexing.

## Debugging posture for custom environments

The docs name several failure modes that map directly to future RL lab checks:

- zero or incorrect observations/actions usually mean bad binding metadata or uncleared buffers;
- NaN losses after one epoch usually suggest environment data corruption or mismatched observation/action sizes;
- missing reset logic can hide stuck agents or synchronized rollout artifacts;
- observations, rewards, and terminals must be explicitly cleared when only partially written;
- observation and reward magnitudes should stay roughly human-scale, with random huge values treated as suspect;
- binding arguments must match the standalone C path.

The practical rule: if the agent does not learn, first distrust the environment contract. Only after data layout, reset, reward, terminal, and scale checks pass should the team blame PPO, Protein, or hyperparameters.

## Training and tuning loop

The PufferLib docs expose a compact command loop:

```text
bash build.sh ENV_NAME
puffer train ENV_NAME
puffer eval ENV_NAME --load-model-path latest
puffer sweep ENV_NAME
```

The blog pushes the next layer: PufferLib treats sweeps as a first-class unit of work. Protein is presented as a simpler, more robust successor/variant around cost-vs-score search, intended to avoid brittle hyperparameter defaults and random low-cost sampling traps. The broader lesson for `rl-sim-labs` is to compare policies under repeatable run budgets and baselines, not to over-read one lucky seed.

## Algorithmic notes worth carrying forward

PufferLib’s newer PPO stack is not just “vanilla PPO faster.” The blog highlights:

- Muon replacing Adam in the trainer after sweeps showed a step-change on tested environments;
- cosine annealing as a more stable sweep target than linear annealing in their experiments;
- trajectory-segment filtering/prioritized replay based on segment-level advantage, especially relevant for sparse rewards;
- “Puffer Advantage,” a custom advantage function presented as a generalization connecting GAE and VTrace;
- MinGRU/highway-style default models as a faster recurrent alternative to LSTMs in their tested environments.

These are not defaults to cargo-cult. They are candidates to record when a lab result changes materially: optimizer, advantage function, replay/filtering behavior, recurrent architecture, reward sparsity, and sweep budget all belong in the experiment trace.

## Critical Ranger implications

For [[../entities/critical-ranger-ffm|Critical Ranger FFM]], this concept suggests a thin, evidence-first sequence:

1. Lock the zone-control action contract and deterministic indexing before any training claim.
2. Build CPU/local/debug fixtures first; do not use the DigitalOcean VPS for GPU training or native rendering.
3. When using Puffer locally, prefer small build/train/eval smoke tests before broad reward changes.
4. Treat sparse-reward behavior as a first-class design risk; trajectory-level filtering or tuning only matters after the environment signal is trustworthy.
5. Report paired baselines, run budgets, seeds, and evaluation curves; do not equate “policy trained” with “policy works.”
6. Cross-link final claims to [[../../../eval-trace/README|eval-trace]] style evidence gates when results leave prototype mode.

## Related pages

- [[../entities/critical-ranger-ffm|Critical Ranger FFM]]
- [[../../../eval-trace/README|Eval Trace]]
- [[../../../local-ai-infrastructure/README|Local AI Infrastructure]]


<!-- ===== rl-sim-labs/wiki/entities/critical-ranger-ffm.md ===== -->

---
title: Critical Ranger FFM
created: 2026-06-16
updated: 2026-06-16
type: entity
status: compiled
namespace: rl-sim-labs
tags: [rl-sim-labs, reinforcement-learning, pufferlib, zone-control, simulation]
sources:
  - Projects/Critical Ranger FFM/Index.md
confidence: high
---

# Critical Ranger FFM

**Critical Ranger FFM** is the first concrete project under the `rl-sim-labs` namespace. It is a toy forest-fire / PufferLib reinforcement-learning experiment focused on zone-control policies, not a standalone namespace yet.

## Current role in this namespace

Critical Ranger is the seed RL simulation lab:

- environment: forest-fire simulation with self-organized dynamics;
- action model: no-op or thin one selected zone at a decision tick;
- evaluation target: reduce mega-fire frequency versus honest simple baselines;
- constraints: preserve acceptable tree density and stay within intervention budget;
- evidence posture: metrics and anti-cheat gates decide belief, not training reward alone.

## Active roadmap

The active path is the **Zone-Control RL MVP**. The prior switch-point / single-cell efficacy path is parked as diagnostic infrastructure.

Current next implementation gate from the source note:

```text
#54 — zone-control action contract fixtures
```

That slice is intentionally narrow: deterministic zone indexing, no-op action, one-zone thinning contract, decision interval semantics, and CPU-safe fixture tests.

## Promotion boundary

Do not promote Critical Ranger to its own namespace yet. It should remain an entity/project inside `rl-sim-labs` until it has an independent audience, raw experiment corpus, recurring reports, multiple durable document types, and a clear covers/not-covered boundary.

## Source

Compiled from `Projects/Critical Ranger FFM/Index.md`.


<!-- ===== rl-sim-labs/wiki/index.md ===== -->

---
title: RL Sim Labs — Master Index
created: 2026-06-16
updated: 2026-06-18
type: index
status: active
namespace: rl-sim-labs
---

# RL Sim Labs — Master Index

> Content index for `rl-sim-labs`. Add compiled pages here as they are created.

## Concepts

- [[concepts/pufferlib-fast-environment-loop|PufferLib Fast Environment Loop]] — Systems-first pattern for fast PufferLib environment authoring, training, sweeps, and evidence gates.

<!-- Add compiled concepts alphabetically. -->

## Entities

- [[entities/critical-ranger-ffm|Critical Ranger FFM]] — Zone-control RL forest-fire experiment; entity under RL Sim Labs until it earns standalone namespace promotion.

## Summaries

<!-- Add compiled summaries alphabetically. -->

## Syntheses

<!-- Add compiled syntheses alphabetically. -->

## Source Roots

- `Projects/Critical Ranger FFM/Index.md`


<!-- ===== rl-sim-labs/wiki/log.md ===== -->

---
title: RL Sim Labs — Activity Log
created: 2026-06-16
updated: 2026-06-18
type: log
status: scaffold
namespace: rl-sim-labs
---

# RL Sim Labs — Activity Log

> Append-only namespace log.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add Critical Ranger compiled entity

- Added `wiki/entities/critical-ranger-ffm.md` under `rl-sim-labs`.
- Kept Critical Ranger as a project/entity, not a standalone namespace.
- Updated `wiki/index.md` from scaffold to active content index.
- No Daily Notes were copied or compiled.

## 2026-06-18 ingest | Add PufferLib fast environment loop concept

- Ingested `https://puffer.ai/blog.html` into `raw/puffer-ai-blog.md`.
- Ingested `https://puffer.ai/docs.html` into `raw/puffer-ai-docs.md`.
- Added `wiki/concepts/pufferlib-fast-environment-loop.md`.
- Updated `wiki/index.md` with the new compiled concept.
- Kept scope inside `rl-sim-labs`; no Daily Notes were copied or compiled.


<!-- ===== curated-tuning-datasets/CLAUDE.md ===== -->

# Curated Tuning Datasets Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/curated-tuning-datasets/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to dataset/source curation for LoRA/fine-tuning, provenance, scraping/source inventories, corpus readiness, recipe publication, and LKY Brain as an example. Route training runtime to `local-ai-infrastructure` and evaluation method to `eval-trace`.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== curated-tuning-datasets/README.md ===== -->

---
title: Curated Tuning Datasets
created: 2026-06-16
updated: 2026-07-10
type: namespace-overview
status: active
category: data-curation
namespace: curated-tuning-datasets
confidence: high
---

# Curated Tuning Datasets

> Active namespace for provenance-aware corpus curation, dataset recipes, and readiness boundaries.

## Scope

### Covers

Dataset/source curation for LoRA/fine-tuning, provenance, scraping/source inventories, corpus readiness, dataset-recipe publication, and LKY Brain as a completed example.

### Not Covered

Training methods themselves except where they impose dataset-readiness requirements; copyright-risk decisions without provenance evidence.

### Current As

2026-07-10 — active. LKY Brain now covers the verified NAS manifest, local hydrated corpus, public recipe, adapter, and evaluation-readiness boundaries.

## Canonical Source Roots

- `Projects/LKY Archive/Index.md`
- `Projects/LKY Archive/Source Inventory.md`
- `Knowledge/concepts/corpus-to-chat-transformation.md`
- `Knowledge/concepts/dataset-recipe-publication.md`

## Crosslinks

- [[../local-ai-infrastructure/README|local-ai-infrastructure]]
- [[../eval-trace/README|eval-trace]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/curated-tuning-datasets/README.md
/raw/curated-tuning-datasets/wiki/index.md
/wiki/curated-tuning-datasets/README.md
/wiki/curated-tuning-datasets/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== curated-tuning-datasets/wiki/concepts/corpus-to-chat-transformation.md ===== -->

---
title: Corpus-to-Chat Transformation
created: 2026-07-10
updated: 2026-07-10
type: concept
status: compiled
namespace: curated-tuning-datasets
tags: [curated-tuning-datasets, corpus-curation, instruction-backtranslation, temporal-persona]
sources:
  - Knowledge/concepts/corpus-to-chat-transformation.md
  - Projects/LKY Archive/Index.md
confidence: high
---

# Corpus-to-Chat Transformation

A corpus-to-chat transformation converts real dialogue and monologic source material into supervised chat rows while preserving which text is observed, which text is synthetic, which speaker is the loss target, and which temporal context conditions each answer.

## Two-stream contract

### Real dialogue

- Parse and validate speaker attribution.
- Preserve bounded multi-turn windows.
- Train only on the target speaker's assistant turns.
- Hold out whole documents before creating overlapping windows.

### Monologic speeches

- Clean and paragraph-chunk real passages deterministically.
- Generate one project-owned question that the passage directly answers.
- Keep the source passage as the answer; do not synthesize the expert's response.
- Store source ID, normalized-passage hash, date/title, and generation provenance.

The reusable instruction-backtranslation rule is: **synthesize the prompt, not the expert's answer**.

## Temporal conditioning

Put normalized date, role/title, and setting in the system prompt when a speaker's role and views evolve over time. The mapping must be inspectable and malformed dates must fail or normalize explicitly. Temporal context is a label, not proof of historical fidelity.

## LKY Brain instance

- 1,142 interview/press-conference windows;
- 2,895 speech passages with synthetic questions;
- 404 generic-instruction rows;
- 4,441 total training rows;
- 66 windows from 10 whole held-out interviews.

Qwen3 non-thinking mode and assistant-turn-only loss keep the objective on visible LKY-style answers rather than interviewer text or hidden scratchpad behavior.

## Main risks

- stale questions silently rejoining shifted chunks;
- generator-model framing bias in synthetic questions;
- same-event/date leakage across dialogue and speech streams;
- interview-only holdout coverage;
- title/speaker attribution and translation errors;
- style transfer being mistaken for belief or factual fidelity.

Hash-bound joins, explicit stream provenance, document-level splits, cross-stream leakage checks, and the `eval-trace` evidence contract are required before strong generalization claims.


<!-- ===== curated-tuning-datasets/wiki/concepts/dataset-recipe-publication.md ===== -->

---
title: Dataset Recipe Publication
created: 2026-07-10
updated: 2026-07-10
type: concept
status: compiled
namespace: curated-tuning-datasets
tags: [curated-tuning-datasets, dataset-recipe, provenance, hydration, reproducibility]
sources:
  - Knowledge/concepts/dataset-recipe-publication.md
  - Projects/LKY Archive/Index.md
  - Projects/LKY Archive/Source Inventory.md
confidence: high
---

# Dataset Recipe Publication

A **dataset recipe** publishes project-owned labels or transformations, source pointers, schemas, and hydration code instead of redistributing source bodies whose terms or rights remain constrained.

## Good recipe contents

- stable source IDs and URLs;
- provenance metadata;
- project-authored questions, labels, or annotations;
- deterministic retrieval, cleaning, and assembly code;
- schema and pipeline versions;
- source and normalized-passage hashes;
- explicit rights and downstream-use boundaries.

## Hard rule

A recipe is not a legal bypass. Hydration still acquires the source under the source host's terms, and model-weight publication is a different review question from raw-text publication.

## Reproducibility rule

Do not rely only on `source_id + chunk_index`. Source files, extraction libraries, and chunking code can change while the identifier still looks valid. Bind each project-authored label/question to a normalized passage hash and fail closed when the hash drifts.

## LKY Brain example

`lky-brain` publishes about 2,895 synthetic interviewer questions and 1,328 NAS record pointers, plus hydration code, while excluding transcript bodies. That is a strong public boundary. Its next hardening step is to add source/passage hashes, pipeline versioning, and holdout manifests so the recipe is drift-detecting rather than only nominally deterministic.

## Readiness ladder

```text
inventory → recipe → hash-verified hydration → repeated eval → rights/commercial review
```

Each gate is independent; training completion does not collapse them into one status.


<!-- ===== curated-tuning-datasets/wiki/entities/lky-archive.md ===== -->

---
title: LKY Brain / LKY Archive
created: 2026-06-16
updated: 2026-07-15
type: entity
status: active
namespace: curated-tuning-datasets
tags: [curated-tuning-datasets, lky-brain, provenance, dataset-recipe, qlora]
sources:
  - Projects/LKY Archive/Index.md
  - Projects/LKY Archive/Source Inventory.md
  - Projects/LKY Avatar/Index.md
  - https://github.com/pixiiidust/lky-brain
  - https://huggingface.co/datasets/sjsim/lky-reasoning-recipe
confidence: high
---

# LKY Brain / LKY Archive

`lky-brain` is a completed public case study that turns a National Archives of Singapore source manifest into a locally hydrated chat corpus, a Qwen3-14B QLoRA adapter, and a post-hoc reasoning-style evaluation.

## What changed from the original inventory stub

The project is no longer inventory-only:

- 1,328 unique NAS records are cataloged in the committed manifest;
- local extraction/cleaning, turn parsing, corpus filtering, speech chunking, and question backfill ran end to end;
- the assembled training set contains 4,441 rows / about 4.0M tokens;
- a Qwen3-14B QLoRA adapter trained for three epochs on one 16GB consumer GPU;
- the epoch-2 checkpoint and a source-pointer dataset recipe are public;
- a small n=24 held-out evaluation shows a directional shift in judged behavior.

## Dataset design

- **Stream A:** 1,142 interview/press-conference windows, with loss on LKY assistant turns only.
- **Stream B:** 2,895 speech passages paired with synthetic interviewer questions.
- **Generic retention:** 404 Dolly instruction rows.
- **Eval:** 66 windows from 10 whole held-out interviews; the published comparison uses 24 selected rows.
- **Temporal control:** LKY samples carry a dated role/persona prompt. Generic rows use a generic assistant prompt.

## Publication boundary

The public dataset is a **recipe**, not a transcript mirror. It publishes project-authored synthetic questions, NAS metadata pointers, hydration code, and documentation. Transcript bodies remain local and subject to NAS terms.

This reduces source-body redistribution. It does not prove that fetched transcripts or trained model weights are commercial-clean or unrestricted. Apache-2.0 labels cover project-owned code/recipe contributions, not automatically the source archive.

## Evidence boundary

The evaluation supports a provisional behavioral-shift claim, not factual fidelity or general reasoning improvement. Epoch 2 is a sensible checkpoint preference because it preserved more reframing and bounded uncertainty than epoch 3, but the current sample is too small and clustered to establish definitive overfitting.

## Applied downstream relationship

The separate LKY Avatar product now consumes the published epoch-2 adapter through a merged Q4_K_M llama.cpp serving path and pairs it with a tuned voice and animated portrait. That downstream milestone does not turn this corpus-and-adapter entity into a factual knowledge base. Live product use surfaced invented biography, dates, offices, and events, which confirms that style transfer and fact grounding must remain separate evidence lanes.

Use `Projects/LKY Avatar/Index.md` for interaction, voice, portrait, hosting, and factual-grounding status. Keep this page focused on corpus provenance, dataset design, publication boundaries, and the adapter result.

## Related pages

- [[concepts/dataset-recipe-publication|Dataset Recipe Publication]]
- [[syntheses/lky-dataset-readiness-map|LKY Dataset Readiness Map]]
- Cross-namespace: `local-ai-infrastructure/wiki/summaries/lky-brain-consumer-gpu-qlora.md`
- Cross-namespace: `eval-trace/wiki/concepts/style-transfer-evaluation.md`


<!-- ===== curated-tuning-datasets/wiki/index.md ===== -->

---
title: Curated Tuning Datasets — Master Index
created: 2026-06-16
updated: 2026-07-10
type: index
status: active
namespace: curated-tuning-datasets
---

# Curated Tuning Datasets — Master Index

> Compiled index for provenance-aware tuning datasets, publication recipes, and the LKY Brain case study.

## Concepts

- [[concepts/corpus-to-chat-transformation|Corpus-to-Chat Transformation]] — Preserve real dialogue and back-translate monologic speeches into questions without fabricating target-speaker answers.
- [[concepts/dataset-recipe-publication|Dataset Recipe Publication]] — Publish project-owned transformations and source pointers with hash-verified hydration instead of constrained source bodies.

## Entities

- [[entities/lky-archive|LKY Brain / LKY Archive]] — Completed NAS corpus-to-QLoRA case study with provenance, publication, training, and evidence boundaries.

## Summaries

<!-- Add compiled summaries alphabetically. -->

## Syntheses

- [[syntheses/lky-dataset-readiness-map|LKY Dataset Readiness Map]] — Readiness ladder and namespace boundary for the LKY source corpus.

## Source Roots

- `Projects/LKY Archive/Index.md`
- `Projects/LKY Archive/Source Inventory.md`
- `Knowledge/concepts/corpus-to-chat-transformation.md`
- `Knowledge/concepts/dataset-recipe-publication.md`


<!-- ===== curated-tuning-datasets/wiki/log.md ===== -->

---
title: Curated Tuning Datasets — Activity Log
created: 2026-06-16
updated: 2026-07-15
type: log
status: active
namespace: curated-tuning-datasets
---

# Curated Tuning Datasets — Activity Log

> Append-only namespace log.

## 2026-07-15 refresh | Separate LKY Brain source from the applied avatar product

- Updated the LKY Brain / LKY Archive entity with its downstream relationship to `Projects/LKY Avatar/Index.md`.
- Kept corpus provenance, dataset publication, and adapter evidence here while routing voice, interaction, portrait, hosting, and fact-grounding status to the applied product context.
- Recorded the key trust lesson from live use: a reasoning-style adapter can still invent biography and dates, so style transfer is not factual grounding.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add LKY source inventory stub

- Created canonical project/source artifacts under `Projects/LKY Archive/`.
- Replaced `source pending` routing with real source paths.
- Added compiled entity `wiki/entities/lky-archive.md`.
- Updated namespace source roots and index.
- No scraping, data collection, or training work was performed.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add LKY dataset readiness synthesis

- Added `wiki/syntheses/lky-dataset-readiness-map.md` so LKY notes compile under `curated-tuning-datasets` as requested.
- Kept readiness at `inventory-only`; no scraping, data collection, training, or training-safety claim was introduced.
- Updated namespace index.
- No Daily Notes were copied or compiled.

## 2026-07-10 update | Reconcile completed LKY Brain corpus, adapter, and eval

- Replaced the stale inventory-only entity/readiness state with verified repo, manifest, dataset, training, publication, and n=24 evaluation facts.
- Added `wiki/concepts/corpus-to-chat-transformation.md` for real-dialogue windows, instruction back-translation, assistant-only loss, temporal conditioning, and leakage controls.
- Added `wiki/concepts/dataset-recipe-publication.md` as the reusable source-pointer + hydration pattern.
- Preserved NAS rights limits, the no-transcript publication boundary, and the distinction between technical reproducibility and commercial/redistribution clearance.
- Routed the executed consumer-GPU QLoRA path to `local-ai-infrastructure` and the behavioral-eval contract to `eval-trace`.
- Kept LKY Brain in this existing namespace rather than creating a new one; promotion requires an ongoing independent corpus/release lifecycle.


<!-- ===== curated-tuning-datasets/wiki/syntheses/lky-dataset-readiness-map.md ===== -->

---
title: LKY Dataset Readiness Map
created: 2026-06-16
updated: 2026-07-10
type: synthesis
status: compiled
namespace: curated-tuning-datasets
tags: [curated-tuning-datasets, lky-brain, dataset-readiness, provenance, dataset-recipe]
sources:
  - Projects/LKY Archive/Index.md
  - Projects/LKY Archive/Source Inventory.md
  - https://github.com/pixiiidust/lky-brain
confidence: high
---

# LKY Dataset Readiness Map

The LKY work remains primarily a `curated-tuning-datasets` case study even though training is now complete. This namespace owns the source/provenance, transformation, recipe, and readiness contract; training runtime belongs in `local-ai-infrastructure`, and evaluation design belongs in `eval-trace`.

## Current readiness by artifact

| Artifact | Current state | Boundary |
|---|---|---|
| NAS record manifest | retrieval-ready metadata | 1,328 unique pointers; verify source drift |
| Local hydrated corpus | research/training use demonstrated | not redistributed; NAS terms still apply |
| Synthetic-question recipe | publicly published recipe | question joins need stronger passage-hash validation |
| Qwen3-14B adapter | public research artifact | persona/rights/factuality caveats remain |
| Style-transfer evaluation | directional evidence | n=24, 10 documents, one judge, stochastic generation |
| Commercial use | not established | requires separate rights and risk review |

## Updated readiness ladder

```text
source-inventory
→ locally hydrated corpus
→ recipe publication
→ hash-verified reproducibility
→ repeated evaluation
→ redistribution/commercial review
```

These are separate axes. Completing training does not automatically make the source bodies redistribution-safe, the recipe drift-proof, or the adapter commercially cleared.

## What worked

- Source metadata and transcript bodies stayed separate.
- Low-confidence OCR/translation/duplicate/ceremonial material was flagged before assembly.
- Interviews were held out by whole document.
- Synthetic questions were published without transcript bodies.
- Intermediate checkpoints were preserved and evaluated rather than selecting only the lowest train loss.

## Remaining gates

1. Add source and normalized-passage hashes to the recipe.
2. Pin the pipeline commit/schema and fail closed on chunk drift.
3. Record holdout IDs and generated dataset summaries as reproducibility artifacts.
4. Repeat evaluation with fixed/repeated seeds and document-clustered uncertainty.
5. Keep NAS rights/terms and model-weight publication risk as explicit review lanes.
6. Add tests/CI, a root code license, and a machine-readable run manifest tying commit, source/dataset hashes, executed config, checkpoint, generation, and eval artifacts together.
7. Pin the version-sensitive training stack and generate report conclusions from result data rather than hardcoded percentages.

## Cross-namespace ownership

- `curated-tuning-datasets` — manifest, provenance, cleaning, recipe, readiness.
- `local-ai-infrastructure` — successful Unsloth/WSL2/16GB QLoRA path and runtime landmines.
- `eval-trace` — trait rubric, paired candidates, uncertainty, and claim strength.


<!-- ===== local-ai-infrastructure/CLAUDE.md ===== -->

# Local AI Infrastructure Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/local-ai-infrastructure/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Treat `Knowledge/` and `Projects/` as canonical authoring sources.
- Treat Daily Notes as scratch chronology, not direct compiled content.
- Keep this namespace scoped to: Local-first AI setup, local LLMs, LoRA/fine-tuning infrastructure, RAG over compiled wikis, deterministic local workflow offload, and hardware/software constraints.
- Do not widen scope silently; propose a namespace promotion/routing update first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added.


<!-- ===== local-ai-infrastructure/README.md ===== -->

---
title: Local AI Infrastructure
created: 2026-06-16
updated: 2026-07-17
type: namespace-overview
status: active
category: infrastructure
namespace: local-ai-infrastructure
confidence: high
---

# Local AI Infrastructure

> Active namespace for local-first models, retrieval, fine-tuning, deployment, and hardware/software constraints.

## Scope

### Covers

Local-first AI setup, local LLMs, LoRA/fine-tuning infrastructure, RAG over compiled wikis, deterministic local workflow offload, and hardware/software constraints.

### Not Covered

Cloud-only infrastructure unless it affects local-first migration; product UX unless tied to local model constraints.

### Current As

2026-07-17 — active. Includes local retrieval/RAG concepts, VPS app operation, and the LKY Brain consumer-GPU QLoRA case study with checkout-portable launchers, documented PEFT/vLLM paths, executed downstream llama.cpp Q4_K_M serving, tuned-voice co-placement, and the application-layer audited retrieval seam used by LKY Avatar.

## Canonical Source Roots

- `Knowledge/concepts/local-retrieval-agent-infrastructure.md`
- `Knowledge/concepts/rag-over-agent-wikis.md`
- `Projects/LKY Archive/Index.md`
- `Projects/LKY Avatar/Index.md`

## Crosslinks

- [[../pixi-vault/README|pixi-vault]]
- [[../curated-tuning-datasets/README|curated-tuning-datasets]]
- [[../rl-sim-labs/README|rl-sim-labs]]

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/local-ai-infrastructure/README.md
/raw/local-ai-infrastructure/wiki/index.md
/wiki/local-ai-infrastructure/README.md
/wiki/local-ai-infrastructure/wiki/index.md
```

## Maintenance

- Edit canonical source notes first.
- Use `Wiki Compiler Maps/Namespace Wiki Compiler Map.md` for routing decisions.
- Do not compile Daily Notes directly unless promoted or verified.


<!-- ===== local-ai-infrastructure/raw/transcripts/tonbi-vps-agent-web-app-workflow-2026.md ===== -->

---
source_url: https://youtu.be/K8ZTlMaDfmQ?si=IuNRaHVc-fFHZw41
ingested: 2026-06-19
sha256: 3718867c216538e104df7998eb758988e9fd4f264cc916a554fb6a36efd339fb
type: transcript
---

# Transcript — The Autonomous Agentic Workflow that Runs My Web App w/ Hermes + a $6 VPS

Source: https://youtu.be/K8ZTlMaDfmQ?si=IuNRaHVc-fFHZw41
Creator/channel: Tonbi AI
Transcript supplied by Jamie in chat on 2026-06-19.

## Video description

When you start vibe-coding apps, the tools push you toward Vercel, Supabase, and Railway — but I run everything on one small VPS with a Hermes agent instead, and I'll show you exactly how. Using my live site Agent Wikis (agentwikis.com — free knowledge bases for agents) as the example, I break down why git is the only "database" a docs/wiki/blog-class site needs, how the agent lives on the box and serves the site through Caddy, and the autonomous Cron pipeline that keeps every wiki fresh behind a single Telegram approval. Then I demo the new "demand loop": agents search the wikis via an MCP server, repeated misses (privacy-preserving, no prompts or IPs stored) become an authoring backlog, and the agent researches and fills those gaps automatically — live on the site in minutes. This is Part 1 (the site that needs no database); Part 2 deploys a game app that does need one, on the same box.

## Chaptered transcript notes

### 1. Replacing Vercel/Supabase/Railway with a VPS + agent

The setup replaces common beginner deployment platforms — Vercel, Supabase, Railway — with a small VPS and one Hermes agent that maintains web apps, content, and business workflows. The video uses Agent Wikis as the live example and promises a later database-backed game app example.

### 2. The usual stack and what it really gives you

Vercel, Railway, and Supabase provide deployment, managed Postgres, backups, auth, realtime, row-level security, storage, and beginner convenience. The core claim is not that they are bad, but that their main value is de-risking and convenience. A VPS can replace the core functions for some project classes, but not all.

### 3. Agent Wikis: when git is your database

Agent Wikis has no application database. It is a folder of Markdown files, one git clone per wiki, rendered from disk. The server renders Markdown on each request and keeps a search index in memory, rebuilding only when files change. For docs, blogs, wikis, marketing pages, and similar content sites, git can act as database, CMS, and deploy pipeline. A git push plus server pull makes content live without app restart or build.

### 4. The VPS setup

The site runs as a tenant on a small VPS that already hosts the Hermes agent. Caddy terminates TLS and adds a virtual host that reverse-proxies the public domain to localhost; Caddy auto-provisions certificates. The operator can SSH into the VPS and run Hermes directly against files on the box. The agent does not receive unrestricted access; the security model should scope it to the site/workspace areas it needs.

### 5. The content pipeline

A cron job fires scout/research agents to check sources such as releases, changelogs, major features, and community notes for each wiki. They deduplicate, research what is genuinely new, and create a plan. A Telegram human gate approves the plan. After approval, the system ingests sources, lints, commits to git, and the site becomes live within roughly 15 minutes. Weekly cadence controls token cost.

### 6. The demand loop

Agent Wikis learns from what agents ask for without storing prompts or identities. Agents query through an MCP server. The server receives a distilled query, records only aggregate hit/miss information, and does not store prompts, IPs, or identity. Repeated misses become an authoring backlog. Research agents turn those misses into candidate updates, propose page-vs-extension decisions, and wait for a human approval gate.

### 7. Live demo: filling demand gaps autonomously

The demo parses five live demand gaps, each asked at least twice in seven days. It creates item files and child cards, routes them through research and verification, and blocks at the human proposal gate. One example adds a webhook route rate limit answer to the messaging gateway page: each webhook route defaults to 30 requests per minute using a fixed window. Lint checks verify formatting and conflicts before commit.

### 8. Two human gates + merging live

The workflow has two gates: proposal approval before writing, then final diff review and merge to main. The author may eventually automate the merge gate after confidence grows, but currently keeps human review before live merge. Once merged, the live site updates automatically.

### 9. When a single box is not enough

The VPS pattern is not universal. Use managed services when the project needs real auth/password resets, cannot-lose or regulated data, managed Postgres, global/viral traffic, email deliverability, team preview deploys, or sensitive credential handling. The video frames the VPS pattern as appropriate for solo/operator-controlled apps and content/wiki-class sites first.


<!-- ===== local-ai-infrastructure/wiki/concepts/local-retrieval-agent-infrastructure.md ===== -->

---
title: Local Retrieval Agent Infrastructure
created: 2026-06-18
updated: 2026-06-18
type: concept
status: compiled
namespace: local-ai-infrastructure
tags: [agent-systems, ai, architecture, workflow, knowledge-management]
sources:
  - /root/.hermes/knowledge/concepts/local-retrieval-agent-infrastructure.md
  - Knowledge/concepts/local-retrieval-agent-infrastructure.md
confidence: medium
---

# Local Retrieval Agent Infrastructure

## Definition

**Local retrieval agent infrastructure** is the reference pattern for giving agents private, source-grounded retrieval over local knowledge without sending the private corpus to hosted systems.

Reference pipeline:

```text
ingest → clean → chunk → embed → Qdrant/vector store → retrieve → rerank → MCP/agent access
```

The pattern is useful as architecture vocabulary. It is not an implementation approval.

## Current synthesis

The vault source describes a local RAG stack inspired by Krill-style infrastructure:

1. ingest documents from approved local sources;
2. clean and neutralize sensitive or irrelevant material;
3. chunk by stable sections with metadata;
4. embed chunks with a local embedding model;
5. store vectors in Qdrant or a similar vector database;
6. retrieve a broad candidate set;
7. rerank to a small evidence packet;
8. expose results to an agent through MCP or another controlled local interface.

For Jamie’s current agent workflow, the governance lesson matters more than the stack: improve explicit routing first, then only add retrieval infrastructure if static wiki/index/llms routing fails an important question set. See [[agent-wikis]], [[rag-over-agent-wikis]], and [[runtime-memory-knowledge-routing]].

## Application

Use this page to reason about:

- when a markdown/`llms.txt` knowledge pack is enough;
- when a static retrieval eval should be written before infrastructure;
- how private-corpus retrieval should preserve provenance and freshness;
- why compiled/synthesized wiki pages are usually a better retrieval corpus than raw transcripts;
- how hardware/local-model lessons differ from agent workflow governance.

Hardware/local-model lessons answer “can this run locally?” Workflow-governance lessons answer “should this be routed, verified, and maintained this way?” Keep those questions separate.

## Boundaries

This concept does **not** authorize:

- installing Qdrant, Ollama, MCP servers, vector databases, rerankers, or embedding services;
- changing providers, gateways, profile config, cron jobs, webhooks, secrets, or deployment routing;
- building or deploying RAG infrastructure;
- generating or publishing public wiki output;
- creating automatic memory pruning, model fine-tuning, profile creation, or provider changes;
- treating raw transcripts or scratch notes as equivalent to compiled wiki pages;
- replacing explicit routing with embeddings.

If retrieval is needed, start with a separate approved issue that defines eval questions, privacy boundaries, corpus scope, verification, and rollback.

## Related pages

- [[agent-wikis]]
- [[rag-over-agent-wikis]]
- [[runtime-memory-knowledge-routing]]
- [[self-improving-agent-systems]]
- [[moc-knowledge-cortex]]
- [[bounded-context-tree-pattern]]

## Sources

- `/root/ObsidianVault/Knowledge/concepts/local-retrieval-agent-infrastructure.md`
- `/root/ObsidianVault/Knowledge/concepts/agent-wikis.md`
- `/root/ObsidianVault/Knowledge/concepts/rag-over-agent-wikis.md`


<!-- ===== local-ai-infrastructure/wiki/concepts/rag-over-agent-wikis.md ===== -->

---
title: RAG over Agent Wikis
created: 2026-06-16
updated: 2026-06-16
type: concept
status: compiled
namespace: local-ai-infrastructure
tags: [local-ai-infrastructure, rag, agent-wikis, retrieval, infrastructure]
sources:
  - Knowledge/concepts/rag-over-agent-wikis.md
  - Knowledge/concepts/local-retrieval-agent-infrastructure.md
confidence: medium
---

# RAG over Agent Wikis

**RAG over Agent Wikis** means using maintained compiled wiki pages as the retrieval corpus for agents, instead of retrieving directly from raw source dumps or asking the model to answer from memory.

## Infrastructure shape

The practical loop is:

```text
compiled wiki pages → chunks/sections → embeddings → retrieval/rerank → cited answer
```

For Jamie's stack, the important design choice is that the wiki compilation layer comes before the vector layer. Retrieval quality should be improved by curated pages, frontmatter, source metadata, freshness, and namespace boundaries before adding infrastructure complexity.

## Local-first implementation posture

A future local prototype can use:

- compiled `pixi-wiki` Markdown pages as the corpus;
- local embeddings such as `nomic-embed-text` or a similar sentence model;
- FAISS or Qdrant for local vector storage;
- optional reranking for quality;
- source metadata preserved for citations and freshness checks.

## Current Pixi Wiki use

`pixi-wiki` is the current public corpus candidate for this pattern. Its generated pages include namespace scopes, page metadata, raw Markdown mirrors, full-corpus exports, and navigable HTML. That structure should be used as the first retrieval/eval surface before adding a vector database or runtime RAG service.

## Quality gates

Do not ship retrieval infrastructure because it sounds useful. Use evals:

- recall@k for known routing questions;
- citation support for factual answers;
- fallback behavior when a namespace does not cover the query;
- change-aware questions that test whether updated wiki metadata helps.

## Boundary

No MCP server, vector DB, crawler, hosted search, or runtime RAG is approved by this compiled page. This page is an infrastructure concept and future implementation home, not a build authorization.

## Source

Compiled from `Knowledge/concepts/rag-over-agent-wikis.md` and `Knowledge/concepts/local-retrieval-agent-infrastructure.md`.


<!-- ===== local-ai-infrastructure/wiki/concepts/vps-agent-web-app-pattern.md ===== -->

---
title: VPS Agent Web App Pattern
created: 2026-06-19
updated: 2026-06-19
type: concept
status: compiled
namespace: local-ai-infrastructure
tags: [local-ai-infrastructure, vps, hermes-agent, agent-workflows, gitops, web-apps]
sources:
  - raw/transcripts/tonbi-vps-agent-web-app-workflow-2026.md
  - https://youtu.be/K8ZTlMaDfmQ?si=IuNRaHVc-fFHZw41
confidence: medium
---

# VPS Agent Web App Pattern

The **VPS Agent Web App Pattern** uses a small always-on VPS plus a resident agent to replace parts of the beginner Vercel/Supabase/Railway stack for simple, operator-controlled web apps. It works best when the app is mostly files, Markdown, static-ish content, or a small service where the agent can safely own the deploy loop.

This is not “VPS beats managed platforms.” The useful distinction is: managed platforms buy convenience and de-risking; a VPS buys control, low recurring cost, direct file access, and an agent that can operate the system where it runs.

## Core shape

```text
git-backed content/app repo
        ↓
VPS workspace with one app clone + one clone per knowledge base
        ↓
local web server / app process
        ↓
Caddy vhost + automatic TLS
        ↓
resident Hermes agent reachable by SSH or gateway
        ↓
cron/scout/research/update loops with human gates
```

For docs, blogs, wikis, and marketing pages, git can be the database, CMS, and deploy pipeline. The server can render Markdown from disk, keep a search index in memory, and rebuild only when files change. In that class of system, a database would answer a question the app does not actually ask.

## What the agent replaces

The resident agent can cover a subset of what Vercel/Supabase/Railway usually provide:

| Managed stack job | VPS-agent equivalent | Boundary |
|---|---|---|
| Frontend deploy | git push/pull, Caddy vhost, local app process | Good for small sites; weak for preview deploy/team workflows. |
| CMS updates | Markdown files in git | Good for docs/wiki/blog content; weak for multi-user editing. |
| Background jobs | Hermes cron / shell cron / systemd timers | Needs explicit logging and recovery. |
| Content freshness | scout agents + source checks + lint + commit | Needs human gates until trust is earned. |
| Admin console | SSH + Hermes CLI/gateway | Powerful but must be scoped. |
| Search/retrieval feedback | aggregate MCP hit/miss demand loop | Must avoid prompt/IP/user logging. |

## Agent Wikis example

The transcript's example is Agent Wikis: a public wiki-of-wikis where each wiki is a folder of Markdown files. The site renders from disk, uses git as the deploy mechanism, and avoids an application database.

That maps closely to Pixi Wiki's source/output model:

- `pixi-vault` holds source truth and compiled namespace source.
- `pixi-wiki` publishes raw Markdown, rendered HTML, `llms.txt`, `llms-full.txt`, `index.json`, and MCP-facing corpus files.
- [[rag-over-agent-wikis|RAG over Agent Wikis]] uses the compiled wiki as retrieval corpus before adding heavier vector infrastructure.
- [[../../../pixi-vault/wiki/syntheses/pixi-vault-to-pixi-wiki-publishing-model|Pixi Vault to Pixi Wiki Publishing Model]] defines the publish boundary.

## Content freshness loop

The durable workflow pattern is:

```text
cron fires
  → scout checks sources
  → deduplicate and score newness
  → research what matters
  → propose page changes
  → human gate approves plan
  → ingest/update Markdown
  → lint and verify
  → commit to git
  → merge/pull makes site live
```

The human gate is important. It keeps the agent from turning noisy sources into public content just because it can write. A second merge/diff gate is useful until the operator trusts the loop.

## Demand loop

The demand loop is the stronger product idea:

```text
agent asks wiki via MCP
  → server records aggregate hit/miss for distilled query
  → repeated misses become backlog candidates
  → scout/research agents propose additions
  → human approves
  → wiki fills real usage gaps
```

The privacy contract matters more than the automation: record aggregate misses, not prompts, IP addresses, or identities. The loop should learn what the knowledge base lacks without becoming surveillance infrastructure.

## When to use this pattern

Use it when:

- the app is a docs/wiki/blog/marketing/content site;
- git can be the source of truth;
- one operator can tolerate SSH/Git-based operations;
- the resident agent can be scoped to the app workspace;
- freshness comes from source monitoring and editorial review;
- downtime or rollback risk is acceptable for a small VPS.

Avoid it, or add managed services, when:

- the app needs real auth, password resets, or user account recovery;
- it stores cannot-lose or regulated data;
- it needs managed Postgres, backups, row-level security, or object storage guarantees;
- it may face global/viral traffic;
- it needs high email deliverability;
- a team needs preview deploys and parallel environments;
- secrets or credentials require stronger isolation than a general-purpose agent workspace.

## Pixi Wiki routing

Primary namespace: `local-ai-infrastructure`, because the reusable pattern is about local/VPS deployment topology, file-backed web apps, Caddy/git operations, and deciding when a single box can replace managed infrastructure.

Crosslinks:

- [[../../../agent-workflows/wiki/syntheses/pixoid-crew-operating-model|Pixoid Crew Operating Model]] — route governance, human gates, verification, and durable state.
- [[../../../hermes-agent/wiki/concepts/source-priority|Hermes Source Priority]] — use official Hermes docs/local source for commands and runtime behavior; this transcript is a pattern source, not command truth.
- [[../../../pixi-vault/wiki/entities/pixi-wiki|Pixi Wiki]] — the public wiki surface where this pattern can inform source→generated publishing.

## Open questions

- Should Pixi Wiki eventually have its own demand-loop telemetry over MCP queries, and if so what aggregate-only privacy contract is acceptable?
- Which parts of the publish workflow are safe to automate beyond the current regenerate/test/push/live-verify loop?
- Should a future `agent-workflows` page split out the human-gated content freshness loop from this infrastructure page?

## Source

Compiled from Tonbi AI's video transcript, “The Autonomous Agentic Workflow that Runs My Web App w/ Hermes + a $6 VPS,” supplied by Jamie on 2026-06-19.


<!-- ===== local-ai-infrastructure/wiki/index.md ===== -->

---
title: Local AI Infrastructure — Master Index
created: 2026-06-16
updated: 2026-07-17
type: index
status: active
namespace: local-ai-infrastructure
---

# Local AI Infrastructure — Master Index

> Scaffold index for `local-ai-infrastructure`. Add compiled pages here as they are created.

## Concepts

- [[concepts/local-retrieval-agent-infrastructure|Local Retrieval-Augmented Agent Infrastructure]] — Local-first model/retrieval stack pattern for private corpora and agent memory.
- [[concepts/rag-over-agent-wikis|RAG over Agent Wikis]] — Retrieval architecture over compiled wiki pages rather than raw source dumps.
- [[concepts/vps-agent-web-app-pattern|VPS Agent Web App Pattern]] — Small-VPS + resident-agent pattern for git-backed web apps, Caddy/TLS hosting, human-gated content freshness loops, and when not to replace managed platforms.

## Entities

<!-- Add compiled entities alphabetically. -->

## Summaries

- [[summaries/lky-brain-consumer-gpu-qlora|LKY Brain Consumer-GPU QLoRA Case Study]] — Executed Qwen3-14B/Unsloth training plus downstream llama.cpp Q4_K_M serving beside the tuned voice on one 16GB GPU, now with an application-layer audited retrieval seam; preserves config drift, live-proof, and reproducibility boundaries.

## Syntheses

- Cross-namespace summary: [[../../hermes-agent/wiki/summaries/external-hermes-wikis-import-review|External Hermes Wikis Import Review]] — Marks Local Stack / Airplane Mode as local-infrastructure primary, with deployment backend tradeoffs crosslinked from Hermes Agent.

## Source Roots

- `Knowledge/concepts/local-retrieval-agent-infrastructure.md`
- `Knowledge/concepts/rag-over-agent-wikis.md`
- `Projects/LKY Archive/Index.md`
- `Projects/LKY Avatar/Index.md`
- `raw/transcripts/tonbi-vps-agent-web-app-workflow-2026.md`
- `https://youtu.be/K8ZTlMaDfmQ?si=IuNRaHVc-fFHZw41`


<!-- ===== local-ai-infrastructure/wiki/log.md ===== -->

---
title: Local AI Infrastructure — Activity Log
created: 2026-06-16
updated: 2026-07-17
type: log
status: active
namespace: local-ai-infrastructure
---

# Local AI Infrastructure — Activity Log

> Append-only namespace log.

## 2026-07-17 refresh | LKY Avatar application-layer fact retrieval

- Updated the LKY Brain case study after `lky-avatar` issue #45 / PR #47 merged a small audited fact sheet, deterministic per-turn retrieval, uncertainty instructions, Singapore STT keyterms, and a 12-question factuality eval.
- Preserved the serving boundary: the Q4_K_M llama.cpp brain is unchanged; grounding belongs to the voice-agent application layer.
- Preserved the proof boundary: tests cover the seams, while real-microphone STT and grounding-on/off local-brain quality results remain pending.

## 2026-07-15 refresh | LKY Brain downstream avatar serving path

- Refreshed the LKY Brain consumer-GPU summary from the separate `lky-avatar` integration evidence.
- Added the executed merged-LoRA Q4_K_M llama.cpp route, 80.5 tok/s warm decode, tuned-voice co-placement, and ten-turn no-failure/VRAM evidence.
- Added the later interactive chat REPL and its temperature 0.7 / repetition-penalty 1.1 correction while preserving the historical evaluation boundary.
- Kept the boundary that this verifies one local product path, not vLLM, multi-user capacity, factual reliability, or a reproducible locked training environment.

## 2026-06-16 create | Namespace scaffold initialized

- Created README, CLAUDE instructions, raw folder, index/log, and typed wiki folders.
- Source routing comes from `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Add first local-AI infrastructure compiled concepts

- Added `wiki/concepts/local-retrieval-agent-infrastructure.md`.
- Added `wiki/concepts/rag-over-agent-wikis.md`.
- Updated `wiki/index.md` from scaffold to active content index.
- Preserved the boundary that this is not approval to build MCP/vector/search runtime infrastructure.
- No Daily Notes were copied or compiled.

## 2026-06-16 update | Link Pixi Wiki to RAG-over-wiki posture

- Updated `wiki/concepts/rag-over-agent-wikis.md` to name `pixi-wiki` as the current public corpus candidate.
- Preserved the eval-first boundary: use the compiled wiki as the first retrieval/eval surface before adding vector DB or runtime RAG infrastructure.
- No Daily Notes were copied or compiled.

## 2026-06-18 update | Crosslink Hermes local-stack routing

- Added cross-namespace pointer to the Hermes Agent external wiki import review for Local Stack / Airplane Mode and deployment-backend routing.
- No Daily Notes were copied or compiled.
## 2026-06-18 update | Refresh local retrieval infrastructure boundary

- Refreshed `wiki/concepts/local-retrieval-agent-infrastructure.md` from the verified local Hermes KB closure synthesis.
- Preserved the explicit no-install/no-MCP/no-RAG-build/no-provider/no-deploy authorization boundary.

## 2026-06-19 ingest | Tonbi VPS agent web app workflow

- Added `raw/transcripts/tonbi-vps-agent-web-app-workflow-2026.md` from Jamie-supplied transcript of Tonbi AI video.
- Added `wiki/concepts/vps-agent-web-app-pattern.md` as a local-infrastructure concept for small-VPS + resident-agent web app operation.
- Updated `wiki/index.md` with the new concept and source handles.
- Routed workflow/human-gate material by crosslink to `agent-workflows`; kept primary namespace as `local-ai-infrastructure` because the reusable decision is VPS/local deployment topology.

## 2026-07-10 add | LKY Brain consumer-GPU QLoRA case study

- Added `wiki/summaries/lky-brain-consumer-gpu-qlora.md` from the verified public repo and training report.
- Distinguished the successful Unsloth script from the retained but unexecuted Axolotl portability config.
- Captured WSL2 + Blackwell failure isolation, non-packed training, plain-Transformers inference, checkpoint preservation, and environment-specific boundaries.
- Crosslinked source/provenance to `curated-tuning-datasets` and evidence quality to `eval-trace`.

## 2026-07-10 refresh | LKY Brain public-use and portability milestone

- Refreshed the consumer-GPU QLoRA summary from repo commit `da490f6`.
- Recorded checkout-relative launchers, the documented 4-bit PEFT quick-test path, and the vLLM OpenAI-compatible serving path.
- Preserved the boundary between the executed training run and newly documented but not review-executed inference/serving examples.
- Confirmed that dataset, training, and evaluation numbers did not change in this prose/portability refresh.


<!-- ===== local-ai-infrastructure/wiki/summaries/lky-brain-consumer-gpu-qlora.md ===== -->

---
title: LKY Brain Consumer-GPU QLoRA Case Study
created: 2026-07-10
updated: 2026-07-17
type: summary
status: compiled
namespace: local-ai-infrastructure
tags: [local-ai-infrastructure, qlora, consumer-gpu, wsl2, blackwell, reproducibility, llama-cpp, voice-ai]
sources:
  - Projects/LKY Archive/Index.md
  - Projects/LKY Avatar/Index.md
  - https://github.com/pixiiidust/lky-brain
confidence: high
---

# LKY Brain Consumer-GPU QLoRA Case Study

`lky-brain` demonstrates a complete Qwen3-14B QLoRA run on one RTX 5070 Ti 16GB GPU under WSL2 Ubuntu 24.04. The useful infrastructure lesson is not one magic config; it is how to isolate the actual failing layer and preserve a working evidence path.

## Successful run

- base: Qwen3-14B, non-thinking mode;
- quantization: 4-bit QLoRA;
- adapter: rank 64 / alpha 128 across linear projections;
- actual trainer: Unsloth;
- maximum sequence length: 2,048;
- assistant-turn-only loss;
- micro-batch 1, gradient accumulation 8;
- three epochs, final train loss 1.247;
- generation: plain Transformers + PEFT;
- judging: separate Claude API pass.

## Portability config vs executed config

The retained Axolotl YAML is not the executed evidence on this machine. It specifies 4,096 sequence length, packing, dropout 0.05, and in-loop eval. The successful Unsloth path used 2,048, `packing=False`, dropout 0.0, and no in-loop eval.

Agents should quote the executed script (`train/train_unsloth.py`) when describing the result and treat `train/lky-qlora.yml` as a portability candidate only.

## Failure isolation pattern

1. Probe raw CUDA allocation, matmul, dtype, and 4-bit load.
2. Reproduce a manual quantized LoRA train step.
3. Compare framework paths.
4. Disable the smallest failing optimization: varlen packing, pinned memory, or custom inference kernel.
5. Preserve diagnostic scripts and working launchers.
6. Decouple GPU generation from API judging.
7. Save intermediate checkpoints because post-hoc quality may peak before final train loss.

## Environment-specific findings

On this WSL2 + Blackwell stack:

- Axolotl crashed during model loading even when plain Transformers/bitsandbytes worked.
- Unsloth import order mattered because it patches TRL/Transformers.
- Triton required a C compiler.
- packed/varlen attention crashed; dense non-packed training worked.
- pinned-memory loading and Unsloth's Qwen3 inference kernel were avoided.

These are verified for this run, not universal prescriptions for every GPU, WSL version, or future package release.

## Portable use and serving path

The public-readability refresh at repo commit `da490f6` replaced machine-specific checkout paths in the setup, training, generation, and upload launchers with paths derived from each script's location.

The repo now documents two downstream paths:

- **Quick local inference:** load Qwen3-14B in 4-bit with Transformers/bitsandbytes, attach `sjsim/lky-qlora` through PEFT, and run with about 16GB VRAM.
- **OpenAI-compatible serving:** run vLLM with LoRA enabled, register the adapter as `lky`, keep maximum LoRA rank at 64, and disable Qwen3 thinking in request metadata.

The serving guide estimates about 28GB for the full-precision 14B base and points readers toward a 40GB card, or a 24GB card with quantization. These examples make the project easier to try and integrate, but they were not executed as part of this VPS review and should not be promoted to verified serving evidence yet.

## Interactive chat path and sampling correction

Repo commit `3a9f6a5` added a streaming Transformers + PEFT chat REPL with conversation history, `/date` era switching, and `/reset`. The documented interactive defaults are temperature 0.7 with repetition penalty 1.1 after temperature 0.8 without a penalty produced degenerate loops in field use.

This is an executed local interaction path, not evidence for the unexecuted vLLM example. It also does not rewrite the historical n=24 style-evaluation contract, which used its original stochastic generation settings.

## Executed downstream serving in LKY Avatar

The separate `lky-avatar` product has now executed a different serving route on the same RTX 5070 Ti:

- merge the published epoch-2 LoRA into Qwen3-14B;
- quantize the merged model to Q4_K_M GGUF;
- serve through llama.cpp's OpenAI-compatible `llama-server`;
- use the same client seam as the slower 4-bit Transformers + PEFT fallback.

Measured warm brain performance was 80.5 tok/s p50 decode and about 0.05 s time to first token. The brain plus the fine-tuned Chatterbox voice then completed a ten-turn same-GPU placement run with zero failures; TTS RTF mean/max was 0.369/0.397 and total-card VRAM peaked at 15,813 MiB of 16,303 MiB.

This verifies one local product-serving path. It does not validate the README's vLLM example, establish multi-user serving capacity, or make the style adapter factually reliable. Live use exposed confident biography/date/place hallucinations.

The application layer now adds a small audited fact sheet, deterministic section retrieval per turn, a source-over-memory and uncertainty block immediately before the latest question, and Singapore proper-noun input boosts without changing llama-server. A 12-question eval separates factual accuracy, persona quality, and fabrication and supports matched grounding-on/off runs.

Repository verification passed 148 root tests and 199 voice-agent tests with 3 live-service skips. That proves the retrieval, prompt, config, STT-construction, and eval seams as code; it does not prove the model-quality lift. Real-microphone STT and a local-brain grounding-on/off run remain the acceptance evidence.

## Evidence boundary

The repo has no CI or unit-test suite for the data/training pipeline, and the generated datasets/checkpoints are intentionally gitignored. The `uv.lock` covers the data-pipeline environment, but the version-sensitive Unsloth/TRL/Transformers/PEFT/Torch/bitsandbytes training stack is installed separately without exact pins. Reproducibility therefore depends on live sources, external model artifacts, package resolution, and operator-run hydration/training steps. The portable shell paths reduce checkout-specific friction but do not solve dependency or artifact reproducibility. Add training locks, manifests, hashes, schema versions, a small CPU-only pipeline fixture, and GPU smoke checks for the documented inference/serving paths before calling the template fully reproducible.


<!-- ===== pattern-language/CLAUDE.md ===== -->

# Pattern Language Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/pattern-language/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Preserve source provenance and the non-commercial attribution guardrail from `zenodotus280/apl-md`.
- Treat imported pattern pages as reference/constraint material, not as commercial-clean training data.
- Keep this namespace scoped to the A Pattern Language corpus and agent-facing spatial-design retrieval guidance.
- Do not implement the Unreal MCP adapter here; capture adapter ideas as deferred design notes until the namespace is live and searchable.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added or the import is refreshed.


<!-- ===== pattern-language/README.md ===== -->

---
title: Pattern Language
created: 2026-07-01
updated: 2026-07-01
type: namespace-overview
status: active
category: spatial-design
namespace: pattern-language
confidence: medium
source_repository: https://github.com/zenodotus280/apl-md
source_license_note: Non-commercial reuse with attribution; see source LICENSE.md.
---

# Pattern Language

> Spatial-design pattern reference for agents, compiled from the abridged `zenodotus280/apl-md` Markdown manifestation of Christopher Alexander's *A Pattern Language*.

## Scope

### Covers

The `pattern-language` namespace covers the abridged, hyper-textual pattern corpus from `apl-md`: 253 built-environment patterns, their Problem/Solution framing, related-pattern graph, provenance, license guardrails, and agent-facing retrieval guidance for spatial design and worldbuilding.

### Not Covered

This namespace does not cover generic architecture theory outside the imported corpus, commercial training-data clearance, complete republication of the original book beyond the `apl-md` abridged material, or implementation of an Unreal MCP adapter. Unreal/worldbuilding adapter design is tracked as a deferred follow-up.

### Current As

2026-07-01 — Initial namespace release imports 253 pattern documents from `zenodotus280/apl-md`, preserves related-pattern wikilinks, and adds agent retrieval/worldbuilding guidance plus deferred Unreal MCP adapter notes.

## Canonical Source Roots

- External source repo: `https://github.com/zenodotus280/apl-md`
- Source permission note: `https://github.com/zenodotus280/apl-md/blob/master/LICENSE.md`
- Imported corpus path: `Patterns/*.md` in the source repo
- Pixi Wiki tracker: `https://github.com/pixiiidust/pixi-wiki/issues/42`

## Provenance and License Guardrail

**Non-commercial reuse with attribution** is the governing guardrail. The source repo states that permission was granted on 2024-04-14 to reproduce and reuse portions of text from `patternlanguage.com` for non-commercial purposes and with proper attribution to Christopher Alexander and *A Pattern Language*. This namespace keeps that guardrail visible.

Use this corpus for private/internal/non-commercial reference, retrieval, critique, education, and design experiments. Do not present it as a commercial-clean training dataset or as unrestricted source material for redistribution.

## Agent Use Contract

- Start with [[summaries/for-agents-spatial-pattern-retrieval|For Agents — Spatial Pattern Retrieval]].
- Retrieve a bounded set of patterns, usually 5–12, before proposing a design.
- Translate pattern Problem/Solution text into constraints, adjacency rules, scale cues, layout moves, and verification checks.
- Cite pattern names/numbers in the design brief so a human can inspect the rationale.
- Avoid quoting long source passages unless the user explicitly needs the source wording.

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/pattern-language/README.md
/raw/pattern-language/wiki/index.md
/wiki/pattern-language/README.md.html
/wiki/pattern-language/wiki/index.md.html
/wiki/pattern-language/llms.txt
```


<!-- ===== pattern-language/wiki/concepts/patterns/a-place-to-wait-150.md ===== -->

---
title: "A Place to Wait (150)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 150
pattern_name: "A Place to Wait"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/A%20Place%20to%20Wait%20%28150%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Interchange (34)"
  - "Health Center (47)"
  - "Small Services Without Red Tape (81)"
  - "Office Connections (82)"
  - "Street Windows (164)"
  - "Window Place (180)"
  - "Street Cafe (88)"
  - "Opening to the Street (165)"
  - "Garden Seat (176)"
  - "Sleeping in Public (94)"
  - "Still Water (71)"
  - "Light on Two Sides of Every Room (159)"
  - "The Shape of Indoor Space (191)"
---

# A Place to Wait (150)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The process of waiting has inherent conflicts in it.

### Solution
>In places where people end up waiting (for a bus, for an appointment, for a plane), create a situation which makes the waiting positive. Fuse the waiting with some other activity—newspaper, coffee, pool tables, horseshoes; something which draws people in who are not simply waiting. And also the opposite: make a place which can draw a person waiting into a reverie; quiet; a positive silence.

### Related Patterns
... in any office, or workshop, or public service, or station, or clinic, where people have to wait - [[Interchange (34)]], [[Health Center (47)]], [[Small Services Without Red Tape (81)]], [[Office Connections (82)]], it is essential to provide a special place for waiting, and doubly essential that this place not have the sordid, enclosed, time-slowed character of ordinary waiting rooms.

The active part might have a window on the street - [[Street Windows (164)]], [[Window Place (180)]], a cafe - [[Street Cafe (88)]], games, positive engagements with the people passing by - [[Opening to the Street (165)]]. The quiet part might have a quiet garden seat - [[Garden Seat (176)]], a place for people to doze [[Sleeping in Public (94)]], perhaps a pond with fish in it - [[Still Water (71)]]. To the extent that this waiting space is a room, or a group of rooms, it gets its detailed shape from [[Light on Two Sides of Every Room (159)]] and [[The Shape of Indoor Space (191)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 707.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/a-room-of-ones-own-141.md ===== -->

---
title: "A Room of One's Own (141)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 141
pattern_name: "A Room of One's Own"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/A%20Room%20of%20One%27s%20Own%20%28141%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Teenager's Cottage (154)"
  - "Old Age Cottage (155)"
  - "Intimacy Gradient (127)"
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "Common Areas at the Heart (129)"
  - "Bed Alcove (188)"
  - "Dressing Rooms (189)"
  - "Home Workshop (157)"
  - "Alcoves (179)"
  - "Workspace Enclosure (183)"
  - "Things From Your Life (253)"
  - "Light on Two Sides of Every Room (159)"
  - "The Shape of Indoor Space (191)"
---

# A Room of One's Own (141)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No one can be close to others, without also having frequent opportunities to be alone.

### Solution
>Give each member of the family a room of their own, especially adults. A minimum room of one’s own is an alcove with a desk, shelves, and curtain. The maximum is a cottage—like a [[Teenager's Cottage (154)]] , or an [[Old Age Cottage (155)]]. In all cases, especially the adult ones, place these rooms at the far ends of the intimacy gradient—far from the common rooms.

### Related Patterns
... the [[Intimacy Gradient (127)]] makes it clear that every house needs rooms where individuals can be alone. In any household which has more than one person, this need is fundamental and essential - [[The Family (75)]], [[House for a Small Family (76)]], [[House for a Couple (77)]]. This pattern, which defines the rooms that people can have to themselves, is the natural counterpart and complement to the social activity provided for in [[Common Areas at the Heart (129)]].

Use this pattern as an antidote to the extremes of "togetherness" created by [[Common Areas at the Heart (129)]]. Even for small children, give them at least an alcove in the communal sleeping area - [[Bed Alcove (188)]]; and for the man and woman, give each of them a separate room, beyond the couples realm they share; it may be an expanded dressing room - [[Dressing Rooms (189)|Dressing Room (189)]], a home workshop - [[Home Workshop (157)]], or once again, an alcove off some other room - [[Alcoves (179)]], [[Workspace Enclosure (183)]] - If there is money for it, it may even be possible to give a person a cottage, attached to the main structure - [[Teenager's Cottage (154)]], [[Old Age Cottage (155)]]. In every case there must at least be room for a desk, a chair, and [[Things From Your Life (253)]]. And for the detailed shape of the room, see [[Light on Two Sides of Every Room (159)]] and [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 668.
> #APL/confidence/high
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/access-to-water-25.md ===== -->

---
title: "Access to Water (25)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 25
pattern_name: "Access to Water"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Access%20to%20Water%20%2825%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sacred Sites (24)"
  - "Promenade (31)"
  - "The Countryside (7)"
  - "Parallel Roads (23)"
  - "Small Parking Lots (103)"
---

# Access to Water (25)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Whether the sacred sites are large or small, whether they are at the center of the towns, in neighborhoods, or in the deepest countryside, establish ordinances which will protect them absolutely—so that our roots in the visible surroundings cannot be violated.

### Solution
>When natural bodies of water occur near human settlements, treat them with great respect. Always preserve a belt of common land, immediately beside the water. And allow dense settlements to come right down to the water only at infrequent intervals along the water’s edge.

### Related Patterns
... Water is always precious. Among the special natural places covered by [[Sacred Sites (24)]], we single out the ocean beaches, lakes, and river banks, because they are irreplaceable. Their maintenance and proper use require a special pattern.

The width of the common land will vary with the types of water and the ecological conditions. In one case, it may be no more than a simple stone promenade along a river bank a few feet wide [[Promenade (31)]]. In another case, it may be a swath of dunes extending hundreds of yards beyond a beach -- [[The Countryside (7)]]. In any case, do not build roads along the water within one mile of the water; instead make all the approach roads at right angles to the edge, and very far apart -- [[Parallel Roads (23)]]. If parking is provided, keep the lots small -- [[Small Parking Lots (103)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 135.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/accessible-green-60.md ===== -->

---
title: "Accessible Green (60)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 60
pattern_name: "Accessible Green"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Accessible%20Green%20%2860%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Work Community (41)"
  - "Subculture Boundary (13)"
  - "Neighborhood Boundary (15)"
  - "Quiet Backs (59)"
  - "Tree Places (171)"
  - "Positive Outdoor Space (106)"
  - "Garden Wall (173)"
  - "Holy Ground (66)"
  - "Grave Sites (70)"
  - "Local Sports (72)"
  - "Animals (74)"
  - "Sleeping in Public (94)"
---

# Accessible Green (60)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People need green open places to go to; when they are close they use them. But if the greens are more than three minutes away, the distance overwhelms the need.

### Solution
>Build one open public green within three minutes’ walk—about 750 feet—of every house and workplace. This means that the greens need to be uniformly scattered at 1,500-foot intervals, through the city. Make the greens at least 150 feet across, and at least 60,000 square feet in area.

### Related Patterns
... at the heart of neighborhoods, and near all work communities, there need to be small greens - [[Identifiable Neighborhood (14)]], [[Work Community (41)]] Of course it makes the most sense to locate these greens in such a way that they help form the boundaries and neighborhoods and backs - [[Subculture Boundary (13)]], [[Neighborhood Boundary (15)]], [[Quiet Backs (59)]].

Pay special attention to old trees, look after them - [[Tree Places (171)]]; shape the green so that it forms one or more positive room-like spaces and surround it with trees, or walls, or buildings, but not roads or cars - [[Positive Outdoor Space (106)]], [[Garden Wall (173)]]; and perhaps set aside some part of the green for special community functions - [[Holy Ground (66)]], [[Grave Sites (70)]], [[Local Sports (72)]], [[Animals (74)]], [[Sleeping in Public (94)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 304.
> #APL/confidence/high
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/activity-nodes-30.md ===== -->

---
title: "Activity Nodes (30)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 30
pattern_name: "Activity Nodes"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Activity%20Nodes%20%2830%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Promenade (31)"
  - "Network of Paths and Cars (52)"
  - "Pedestrian Street (100)"
  - "Community of 7000 (12)"
  - "Subculture Boundary (13)"
  - "Neighborhood Boundary (15)"
  - "Eccentric Nucleus (28)"
  - "Density Rings (29)"
  - "Night Life (33)"
  - "Paths and Goals (120)"
  - "Degrees of Publicness (36)"
  - "Small Public Squares (61)"
  - "Work Community (41)"
  - "University as a Marketplace (43)"
  - "Local Town Hall (44)"
  - "Health Center (47)"
  - "Birth Places (65)"
  - "Teenage Society (84)"
  - "Shopfront Schools (85)"
  - "Individually Owned Shops (87)"
  - "Street Cafe (88)"
  - "Beer Hall (90)"
  - "Food Stands (93)"
---

# Activity Nodes (30)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Community facilities scattered individually through the city do nothing for the life of the city.

### Solution
>Create nodes of activity throughout the community, spread about 300 yards apart. First identify those existing spots in the community where action seems to concentrate itself. Then modify the layout of the paths in the community to bring as many of them through these spots as possible. This makes each spot function as a “node” in the path network. Then, at the center of each node, make a small public square, and surround it with a combination of community facilities and shops which are mutually supportive.

### Related Patterns
... this pattern forms those essential nodes of life which help to generate [[Identifiable Neighborhood (14)]], [[Promenade (31)]], [[Network of Paths and Cars (52)]], and [[Pedestrian Street (100)]]. To understand its action, imagine that a community and its boundary are growing under the influence of [[Community of 7000 (12)]], [[Subculture Boundary (13)]], [[Identifiable Neighborhood (14)]], [[Neighborhood Boundary (15)]], [[Eccentric Nucleus (28)]], and [[Density Rings (29)]]. As they grow, certain "stars" begin to form, where the most important paths meet. These stars are potentially vital spots of a community. The growth of these stars and of the paths which form them need to be guided to form genuine community crossroads.

Connect those centers which are most dense, with a wider, more important path for strolling -- [[Promenade (31)]]; make special centers for night activities -- [[Night Life (33)]]; whenever new paths are built, make certain that they pass through the centers, so that they intensify the life still further -- [[Paths and Goals (120)]]; and differentiate the paths so they are wide near the centers and smaller away from them -- [[Degrees of Publicness (36)]]. At the heart of every center, build a small public square -- [[Small Public Squares (61)]], and surround each square with an appropriate mix of mutually self-reinforcing facilities -- [[Work Community (41)]], [[University as a Marketplace (43)]], [[Local Town Hall (44)]], [[Health Center (47)]], [[Birth Places (65)]], [[Teenage Society (84)]], [[Shopfront Schools (85)]], [[Individually Owned Shops (87)]], [[Street Cafe (88)]], [[Beer Hall (90)]], [[Food Stands (93)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 163.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/activity-pockets-124.md ===== -->

---
title: "Activity Pockets (124)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 124
pattern_name: "Activity Pockets"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Activity%20Pockets%20%28124%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Promenade (31)"
  - "Small Public Squares (61)"
  - "Public Outdoor Room (69)"
  - "Pedestrian Street (100)"
  - "Building Thoroughfare (101)"
  - "Path Shape (121)"
  - "Paths and Goals (120)"
  - "Arcades (119)"
  - "Outdoor Room (163)"
  - "Trellised Walk (174)"
  - "Seat Spots (241)"
  - "Sitting Wall (243)"
  - "Building Fronts (122)"
  - "Bus Stop (92)"
  - "Food Stands (93)"
  - "Street Cafe (88)"
  - "A Place to Wait (150)"
---

# Activity Pockets (124)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The life of a public square forms naturally around its edge. If the edge fails, then the space never becomes lively.

### Solution
>Surround public gathering places with pockets of activity—small, partly enclosed areas at the edges, which jut forward into the open space between the paths, and contain activities which make it natural for people to pause and get involved.

### Related Patterns
... in many large scale patterns which define public space, the edge is critical: [[Promenade (31)]], [[Small Public Squares (61)]], [[Public Outdoor Room (69)]], [[Pedestrian Street (100)]], [[Building Thoroughfare (101)]], [[Path Shape (121)]]. This pattern helps complete the edge of all these larger patterns.

Lead paths between the pockets of activity - [[Paths and Goals (120)]] - and shape the pockets themselves with arcades and seats, and sitting walls, and columns and trellises - [[Arcades (119)]], [[Outdoor Room (163)]], [[Trellised Walk (174)]], [[Seat Spots (241)]], [[Sitting Wall (243)]]; above all shape them with the fronts of buildings - [[Building Fronts (122)]]; and include, within the pockets, newsstands - [[Bus Stop (92)]], [[Food Stands (93)]], gardens, games, small shops, [[Street Cafe (88)]], and [[A Place to Wait (150)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 599.
> #APL/confidence/high
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/adventure-playground-73.md ===== -->

---
title: "Adventure Playground (73)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 73
pattern_name: "Adventure Playground"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Adventure%20Playground%20%2873%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Land (67)"
  - "Connected Play (68)"
  - "Sunny Place (161)"
  - "Bike Paths and Racks (56)"
  - "Garden Growing Wild (172)"
  - "Child Caves (203)"
  - "Garden Wall (173)"
  - "Sitting Wall (243)"
---

# Adventure Playground (73)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A castle, made of cartons, rocks, and old branches, by a group of children for themselves, is worth a thousand perfectly detailed, exactly finished castles, made for them in a factory.

### Solution
>Set up a playground for the children in each neighborhood. Not a highly finished playground, with asphalt and swings, but a place with raw materials of all kinds—nets, boxes, barrels, trees, ropes, simple tools, frames, grass, and water—where children can create and re-create playgrounds of their own.

### Related Patterns
... inside the local neighborhood, even if there is common land where children can meet and play - [[Common Land (67)]], [[Connected Play (68)]]; it is essential that there be at least one smaller part, which is differentiated, where the play is wilder, and where the children have access to all kinds of junk.

Make sure that the adventure playground is in the sun - [[Sunny Place (161)]] ; make hard surfaces for bikes and carts and toy trucks and trolleys, and soft surfaces for mud and building things - [[Bike Paths and Racks (56)]], [[Garden Growing Wild (172)]], [[Child Caves (203)]] ; and make the boundary substantial with a [[Garden Wall (173)]] or [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 367.
> #APL/confidence/low
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/agricultural-valleys-4.md ===== -->

---
title: "Agricultural Valleys (4)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 4
pattern_name: "Agricultural Valleys"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Agricultural%20Valleys%20%284%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Independent Regions (1)"
  - "City Country Fingers (3)"
  - "The Countryside (7)"
---

# Agricultural Valleys (4)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The land which is best for agriculture happens to be best for buildings too. But it is limited--and once destroyed, it cannot be regained for centuries.

### Solution
>Preserve all agricultural valleys as farmland and protect this land from any development which would destroy or lock up the unique fertility of the soil. Even when valleys are not cultivated now, protect them: keep them for farms and parks and wilds.

### Related Patterns
... this pattern helps maintain the [[Independent Regions (1)]] by making regions more self-sufficient agriculturally; and it will create [[City Country Fingers (3)]] almost automatically by preserving agricultural land in urban areas. But just exactly which land ought to be preserved, and which land will be built upon?

Keep town and city development along the hilltops and hillsides -- [[City Country Fingers (3)]]. And in the valleys, treat the ownership of the land as a form of stewardship, embracing basic ecological responsibilities -- [[The Countryside (7)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 26.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/alcoves-179.md ===== -->

---
title: "Alcoves (179)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 179
pattern_name: "Alcoves"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Alcoves%20%28179%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "Farmhouse Kitchen (139)"
  - "Sequence of Sitting Spaces (142)"
  - "Flexible Office Space (146)"
  - "A Place to Wait (150)"
  - "Small Meeting Rooms (151)"
  - "Ceiling Height Variety (190)"
  - "Half-Open Wall (193)"
  - "Column Place (226)"
  - "Window Place (180)"
  - "Built-in Seats (202)"
  - "Thickening the Outer Walls (211)"
  - "The Shape of Indoor Space (191)"
---

# Alcoves (179)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No homogeneous room, of homogeneous height, can serve a group of people well. To give a group a chance to be together, as a group, a room must also give them the chance to be alone, in one’s and two’s in the same space.

### Solution
>Make small places at the edge of any common room, usually no more than 6 feet wide and 3 to 6 feet deep and possibly much smaller. These alcoves should be large enough for two people to sit, chat, or play and sometimes large enough to contain a desk or a table.

### Related Patterns
... many large rooms are not complete unless they have smaller rooms and alcoves opening off them. This pattern, and several which follow it, define the form of minor rooms and alcoves which help to complete [[Common Areas at the Heart (129)]], [[Farmhouse Kitchen (139)]], [[Sequence of Sitting Spaces (142)]], [[Flexible Office Space (146)]], [[A Place to Wait (150)]], [[Small Meeting Rooms (151)]], and many others.

Give the alcove a ceiling which is markedly lower than the ceiling height in the main room - [[Ceiling Height Variety (190)]]; make a partial boundary between the alcove and the common room by using low walls and thick columns - [[Half-Open Wall (193)]], [[Column Place (226)]]; when the alcove is on an outside wall, make it into a window place, with a nice window, low sill, and a built-in seat - [[Window Place (180)]], [[Built-in Seats (202)]]; and treat it as [[Thickening the Outer Walls (211)]]. For details on the shape of the alcove, see [[The Shape of Indoor Space (191)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 828.
> #APL/confidence/high
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/animals-74.md ===== -->

---
title: "Animals (74)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 74
pattern_name: "Animals"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Animals%20%2874%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Land (67)"
  - "Your Own Home (79)"
  - "Green Streets (51)"
  - "Accessible Green (60)"
  - "Children's Home (86)"
  - "Compost (178)"
---

# Animals (74)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Animals are as important a part of nature as the trees and grass and flowers. There is some evidence, in addition, which suggests that contact with animals may play a vital role in a child’s emotional development.

### Solution
>Make legal provisions which allow people to keep any animals on their private lots or in private stables. Create a piece of fenced and protected common land, where animals are free to graze, with grass, trees, and water in it. Make at least one system of movement in the neighborhood which is entirely asphalt-free—where dung can fall freely without needing to be cleaned up.

### Related Patterns
... even when there is public land and private land for individual buildings - [[Common Land (67)]], [[Your Own Home (79)]], there is no guarantee that animals can flourish there. This pattern helps to form [[Green Streets (51)]] and [[Common Land (67)]] by giving them the qualities they need to sustain animal life.

Make sure that the green areas - [[Green Streets (51)]], [[Accessible Green (60)]] - are all connected to one another to form a continuous swath throughout the city for domestic and wild animals. Place the animal commons near a children's home and near the local schools, so children can take care of the animals - [[Children's Home (86)]]; if there is a lot of dung, make sure that it can be used as a fertilizer - [[Compost (178)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 371.
> #APL/confidence/low
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/arcades-119.md ===== -->

---
title: "Arcades (119)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 119
pattern_name: "Arcades"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Arcades%20%28119%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Cascade of Roofs (116)"
  - "Pedestrian Street (100)"
  - "Connected Buildings (108)"
  - "Circulation Realms (98)"
  - "Ceiling Height Variety (190)"
  - "Sheltering Roof (117)"
  - "Column Place (226)"
  - "Low Doorway (224)"
  - "Column Connections (227)"
  - "Building Edge (160)"
  - "Half-Open Wall (193)"
  - "Structure Follows Social Spaces (205)"
  - "Thickening the Outer Walls (211)"
---

# Arcades (119)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Arcades—covered walkways at the edge of buildings, which are partly inside, partly outside—play a vital role in the way that people interact with buildings.

### Solution
>Wherever paths run along the edge of buildings, build arcades, and use the arcades, above all, to connect up the buildings to one another, so that a person can walk from place to place under the cover of the arcades.

### Related Patterns
... the [[Cascade of Roofs (116)]] may be completed by arcades. Paths along the building, short paths between buildings, [[Pedestrian Street (100)]], paths between [[Connected Buildings (108)]], and parts of [[Circulation Realms (98)]] are all best as arcades. This is one of the most beautiful patterns in the language; it affects the total character of buildings as few other patterns do.

Keep the arcade low - [[Ceiling Height Variety (190)]]; bring the roof of the arcade as low as possible - [[Sheltering Roof (117)]]; make the columns thick enough to lean against - [[Column Place (226)]]; and make the openings between columns narrow and low - [[Low Doorway (224)]], [[Column Connections (227)]] either by arching them or by making deep beams or with lattice work - so that the inside feels enclosed - [[Building Edge (160)]], [[Half-Open Wall (193)]]. For construction see [[Structure Follows Social Spaces (205)]] and [[Thickening the Outer Walls (211)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 580.
> #APL/confidence/high
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/bathing-room-144.md ===== -->

---
title: "Bathing Room (144)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 144
pattern_name: "Bathing Room"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bathing%20Room%20%28144%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Common Areas at the Heart (129)"
  - "Couple's Realm (136)"
  - "Children's Realm (137)"
  - "Sleeping to the East (138)"
  - "Bed Cluster (143)"
  - "Light on Two Sides of Every Room (159)"
  - "Filtered Light (238)"
  - "Garden Wall (173)"
  - "Still Water (71)"
  - "Compost (178)"
  - "The Shape of Indoor Space (191)"
---

# Bathing Room (144)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem

    “The motions we call bathing are mere ablutions which formerly preceded the bath. The place where they are performed, though adequate for the routine, does not deserve to be called a bathroom.”

    — Bernard Rudofsky

### Solution
>Concentrate the bathing room, toilets, showers, and basins of the house in a single tiled area. Locate this bathing room beside the couple’s realm—with private access—in a position halfway between the private secluded parts of the house and the common areas; if possible, give it access to the outdoors; perhaps a tiny balcony or walled garden.
>Put in a large bath—large enough for at least two people to get completely immersed in water; an efficiency shower and basins for the actual business of cleaning; and two or three racks for huge towels—one by the door, one by the shower, one by the sink.

### Related Patterns
... this pattern defines and places the main bathroom of a building. It does it by changing the present character of bathing rooms completely: And its position is so clear, and so essential, that it will probably help to form the sleeping areas and public areas given by larger patterns: [[Intimacy Gradient (127)]], [[Common Areas at the Heart (129)]], [[Couple's Realm (136)]], [[Children's Realm (137)]], [[Sleeping to the East (138)]], [[Bed Cluster (143)]].

Above all, make sure that there is light, plenty of light - [[Light on Two Sides of Every Room (159)]] and [[Filtered Light (238)]]; try to place the bathing room so that it opens out into a private part of the garden - [[Garden Wall (173)]], and perhaps even gives direct access to some local swimming pool - [[Still Water (71)]]. Line up the toilet with the compost chamber - [[Compost (178)]]; and for the detailed shape of the room and its construction, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 681.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/bed-alcove-188.md ===== -->

---
title: "Bed Alcove (188)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 188
pattern_name: "Bed Alcove"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bed%20Alcove%20%28188%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Bed Cluster (143)"
  - "Communal Sleeping (186)"
  - "Marriage Bed (187)"
  - "A Room of One's Own (141)"
  - "Ceiling Height Variety (190)"
  - "Thick Walls (197)"
  - "Open Shelves (200)"
  - "Natural Doors and Windows (221)"
  - "Half-Open Wall (193)"
  - "Dressing Rooms (189)"
  - "The Shape of Indoor Space (191)"
---

# Bed Alcove (188)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Bedrooms make no sense.

### Solution
>Don’t put single beds in empty rooms called bedrooms, but instead put individual bed alcoves off rooms with other nonsleeping functions, so the bed itself becomes a tiny private haven.
>If you are building a very small house no more than 300 or 400 square feet—perhaps with the idea of adding to it gradually—this pattern plays an essential role. It will probably be best then to put the alcoves off the family room.

### Related Patterns
... bed alcoves help to generate the form of [[Bed Cluster (143)]], [[Communal Sleeping (186)]] and [[Marriage Bed (187)]] For children, each alcove also functions as [[A Room of One's Own (141)]], so that even in the smallest house, not only the adults, but every child can have at least a small place to call his own.

Build the ceiling low - [[Ceiling Height Variety (190)]]; add some storage in the walls around the alcove - [[Thick Walls (197)]], [[Open Shelves (200)]], and a window, in a natural position - [[Natural Doors and Windows (221)]]. Perhaps [[Half-Open Wall (193)]] will help to give the alcove the right enclosure. Where space is very tight, combine the bed alcove with [[Dressing Rooms (189)|Dressing Room (189)]]. And finally, give each alcove, no matter how small, the characteristics of any indoor space - [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 868.
> #APL/confidence/high
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/bed-cluster-143.md ===== -->

---
title: "Bed Cluster (143)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 143
pattern_name: "Bed Cluster"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bed%20Cluster%20%28143%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Couple's Realm (136)"
  - "Children's Realm (137)"
  - "Sleeping to the East (138)"
  - "Communal Sleeping (186)"
  - "Bed Alcove (188)"
  - "Dressing Rooms (189)"
  - "Closets Between Rooms (198)"
  - "Child Caves (203)"
  - "Light on Two Sides of Every Room (159)"
  - "The Shape of Indoor Space (191)"
---

# Bed Cluster (143)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Every child in the family needs a private place, generally centered around the bed. But in many cultures, perhaps all cultures, young children feel isolated if they sleep alone, if their sleeping area is too private.

### Solution
>Place the children’s beds in alcoves or small alcove-like rooms, around a common playspace. Make each alcove large enough to contain a table, or chair, or shelves—at least some floor area, where each child has their own things. Give the alcoves curtains looking into the common space, but not walls or doors, which will tend once more to isolate the beds too greatly.

### Related Patterns
... the sleeping areas have been defined to be inside the [[Couple's Realm (136)]] and [[Children's Realm (137)]]. Beyond that, they are in places facing east to get the morning light - [[Sleeping to the East (138)]]. This pattern defines the grouping of the beds within the sleeping areas, and also helps to generate the general sleeping areas themselves.

Another version of this pattern, more suitable for adults, is given by [[Communal Sleeping (186)]]. In both cases, build the individual alcoves according to [[Bed Alcove (188)]]; if the cluster is for children, shape the playspace in the middle according to the specifications of [[Children's Realm (137)]], and make the path which leads from the beds, past the kitchen, to the outdoors, according to that pattern too. Use the location of dressing areas and closets to help shape the bed cluster and the individual alcoves - [[Dressing Rooms (189)|Dressing Room (189)]], [[Closets Between Rooms (198)]]; include some tiny nooks and crannies - [[Child Caves (203)]]. Give the entire space [[Light on Two Sides of Every Room (159)]]. And for the shape of this space in more detail and its construction, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 676.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/beer-hall-90.md ===== -->

---
title: "Beer Hall (90)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 90
pattern_name: "Beer Hall"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Beer%20Hall%20%2890%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Neighborhood Boundary (15)"
  - "Promenade (31)"
  - "Night Life (33)"
  - "Alcoves (179)"
  - "The Fire (181)"
  - "Ceiling Height Variety (190)"
  - "Building Complex (95)"
---

# Beer Hall (90)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Where can people sing, and drink, and shout, and let go of their sorrows?

### Solution
>Somewhere in the community at least one big place where a few hundred people can gather, with beer and wine, music, and perhaps a half-dozen activities, so that people are continually criss-crossing from one to another.

### Related Patterns
... in an occasional neighborhood, which functions as the focus of a group of neighborhoods, or in a boundary between neighborhoods - [[Neighborhood Boundary (15)]] - or on the promenade which forms the focus of a large community - [[Promenade (31)]], [[Night Life (33)]] - there is a special need for something larger and more raucous than a street cafe.

Put the tables in two-ended alcoves, roomy enough for people to pass through on their way between activities - [[Alcoves (179)]]; provide a fire, as the hub of one activity - [[The Fire (181)]]; and a variety of ceiling heights to correspond to different social groupings - [[Ceiling Height Variety (190)]]. For the shape of the building, gardens, parking, and surroundings, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 444.
> #APL/confidence/low
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/bike-paths-and-racks-56.md ===== -->

---
title: "Bike Paths and Racks (56)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 56
pattern_name: "Bike Paths and Racks"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bike%20Paths%20and%20Racks%20%2856%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Looped Local Roads (49)"
  - "Network of Paths and Cars (52)"
  - "Main Entrance (110)"
  - "Arcades (119)"
  - "Quiet Backs (59)"
  - "Garden Wall (173)"
---

# Bike Paths and Racks (56)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Bikes are cheap, healthy, and good for the environment; but the environment is not designed for them. Bikes on roads are threatened by cars; bikes on paths threaten pedestrians.

### Solution
>Build a system of paths designated as bike paths, with the following special properties: the bike paths are marked clearly with a special, easily recognizable surface (for example, a red asphalt surface). As far as possible they run along local roads, or major pedestrian paths. Where a bike path runs along a local road, its surface may be level with the road—if possible, on the sunny side; where a bike path runs along a pedestrian path, keep it separate from that path and a few inches below it. Bring the system of bike paths to within 100 feet of every building, and give every building a bike rack near its main entrance.

### Related Patterns
... within a [[Local Transport Areas (11)]] there is a heavy concentration of small vehicles like bikes, electric carts, perhaps even horses, which need a system of bike paths. The bike paths will play a very large role in helping to create the local transport areas, and may also help to modify [[Looped Local Roads (49)]] and [[Network of Paths and Cars (52)]].

Build the racks for bikes to one side of the main entrance, so that the bikes don't interfere with people's natural movement in and out -- [[Main Entrance (110)]], and give it some shelter, with the path from the racks to the entrance also under shelter -- [[Arcades (119)]]; keep the bikes out of quiet walks and quiet gardens -- [[Quiet Backs (59)]], [[Garden Wall (173)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 289.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/birth-places-65.md ===== -->

---
title: "Birth Places (65)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 65
pattern_name: "Birth Places"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Birth%20Places%20%2865%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "Life Cycle (26)"
  - "Common Areas at the Heart (129)"
  - "Couple's Realm (136)"
  - "Farmhouse Kitchen (139)"
  - "Half-Hidden Garden (111)"
  - "Garden Wall (173)"
  - "Building Complex (95)"
---

# Birth Places (65)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>It seems unlikely that any process which treats childbirth as a sickness could possibly be a healthy part of a healthy society.

### Solution
>Build local birth places where women go to have their children: places that are specially tailored to childbirth as a natural, eventful moment—where the entire family comes for prenatal care and education; where fathers and midwives help during the hours of labor and birth.

### Related Patterns
... both birth and death need recognition throughout society where people are, as part of local communities and neighborhoods - [[Community of 7000 (12)]], [[Identifiable Neighborhood (14)]], [[Life Cycle (26)]]. As far as birth is concerned, each group of neighborhoods must be able to take care of the birth process, in local, human terms. (Note: The development of this pattern is due largely to the work of Judith Shaw, at this writing a graduate student in architecture at the University of California, Berkeley, and a mother of three children.)

Include rooms where after the birth the mother and her baby can stay together with the other members of the family - sleep together, eat together, cook together - [[Common Areas at the Heart (129)]], [[Couple's Realm (136)]], [[Farmhouse Kitchen (139)]] ; provide a partly private garden to walk in - [[Half-Hidden Garden (111)]], [[Garden Wall (173)]]; for the shape of the building, gardens, parking, and surroundings, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 328.
> #APL/confidence/low
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/box-columns-216.md ===== -->

---
title: "Box Columns (216)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 216
pattern_name: "Box Columns"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Box%20Columns%20%28216%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Root Foundations (214)"
  - "Final Column Distribution (213)"
  - "Floor-Ceiling Vaults (219)"
  - "Perimeter Beams (217)"
  - "Column Connections (227)"
  - "Column Place (226)"
---

# Box Columns (216)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In all the world’s traditional and historic buildings, the columns are expressive, beautiful, and treasured elements. Only in modern buildings have they become ugly and meaningless.

### Solution
>Make the columns in the form of filled hollow tubes, with a stiff tubular outer skin, and a solid core that is strong in compression. Give the skin of the column some tensile strength—preferably in the skin itself, but perhaps with reinforcing wires in the fill.

### Related Patterns
... if you use [[Root Foundations (214)]], the columns must be made at the same time as the foundations, since the foundation and the column are integral. The height, spacing, and thickness of the various columns in the building are given by [[Final Column Distribution (213)]]. This pattern describes the details of construction for the individual columns.

 As you already know, it is best to build the columns integral with [[Root Foundations (214)]] on the ground floor, or integral with the [[Floor-Ceiling Vaults (219)]] on upper floors, and to fill them in one continuous pour. Once the columns are in position, put in the [[Perimeter Beams (217)]], and fill the beams at the same time that you fill the upper part of the column. If the column is free standing, put in column braces or column capitals - [[Column Connections (227)]] - to brace the connection between the two. And make the columns especially thick, or build them in pairs, where they are free-standing, so that they form a [[Column Place (226)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1012.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/building-complex-95.md ===== -->

---
title: "Building Complex (95)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 95
pattern_name: "Building Complex"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Building%20Complex%20%2895%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Long Thin House (109)"
  - "Building Fronts (122)"
  - "Main Entrance (110)"
  - "Arcades (119)"
  - "Circulation Realms (98)"
  - "Main Building (99)"
  - "Site Repair (104)"
  - "South Facing Outdoors (105)"
  - "Wings of Light (107)"
  - "Structure Follows Social Spaces (205)"
---

# Building Complex (95)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A building cannot be a human building unless it is a complex of still smaller buildings or smaller parts which manifest its own internal social facts.

### Solution
>Never build monolithic buildings. Whenever possible translate your building program into a building complex, whose parts manifest the actual social facts of the situation. At low densities, a building complex may take the form of a collection of small buildings connected by arcades, paths, bridges, shared gardens, and walls.
>At higher densities, a single building can be treated as a building complex, if its important parts are picked out and made identifiable while still part of one three-dimensional fabric.
>Even a small building, a house for example, can be conceived as a "building complex"—perhaps part of it is higher than the rest with wings and an adjoining cottage.

### Related Patterns
... this pattern, the first of the 130 patterns which deal specifically with buildings, is the bottleneck through which all languages pass from the social layouts of the earlier patterns to the smaller ones which define individual spaces.

At the highest densities, 3 or 4 stories, and along pedestrian streets, break the buildings into narrow, tall separate buildings, side by side, with common walls, each with its own internal or external stair. As far as possible insist that they be built piecemeal, one at a time, so that each one has time to be adapted to its neighbor. Keep the frontage as low as 25 or 30 feet. [[Long Thin House (109)]], [[Building Fronts (122)]]; [[Main Entrance (110)]] and perhaps a part of an [[Arcades (119)]] which connects to next door buildings.

Arrange the buildings in the complex to form realms of movement - [[Circulation Realms (98)]]; build one building from the collection as a main building - the natural center of the site [[Main Building (99)]]; place individual buildings where the land is least beautiful, least healthy - [[Site Repair (104)]]; and put them to the north of their respective open space to keep the gardens sunny - [[South Facing Outdoors (105)]]; subdivide them further, into narrow wings, no more than 25 or 30 feet across [[Wings of Light (107)]]. For details of construction, start with [[Structure Follows Social Spaces (205)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 468.
> #APL/confidence/high
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/building-edge-160.md ===== -->

---
title: "Building Edge (160)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 160
pattern_name: "Building Edge"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Building%20Edge%20%28160%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Light on Two Sides of Every Room (159)"
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Arcades (119)"
  - "Outdoor Room (163)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Connection to the Earth (168)"
  - "Sunny Place (161)"
  - "North Face (162)"
  - "Stair Seats (125)"
  - "Street Windows (164)"
  - "Seat Spots (241)"
  - "Front Door Bench (242)"
---

# Building Edge (160)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A building is most often thought of as something which turns inward—toward its rooms. People do not often think of a building as something which must also be oriented toward the outside.

### Solution
>Make sure that you treat the edge of the building as a "thing", a "place", a zone with volume to it, not a line or interface which has no thickness. Crenelate the edge of buildings with places that invite people to stop. Make places that have depth and a covering, places to sit, lean, and walk, especially at those points along the perimeter which look onto interesting outdoor life.

### Related Patterns
... assume that the position of the building edge is fixed - most recently by [[Light on Two Sides of Every Room (159)]] - and before that by the position of the building wings and their interior spaces and by the courts and gardens and streets between the buildings - [[Wings of Light (107)]], [[Positive Outdoor Space (106)]]. This pattern now sets the stage for the development of the zone between the indoors and the outdoors. Often this "zone" is thought of as an edge, a line on paper without thickness, a wall. But this is altogether wrong ...

Do it with arcades, galleries, porches, and terraces [[Arcades (119)]], [[Outdoor Room (163)]] , [[Gallery Surround (166)]], [[Six-Foot Balcony (167)]], [[Connection to the Earth (168)]]; take special account of the sun - [[Sunny Place (161)]], [[North Face (162)]]; and put in seats and windows which complete the feeling of connection - [[Stair Seats (125)]], [[Street Windows (164)]], [[Seat Spots (241)]], [[Front Door Bench (242)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 752.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/building-fronts-122.md ===== -->

---
title: "Building Fronts (122)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 122
pattern_name: "Building Fronts"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Building%20Fronts%20%28122%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Arcades (119)"
  - "Path Shape (121)"
  - "Activity Pockets (124)"
  - "Building Edge (160)"
  - "Private Terrace on the Street (140)"
  - "Gallery Surround (166)"
  - "Stair Seats (125)"
  - "Open Stairs (158)"
  - "Street Windows (164)"
  - "Opening to the Street (165)"
  - "Front Door Bench (242)"
---

# Building Fronts (122)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Building set-backs from the street, originally invented to protect the public welfare by giving every building light and air, have actually helped greatly to destroy the street as a social space.

### Solution
>On no account allow set-backs between streets or paths or public open land the the buildings which front on them. The set-backs do nothing valuable and almost always destroy the value of the open areas between the buildings. Build right up to the paths; change the laws in all communities where obsolete by-laws make this impossible. And let the building fronts take on slightly uneven angles as they accommodate to the shape of the street.

### Related Patterns
... this pattern helps to shape the paths and buildings simultaneously; and so completes [[Building Complex (95)]], [[Wings of Light (107)]], [[Positive Outdoor Space (106)]], [[Arcades (119)]], [[Path Shape (121)]], and also [[Activity Pockets (124)]].

Detail the fronts of buildings, indeed the whole building perimeter, according to the pattern [[Building Edge (160)]]. If some outdoor space is needed at the front of the building, make it part of the street life by making it a [[Private Terrace on the Street (140)]] or [[Gallery Surround (166)]]; and give the building many openings onto the street - [[Stair Seats (125)]], [[Open Stairs (158)]], [[Street Windows (164)]], [[Opening to the Street (165)]], [[Front Door Bench (242)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 593.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/building-thoroughfare-101.md ===== -->

---
title: "Building Thoroughfare (101)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 101
pattern_name: "Building Thoroughfare"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Building%20Thoroughfare%20%28101%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Pedestrian Street (100)"
  - "Circulation Realms (98)"
  - "Building Complex (95)"
  - "Open Stairs (158)"
  - "Family of Entrances (102)"
  - "Activity Pockets (124)"
  - "Reception Welcomes You (149)"
  - "Window Place (180)"
  - "Ceiling Height Variety (190)"
  - "Tapestry of Light and Dark (135)"
  - "Interior Windows (194)"
  - "Solid Doors with Glass (237)"
  - "Pedestrian Density (123)"
---

# Building Thoroughfare (101)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When a public building complex cannot be completely served by outdoor pedestrian streets, a new form of indoor street, quite different from the conventional corridor, is needed.

### Solution
>Wherever density or climate force the main lines of circulation indoors, build them as building thoroughfares. Place each thoroughfare in a position where it functions as a shortcut, as continuous as possible with the public street outside, with wide open entrances. And line its edges with windows, places to sit, counters, and entrances which project out into the hall and expose the buildings’ main functions to the public. Make it wider than a normal corridor—at least 11 feet wide and more usually, 15 to 20 feet wide; give it a high ceiling, at least 15 feet, with a glazed roof if possible and low places along the edge. If the street is several stories high, then the walkways along the edges, on the different stories, can be used to form the low places.

### Related Patterns
... if the building complex is built at high density, then at least part of the circulation cannot be made of outdoor [[Pedestrian Street (100)]] because the buildings cover too much of the land; in this case, the main spines of the [[Circulation Realms (98)]] must take the form of building thoroughfares similar to pedestrian streets, but partly or wholly inside the buildings. Building thoroughfares replace the terrible corridors which destroy so much of modern building, and help to generate the indoor layout of a [[Building Complex (95)]].

Treat the thoroughfare as much like a [[Pedestrian Street (100)]] as possible, with [[Open Stairs (158)]] coming into it from upper storys. Place entrances, reception points, and seats to form the pockets of activity under the lower ceilings at the edges [[Family of Entrances (102)]], [[Activity Pockets (124)]], [[Reception Welcomes You (149)]], [[Window Place (180)]], [[Ceiling Height Variety (190)]], and give these places strong natural light - [[Tapestry of Light and Dark (135)]]. Make a connection to adjacent rooms with [[Interior Windows (194)]] and [[Solid Doors with Glass (237)]]. To give the building thoroughfare the proper sense of liveliness, calculate its overall size according to [[Pedestrian Density (123)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 492.
> #APL/confidence/low
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/built-in-seats-202.md ===== -->

---
title: "Built-in Seats (202)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 202
pattern_name: "Built-in Seats"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Built-in%20Seats%20%28202%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sequence of Sitting Spaces (142)"
  - "Entrance Room (130)"
  - "Alcoves (179)"
  - "Window Place (180)"
  - "Thick Walls (197)"
  - "Thickening the Outer Walls (211)"
---

# Built-in Seats (202)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Built-in seats are great. Everybody loves them. They make a building feel comfortable and luxurious. But most often they do not actually work. They are placed wrong, or too narrow, or the back does not slope, or the view is wrong, or the seat is too hard. This pattern tells you what to do to make a built-in seat that really works.

### Solution
>Before you build the seat, get hold of an old arm chair or a sofa, and put it into the position where you intend to build a seat. Move it until you really like it. Leave it there for a few days. See if you enjoy sitting in it. Move it if you don’t. When you have got it into a position which you like, and where you often find yourself sitting, you know it is a good position. Now build a seat that is just as wide, and just as well-padded—and your built-in seat will work.

### Related Patterns
... throughout the building - [[Sequence of Sitting Spaces (142)]] - there are alcoves, entrances, corners, and windows where it is natural to make built-in seats - [[Entrance Room (130)]], [[Alcoves (179)]], [[Window Place (180)]]. This pattern helps complete them.

Once you decide where to put the seat, make it part of the [[Thick Walls (197)]], so that it is a part of the structure, not just an addition - [[Thickening the Outer Walls (211)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 924.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/bulk-storage-145.md ===== -->

---
title: "Bulk Storage (145)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 145
pattern_name: "Bulk Storage"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bulk%20Storage%20%28145%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House for a Small Family (76)"
  - "Self-Governing Workshops and Offices (80)"
  - "Individually Owned Shops (87)"
  - "Building Complex (95)"
  - "Sheltering Roof (117)"
  - "Terraced Slope (169)"
  - "Ground Floor Slab (215)"
  - "Rooms to Rent (153)"
  - "North Face (162)"
---

# Bulk Storage (145)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In houses and workplaces there is always some need for bulk storage space; a place for things like suitcases, old furniture, old files, boxes—all those things which you are not ready to throw away, and yet not using every day.

### Solution
>Do not leave bulk storage till last or forget it. Include a volume for bulk storage in the building—its floor area at least 15 to 20 percent of the whole building area—not less. Place this storage somewhere in the building where it costs less than other rooms—because, of course, it doesn’t need a finish.

### Related Patterns
... this pattern helps to complete any [[House for a Small Family (76)]], [[Self-Governing Workshops and Offices (80)]], and [[Individually Owned Shops (87)]]. More generally, it is needed to fill out every [[Building Complex (95)]].

Put the storage in the apex of the roof if the roof has a steep pitch - [[Sheltering Roof (117)]]; if there is a sloping site, put it in a basement - [[Terraced Slope (169)]], [[Ground Floor Slab (215)]]; otherwise, put it in a shed which can perhaps be made into a cottage later - [[Rooms to Rent (153)]]. No matter whether it is an attic, cellar, or shed, it is usually good advice to follow [[North Face (162)]] and situate bulk storage to the north of the building, leaving the sunny, spaces for rooms and gardens ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 687.
> #APL/confidence/low
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/bus-stop-92.md ===== -->

---
title: "Bus Stop (92)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 92
pattern_name: "Bus Stop"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Bus%20Stop%20%2892%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mini-Buses (20)"
  - "Main Gateways (53)"
  - "Public Outdoor Room (69)"
  - "Path Shape (121)"
  - "A Place to Wait (150)"
  - "Food Stands (93)"
  - "Seat Spots (241)"
---

# Bus Stop (92)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Bus stops must be easy to recognize, and pleasant, with enough activity around them to make people comfortable and safe.

### Solution
>Build bus stops so that they form tiny centers of public life. Build them as part of the gateways into neighborhoods, work communities, parts of town. Locate them so that they work together with several other activities, at least a newsstand, maps, outdoor shelter, seats, and in various combinations, corner groceries, smoke shops, coffee bar, tree places, special road crossings, public bathrooms, squares…

### Related Patterns
... within a town whose public transportation is based on [[Mini-Buses (20)]], genuinely able to serve people, almost door to door, for a low price, and very fast, there need to be bus stops within a few hundred feet of every house and workplace. This pattern gives the form of the bus stops ...

Make a full gateway to the neighborhood next to the bus stop, or place the bus stop where the best gateway is already - [[Main Gateways (53)]]; treat the physical arrangement according to the patterns for [[Public Outdoor Room (69)]], [[Path Shape (121)]], and [[A Place to Wait (150)]]; provide a [[Food Stands (93)]]: place the seats according to sun, wind protection, and view - [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 451.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/canvas-roofs-244.md ===== -->

---
title: "Canvas Roofs (244)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 244
pattern_name: "Canvas Roofs"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Canvas%20Roofs%20%28244%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Roof Garden (118)"
  - "Arcades (119)"
  - "Private Terrace on the Street (140)"
  - "Outdoor Room (163)"
  - "Gallery Surround (166)"
  - "Trellised Walk (174)"
  - "Window Place (180)"
  - "Small Parking Lots (103)"
  - "Filtered Light (238)"
  - "Ornament (249)"
  - "Warm Colors (250)"
---

# Canvas Roofs (244)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There is a very special beauty about tents and canvas awnings. The canvas has a softness, a suppleness, which is in harmony with wind and light and sun. A house or any buildings built with some canvas will touch all the elements more nearly than it can when it is made only with hard conventional materials.

### Solution
>Build canvas roofs and walls and awnings wherever there are spaces which need softer light or partial shade in summer, or partial protection from mist and dew in autumn and winter. Build them to fold away, with ropes or wires to pull them, so that they can easily be opened.

### Related Patterns
... around every building there are [[Roof Garden (118)]], [[Arcades (119)]], [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]], [[Gallery Surround (166)]], [[Trellised Walk (174)]], and [[Window Place (180)]], even [[Small Parking Lots (103)]], which all become more subtle and more beautiful with canvas roofs and awnings. And the awnings always help to create [[Filtered Light (238)]].

Use the canvas awnings, especially, to filter light over those windows which face west and south and glare because they face the sky - [[Filtered Light (238)]]. Colored canvas will add special life - [[Ornament (249)]], [[Warm Colors (250)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1128.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/car-connection-113.md ===== -->

---
title: "Car Connection (113)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 113
pattern_name: "Car Connection"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Car%20Connection%20%28113%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Main Entrance (110)"
  - "Entrance Transition (112)"
  - "Intimacy Gradient (127)"
  - "Common Areas at the Heart (129)"
  - "Outdoor Room (163)"
  - "Structure Follows Social Spaces (205)"
  - "Arcades (119)"
  - "Paths and Goals (120)"
  - "Raised Flowers (245)"
  - "North Face (162)"
---

# Car Connection (113)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The process of arriving in a house, and leaving it, is fundamental to our daily lives; and very often it involves a car. But the place where cars connect to houses, far from being important and beautiful, is often off to one side and neglected.

### Solution
>Place the parking place for the car and the main entrance, in such a relation to each other, that the shortest route from the parked car into the house, both to the kitchen and to the living rooms, is always through the main entrance. Make the parking place for the car into an actual room which makes a positive and grace place where the car stands, not just a gap in the terrain.

### Related Patterns
... once you have the entrance of the building fixed and its transition clear - [[Main Entrance (110)]], [[Entrance Transition (112)]] - it is necessary to work out how a person can approach the building by car. Of course, in a pedestrian precinct this will not apply; but generally the car itself must have a housing somewhere near the building; and when this is so, its place and character are critical.

 Place both kitchen and main common living room just inside the main entrance-[[Intimacy Gradient (127)]], [[Common Areas at the Heart (129)]]; treat the place for the car as if it were an actual outdoor room - [[Outdoor Room (163)]]. If it is enclosed, build the enclosure according to [[Structure Follows Social Spaces (205)]]; and make the path between this room and the front door a beautiful path, preferably the same as the one used by people who come on foot - [[Entrance Transition (112)]], [[Arcades (119)]], [[Paths and Goals (120)]], [[Raised Flowers (245)]]. If you can, put the car connection on the north face of the building - [[North Face (162)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 553.
> #APL/confidence/low
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/carnival-58.md ===== -->

---
title: "Carnival (58)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 58
pattern_name: "Carnival"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Carnival%20%2858%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Promenade (31)"
  - "Night Life (33)"
  - "Small Public Squares (61)"
  - "Dancing in the Street (63)"
  - "Public Outdoor Room (69)"
  - "Food Stands (93)"
  - "Pedestrian Street (100)"
  - "Canvas Roofs (244)"
---

# Carnival (58)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Just as an individual person dreams fantastic happenings to release the inner forces which cannot be encompassed by ordinary events, so, too, a city needs its dreams.

### Solution
>Set aside some part of town as a carnival—mad sideshows, tournaments, acts, displays, competitions, dancing, music, street theater, clowns, freak events, which allow people to reveal their madness; weave a wide pedestrian street through this area; run booths along the street, narrow alleys; at one end an outdoor theater; perhaps connect the theater stage directly to the carnival street, so the two spill into and feed one another.

### Related Patterns
... once in a while, in a subculture which is particularly open to it, a promenade may break into a wilder rhythm - [[Promenade (31)]], [[Night Life (33)]] - and perhaps every promenade may have a touch of this.

Dancing in the street, food stands, an outdoor room or two, a square where the theater is, and tents and canvas will all help to make it even livelier - [[Small Public Squares (61)]], [[Dancing in the Street (63)]], [[Public Outdoor Room (69)]], [[Food Stands (93)]], [[Pedestrian Street (100)]], [[Canvas Roofs (244)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 298.
> #APL/confidence/low
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/cascade-of-roofs-116.md ===== -->

---
title: "Cascade of Roofs (116)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 116
pattern_name: "Cascade of Roofs"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Cascade%20of%20Roofs%20%28116%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Number of Stories (96)"
  - "Main Building (99)"
  - "Wings of Light (107)"
  - "Sheltering Roof (117)"
  - "Roof Garden (118)"
  - "Ceiling Height Variety (190)"
  - "Structure Follows Social Spaces (205)"
  - "Roof Layout (209)"
---

# Cascade of Roofs (116)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Few buildings will be structurally and socially intact, unless the floors step down toward the ends of wings, and unless the roof, accordingly, forms a cascade.

### Solution
>Visualize the whole building, or building complex, as a system of roofs.
>Place the largest, highest, and widest roofs over those parts of the building which are most significant: when you come to lay the roofs out in detail, you will be able to make all lesser roofs cascade off these large roofs and form a stable self-buttressing system, which is congruent with the hierarchy of social spaces underneath the roofs.

### Related Patterns
... this pattern helps complete the [[Building Complex (95)]], [[Number of Stories (96)]], [[Main Building (99)]], and [[Wings of Light (107)]], and it can also be used to help create these patterns. If you are designing a building from scratch, these larger patterns have already helped you to decide how high your buildings are; and they have given you a rough layout, in wings, with an idea of what spaces there are going to be in each floor of the wings. Now we come to the stage where it is necessary to visualize the building as a volume and, therefore, above all else, as a system of roofs.

Make the roofs a combination of steeply pitched or domed, and flat shapes - [[Sheltering Roof (117)]], [[Roof Garden (118)]]. Prepare to place small rooms at the outside and ends of wings, and large rooms in the middle - [[Ceiling Height Variety (190)]]. Later, once the plan of the building is more exactly defined, you can lay out the roofs exactly to fit the cascade to individual rooms; and at that stage the cascade will begin to have a structural effect of great importance - [[Structure Follows Social Spaces (205)]], [[Roof Layout (209)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 565.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/ceiling-height-variety-190.md ===== -->

---
title: "Ceiling Height Variety (190)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 190
pattern_name: "Ceiling Height Variety"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Ceiling%20Height%20Variety%20%28190%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Floor-Ceiling Vaults (219)"
  - "Bulk Storage (145)"
  - "The Shape of Indoor Space (191)"
  - "Structure Follows Social Spaces (205)"
  - "Final Column Distribution (213)"
---

# Ceiling Height Variety (190)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A building in which ceiling heights are all the same is virtually incapable of making people feel comfortable.

### Solution
>Vary the ceiling heights continuously throughout the building, especially between rooms which open into each other, so that the relative intimacy of different spaces can be felt. In particular, make ceilings high in rooms which are public or meant for large gatherings (10 to 12 feet), lower in rooms for smaller gatherings (7 to 9 feet), and very low in rooms for one or two people (6 to 7 feet).

### Related Patterns
... this pattern helps to form the rooms. It therefore helps to complete all the patterns which define rooms, or arcades, or balconies, or outdoor rooms or minor rooms: in short, just about all of the last 100 patterns. If you have been imagining these spaces while you walk about on the actual site, then all these spaces will already be three-dimensional in your mind: they will be volumes of space, not merely areas on plan. Now, with this pattern, which determines ceiling heights, the next pattern which determines the exact shape of each room, and the remaining patterns in the language, we fill out this three dimensional conception of the building.

The construction of floor vaults will create variations in ceiling height almost automatically since the vault starts about 6 feet 6 inches high and rises a further distance which is one - fifth of the room diameter - [[Floor-Ceiling Vaults (219)]]. Where ceiling height varies within one story, put storage in the spaces between the different heights - [[Bulk Storage (145)]]. Get the shape of individual rooms under any given ceiling height from [[The Shape of Indoor Space (191)]] and [[Structure Follows Social Spaces (205)]]; and vary ceiling heights from story to story - the highest ceilings on the ground floor and the lowest on the top floor - see the table in [[Final Column Distribution (213)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 876.
> #APL/confidence/high
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/child-caves-203.md ===== -->

---
title: "Child Caves (203)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 203
pattern_name: "Child Caves"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Child%20Caves%20%28203%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Adventure Playground (73)"
  - "Children's Home (86)"
  - "Children's Realm (137)"
  - "Thick Walls (197)"
  - "Thickening the Outer Walls (211)"
  - "Low Doorway (224)"
---

# Child Caves (203)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Children love to be in tiny, cave-like places.

### Solution
>Wherever children play, around the house, in the neighborhood, in schools, make small “caves” for them. Tuck these caves away in natural leftover spaces, under stairs, under kitchen counters. Keep the ceiling heights low—2 feet 6 inches to 4 feet—and the entrance tiny.

### Related Patterns
... the places specially devoted to children's play - [[Adventure Playground (73)]], [[Children's Home (86)]], [[Children's Realm (137)]] - and [[Thick Walls (197)]] - can be embellished with a special detail.

Build the caves right into the fabric of the walls - [[Thickening the Outer Walls (211)]]. Make the doors very tiny to match the caves - an extreme version of [[Low Doorway (224)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 927.
> #APL/confidence/low
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/children-in-the-city-57.md ===== -->

---
title: "Children in the City (57)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 57
pattern_name: "Children in the City"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Children%20in%20the%20City%20%2857%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Parallel Roads (23)"
  - "Promenade (31)"
  - "Looped Local Roads (49)"
  - "Green Streets (51)"
  - "Network of Paths and Cars (52)"
  - "Bike Paths and Racks (56)"
  - "Network of Learning (18)"
  - "Street Windows (164)"
  - "Connected Play (68)"
  - "Adventure Playground (73)"
  - "Shopfront Schools (85)"
  - "Children's Home (86)"
  - "Old People Everywhere (40)"
  - "Work Community (41)"
  - "University as a Marketplace (43)"
  - "Grave Sites (70)"
  - "Local Sports (72)"
  - "Animals (74)"
  - "Teenage Society (84)"
---

# Children in the City (57)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If children are not able to explore the whole of the adult world round about them, they cannot become adults. But modern cities are so dangerous that children cannot be allowed to explore them freely.

### Solution
>As part of the network of bike paths, develop one system of paths that is extra safe—entirely separate from automobiles, with lights and bridges at the crossings, with homes and shops along it, so that there are nearly always many eyes on the path. Let this path go through every neighborhood, so that children can get onto it without crossing a main road. And run the path all through the city, down pedestrian streets, through workshops, assembly plants, warehouses, interchanges, print houses, bakeries, all the interesting “invisible” life of a town—so that the children can roam freely on their bikes and trikes.

### Related Patterns
... roads, bike paths, and main pedestrian paths are given their position by [[Parallel Roads (23)]], [[Promenade (31)]], [[Looped Local Roads (49)]], [[Green Streets (51)]], [[Network of Paths and Cars (52)]], [[Bike Paths and Racks (56)]]. Some of them are safe for children, others are less safe. Now, finally, to complete the paths and roads, it is essential to define at least one place, right in the very heart of cities, where children can be completely free and safe. If handled properly, this pattern can play a great role in helping to create the [[Network of Learning (18)]].

Line the children's path with windows, especially from rooms that are in frequent use, so that the eyes upon the street make it safe for the children -- [[Street Windows (164)]]; make it touch the children's place all along the path -- [[Connected Play (68)]], [[Adventure Playground (73)]], [[Shopfront Schools (85)]], [[Children's Home (86)]], but also make it touch other phases of the life cycle -- [[Old People Everywhere (40)]], [[Work Community (41)]], [[University as a Marketplace (43)]], [[Grave Sites (70)]], [[Local Sports (72)]], [[Animals (74)]], [[Teenage Society (84)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 293.
> #APL/confidence/low
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/childrens-home-86.md ===== -->

---
title: "Children's Home (86)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 86
pattern_name: "Children's Home"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Children%27s%20Home%20%2886%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Children in the City (57)"
  - "Connected Play (68)"
  - "Network of Learning (18)"
  - "Building Complex (95)"
  - "Building Thoroughfare (101)"
  - "Adventure Playground (73)"
  - "Your Own Home (79)"
  - "The Family (75)"
  - "Common Areas at the Heart (129)"
---

# Children's Home (86)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The task of looking after little children is a much deeper and more fundamental social issue than the phrases “babysitting” and “child care” suggest.

### Solution
>In every neighborhood, build a children’s home—a second home for children—a large rambling house or workplace—a place where children can stay for an hour or two, or for a week. At least one of the people who run it must live on the premises; it must be open 24 hours a day; open to children of all ages; and it must be clear, from the way that it is run, that it is a second family for the children—not just a place where baby-sitting is available.

### Related Patterns
... within each neighborhood there are hundreds of children. The children, especially the young ones, are helped in their relation to the world by the patterns [[Children in the City (57)]] and [[Connected Play (68)]]. However, these very general provisions in the form of public land need to be supported by some kind of communal place, where they can stay without their parents for a few hours, or a few days, according to necessity. This pattern is a part of the [[Network of Learning (18)]] for the youngest children.

Treat the building as a collection of small connected buildings - [[Building Complex (95)]]; lay an important neighborhood path right through the building, so that children who are not a part of the school can see and get to know it by meeting the children who are - [[Building Thoroughfare (101)]] attach it to the local [[Adventure Playground (73)]] ; make the teachers' house an integral part of the interior - [[Your Own Home (79)]]; and treat the common space itself as the hearth of a larger family - [[The Family (75)]], [[Common Areas at the Heart (129)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 426.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/childrens-realm-137.md ===== -->

---
title: "Children's Realm (137)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 137
pattern_name: "Children's Realm"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Children%27s%20Realm%20%28137%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House for a Small Family (76)"
  - "Common Areas at the Heart (129)"
  - "Couple's Realm (136)"
  - "Children's Realm (137)"
  - "Connected Play (68)"
  - "Farmhouse Kitchen (139)"
  - "Home Workshop (157)"
  - "Bathing Room (144)"
  - "Bed Cluster (143)"
  - "Short Passages (132)"
  - "Outdoor Room (163)"
---

# Children's Realm (137)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If children do not have space to release a tremendous amount of energy when they need to, they will drive themselves and everybody else in the family up the wall.

### Solution
>Start by placing the small area which will belong entirely to the children—the cluster of their beds. Place it in a separate position toward the back of the house, and in such a way that a continuous playspace can be made from this cluster to the street, almost like a wide swath inside the house, muddy, toys strewn along the way, touching those family rooms which children need—the bathroom and the kitchen most of all—passing the common area along one side (but leaving quiet sitting areas and the couple’s realm entirely separate and inviolate), reaching out to the street, either through its own door or through the entrance room, and ending in an outdoor room, connected to the street, and sheltered, and large enough so that the children can play in it when it rains, yet still be outdoors.

### Related Patterns
... in a [[House for a Small Family (76)]], there are three main areas: a [[Common Areas at the Heart (129)]], a [[Couple's Realm (136)]] and a [[Children's Realm (137)]] which overlaps the common area. If the common area and couple's realm are in position, it is now possible to weave in this partly separate, partly overlapping place for children, which we call a realm, although we recognize that it is not a separate realm but more an aspect of the house, reserved for children, a mode of functioning which is physically separate only in certain parts. It is that component of [[Connected Play (68)]] which acts within the individual houses.

As you place this swath between the children's beds and the street, place the [[Farmhouse Kitchen (139)]] and the [[Home Workshop (157)]] to one side of the path, touching it, yet not violated by it. Do the same for [[Bathing Room (144)]], and give it some connection to the children's beds. Develop the cluster of children's beds according to [[Bed Cluster (143)]]; make the long passages which form the realm as light and warm as possible - [[Short Passages (132)]]; make the [[Outdoor Room (163)]] large enough for boisterous activity ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 651.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/circulation-realms-98.md ===== -->

---
title: "Circulation Realms (98)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 98
pattern_name: "Circulation Realms"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Circulation%20Realms%20%2898%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Number of Stories (96)"
  - "Main Gateways (53)"
  - "Common Land (67)"
  - "Pedestrian Street (100)"
  - "Main Building (99)"
  - "Building Thoroughfare (101)"
  - "Hierarchy of Open Space (114)"
  - "Courtyards Which Live (115)"
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Paths and Goals (120)"
---

# Circulation Realms (98)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In many modern building complexes the problem of disorientation is acute. People have no idea where they are, and they experience considerable mental stress as a result.

### Solution
>Lay out very large buildings and collections of small buildings so that one reaches a given point inside by passing through a sequence of realms, each marked by a gateway and becoming smaller and smaller, as one passes from each one, through a gateway, to the next. Choose the realms so that each one can be easily named, so that you can tell a person where to go, simply by telling them which realms to go through.

### Related Patterns
... once you have some rough idea how many buildings you are going to build - [[Building Complex (95)]], and how high they are to be - [[Number of Stories (96)]], you can work out roughly what kind of layout they should have to make the access to them clear and comfortable. This pattern defines the overall philosophy of layout.

Treat the first entrances to the whole system of circulation realms, the very largest ones, as gateways - [[Main Gateways (53)]]; make the major realms, which open off the gateways, pedestrian streets or common land - [[Common Land (67)]], [[Pedestrian Street (100)]]; then, make minor realms with individual buildings, and courtyards, and major indoor streets - [[Main Building (99)]], [[Building Thoroughfare (101)]], [[Hierarchy of Open Space (114)]], [[Courtyards Which Live (115)]]; and mark the entrance to these minor realms with minor entrances that still stand out quite clearly - [[Family of Entrances (102)]], [[Main Entrance (110)]]. Make the layout of paths consonant with [[Paths and Goals (120)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 480.
> #APL/confidence/high
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/city-country-fingers-3.md ===== -->

---
title: "City Country Fingers (3)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 3
pattern_name: "City Country Fingers"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/City%20Country%20Fingers%20%283%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Distribution of Towns (2)"
  - "Agricultural Valleys (4)"
  - "Mosaic of Subcultures (8)"
  - "Web of Public Transport (16)"
  - "Ring Roads (17)"
---

# City Country Fingers (3)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Continuous sprawling urbanization destroys life, and makes cities unbearable. But the sheer size of cities is also valuable and potent.

### Solution
>Keep interlocking fingers of farmland and urban land, even at the center of the metropolis. The urban fingers should never be more than 1 mile wide, while the farmland fingers should never be less than 1 mile wide.

### Related Patterns
... the distribution of towns required to make a balanced region -- [[The Distribution of Towns (2)]] -- can be further helped by controlling the balance of urban land and open countryside within the towns and cities themselves.

Whenever land is hilly, keep the country fingers in the valleys and the city fingers on the upper slopes of the hillsides -- [[Agricultural Valleys (4)]]. Break the city fingers into hundreds of distinct self-governing subcultures -- [[Mosaic of Subcultures (8)]], and run the major roads and railways down the middle of these fingers -- [[Web of Public Transport (16)]], [[Ring Roads (17)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 21.
> #APL/confidence/high
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/climbing-plants-246.md ===== -->

---
title: "Climbing Plants (246)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 246
pattern_name: "Climbing Plants"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Climbing%20Plants%20%28246%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Trellised Walk (174)"
  - "Filtered Light (238)"
---

# Climbing Plants (246)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A building finally becomes a part of its surroundings when the plants grow over parts of it as freely as they grow along the ground.

### Solution
>On sunny walls, train climbing plants to grow up round the openings in the wall—the windows, doors, porches, arcades, and trellises.

### Related Patterns
... two earlier patterns can be helped by climbing plants around the building: [[Trellised Walk (174)]] and [[Filtered Light (238)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1135.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/closets-between-rooms-198.md ===== -->

---
title: "Closets Between Rooms (198)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 198
pattern_name: "Closets Between Rooms"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Closets%20Between%20Rooms%20%28198%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Workspace Enclosure (183)"
  - "Dressing Rooms (189)"
  - "Corner Doors (196)"
  - "Thick Walls (197)"
---

# Closets Between Rooms (198)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The provision of storage and closets usually comes as an afterthought.

### Solution
>Mark all the rooms where you want closets. Then place the closets themselves on those interior walls which lie between two rooms and between rooms and passages where you need acoustic insulation. Place them so as to create transition spaces for the doors into the rooms. On no account put closets on exterior walls. It wastes the opportunity for good acoustic insulation and cuts off precious light.

### Related Patterns
... given the layout of rooms, it is now necessary to decide exactly where to put the built-in cupboards and closets. Use them, especially, to help form the enclosure around a workspace - [[Workspace Enclosure (183)]], around a dressing space - [[Dressing Rooms (189)|Dressing Room (189)]], and around the doors of rather private rooms so that the doorway itself gets some depth - [[Corner Doors (196)]].

Later, include the closets as part of the overall building structure - [[Thick Walls (197)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 913.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/column-connections-227.md ===== -->

---
title: "Column Connections (227)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 227
pattern_name: "Column Connections"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Column%20Connections%20%28227%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Efficient Structure (206)"
  - "Arcades (119)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Column Place (226)"
  - "Frames as Thickened Edges (225)"
  - "Ornament (249)"
---

# Column Connections (227)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The strength of a structure depends on the strength of its connections; and these connections are most critical of all at corners, especially at the corners where the columns meet the beams.

### Solution
>Build connections where the columns meet the beams. Any distribution of material which fills the corner up will do: fillets, gussets, column capitals, mushroom columns, and most general of all, the arch, which connects column and beam in a continuous curve.

### Related Patterns
... the columns are in position, and have been tied together by a perimeter beam - [[Box Columns (216)]], [[Perimeter Beams (217)]]. According to the principles of continuity which govern the basic structure - [[Efficient Structure (206)]], the connections need stiffening to lead the forces smoothly from the beams into the columns, especially when the columns are free standing as they are in an arcade or balcony - [[Arcades (119)]], [[Gallery Surround (166)]], [[Six-Foot Balcony (167)]], [[Column Place (226)]]. You may also do the same in the upper corners of your door and window frames - [[Frames as Thickened Edges (225)]] - making arched openings.

The connection is one of the most natural places for [[Ornament (249)]]: there is a wide variety of possible connections, carvings, fretwork, painting, for this critical position. In certain cases, the connection may act as an umbrella for a [[Column Place (226)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1068.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/column-place-226.md ===== -->

---
title: "Column Place (226)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 226
pattern_name: "Column Place"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Column%20Place%20%28226%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Columns at the Corners (212)"
  - "Public Outdoor Room (69)"
  - "Arcades (119)"
  - "Outdoor Room (163)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Trellised Walk (174)"
  - "Box Columns (216)"
  - "Column Connections (227)"
  - "Sitting Wall (243)"
  - "Raised Flowers (245)"
  - "Different Chairs (251)"
---

# Column Place (226)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Thin columns, spindly columns, columns which take their shape from structural arguments alone, will never make a comfortable environment.

### Solution
>When a column is free standing, make it as thick as a person—at least 12 inches, preferably 16 inches: and form places around it where people can sit and lean comfortably: a step, a small seat built up against the column, or a space formed by a pair of columns.

### Related Patterns
... certain columns, especially those which are free standing, play an important social role, beyond their structural role as [[Columns at the Corners (212)]]. These are, especially, the columns which help to form arcades, galleries, porches, walkways, and outdoor rooms - [[Public Outdoor Room (69)]], [[Arcades (119)]], [[Outdoor Room (163)]], [[Gallery Surround (166)]], [[Six-Foot Balcony (167)]], [[Trellised Walk (174)]]. This pattern defines the character these columns need to make them function socially.

You can get the extra thickness quite cheaply if you build the column as a [[Box Columns (216)]]; complete the "place" the column forms, by giving it a "roof" in the form of a column capital, or vault which springs from the column, or by bracing the column against the beams - [[Column Connections (227)]]. And when it makes sense, make the column base a [[Sitting Wall (243)]], a place for flowers - [[Raised Flowers (245)]], or a place for a chair or table - [[Different Chairs (251)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1064.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/columns-at-the-corners-212.md ===== -->

---
title: "Columns at the Corners (212)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 212
pattern_name: "Columns at the Corners"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Columns%20at%20the%20Corners%20%28212%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Roof Layout (209)"
  - "Floor and Ceiling Layout (210)"
  - "Structure Follows Social Spaces (205)"
  - "Gradual Stiffening (208)"
  - "Final Column Distribution (213)"
  - "Floor-Ceiling Vaults (219)"
  - "Roof Vaults (220)"
  - "Root Foundations (214)"
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Column Place (226)"
---

# Columns at the Corners (212)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We have already established the idea that the structural components of a building should be congruent with its social spaces.

### Solution
>On your rough building plan, draw a dot to represent a column at the corner of every room and in the corners formed by lesser spaces like thick walls and alcoves. Then transfer these dots onto the ground out on the site with stakes.

### Related Patterns
... assume that you have worked out the roof plan, and laid out ceiling vaults for every room on every floor - [[Roof Layout (209)]], [[Floor and Ceiling Layout (210)]]. These vaults are not only the basis of the structure, but also define the social spaces underneath them. Now it is time to put columns at the corners of the vaults. This will both complete them as clearly defined social spaces - [[Structure Follows Social Spaces (205)]] - and also be the first constructive step in the erection of the building - [[Gradual Stiffening (208)]].

Once you have the columns for each floor on your vault plan, reconcile them from floor to floor and put in intermediate columns - [[Final Column Distribution (213)]]. Note, especially, that it is not necessary for the corner columns to fall on a grid. The floor vaults and roof vaults can be made to fit any arrangement of columns, and still make a coherent structure - thus allowing the social spaces to determine the building shape without undue constraint from purely structural considerations - [[Floor-Ceiling Vaults (219)]], [[Roof Vaults (220)]].

These columns will not only guide your mental image of the building, they will also guide construction: first put the columns and the column foundations in place; then, to make the frame complete, tie the columns together around each room with the perimeter beam - [[Root Foundations (214)]], [[Box Columns (216)]], [[Perimeter Beams (217)]]. Give special emphasis to all free-standing columns with the idea that when you build them, you will make them very thick - [[Column Place (226)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 989.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Structural-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/common-areas-at-the-heart-129.md ===== -->

---
title: "Common Areas at the Heart (129)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 129
pattern_name: "Common Areas at the Heart"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Common%20Areas%20at%20the%20Heart%20%28129%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Indoor Sunlight (128)"
  - "Cascade of Roofs (116)"
  - "Farmhouse Kitchen (139)"
  - "Communal Eating (147)"
  - "The Fire (181)"
  - "Light on Two Sides of Every Room (159)"
  - "The Shape of Indoor Space (191)"
  - "Sequence of Sitting Spaces (142)"
  - "Outdoor Room (163)"
  - "Arcades (119)"
  - "The Flow Through Rooms (131)"
  - "Short Passages (132)"
---

# Common Areas at the Heart (129)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No social group—whether a family, a work group, or a school group—can survive without constant informal contact among its members.

### Solution
>Create a single common area for every social group. Locate it at the center of gravity of all the spaces the group occupied, and in such a way that the paths which go in and out of the building lie tangent to it.

### Related Patterns
... along the [[Intimacy Gradient (127)]], in every building and in every social group within the building, it is necessary to place the common areas. Place them on the sunlit side to reinforce the pattern of [[Indoor Sunlight (128)]]; and, when they are large, give them the higher roofs of the [[Cascade of Roofs (116)]].

Most basic of all to common areas are food and fire. Include [[Farmhouse Kitchen (139)]], [[Communal Eating (147)]], and [[The Fire (181)]]. For the shape of the common area in fine detail, see [[Light on Two Sides of Every Room (159)]] and [[The Shape of Indoor Space (191)]]. Make sure that there are plenty of different sitting places, different in character for different kinds of moments - [[Sequence of Sitting Spaces (142)]]. Include an [[Outdoor Room (163)]]. And make the paths properly tangent to the common areas - [[Arcades (119)]], [[The Flow Through Rooms (131)]], [[Short Passages (132)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 618.
> #APL/confidence/high
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/common-land-67.md ===== -->

---
title: "Common Land (67)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 67
pattern_name: "Common Land"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Common%20Land%20%2867%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Accessible Green (60)"
  - "House Cluster (37)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "Work Community (41)"
  - "South Facing Outdoors (105)"
  - "Positive Outdoor Space (106)"
  - "Hierarchy of Open Space (114)"
  - "Public Outdoor Room (69)"
  - "Local Sports (72)"
  - "Vegetable Garden (177)"
  - "Connected Play (68)"
  - "Green Streets (51)"
---

# Common Land (67)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Without common land no social system can survive.

### Solution
>Give over 25 percent of the land in house clusters to common land which touches, or is very near, the homes which share it. Basic: be wary of the automobile; on no account let it dominate this land.

### Related Patterns
... just as there is a need for public land at the neighborhood level - [[Accessible Green (60)]], so also, within the clusters and work communities from which the neighborhoods are made, there is a need for smaller and more private kinds of common land shared by a few work groups or a few families. This common land, in fact, forms the very heart and soul of any cluster. Once it is defined, the individual buildings of the cluster form around it - [[House Cluster (37)]], [[Row Houses (38)]], [[Housing Hill (39)]], [[Work Community (41)]].

Shape the common land so it has some enclosure and good sunlight - [[South Facing Outdoors (105)]], [[Positive Outdoor Space (106)]]; and so that smaller and more private pieces of land and pockets always open onto it - [[Hierarchy of Open Space (114)]]; provide communal functions within the land - [[Public Outdoor Room (69)]], [[Local Sports (72)]], [[Vegetable Garden (177)]]; and connect the different and adjacent pieces of common land to one another to form swaths of connected play space - [[Connected Play (68)]]. Roads can be part of common land if they are treated as [[Green Streets (51)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 336.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/communal-eating-147.md ===== -->

---
title: "Communal Eating (147)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 147
pattern_name: "Communal Eating"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Communal%20Eating%20%28147%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "The Family (75)"
  - "Self-Governing Workshops and Offices (80)"
  - "Small Work Groups (148)"
  - "Small Meeting Rooms (151)"
  - "Farmhouse Kitchen (139)"
  - "Eating Atmosphere (182)"
---

# Communal Eating (147)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Without communal eating, no human group can hold together.

### Solution
>Give every institution and social group a place where people can eat together. Make the common meal a regular event. In particular, start a common lunch in every work place, so that a genuine meal around a common table (not out of boxes, machines, or bags) becomes an important, comfortable, and daily event with room for invited guests. In our own work group at the Center, we found this worked most beautifully when we took it in turns to cook the lunch. The lunch became an event: a gathering: something that each of us put our love and energy into, on our day to cook.

### Related Patterns
... this pattern helps complete all those human groups and institutions which have [[Common Areas at the Heart (129)]] in them, and most of all it helps to complete workshops and offices and extended families - [[The Family (75)]], [[Self-Governing Workshops and Offices (80)]]. In all of them, the common area will draw its strength from the sharing of food and drink. This pattern defines it in detail, and shows also how it helps to generate a larger social order.

If the institution is large, find some way of breaking it down into smaller groups which eat together, so that no one group which eats together has more than about a dozen people in it - [[Small Work Groups (148)]], [[Small Meeting Rooms (151)]]. Build the kitchen all around the eating place like a [[Farmhouse Kitchen (139)]]; make the table itself a focus of great importance - [[Eating Atmosphere (182)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 696.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/communal-sleeping-186.md ===== -->

---
title: "Communal Sleeping (186)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 186
pattern_name: "Communal Sleeping"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Communal%20Sleeping%20%28186%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Couple's Realm (136)"
  - "Children's Realm (137)"
  - "Sleeping to the East (138)"
  - "Bed Cluster (143)"
  - "Marriage Bed (187)"
  - "Bed Alcove (188)"
  - "Alcoves (179)"
  - "Dressing Rooms (189)"
---

# Communal Sleeping (186)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In many traditional and primitive cultures, sleep is a communal activity without the sexual overtones it has in the West today. We believe that it may be a vital social function, which plays a role as fundamental and as necessary to people as communal eating.

### Solution
>Arrange the sleeping area so that there is the possibility for children and adults to sleep in the same space, in sight and sound of one another, at least as an occasional alternative to their more usual sleeping habits.
>This can be done in the common area near the fireplace, where the entire household and guests can sleep together—one large mat and some blankets in an alcove. It is also possible to build bed alcoves for overnight guests, in an extended couple’s realm.

### Related Patterns
... by this time the sleeping areas have been defined - [[Couple's Realm (136)]], [[Children's Realm (137)]], [[Sleeping to the East (138)]], [[Bed Cluster (143)]]. It remains only to build in the actual detailed space which forms the beds themselves - [[Marriage Bed (187)]], [[Bed Alcove (188)]]. However, before we consider these patterns, we wish to draw attention to a slightly more general pattern which may affect their detailed positions.

Place the [[Alcoves (179)]] and [[Marriage Bed (187)]] and the [[Bed Alcove (188)]] and [[Dressing Rooms (189)]] accordingly. The children have this pattern for themselves already - if bed alcoves are placed in a cluster - [[Bed Cluster (143)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 861.
> #APL/confidence/low
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/community-of-7000-12.md ===== -->

---
title: "Community of 7000 (12)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 12
pattern_name: "Community of 7000"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Community%20of%207000%20%2812%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Subculture Boundary (13)"
  - "Identifiable Neighborhood (14)"
  - "Eccentric Nucleus (28)"
  - "Promenade (31)"
  - "Local Town Hall (44)"
---

# Community of 7000 (12)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Individuals have no effective voice in any community of more than 5,000–10,000 persons.

### Solution
>Decentralize city governments in a way that gives local control to communities of 5,000 to 10,000 persons. As nearly as possible, use natural geographic and historical boundaries to mark these communities. Give each community the power to initiate, decide, and execute the affairs that concern it closely: land use, housing, maintenance, streets, parks, police, schooling, welfare, neighborhood services.

### Related Patterns
... the [[Mosaic of Subcultures (8)]] is made up of a great number of large and small self-governing communities and neighborhoods. Community of 7000 helps define the structure of the large communities.

Separate the communities from one another by means of substantial areas -- [[Subculture Boundary (13)]]; subdivide each community into 10 or 20 independent neighborhoods, each with a representative on the community council -- [[Identifiable Neighborhood (14)]]; provide a central place where people have a chance to come together -- [[Eccentric Nucleus (28)]], [[Promenade (31)]]; and in this central place provide a local town hall, as a focal point for the community's political activity -- [[Local Town Hall (44)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 70
> #APL/confidence/medium
>
> #APL/Town-Patterns/Communities


<!-- ===== pattern-language/wiki/concepts/patterns/compost-178.md ===== -->

---
title: "Compost (178)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 178
pattern_name: "Compost"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Compost%20%28178%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Fruit Trees (170)"
  - "Vegetable Garden (177)"
  - "House Cluster (37)"
  - "Animals (74)"
  - "Bathing Room (144)"
---

# Compost (178)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Our current ways of getting rid of sewage poison the great bodies of natural water, and rob the land around our buildings of the nutrients they need.

### Solution
>Arrange all toilets over a dry composting chamber. Lead organic garbage chutes to the same chamber, and use the combined products for fertilizer.

### Related Patterns
... the garden is a valuable part of the house, because it can help you grow fruit and vegetables - [[Fruit Trees (170)]], [[Vegetable Garden (177)]]. But it can only flourish if it gets nourishment; and this nourishment, in the form of compost, can only be created when the garbage and the wastes from the individual houses and [[House Cluster (37)]] and from the [[Animals (74)]] are properly organized.

Add to the effect of dry composting by re-using waste water; run all water drains into the garden to irrigate the soil; use organic soap - [[Bathing Room (144)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 822.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/connected-buildings-108.md ===== -->

---
title: "Connected Buildings (108)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 108
pattern_name: "Connected Buildings"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Connected%20Buildings%20%28108%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Courtyards Which Live (115)"
  - "Arcades (119)"
  - "Outdoor Room (163)"
---

# Connected Buildings (108)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Isolated buildings are symptoms of a disconnected, sick society.

### Solution
>Connect your building up, wherever possible, to the existing buildings round about. Do not keep set backs between buildings; instead, try to form new buildings as continuations of the older buildings.

### Related Patterns
... this pattern helps to complete [[Building Complex (95)]], [[Wings of Light (107)]], and [[Positive Outdoor Space (106)]]. It helps to create positive outdoor space, especially, by eliminating all the wasted areas between buildings. As you connect each building to the next you will find that you make the outdoor space positive, almost instinctively.

Connect buildings with arcades, and outdoor rooms, and courtyards where they cannot be connected physically, wall to wall - [[Courtyards Which Live (115)]], [[Arcades (119)]], [[Outdoor Room (163)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 531.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/connected-play-68.md ===== -->

---
title: "Connected Play (68)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 68
pattern_name: "Connected Play"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Connected%20Play%20%2868%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Land (67)"
  - "House Cluster (37)"
  - "Green Streets (51)"
  - "Children's Home (86)"
  - "Still Water (71)"
  - "Animals (74)"
  - "Adventure Playground (73)"
---

# Connected Play (68)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If children don’t play enough with other children during the first five years of life, there is a great chance that they will have some kind of mental illness later in their lives.

### Solution
>Lay out common land, paths, gardens, and bridges so that groups of at least 64 households are connected by a swath of land that does not cross traffic. Establish this land as the connected play space for the children in these households.

### Related Patterns
... suppose the common land that connects clusters to one another is being provided - [[Common Land (67)]]. Within this common land, it is necessary to identify play space for children and, above all, to make sure that the relationship between adjacent pieces of common land allows this play space to form.

Do this by connecting several [[House Cluster (37)|House Clusters (37)]] with [[Green Streets (51)]] and safe paths. Place the local [[Children's Home (86)]] in this play space. Within the play space, make sure the children have access to mud, and plants, and animals, and water - [[Still Water (71)]], [[Animals (74)]]; set aside one area where there is all kinds of junk that they can use to make things - [[Adventure Playground (73)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 341.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/connection-to-the-earth-168.md ===== -->

---
title: "Connection to the Earth (168)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 168
pattern_name: "Connection to the Earth"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Connection%20to%20the%20Earth%20%28168%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Edge (160)"
  - "Arcades (119)"
  - "Private Terrace on the Street (140)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Entrance Room (130)"
  - "Outdoor Room (163)"
  - "Terraced Slope (169)"
  - "Ground Floor Slab (215)"
  - "Soft Tile and Brick (248)"
  - "Paving With Cracks Between the Stones (247)"
---

# Connection to the Earth (168)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A house feels isolated from the nature around it, unless its floors are interleaved directly with the earth that is around the house.

### Solution
>Connect the building to the earth around it by building a series of paths and terraces and steps around the edge. Place them deliberately to make the boundary ambiguous—so that it is impossible to say exactly where the building stops and earth begins.

### Related Patterns
... this pattern helps to create the [[Building Edge (160)]] and its [[Arcades (119)]], [[Private Terrace on the Street (140)]], the [[Gallery Surround (166)]], and [[Six-Foot Balcony (167)]], by specifying the way the floor of the building reaches out into the land and gardens round about it.

Use the connection to the earth to form the ground for outdoor rooms, and entrances, and terraces - [[Entrance Room (130)]], [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]], [[Terraced Slope (169)]]; prepare to tie the terraces continuously into the wall which forms the edge of the ground floor slab, to make the very structure of the building feel connected to the earth - [[Ground Floor Slab (215)]]; and where you come to form the terrace surfaces, use things like hand-made bricks and softbaked crumbling biscuit-fired tile - [[Soft Tile and Brick (248)]]; and further out, along the paths a little distance from the house, leave cracks between the tiles to let the grass and flowers grow between them - [[Paving With Cracks Between the Stones (247)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 785.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/cooking-layout-184.md ===== -->

---
title: "Cooking Layout (184)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 184
pattern_name: "Cooking Layout"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Cooking%20Layout%20%28184%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Farmhouse Kitchen (139)"
  - "Sunny Counter (199)"
  - "Thick Walls (197)"
  - "Open Shelves (200)"
---

# Cooking Layout (184)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Cooking is uncomfortable if the kitchen counter is too short and also if it is too long.

### Solution
>To strike the balance between the kitchen which is too small, and the kitchen which is too spread out, place the stove, sink, and food storage and counter in such a way that:
>1. No two of the four are more than 10 feet apart.
>2. The total length of counter—excluding sink, stove, and refrigerator—is at least 12 feet.
>3. No one section of the counter is less than 4 feet long.
>
>There is no need for the counter to be continuous or entirely “built-in” as it is in many modern kitchens—it can even consist of free-standing tables or counter tops. Only the three functional relationships described above are critical.

### Related Patterns
... within the [[Farmhouse Kitchen (139)]], or any other kind of kitchen, it is essential that the cooking area be fashioned as a workshop for the preparation of food, and not as some kind of magazine kitchen with built-in counters and decorator colors. This down-to-earth and working character of a good kitchen comes in large part from the arrangement of the stove and food and counter.

Place the most important part of the working surface in the sunlight - [[Sunny Counter (199)]]; put all the kitchen tools and plates and saucepans and nonperishable food around the walls, one deep, so all of it is visible, and all of it directly open to reach - [[Thick Walls (197)]], [[Open Shelves (200)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 853.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/corner-doors-196.md ===== -->

---
title: "Corner Doors (196)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 196
pattern_name: "Corner Doors"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Corner%20Doors%20%28196%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Flow Through Rooms (131)"
  - "Sequence of Sitting Spaces (142)"
  - "Tapestry of Light and Dark (135)"
  - "Low Doorway (224)"
  - "Closets Between Rooms (198)"
  - "Frames as Thickened Edges (225)"
  - "Ornament (249)"
  - "Solid Doors with Glass (237)"
---

# Corner Doors (196)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The success of a room depends to a great extent on the position of the doors. If the doors create a pattern of movement which destroys the places in the room, the room will never allow people to be comfortable.

### Solution
>Except in very large rooms, a door only rarely makes sense in the middle of a wall. It does in an entrance room, for instance, because this room gets its character essentially from the door. But in most rooms, especially in small ones, put the doors as near the corners of the room as possible. If the room has two doors, and people move through it, keep both doors at one end of the room.

### Related Patterns
... this pattern helps you place doors exactly. Use it to help create the larger [[The Flow Through Rooms (131)]]. You can use it too, to generate a [[Sequence of Sitting Spaces (142)]], by leaving small corners for sitting, uninterrupted by the doors; and you can use it to create [[Tapestry of Light and Dark (135)]], since every door, if glazed and near a window, will create a natural pool of light which people gravitate toward.

When a door marks a transition, as it does into a bedroom or a private place, for instance, make it as low as you dare - [[Low Doorway (224)]] ; and thicken the entry way with closet space where it needs to be especially private - [[Closets Between Rooms (198)]]. Later, when you make the door frame, make it integral with the wall, and decorate it freely - [[Frames as Thickened Edges (225)]], [[Ornament (249)]]; except when rooms are very private, put windows in the door - [[Solid Doors with Glass (237)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 904.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/corner-grocery-89.md ===== -->

---
title: "Corner Grocery (89)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 89
pattern_name: "Corner Grocery"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Corner%20Grocery%20%2889%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Market of Many Shops (46)"
  - "Web of Shopping (19)"
  - "Identifiable Neighborhood (14)"
  - "Individually Owned Shops (87)"
  - "The Shape of Indoor Space (191)"
  - "Thick Walls (197)"
  - "Open Shelves (200)"
  - "Main Entrance (110)"
  - "Opening to the Street (165)"
  - "Building Complex (95)"
---

# Corner Grocery (89)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>It has lately been assumed that people no longer want to walk to local stores. This assumption is mistaken.

### Solution
>Give every neighborhood at least one corner grocery, somewhere near its heart. Place these corner groceries every 200 to 800 yards, according to the density, so that each one serves about 100 people. Place them on corners, where large numbers of people are going past. And combine them with houses, so that people who run them can live over them or next to them.

### Related Patterns
... the major shopping needs, in any community, are taken care of by the [[Market of Many Shops (46)]]. However, the [[Web of Shopping (19)]] is not complete, unless there are also much smaller shops, more widely scattered, helping to supplement the markets, and helping to create the natural identity of [[Identifiable Neighborhood (14)]].

Prevent franchises and pass laws which prevent the emergence of those much larger groceries which swallow up the corner groceries - [[Individually Owned Shops (87)]]. Treat the inside of the shop as a room, lined with goods - [[The Shape of Indoor Space (191)]], [[Thick Walls (197)]], [[Open Shelves (200)]]; give it a clear and wide entrance so that everyone can see it - [[Main Entrance (110)]], [[Opening to the Street (165)]]. And for the shape of the grocery, as a small building or as part of a larger building, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 440.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/country-towns-6.md ===== -->

---
title: "Country Towns (6)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 6
pattern_name: "Country Towns"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Country%20Towns%20%286%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Distribution of Towns (2)"
  - "Community of 7000 (12)"
  - "Life Cycle (26)"
  - "The Countryside (7)"
---

# Country Towns (6)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The big city is a magnet. It is terribly hard for small towns to stay alive and healthy in the face of central urban growth.

### Solution
>Preserve country towns where they exist; and encourage the growth of new self-contained towns, with populations between 500 and 10,000, entirely surrounded by open countryside and at least 10 miles from neighboring towns. Make it the region's collective concern to to give each town the wherewithal it needs to build a base of local industry, so that these towns are not dormitories for people who work in other places, but real towns -- able to sustain the whole of life.

### Related Patterns
... this pattern forms the backbone of the [[The Distribution of Towns (2)]], which requires that scores of smaller country towns support the larger towns and cities of the region.

Treat each of these small towns as a political community, with full provision for all the stages of human life -- [[Community of 7000 (12)]], [[Life Cycle (26)]]. Treat the belt of open country which surrounds the town as farm land which belongs to the people and can be freely used by them -- [[The Countryside (7)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 33.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/couples-realm-136.md ===== -->

---
title: "Couple's Realm (136)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 136
pattern_name: "Couple's Realm"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Couple%27s%20Realm%20%28136%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "Intimacy Gradient (127)"
  - "Sitting Circle (185)"
  - "Light on Two Sides of Every Room (159)"
  - "Marriage Bed (187)"
  - "Sleeping to the East (138)"
  - "Dressing Rooms (189)"
  - "Bathing Room (144)"
  - "The Shape of Indoor Space (191)"
  - "Low Doorway (224)"
  - "Closets Between Rooms (198)"
---

# Couple's Realm (136)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The presence of children in a family often destroys the closeness and the special privacy which a couple needs together.

### Solution
>Make a special part of the house distinct from the common areas and all the children’s rooms, where the man and woman of the house can be together in private. Give this place a quick path to the children’s rooms, but, at all costs, make it a distinctly separate realm.

### Related Patterns
... this pattern helps to complete [[The Family (75)]], [[House for a Small Family (76)]] and [[House for a Couple (77)]]. It also ties in to a particular position on the [[Intimacy Gradient (127)]], and can be used to help generate that gradient, if it doesn't exist already.

Even if it's very tiny, give it a sitting area, a place to relax, read, make love, play music - [[Sitting Circle (185)]]. Give it [[Light on Two Sides of Every Room (159)]]. At the heart of the couple's realm, place the bed - [[Marriage Bed (187)]] so it has morning light - [[Sleeping to the East (138)]], and, beside it, the [[Dressing Rooms (189)|Dressing Room (189)]] ; if possible, try to place the bathing room to open off the couple's realm - [[Bathing Room (144)]]. For the shape of this room in fine detail and its construction, see [[The Shape of Indoor Space (191)]]. And keep the area private with a [[Low Doorway (224)]] or two doors - [[Closets Between Rooms (198)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 648.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/courtyards-which-live-115.md ===== -->

---
title: "Courtyards Which Live (115)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 115
pattern_name: "Courtyards Which Live"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Courtyards%20Which%20Live%20%28115%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Positive Outdoor Space (106)"
  - "Hierarchy of Open Space (114)"
  - "Arcades (119)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Sunny Place (161)"
  - "Zen View (134)"
  - "Outdoor Room (163)"
  - "Garden Wall (173)"
  - "Roof Layout (209)"
  - "Something Roughly in the Middle (126)"
---

# Courtyards Which Live (115)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The courtyards built in modern buildings are very often dead. They are intended to be private open spaces for people to use—but they end up unused, full of gravel and abstract sculptures.

### Solution
>Place every courtyard in such a way that there is a view out of it to some larger open space; place it so that at least two or three doors open from the building into it and so that the natural paths which connect these doors pass across the courtyard. And, at one edge, beside a door, make a roofed veranda or a porch, which is continuous with both the inside and the courtyard.

### Related Patterns
... within the general scheme of outdoor spaces, made positive according to the patterns [[Positive Outdoor Space (106)]] and [[Hierarchy of Open Space (114)]], it is necessary to pay special attention to those smallest ones, less than 30 or 40 feet across the courtyards - because it is especially easy to make them in such a way that they do not live.

Build the porch according to the patterns for [[Arcades (119)]], [[Gallery Surround (166)]], and [[Six-Foot Balcony (167)]] ; make sure that it is in the sun - [[Sunny Place (161)]]; build the view out according to the [[Hierarchy of Open Space (114)]] and [[Zen View (134)]]; make the courtyard like an [[Outdoor Room (163)]] and a [[Garden Wall (173)]] for more enclosure; make the height of the eaves around any courtyard of even height; if there are gable ends, hip them to make the roof edge level - [[Roof Layout (209)]]; Put [[Something Roughly in the Middle (126)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 561.
> #APL/confidence/high
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/dancing-in-the-street-63.md ===== -->

---
title: "Dancing in the Street (63)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 63
pattern_name: "Dancing in the Street"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Dancing%20in%20the%20Street%20%2863%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Magic of the City (10)"
  - "Promenade (31)"
  - "Night Life (33)"
  - "Carnival (58)"
  - "Small Public Squares (61)"
  - "Activity Pockets (124)"
  - "Public Outdoor Room (69)"
  - "Food Stands (93)"
  - "Canvas Roofs (244)"
---

# Dancing in the Street (63)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Why is it that people don’t dance in the streets today?

### Solution
>Along the promenades, in squares and evening centers, make a slightly raised platform to form a bandstand, where street musicians and local bands can play. Cover it, and perhaps build in at ground level tiny stalls for refreshment. Surround the bandstand with paved surface for dancing—no admission charge.

### Related Patterns
... several patterns have laid the groundwork for evening activity in public - [[Magic of the City (10)]], [[Promenade (31)]], [[Night Life (33)]], [[Carnival (58)]], [[Small Public Squares (61)]]. To make these places alive at night, there is nothing like music and dancing; this pattern simply states the physical conditions which will encourage dancing and music to fill the streets.

Place the bandstand in a pocket of activity, toward the edge of a square or a promenade - [[Activity Pockets (124)]]; make it a room, defined by trellises and columns - [[Public Outdoor Room (69)]]; build [[Food Stands (93)]] around the bandstand; and for dancing, maybe colored canvas canopies, which reach out over portions of the street, and make the street, or parts of it, into a great, half-open ten t- [[Canvas Roofs (244)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 319.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/deep-reveals-223.md ===== -->

---
title: "Deep Reveals (223)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 223
pattern_name: "Deep Reveals"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Deep%20Reveals%20%28223%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Light on Two Sides of Every Room (159)"
  - "Frames as Thickened Edges (225)"
  - "Thick Walls (197)"
  - "Filtered Light (238)"
  - "Half-Inch Trim (240)"
  - "Climbing Plants (246)"
---

# Deep Reveals (223)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Windows with a sharp edge where the frame meets the wall create harsh, blinding glare, and make the rooms they serve uncomfortable.

### Solution
>Make the window frame a deep, splayed edge: about a foot wide and splayed at about 50 to 60 degrees to the plane of the window, so that the gentle gradient of daylight gives a smooth transition between the light of the window and the dark of the inner wall.

### Related Patterns
... this pattern helps to complete the work of [[Light on Two Sides of Every Room (159)]], by going even further to reduce glare; and it helps to shape the [[Frames as Thickened Edges (225)]].

Build the depth of the frame so that it is continuous with the structure of the walls - [[Frames as Thickened Edges (225)]]; if the wall is thin, make up the necessary depth for the reveal on the inside face of the wall, with bookshelves, closets or other [[Thick Walls (197)]]; embellish the edge of the window even further, to make light even softer, with lace work, tracery, and climbing plants - [[Filtered Light (238)]], [[Half-Inch Trim (240)]], [[Climbing Plants (246)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1053.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Fenestration


<!-- ===== pattern-language/wiki/concepts/patterns/degrees-of-publicness-36.md ===== -->

---
title: "Degrees of Publicness (36)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 36
pattern_name: "Degrees of Publicness"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Degrees%20of%20Publicness%20%2836%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Activity Nodes (30)"
  - "Density Rings (29)"
  - "Housing Hill (39)"
  - "Row Houses (38)"
  - "House Cluster (37)"
  - "Pedestrian Street (100)"
  - "Raised Walk (55)"
  - "Green Streets (51)"
  - "Path Shape (121)"
  - "Pedestrian Density (123)"
---

# Degrees of Publicness (36)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People are different, and the way they want to place their houses in a neighborhood is one of the most basic kinds of difference.

### Solution
>Make a clear distinction between three kinds of homes—those on quiet backwaters, those on busy streets, and those that are more or less in between. Make sure that those on quiet backwaters are on twisting paths, and that these houses are themselves physically secluded; make sure that the more public houses are on busy streets with many people passing by all day long and that the houses themselves are relatively exposed to the passers-by. The in-between houses may then be located on the paths halfway between the other two. Give every neighborhood about equal numbers of these three kinds of homes.

### Related Patterns
... within the neighborhoods - [[Identifiable Neighborhood (14)]] - there are naturally some areas where life is rather concentrated [[Activity Nodes (30)]], others where it is slower, and others in between - [[Density Rings (29)]]. It is essential to differentiate groups of houses and the paths which lead to them according to this gradient.

Use this pattern to help differentiate the houses both in neighborhoods and in house clusters. Within a neighborhood, place higher density clusters along the busier streets - [[Housing Hill (39)]], [[Row Houses (38)]], and lower density clusters along the backwaters [[House Cluster (37)]], [[Row Houses (38)]]. The actual busy streets themselves should either be [[Pedestrian Street (100)|Pedestrian Streets (100)]] or [[Raised Walk (55)|Raised Walks (55)]] on major roads; the backwaters [[Green Streets (51)]], or narrow paths with a distinct [[Path Shape (121)]]. Where lively streets are wanted, make sure the density of housing is high enough to generate the liveliness - [[Pedestrian Density (123)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 192.
> #APL/confidence/high
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/density-rings-29.md ===== -->

---
title: "Density Rings (29)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 29
pattern_name: "Density Rings"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Density%20Rings%20%2829%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Eccentric Nucleus (28)"
  - "Mosaic of Subcultures (8)"
  - "Subculture Boundary (13)"
  - "Community of 7000 (12)"
  - "House Cluster (37)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "Promenade (31)"
  - "Small Public Squares (61)"
  - "Pedestrian Density (123)"
---

# Density Rings (29)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People want to be close to shops and services, for excitement and convenience. And they want to be away from services, for quiet and green. The exact balance of these two desires varies from person to person, but in the aggregate it is the balance of these two desires which determines the gradient of housing densities in a neighborhood.

### Solution
>Once the nucleus of a community is clearly placed—define rings of decreasing local housing density around this nucleus. If you cannot avoid it, choose the densities from the foregoing table. But, much better, if you can possibly manage it, play the density rings game, to obtain these densities, from the intuitions of the very people who are going to live in the community.

### Related Patterns
... in [[Eccentric Nucleus (28)]] we have given a general form for the configuration of density "peaks" and "valleys", with respect to the [[Mosaic of Subcultures (8)]] and [[Subculture Boundary (13)]]. Suppose now that the center of commercial activity in a [[Community of 7000 (12)]] is placed according to the overall density within the region. We then face the problem of establishing local densities, for house clusters and work communities, at different distances around this peak. This pattern gives a rule for working out the gradient density of these local densities. Most concretely, this gradient of density can be specified, by drawing rings at different distances from the main center of activity and then assigning different densities to each ring, so that the densities in the succeeding rings create the gradient of density. The gradient will vary from community to community -- both according to the cultural background of the people.

Within the rings of density, encourage housing to take the form of housing clusters -- self-governing cooperatives of 8 to 15 households, their physical size varying according to the density -- [[House Cluster (37)]]. According to the densities in the different rings, build these houses as free-standing houses -- [[House Cluster (37)]], [[Row Houses (38)]], or higher density clusters of housing -- [[Housing Hill (39)]]. Keep public spaces -- [[Promenade (31)]], [[Small Public Squares (61)]] -- to those areas which have a high enough density around them to keep them alive -- [[Pedestrian Density (123)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 156.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/different-chairs-251.md ===== -->

---
title: "Different Chairs (251)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 251
pattern_name: "Different Chairs"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Different%20Chairs%20%28251%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sequence of Sitting Spaces (142)"
  - "Sitting Circle (185)"
  - "Built-in Seats (202)"
  - "Pools of Light (252)"
---

# Different Chairs (251)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People are different sizes; they sit in different ways. And yet there is a tendency in modern times to make all chairs alike.

### Solution
>Never furnish any place with chairs that are identically the same. Choose a variety of different chairs, some big, some small, some softer than others, some rockers, some very old, some new, with arms, without arms, some wicker, some wood, some cloth.

### Related Patterns
... when you are ready to furnish rooms, choose the variety of furniture as carefully as you have made the building, so that each piece of furniture, loose or built in, has the same unique and organic individuality as the rooms and alcoves have - each different, according to the place it occupies - [[Sequence of Sitting Spaces (142)]], [[Sitting Circle (185)]], [[Built-in Seats (202)]].

Where chairs are placed alone and where chairs are gathered, reinforce the character of the places which the chairs create with [[Pools of Light (252)]], each local to the group of chairs it marks ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1157.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Ornamentation


<!-- ===== pattern-language/wiki/concepts/patterns/dormer-windows-231.md ===== -->

---
title: "Dormer Windows (231)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 231
pattern_name: "Dormer Windows"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Dormer%20Windows%20%28231%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sheltering Roof (117)"
  - "Window Place (180)"
  - "Roof Vaults (220)"
  - "Alcoves (179)"
  - "Gradual Stiffening (208)"
  - "Columns at the Corners (212)"
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Wall Membranes (218)"
  - "Floor-Ceiling Vaults (219)"
  - "Frames as Thickened Edges (225)"
  - "Windows Which Open Wide (236)"
  - "Small Panes (239)"
---

# Dormer Windows (231)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We know from our discussion of Sheltering Roof (117) that the top story of the building should be right inside the roof, surrounded by it.

### Solution
>Wherever you have windows in the roof, make dormer windows which are high enough to stand in, and frame them like any other alcoves in the building.

### Related Patterns
... this pattern helps to complete [[Sheltering Roof (117)]]. If you have followed sheltering roof, your roof has living space within it: and it must therefore have windows in it, to bring light into the roof. This pattern is a special kind of [[Window Place (180)]], which completes the [[Roof Vaults (220)]], in these situations.

Frame them like [[Alcoves (179)]] and [[Window Place (180)]] with [[Gradual Stiffening (208)]], [[Columns at the Corners (212)]], [[Box Columns (216)]], [[Perimeter Beams (217)]], [[Wall Membranes (218)]], [[Floor-Ceiling Vaults (219)]], [[Roof Vaults (220)]] and [[Frames as Thickened Edges (225)]].
Put [[Windows Which Open Wide (236)]] in them, and make [[Small Panes (239)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1081.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/dressing-rooms-189.md ===== -->

---
title: "Dressing Rooms (189)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 189
pattern_name: "Dressing Rooms"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Dressing%20Rooms%20%28189%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Marriage Bed (187)"
  - "Bed Alcove (188)"
  - "Bathing Room (144)"
  - "Light on Two Sides of Every Room (159)"
  - "Thick Walls (197)"
  - "Closets Between Rooms (198)"
  - "Open Shelves (200)"
  - "Waist-High Shelf (201)"
  - "The Shape of Indoor Space (191)"
---

# Dressing Rooms (189)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
> Dressing and undressing, storing clothes, having clothes lying around, have no reason to be part of any larger complex of activities. Indeed they disturb other activities: they are so self-contained that they themselves need concentrated space which has no other function.

### Solution
> Give everyone a dressing room-either private or shared - between their bed and the bathing room. Make this dressing room big enough so there is an open area in it at least six feet in diameter; about six linear feet of clothes hanging space; and another six feet of open shelves; two or three drawers; and a mirror.

### Related Patterns
... if the beds are in position - [[Marriage Bed (187)]], [[Bed Alcove (188)]] - we can give detailed attention to the dressing spaces - both to the closets where people keep their clothes and to the space they use for dressing. These dressing spaces may also help to form the [[Bathing Room (144)]].

Place each dressing room so that it gets plenty of natural [[Light on Two Sides of Every Room (159)]]. Use [[Thick Walls (197)]], [[Closets Between Rooms (198)]], and [[Open Shelves (200)]] to form its walls; include a wide shelf around the edge - [[Waist-High Shelf (201)]]; and for the detailed shape of the room, see [[The Shape of Indoor Space (191)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 872.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/duct-space-229.md ===== -->

---
title: "Duct Space (229)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 229
pattern_name: "Duct Space"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Duct%20Space%20%28229%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Efficient Structure (206)"
  - "Floor-Ceiling Vaults (219)"
  - "Radiant Heat (230)"
  - "Pools of Light (252)"
---

# Duct Space (229)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>You never know where pipes and conduits are; they are buried somewhere in the walls; but where exactly are they?

### Solution
>Make ducts to carry hot air conduit, plumbing, gas, and other services in the triangular space, within the vault, around the upper edge of every room. Connect the ducts for different rooms by vertical ducts, in special chases, in the corners of rooms. Build outlets and panels at intervals along the duct for access to the conduits.

### Related Patterns
... in a building built according to the principle, of [[Efficient Structure (206)]] and built with vaulted floors - [[Floor-Ceiling Vaults (219)]], there is a triangular volume, unused, around the edge of every room. This is the most natural place to put the ducts.

Once the duct is in, you can fill up the triangle with lightweight concrete - [[Floor-Ceiling Vaults (219)]]. Place heating panels along the surface of the triangle - [[Radiant Heat (230)]]; and place outlets for lights at frequent intervals below the duct, with leads and conduits running down in rebates along the window frames - [[Pools of Light (252)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1076.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/eating-atmosphere-182.md ===== -->

---
title: "Eating Atmosphere (182)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 182
pattern_name: "Eating Atmosphere"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Eating%20Atmosphere%20%28182%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Communal Eating (147)"
  - "Farmhouse Kitchen (139)"
  - "Pools of Light (252)"
  - "Warm Colors (250)"
  - "Different Chairs (251)"
  - "Built-in Seats (202)"
  - "Open Shelves (200)"
  - "Waist-High Shelf (201)"
---

# Eating Atmosphere (182)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When people eat together, they may actually be together in spirit—or they may be far apart. Some rooms invite people to eat leisurely and comfortably and feel together, while others force people to eat as quickly as possible so they can go somewhere else to relax.

### Solution
>Put a heavy table in the center of the eating space—large enough for a whole family or the group of people using it. Put a light over the table to create a pool of light over the group, and enclose the space with walls or with contrasting darkness. Make the space large enough so the chairs can be pulled back comfortably, and provide shelves and counters close at hand for things related to the meal.

### Related Patterns
... we have already pointed out how vitally important all kinds of communal eating are in helping to maintain a bond among a group of people - [[Communal Eating (147)]]; and we have given some idea of how the common eating may be placed as part of the kitchen itself - [[Farmhouse Kitchen (139)]]. This pattern gives some details of the eating atmosphere.

Get the details of the light from [[Pools of Light (252)]] ; and choose the colors to make the place warm and dark and comfortable at night - [[Warm Colors (250)]]; put a few soft chairs nearby - [[Different Chairs (251)]]; or put [[Built-in Seats (202)]] with big cushions against one wall; and for the storage space - [[Open Shelves (200)]] and [[Waist-High Shelf (201)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 844.
> #APL/confidence/low
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/eccentric-nucleus-28.md ===== -->

---
title: "Eccentric Nucleus (28)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 28
pattern_name: "Eccentric Nucleus"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Eccentric%20Nucleus%20%2828%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Four-Story Limit (21)"
  - "Magic of the City (10)"
  - "Community of 7000 (12)"
  - "Subculture Boundary (13)"
  - "Density Rings (29)"
  - "Activity Nodes (30)"
  - "Promenade (31)"
  - "Shopping Street (32)"
  - "Sacred Sites (24)"
  - "Quiet Backs (59)"
  - "Still Water (71)"
---

# Eccentric Nucleus (28)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The random character of local densities confuses the identity of our communities, and also creates a chaos in the pattern of land use.

### Solution
>Encourage growth and the accumulation of density to form a clear configuration of peaks and valleys according to the following rules:

>1. Consider the town as a collection of communities of 7,000. These communities will be between 1/4 mile across and 2 miles, according to their overall density.
>2. Mark that point in the boundary of each community which is closest to the nearest major urban center. This point will be the peak of the density, and the core of the “eccentric” nucleus.
>3. Allow the high density to bulge in from the boundary, toward the center of gravity of the community, thus enlarging the eccentric nucleus toward the center.
>4. Continue this high density to form a ridge around the boundary in horseshoe fashion—with the length of the horseshoe dependent on the overall mean gross density, at that part of the city, and the bulge of the horseshoe toward the center of the region, so that the horseshoes form a gradient, according to their position in the region. Those close to a major downtown are almost complete; those further away are only half-complete; and those furthest from centers are shrunken to a point.

### Related Patterns
... so far, we have established an overall height restriction, with its attendant limitation on average density -- [[Four-Story Limit (21)]]. If we assume also, that the city contains major centers for every 300,000 people, spaced according to the rules in [[Magic of the City (10)]], it will follow that the overall density of the city slopes off away from these centers: the high density near to them, the lowest far away. This means that any individual [[Community of 7000 (12)]] will have an overall density given by its distance from the nearest downtown. The question then arises: How should density vary locally, within this community; what geometric pattern should the density have? The question is complicated greatly by the principle of [[Subculture Boundary (13)]], which requires that communities are surrounded by their services, instead of having their services at their geometric centers. This pattern, and the next, defines a local distribution of density which is compatible with this context.

Given this overall configuration, now calculate the average densities at different distances from this ridge of high density, according to the computations given in the next pattern -- [[Density Rings (29)]]; keep major shopping streets and promenades toward the dense part of the horseshoe -- [[Activity Nodes (30)]], [[Promenade (31)]], [[Shopping Street (32)]]; and keep quiet areas toward the open part of the horseshoe -- [[Sacred Sites (24)]], [[Quiet Backs (59)]], [[Still Water (71)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 150.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/efficient-structure-206.md ===== -->

---
title: "Efficient Structure (206)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 206
pattern_name: "Efficient Structure"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Efficient%20Structure%20%28206%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Structure Follows Social Spaces (205)"
  - "Floor and Ceiling Layout (210)"
  - "Floor-Ceiling Vaults (219)"
  - "Roof Layout (209)"
  - "Roof Vaults (220)"
  - "Final Column Distribution (213)"
  - "Columns at the Corners (212)"
  - "Perimeter Beams (217)"
  - "Box Columns (216)"
  - "Wall Membranes (218)"
  - "Frames as Thickened Edges (225)"
  - "Column Connections (227)"
---

# Efficient Structure (206)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Some buildings have column and beam structures; others have load-bearing walls with slab floors; others are vaulted structures, or domes, or tents. But which of these, or what mixture of them, is actually the most efficient? What is the best way to distribute materials throughout a building, so as to enclose the space, strongly and well, with the least amount of material?

### Solution
>Conceive the building as a building made from one continuous body of compressive material. In its geometry, conceive it as a three-dimensional system of individually vaulted spaces, most of them roughly rectangular; with thin load-bearing walls, each stiffened by columns at intervals along its length, thickened where walls meet walls and where walls meet vaults and stiffened around the openings.

### Related Patterns
... this pattern complements the pattern [[Structure Follows Social Spaces (205)]]. Where that pattern defines the relationship between the social spaces and the structure, this pattern lays down the kind of structure which is dictated by pure engineering. As you will see, it is compatible with [[Structure Follows Social Spaces (205)]], and will help to create it.

The layout of the inner vaults is given in [[Floor and Ceiling Layout (210)]] and [[Floor-Ceiling Vaults (219)]]; the layout of the outer vaults which form the roof is given in [[Roof Layout (209)]] and [[Roof Vaults (220)]]. The layout of the stiffeners which make the walls is given in [[Final Column Distribution (213)]]; the layout of the thickening where walls meet walls is given by [[Columns at the Corners (212)]]; the thickening where walls meet vaults is given by [[Perimeter Beams (217)]]; the construction of the columns and the walls is given by [[Box Columns (216)]] and [[Wall Membranes (218)]]; the thickening of doors and window frames is given by [[Frames as Thickened Edges (225)]]; and the non- right-angled connection between columns and beams by [[Column Connections (227)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 946.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Emergent-Structure


<!-- ===== pattern-language/wiki/concepts/patterns/entrance-room-130.md ===== -->

---
title: "Entrance Room (130)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 130
pattern_name: "Entrance Room"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Entrance%20Room%20%28130%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Entrance Transition (112)"
  - "Car Connection (113)"
  - "Private Terrace on the Street (140)"
  - "Gallery Surround (166)"
  - "Front Door Bench (242)"
  - "Tapestry of Light and Dark (135)"
  - "Light on Two Sides of Every Room (159)"
  - "Solid Doors with Glass (237)"
  - "Built-in Seats (202)"
  - "Sequence of Sitting Spaces (142)"
  - "Waist-High Shelf (201)"
  - "The Shape of Indoor Space (191)"
---

# Entrance Room (130)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Arriving in a building, or leaving it, you need a room to pass through, both inside the building and outside it. This is the entrance room.

### Solution
>At the main entrance to a building, make a light-filled room which marks the entrance and straddles the boundary between indoors and outdoors, covering some space outdoors and some space indoors. The outside part may be like an old-fashioned porch; the inside like a hall or sitting room.

### Related Patterns
... the position and overall shape of entrances is given by [[Family of Entrances (102)]], [[Main Entrance (110)]] and [[Entrance Transition (112)]]. This pattern gives the entrances their detailed shape, their shape and body and three dimensions, and helps complete the form begun by [[Car Connection (113)]], and the [[Private Terrace on the Street (140)]].

Give that part of the entrance which sticks out into the street or garden a physical character which, as far as possible, make it one of the family of entrances along the street - [[Family of Entrances (102)]]; where it is appropriate, make it a porch - [[Gallery Surround (166)]]; and include a bench or seat, where people can watch the world go by or wait for someone - [[Front Door Bench (242)]]. As for the indoor part of the entrance room, above all, make sure that it is filled with light from two or even three sides, so that the first impression of the building is of light - [[Tapestry of Light and Dark (135)]], [[Light on Two Sides of Every Room (159)]]. Put windows in the door itself - [[Solid Doors with Glass (237)]]. Put in [[Built-in Seats (202)]] and make the room part of the [[Sequence of Sitting Spaces (142)]]; provide a [[Waist-High Shelf (201)]] for packages. And finally, for the overall shape of the entrance room and its construction, begin with [[The Shape of Indoor Space (191)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 622.
> #APL/confidence/high
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/entrance-transition-112.md ===== -->

---
title: "Entrance Transition (112)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 112
pattern_name: "Entrance Transition"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Entrance%20Transition%20%28112%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Main Gateways (53)"
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Half-Hidden Garden (111)"
  - "Zen View (134)"
  - "Garden Wall (173)"
  - "Tapestry of Light and Dark (135)"
  - "Trellised Walk (174)"
  - "Entrance Room (130)"
  - "Intimacy Gradient (127)"
---

# Entrance Transition (112)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Buildings, and especially houses, with a graceful transition between the street and the inside, are more tranquil than those which open directly off the street.

### Solution
>Make a transition space between the street and the front door. Bring the path which connects street and entrance through this transition space, and mark it with a change of light, a change of sound, a change of direction, a change of surface, a change of level, perhaps by gateways which make a change of enclosure, and above all with a change of view.

### Related Patterns
... whatever kind of building or building complex you are making, you have a rough position for its major entrances the gateways to the site from [[Main Gateways (53)]]; the entrances to individual buildings from [[Family of Entrances (102)]], [[Main Entrance (110)]]. In every case, the entrances create a transition between the "outside" - the public world - and some less public inner world. If you have [[Half-Hidden Garden (111)]] the gardens help to intensify the beauty of the transition. This pattern now elaborates and reinforces the transition which entrances and gardens generate.

Emphasize the momentary view which marks the transition by a glimpse of a distant place - [[Zen View (134)]] ; perhaps make a gateway or a simple garden gate to mark the entrance - [[Garden Wall (173)]] ; and emphasize the change of light - [[Tapestry of Light and Dark (135)]], [[Trellised Walk (174)]]. The transition runs right up to the front door, up to the [[Entrance Room (130)]], and marks the beginning of the [[Intimacy Gradient (127)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 548.
> #APL/confidence/high
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/family-of-entrances-102.md ===== -->

---
title: "Family of Entrances (102)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 102
pattern_name: "Family of Entrances"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Family%20of%20Entrances%20%28102%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Circulation Realms (98)"
  - "Main Entrance (110)"
  - "Entrance Transition (112)"
  - "Entrance Room (130)"
  - "Reception Welcomes You (149)"
---

# Family of Entrances (102)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When a person arrives in a complex of offices or services or workshops, or in a group of related houses, there is a good chance they will experience confusion unless the whole collection is laid out before them, so that they can see the entrance of the place where they are going.

### Solution
>Lay out the entrances to form a family. This means:

>1. They form a group, are visible together, and each visible from all the others.
>2. They are all broadly similar, for instances all porches, or all gates in a wall, or all marked by a similar kind of doorway.

### Related Patterns
... this pattern is an embellishment of [[Circulation Realms (98)]] which portrayed a series of realms, in a large building or a building complex, with a major entrance or gateway into each realm and a collection of minor doorways, gates, and openings off each realm. This pattern applies to the relationship between these "minor" entrances.

In detail, make the entrances bold and easy to see - [[Main Entrance (110)]] ; when they lead into private domains, houses and the like, make a transition in between the, public street and the inside - [[Entrance Transition (112)]]; and shape the entrance itself as a room, which straddles the wall, and is thus both inside and outside as a projecting volume, covered and protected from the rain and sun - [[Entrance Room (130)]]. If it is an entrance from an indoor street into a public office, make reception part of the entrance - [[Reception Welcomes You (149)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 499.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/farmhouse-kitchen-139.md ===== -->

---
title: "Farmhouse Kitchen (139)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 139
pattern_name: "Farmhouse Kitchen"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Farmhouse%20Kitchen%20%28139%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "Communal Eating (147)"
  - "Light on Two Sides of Every Room (159)"
  - "Cooking Layout (184)"
  - "Sunny Counter (199)"
  - "Alcoves (179)"
  - "Eating Atmosphere (182)"
  - "Open Shelves (200)"
  - "Waist-High Shelf (201)"
  - "Sequence of Sitting Spaces (142)"
  - "The Shape of Indoor Space (191)"
---

# Farmhouse Kitchen (139)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The isolated kitchen, separate from the family and considered as an efficient but unpleasant factory of food is a hangover from the days of servants; and from the more recent days when women willingly took over the servants’ role.

### Solution
>Make the kitchen bigger than usual, big enough to include the “family room” space, and place it near the center of the commons, not so far back in the house as an ordinary kitchen. Make it large enough to hold a good big table and chairs, some soft and some hard, with counters and stove and sink around the edge of the room; and make it a bright and comfortable room.

### Related Patterns
... you have laid out, or already have, some kind of common area at the center of the building. In many cases, especially in houses, the heart of this common area is a kitchen or an eating area since shared food has more capacity than almost anything to be the basis for communal feelings - [[Common Areas at the Heart (129)]], [[Communal Eating (147)]]. This pattern defines an ancient kind of kitchen where the cooking and the eating and the living are all in a single place.

Give the kitchen [[Light on Two Sides of Every Room (159)]]. When you place the kitchen counters later, make them really long and generous and toward the south to get the light - [[Cooking Layout (184)]], [[Sunny Counter (199)]]; leave room for an alcove or two around the kitchen - [[Alcoves (179)]]; make the table in the middle big, and hang a nice big warm single light right in the middle to draw the family around it - [[Eating Atmosphere (182)]]; surround the walls, when you detail them, with plenty of open shelves for pots, and mugs, and bottles, and jars of jam - [[Open Shelves (200)]], [[Waist-High Shelf (201)]]. Put in a comfortable chair somewhere - [[Sequence of Sitting Spaces (142)]]. And for the room shape and construction, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 660.
> #APL/confidence/high
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/filtered-light-238.md ===== -->

---
title: "Filtered Light (238)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 238
pattern_name: "Filtered Light"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Filtered%20Light%20%28238%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Natural Doors and Windows (221)"
  - "Deep Reveals (223)"
  - "Climbing Plants (246)"
  - "Canvas Roofs (244)"
  - "Warm Colors (250)"
  - "Small Panes (239)"
---

# Filtered Light (238)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Light filtered through leaves, or tracery, is wonderful. But why?

### Solution
>Where the edge of a window or the overhanging eave of a roof is silhouetted against the sky, make a rich, detailed tapestry of light and dark, to break up the light and soften it.

### Related Patterns
... even if the windows are beautifully placed, glare can still be a problem - [[Natural Doors and Windows (221)]]. The softness of the light, in and around the window, makes an enormous difference to the room inside. The shape of the frames can do a part of it - [[Deep Reveals (223)]] - but it still needs additional help.

You can do this, most easily, with climbing plants trained to climb around the outside of the window - [[Climbing Plants (246)]]. If there are no plants, you can also do it beautifully with simple canvas awnings [[Canvas Roofs (244)]], perhaps colored [[Warm Colors (250)]]. You can also help to filter light by making the panes smaller, more delicate, and more elaborate high in the window where the light is strong - [[Small Panes (239)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1105.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/final-column-distribution-213.md ===== -->

---
title: "Final Column Distribution (213)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 213
pattern_name: "Final Column Distribution"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Final%20Column%20Distribution%20%28213%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Columns at the Corners (212)"
  - "Efficient Structure (206)"
  - "Ceiling Height Variety (190)"
  - "Wall Membranes (218)"
  - "Box Columns (216)"
---

# Final Column Distribution (213)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>How should the spacing of the secondary columns which stiffen the walls, vary with ceiling height, number of stories, and the size of rooms?

### Solution
>Make column stiffeners furthest apart on the ground floor and closer and closer together as you go higher in the building. The exact column spacings for a particular building will depend on heights and loads and wall thicknesses. The numbers in the following table are for illustration only, but they show roughly what is needed.

| Building Height | Ground Floor | 2nd Floor | 3rd Floor | 4th Floor |
|:---------------:|:------------:|:---------:|:---------:|:---------:|
|        1        |    2'-5'     |           |           |           |
|        2        |    3'-6'     |   1'-3'   |           |           |
|        3        |    4'-8'     |   3'-6'   |   1'-3'   |           |
|        4        |     >5'      |   4'-8'   |   3'-6'   |   1'-3'   |

>Mark in these extra stiffening columns as dots between the corner columns on the drawings you have made for different floors. Adjust them so they are evenly spaced between each pair of corner columns; but on any one floor, make sure that they are closer together along the walls of small rooms and further apart along the walls of large rooms.

### Related Patterns
... assume that you have placed the corner columns which define the spaces - [[Columns at the Corners (212)]]. It is now necessary to fill in the gaps between the columns with intermediate stiffener columns as required by [[Efficient Structure (206)]]. This pattern gives the spacing of these intermediate stiffener columns, and helps to generate the kind of walls which [[Efficient Structure (206)]] requires. It also helps to generate [[Ceiling Height Variety (190)]].

To the extent consistent with [[Ceiling Height Variety (190)]], make walls and columns progressively shorter the higher you go in the building to keep slenderness ratios low.

And make wall thicknesses and column thicknesses vary with the height - see [[Wall Membranes (218)]]. Our calculations, for a typical lightweight concrete building of the kind we have been discussing, suggest the following orders of magnitude for wall thicknesses: Top story - 2 inches thick; one below top story - 3 inches; two below top story - 4 inches; three stories below top (ground floor on a four story building) - 5 inches. Of course these numbers will change for different loads, or for different materials, but they show the type of variation you can expect.

Column thicknesses must be proportional to wall thicknesses, so that the thinnest walls have the thinnest columns. If they are very thin, it will be possible to make them simply by placing boards, or one thickness of material, outside the outer skins which form the wall membrane - see [[Wall Membranes (218)]]. If the walls are thick, they will need to be full columns, twice as thick as the walls, and roughly square in section, built before the walls, but made in such a way that they can be poured integrally with the walls - [[Box Columns (216)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 995.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Structural-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/flexible-office-space-146.md ===== -->

---
title: "Flexible Office Space (146)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 146
pattern_name: "Flexible Office Space"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Flexible%20Office%20Space%20%28146%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Self-Governing Workshops and Offices (80)"
  - "Office Connections (82)"
  - "Intimacy Gradient (127)"
  - "Common Areas at the Heart (129)"
  - "Light on Two Sides of Every Room (159)"
  - "Ceiling Height Variety (190)"
  - "Column Place (226)"
  - "Small Work Groups (148)"
  - "Half-Private Office (152)"
  - "Reception Welcomes You (149)"
  - "Communal Eating (147)"
---

# Flexible Office Space (146)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Is it possible to create a kind of space which is specifically tuned to the needs of people working, and yet capable of an infinite number of various arrangements and combinations within it?

### Solution
>Lay out the office space as wings of open space, with free-standing columns around their edges, so they define half-private and common spaces opening into one another. Set down enough columns so that people can fill them in over the years, in many different ways—but always in a semi-permanent fashion.
>If you happen to know the working group before you build the space, then make it more like a house, more closely tailored to their needs. In either case, create a variety of space throughout the office—comparable in variety to the different sizes and kinds of space in a large old house.


### Related Patterns
... imagine that you have laid out the basic areas of a workshop or office [[Self-Governing Workshops and Offices (80)]], [[Office Connections (82)]]. Once again, as in a house, the most basic layout of all is given by [[Intimacy Gradient (127)]] and [[Common Areas at the Heart (129)]]. Within their general framework, this pattern helps to define the working space in more detail, and so completes these larger patterns.

Light is critical. The bays of this kind of workspace must either be free-standing (so that there is light behind the alcoves), or the entire bay must be short enough to bring enough light in from the two ends - [[Light on Two Sides of Every Room (159)]]. Use [[Ceiling Height Variety (190)]] and [[Column Place (226)]] to define the proper mix of possible spaces. Above all, lay the workspace out in such a way to make it possible for people to work in twos and threes, always with partial contact and partial privacy - [[Small Work Groups (148)]] and [[Half-Private Office (152)]]. Place a welcoming reception area at the front - [[Reception Welcomes You (149)]]; and in the common areas at the heart arrange a place where people can eat together everyday - [[Communal Eating (147)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 690.
> #APL/confidence/low
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/floor-and-ceiling-layout-210.md ===== -->

---
title: "Floor and Ceiling Layout (210)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 210
pattern_name: "Floor and Ceiling Layout"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Floor%20and%20Ceiling%20Layout%20%28210%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Efficient Structure (206)"
  - "Ceiling Height Variety (190)"
  - "Roof Layout (209)"
  - "Perimeter Beams (217)"
  - "Floor-Ceiling Vaults (219)"
  - "Final Column Distribution (213)"
  - "Floor Surface (233)"
  - "Columns at the Corners (212)"
  - "Thickening the Outer Walls (211)"
---

# Floor and Ceiling Layout (210)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Again, the basic problem is to maintain the integrity of social spaces in the plan.

### Solution
>Draw a vault plan, for every floor. Use two-way vaults most often; and one-way barrel vaults for any spaces which are more than twice as long as they are wide. Draw sections through the building as you plan the vaults, and bear the following facts in mind:

>1. Generally speaking, the vaults should correspond to rooms.
>2. There will have to be a support under the sides of each vault: this will usually be the top of a wall. Under exceptional circumstances, it can be a beam or arch.
>3. A vault may span as little as 5 feet and as much as 30 feet. However, it must have a rise equal to at least 13 percent of its shorter span.
>4. If the edge of one vault is more than a couple of feet (in plan) from the edge of the vault below it—then the lower vault will have to contain an arch to support the load from the upper vault.

### Related Patterns
... [[Efficient Structure (206)]] tells us that the spaces in the building should be vaulted so that the floors and ceilings can be made almost entirely of compression materials. To lay out the floor and ceiling vaults, we must fit them to the variety of ceiling heights over individual rooms - [[Ceiling Height Variety (190)]] and, on the top story, to the layout of the roof vaults - [[Roof Layout (209)]].

Put a [[Perimeter Beams (217)]] on all four sides of every vault, along the top of the bearing wall, or spanning openings. Get the shape of the vaults from [[Floor-Ceiling Vaults (219)]] and as you lay out the sections through the vaults, bear in mind that the perimeter beams get lower and lower on higher floors, because the columns on upper stories must be shorter (top floor columns about 4 feet, one below top 6 feet, two below top 6 to 7 feet, three below top 8 feet) - [[Final Column Distribution (213)]]. Make sure that variations in floor level coincide with the distinctions between quiet and more public areas - [[Floor Surface (233)]]. Complete the definition of the individual spaces which the vaults create with [[Columns at the Corners (212)]]. Include the smallest vaults of all, around the building edge, in [[Thickening the Outer Walls (211)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 978.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Structural-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/floor-ceiling-vaults-219.md ===== -->

---
title: "Floor-Ceiling Vaults (219)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 219
pattern_name: "Floor-Ceiling Vaults"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Floor-Ceiling%20Vaults%20%28219%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Efficient Structure (206)"
  - "Good Materials (207)"
  - "Floor and Ceiling Layout (210)"
  - "Perimeter Beams (217)"
  - "Ceiling Height Variety (190)"
  - "Final Column Distribution (213)"
  - "Root Foundations (214)"
  - "Soft Inside Walls (235)"
  - "Floor Surface (233)"
---

# Floor-Ceiling Vaults (219)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We seek a ceiling vault shape which will support a live load on the floor above, form the ceiling of the room below, and generate as little bending and tension as possible so that compressive materials can be relied on.

### Solution
>Build floors and ceilings in the form of elliptical vaults, which rise between 13 and 20 percent of the shorter span. Use a type of construction which makes it possible to fit the vault to any shapes room after the walls and columns are in position: on no account use a prefabricated vault.

### Related Patterns
... we have already discussed the fact that ordinary joist floors and slab floors are inefficient and wasteful because the tension materials they use to resist bending are less common than pure compression materials - [[Efficient Structure (206)]], [[Good Materials (207)]], and that it is therefore desirable to use vaults wherever possible. This pattern gives the shape and construction of the vaults. The vaults will help to complete [[Floor and Ceiling Layout (210)]], and [[Perimeter Beams (217)]]; and, most important of all, they will help to create the [[Ceiling Height Variety (190)]] in different rooms.

When the main vault is finished, mark the positions of all those columns which will be placed on the floor above it - [[Final Column Distribution (213)]] - Whenever there are columns which are more than 2 feet away from the perimeter beam, strengthen the vault with ribs and extra reinforcing to withstand the vertical forces.

Put all the upper columns in position before you pour the floor of the vault, so that when you pour it, the concrete will pour around the column feet, and anchor them firmly in the same way that they are anchored in the foundations - [[Root Foundations (214)]].

To finish the under surface of the vault paint it or plaster it - [[Soft Inside Walls (235)]]. As for the floor surface above, either wax it and polish it or cover it with soft materials - [[Floor Surface (233)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1027.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/floor-surface-233.md ===== -->

---
title: "Floor Surface (233)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 233
pattern_name: "Floor Surface"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Floor%20Surface%20%28233%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Ground Floor Slab (215)"
  - "Floor-Ceiling Vaults (219)"
  - "Intimacy Gradient (127)"
  - "Soft Tile and Brick (248)"
  - "Ornament (249)"
  - "Warm Colors (250)"
---

# Floor Surface (233)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We want the floor to be comfortable, warm to the touch, inviting. But we also want it to be hard enough to resist wear, and easy to clean.

### Solution
>Zone the house, or building, into two kinds of zones: public zones, and private or more intimate zones. Use hard materials like waxed, red polished concrete, tiles, or hardwood in the public zones. In the more intimate zone, use an underfloor of soft materials, like felt, cheap nylon carpet, or straw matting, and cover it with clothes, and pillows, and carpets, and tapestries. Make a clearly marked edge between the two—perhaps even a step—so that people can take their shoes off when they pass from the public to the intimate.

### Related Patterns
... this pattern tells you how to put the surface on the floors, to finish the [[Ground Floor Slab (215)]] and [[Floor-Ceiling Vaults (219)]]. When properly made, the floor surfaces will also help intensify the gradient of intimacy in the building [[Intimacy Gradient (127)]].

On the hard floor, you can use the same floor as you use on outdoor paths and terraces - hand fired brick and tile - [[Soft Tile and Brick (248)]]. On the soft intimate floors, use materials and cloths that are rich in ornament and color - [[Ornament (249)]], [[Warm Colors (250)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1088.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/food-stands-93.md ===== -->

---
title: "Food Stands (93)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 93
pattern_name: "Food Stands"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Food%20Stands%20%2893%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Activity Nodes (30)"
  - "Road Crossing (54)"
  - "Raised Walk (55)"
  - "Small Public Squares (61)"
  - "Bus Stop (92)"
  - "Activity Pockets (124)"
  - "Canvas Roofs (244)"
  - "Individually Owned Shops (87)"
---

# Food Stands (93)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Many of our habits and institutions are bolstered by the fact that we can get simple, inexpensive food on the street, on the way to shopping, work, and friends.

### Solution
>Concentrate food stands where cars and paths meet—either portable stands or small huts, or built into the fronts of buildings, half-open to the street.

### Related Patterns
... throughout the neighborhood there are natural public gathering places - [[Activity Nodes (30)]], [[Road Crossing (54)]], [[Raised Walk (55)]], [[Small Public Squares (61)]], [[Bus Stop (92)]]. All draw their life, to some extent, from the food stands, the hawkers, and the vendors who fill the street with the smell of food.

Treat these food stands as [[Activity Pockets (124)]] when they are part of a square; Use canvas roofs to make a simple shelter over them - [[Canvas Roofs (244)]] ; and keep them in line with the precepts of [[Individually Owned Shops (87)]]: the best food always comes from people who are in business for themselves, who buy the raw food, and prepare it in their own style ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 454.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/four-story-limit-21.md ===== -->

---
title: "Four-Story Limit (21)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 21
pattern_name: "Four-Story Limit"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Four-Story%20Limit%20%2821%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "City Country Fingers (3)"
  - "Lace of Country Streets (5)"
  - "Magic of the City (10)"
  - "Number of Stories (96)"
  - "Density Rings (29)"
  - "Building Complex (95)"
  - "Housing Hill (39)"
  - "Office Connections (82)"
  - "High Places (62)"
---

# Four-Story Limit (21)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There is abundant evidence to show that high buildings make people crazy.

### Solution
>In any urban area, no matter how dense, keep the majority of buildings four stories high or less. It is possible that certain buildings should exceed this limit, but they should never be buildings for human habitation.

### Related Patterns
... within an urban area, the density of building fluctuates. It will, in general, be rather higher toward the center and lower toward the edges -- [[City Country Fingers (3)]], [[Lace of Country Streets (5)]], [[Magic of the City (10)]]; however, throughout the city, even at its densest points, there are strong human reasons to subject all buildings to height restrictions.

Within the framework of the four-story limit the exact height of individual buildings, according to the area of floor they need, the area of the site, and the height of the surrounding buildings, is given by the pattern [[Number of Stories (96)]]. More global variations of density are given by [[Density Rings (29)]]. The horizontal subdivision of large buildings into smaller units, and separate smaller buildings, is given by [[Building Complex (95)]]. [[Housing Hill (39)]] and [[Office Connections (82)]] help to shape multi-stories apartments and offices within constraints of a four-story limit. And finally, don't take the four-story limit too literally. Occasional exceptions from the general rule are very important -- [[High Places (62)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 114.
> #APL/confidence/high
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/frames-as-thickened-edges-225.md ===== -->

---
title: "Frames as Thickened Edges (225)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 225
pattern_name: "Frames as Thickened Edges"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Frames%20as%20Thickened%20Edges%20%28225%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Natural Doors and Windows (221)"
  - "Efficient Structure (206)"
  - "Gradual Stiffening (208)"
  - "Deep Reveals (223)"
  - "Windows Which Open Wide (236)"
  - "Solid Doors with Glass (237)"
  - "Small Panes (239)"
---

# Frames as Thickened Edges (225)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Any homogeneous membrane which has holes in it will tend to rupture at the holes, unless the edges of the holes are reinforced by thickening.

### Solution
>Do not consider door and window frames as separate rigid structures which are inserted into holes in walls. Think of them instead as thickenings of the very fabric of the wall itself, made to protect the wall against the concentrations of stress which develop around openings.
>In line with this conception, build the frames as thickenings of the wall material, continuous with the wall itself, made of the same materials, and poured, or built up, in a manner which is continuous with the structure of the wall.

### Related Patterns
... assume that columns and beams are in and that you have marked the exact positions of the doors and windows with string or pencil marks - [[Natural Doors and Windows (221)]]. You are ready to build the frames. Remember that a well made frame needs to be continuous with the surrounding wall, so that it helps the building structurally - [[Efficient Structure (206)]], [[Gradual Stiffening (208)]].

In windows, splay the thickening, to create [[Deep Reveals (223)]]; the form of doors and windows which will fill the frame, is given by the later patterns - [[Windows Which Open Wide (236)]], [[Solid Doors with Glass (237)]], [[Small Panes (239)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1059.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Fenestration


<!-- ===== pattern-language/wiki/concepts/patterns/front-door-bench-242.md ===== -->

---
title: "Front Door Bench (242)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 242
pattern_name: "Front Door Bench"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Front%20Door%20Bench%20%28242%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Seat Spots (241)"
  - "Arcades (119)"
  - "Building Edge (160)"
  - "Sunny Place (161)"
  - "Connection to the Earth (168)"
  - "Entrance Room (130)"
  - "Old Age Cottage (155)"
  - "Main Entrance (110)"
  - "Sitting Wall (243)"
  - "Raised Flowers (245)"
---

# Front Door Bench (242)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People like to watch the street.

### Solution
>Build a special bench outside the front door where people from inside can sit comfortably for hours on end and watch the world go by. Place the bench to define a half-private domain in front of the house. A low wall, planting, a tree, can help to create the same domain.

### Related Patterns
... [[Seat Spots (241)]], acting within several larger patterns, creates an atmosphere around the edge of the building which invites lingering - [[Arcades (119)]], [[Building Edge (160)]], [[Sunny Place (161)]], [[Connection to the Earth (168)]]; it is most marked and most important near the entrance - [[Entrance Room (130)]]. This pattern defines a special [[Seat Spots (241)]]: a bench which helps to form the entrance room and the building edge around the entrance. It is always important; but perhaps most important of all, at the door of an [[Old Age Cottage (155)]].

The bench may help to make the entrance visible - [[Main Entrance (110)]]; it can be part of a wall - [[Sitting Wall (243)]], with flowers in the sunshine next to it - [[Raised Flowers (245)]]. Place it with care, according to the rules given in [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1121.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/fruit-trees-170.md ===== -->

---
title: "Fruit Trees (170)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 170
pattern_name: "Fruit Trees"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Fruit%20Trees%20%28170%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Land (67)"
  - "Half-Hidden Garden (111)"
  - "Tree Places (171)"
  - "Garden Seat (176)"
  - "Paths and Goals (120)"
---

# Fruit Trees (170)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In the climates where fruit trees grow, the orchards given the land an almost magical identity: think of the orange groves of Southern California, the cherry trees of Japan, the olive trees of Greece. But the growth of cities seems always to destroy these trees and the quality the possess.

### Solution
>Plant small orchards of fruit trees in gardens and on common land along paths and streets, in parks, in neighborhoods: wherever there are well-established groups that can themselves care for the trees and harvest the fruit.

### Related Patterns
... both the [[Common Land (67)]] outside the workshops, offices and houses, and the private gardens which belong to individual buildings - [[Half-Hidden Garden (111)]], can be helped by planting fruit trees. After all, a garden, whether it is public or private, is a thing of use. Yet it is not a farm. That half way kind of garden which is useful, but also beautiful in spring and autumn, and a marvelous place to walk because it smells so wonderful, is the orchard.

If you have an especially nice fruit tree, make a [[Tree Places (171)]] under it, with a [[Garden Seat (176)]], or arrange a path so the tree can provide a natural goal along the path - [[Paths and Goals (120)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 794.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/gallery-surround-166.md ===== -->

---
title: "Gallery Surround (166)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 166
pattern_name: "Gallery Surround"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Gallery%20Surround%20%28166%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Edge (160)"
  - "Arcades (119)"
  - "Roof Garden (118)"
  - "Pedestrian Street (100)"
  - "Private Terrace on the Street (140)"
  - "Outdoor Room (163)"
  - "Six-Foot Balcony (167)"
  - "Half-Open Wall (193)"
  - "Column Place (226)"
---

# Gallery Surround (166)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If people cannot walk out from the building onto balconies and terraces which look toward the outdoor space around the building, then neither they themselves nor the people outside have any medium which helps them feel the building and the larger public world are intertwined.

### Solution
>Whenever possible, and at every story, build porches, galleries, arcades, balconies, niches, outdoor seats, awnings, trellised rooms, and the like at the edges of the buildings—especially where they open off public spaces and streets, and connect them by doors, directly to the rooms inside.

### Related Patterns
... we continue to fill out the [[Building Edge (160)]]. Assume that arcades have been built wherever they make sense - [[Arcades (119)]]; there are still large areas within the building edge where [[Building Edge (160)]] tells you to make something positive - but so far no patterns have explained how this can be done physically. This pattern shows you how you can complete the edge. It complements [[Roof Garden (118)]] and [[Arcades (119)]] and helps to enliven the [[Pedestrian Street (100)]].

These places should be an integral part of the building territory, and contain seats, tables, furniture, places to stand and talk, places to work outside - all in the public view - [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]]; make the spaces deep enough to be really useful - [[Six-Foot Balcony (167)]] - with columns heavy enough to provide at least partial enclosure - [[Half-Open Wall (193)]], [[Column Place (226)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 777.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/garden-growing-wild-172.md ===== -->

---
title: "Garden Growing Wild (172)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 172
pattern_name: "Garden Growing Wild"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Garden%20Growing%20Wild%20%28172%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Terraced Slope (169)"
  - "Fruit Trees (170)"
  - "Greenhouse (175)"
  - "Garden Seat (176)"
  - "Still Water (71)"
  - "Raised Flowers (245)"
---

# Garden Growing Wild (172)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A garden which grows true to its own laws is not a wilderness, yet not entirely artificial either.

### Solution
>Grow grasses, mosses, bushes, flowers, and trees in a way which comes close to the way that they occur in nature: intermingled, without barriers between them, without bare earth, without formal flower beds, and with all the boundaries and edges made in rough stone and brick and wood which become a part of the natural growth.

### Related Patterns
... with terracing in place and trees taken care of - [[Terraced Slope (169)]], [[Fruit Trees (170)]], we come to the garden itself - to the ground and plants. In short, we must decide what kind of garden to have, what kind of plants to grow, what style of gardening is compatible with both artifice and nature.

Include no formal elements, except where something is specifically called for by function - like a greenhouse [[Greenhouse (175)]], a quiet seat - [[Garden Seat (176)]], some water - [[Still Water (71)]], or flowers placed just where people can touch them and smell them - [[Raised Flowers (245)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 801.
> #APL/confidence/high
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/garden-seat-176.md ===== -->

---
title: "Garden Seat (176)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 176
pattern_name: "Garden Seat"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Garden%20Seat%20%28176%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Garden Growing Wild (172)"
  - "Sunny Place (161)"
  - "Seat Spots (241)"
  - "Filtered Light (238)"
---

# Garden Seat (176)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Somewhere in every garden, there must be at least one spot, a quiet garden seat, in which a person—or two people—can reach into themselves and be in touch with nothing else but nature.

### Solution
>Make a quiet place in the garden—a private enclosure with a comfortable seat, think planting, sun. Pick the place for the sear carefully; pick the place that will give you the most intense kind of solitude.

### Related Patterns
... with the character of the garden fixed - [[Garden Growing Wild (172)]], we consider the special corners which make the garden valuable and somewhat secret. Of these, the most important is the [[Sunny Place (161)]], which has already been described, because it is so fundamental to the building. Now we add to this another seat, more private, where a person can go to sit and think and dream.

Place the garden seat, like other outdoor seats, where it commands a view, is in the sun, is sheltered from the wind - [[Seat Spots (241)]] ; perhaps under bushes and trees where light is soft and dappled - [[Filtered Light (238)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 815.
> #APL/confidence/low
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/garden-wall-173.md ===== -->

---
title: "Garden Wall (173)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 173
pattern_name: "Garden Wall"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Garden%20Wall%20%28173%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Half-Hidden Garden (111)"
  - "Private Terrace on the Street (140)"
  - "Quiet Backs (59)"
  - "Accessible Green (60)"
  - "Positive Outdoor Space (106)"
  - "Trellised Walk (174)"
  - "Half-Open Wall (193)"
  - "Hierarchy of Open Space (114)"
  - "Zen View (134)"
---

# Garden Wall (173)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Gardens and small public parks don’t give enough relief from noise unless they are well-protected.

### Solution
>Form some kind of enclosure to protect the interior of a quiet garden from the sights and sounds of passing traffic. If it is a large garden or a park, the enclosure can be soft, can include bushes, trees, slopes, and so on. The smaller the garden, however, the harder and more defined the enclosure must become. In a very small garden, form the enclosure with buildings or walls; even hedges and fences will not be enough to keep out sound.

### Related Patterns
... in private houses, both the [[Half-Hidden Garden (111)]] and the [[Private Terrace on the Street (140)]] require walls. More generally, not only private gardens, but public gardens too, and even small parks and greens - [[Quiet Backs (59)]], [[Accessible Green (60)]], need some kind of enclosure round them, to make them as beautiful and quiet as possible.

Use the garden wall to help form positive outdoor space - [[Positive Outdoor Space (106)]]; but pierce it with balustrades and windows to make connections between garden and street, or garden and garden - [[Private Terrace on the Street (140)]], [[Trellised Walk (174)]], [[Half-Open Wall (193)]], and above all, give it openings to make views into other larger and more distant spaces - [[Hierarchy of Open Space (114)]], [[Zen View (134)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 805.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/good-materials-207.md ===== -->

---
title: "Good Materials (207)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 207
pattern_name: "Good Materials"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Good%20Materials%20%28207%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Structure Follows Social Spaces (205)"
  - "Efficient Structure (206)"
  - "Gradual Stiffening (208)"
  - "Lapped Outside Walls (234)"
  - "Soft Inside Walls (235)"
---

# Good Materials (207)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There is a fundamental conflict in the nature of materials for building in industrial society.

### Solution
>Use only biodegradable, low-energy-consuming materials, which are easy to cut and modify on site. For bulk materials we suggest ultra-lightweight 40–60 lbs. concrete and earth-based materials like tamped earth, brick, and tile. For secondary materials, use wood planks, gypsum, plywood, cloth, chickenwire, paper, cardboard, particle board, corrugated iron, lime plasters, bamboo, rope, and tile.

### Related Patterns
... the principles of structure allow you to imagine a building in which materials are distributed in the most efficient way, congruent with the social spaces given by the plan - [[Structure Follows Social Spaces (205)]], [[Efficient Structure (206)]]. But of course the structural conception is still only schematic. It can only become firm and cogent in your mind when you know what materials the building will be made of. This pattern helps you settle on materials.

In [[Gradual Stiffening (208)]], We shall Work out the way of using these materials that goes with [[Structure Follows Social Spaces (205)]] and [[Efficient Structure (206)]]. Try to use the materials in such a way as to allow their own texture to show themselves - [[Lapped Outside Walls (234)]], [[Soft Inside Walls (235)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 955.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Emergent-Structure


<!-- ===== pattern-language/wiki/concepts/patterns/gradual-stiffening-208.md ===== -->

---
title: "Gradual Stiffening (208)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 208
pattern_name: "Gradual Stiffening"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Gradual%20Stiffening%20%28208%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Structure Follows Social Spaces (205)"
  - "Efficient Structure (206)"
  - "Good Materials (207)"
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Wall Membranes (218)"
  - "Floor-Ceiling Vaults (219)"
  - "Roof Vaults (220)"
---

# Gradual Stiffening (208)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The fundamental philosophy behind the use of pattern languages is that buildings should be uniquely adapted to individual needs and sites; and that the plans of buildings should be rather loose and fluid, in order to accommodate these subtleties.

### Solution
>Recognize that you are not assembling a building from components like an erector set, but that you are instead weaving a structure which starts out globally complete, but flimsy; then gradually making it stiffer but still rather flimsy; and only finally making it completely stiff and strong.
>We believe that in our own time, the most natural version of this process is to put up a shell of sheet materials, and then make it fully strong by filling it with a compressive fill.

### Related Patterns
... in [[Structure Follows Social Spaces (205)]] and [[Efficient Structure (206)]] we have set down the beginnings of a philosophy, an approach, to construction. [[Good Materials (207)]] tells us something about the materials we ought to use in order to meet human and ecological demands. Now, before we start the practical task of making a structural layout for a building, it is necessary to consider one more philosophical pattern: one which defines the process of construction that will make it possible to use the right materials and get the overall conception of the structure right.

Choose the most natural materials you can, for the outer shell itself - thin wood planks for columns, canvas or burlap for the vaults, plaster board or plank or bricks or hollow tiles for walls - [[Good Materials (207)]].

Use ultra-lightweight 40 to 60 pounds perlite concrete for the compressive fill - it has the same density as wood and can be cut and nailed like wood, both during the construction and in later years when repairs become necessary - [[Good Materials (207)]].

Build up the columns first, then fill them with the ultra-lightweight concrete; then build up the beams and fill them; then the vaults, and cover them with a thin coat of concrete which hardens to form a shell; then fill that shell with even lighter weight materials to form the floors; then make the walls and window frames, and fill them; and finally, the roof, again a thin cloth vault covered with a coat of concrete to form a shell - [[Box Columns (216)]], [[Perimeter Beams (217)]], [[Wall Membranes (218)]], [[Floor-Ceiling Vaults (219)]], [[Roof Vaults (220)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 962.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Emergent-Structure


<!-- ===== pattern-language/wiki/concepts/patterns/grave-sites-70.md ===== -->

---
title: "Grave Sites (70)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 70
pattern_name: "Grave Sites"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Grave%20Sites%20%2870%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Life Cycle (26)"
  - "Identifiable Neighborhood (14)"
  - "Holy Ground (66)"
  - "Common Land (67)"
  - "Quiet Backs (59)"
  - "Tree Places (171)"
  - "Seat Spots (241)"
---

# Grave Sites (70)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No people who turn their backs on death can be alive. The presence of the dead among the living will be a daily fact in any society which encourages its people to live.

### Solution
>Never build massive cemeteries. Instead, allocate pieces of land throughout the community as grave sites—corners of parks, sections of paths, gardens, beside gateways—where memorials to people who have died can be ritually placed with inscriptions and mementos which celebrate their live. Give each grave site an edge, a path, and a quiet corner where people can sit. By custom, this is hallowed ground.

### Related Patterns
... according to [[Life Cycle (26)]] the transitions of a person's life must be available and visible in every community. Death is no exception. This pattern helps to integrate the fact of death with the public spaces of each neighborhood, and, by its very existence, helps to form [[Identifiable Neighborhood (14)]], and [[Holy Ground (66)]] and [[Common Land (67)]].

If possible, keep them in places which are quiet - [[Quiet Backs (59)]]; and provide a simple seat or a bench under a tree, where people can be alone with their memories - [[Tree Places (171)]], [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 353.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/green-streets-51.md ===== -->

---
title: "Green Streets (51)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 51
pattern_name: "Green Streets"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Green%20Streets%20%2851%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Looped Local Roads (49)"
  - "T Junctions (50)"
  - "Common Land (67)"
  - "Network of Paths and Cars (52)"
  - "Small Parking Lots (103)"
  - "Fruit Trees (170)"
  - "Raised Flowers (245)"
  - "Paving With Cracks Between the Stones (247)"
---

# Green Streets (51)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There is too much hot hard asphalt in the world. A local road, which only gives access to buildings, needs a few stones for the wheels of the cars; nothing more. Most of it can still be green.

### Solution
>On local roads, closed to through traffic, plant grass all over the road and set occasional paving stones into the grass to form a surface for the wheels of those cars that need access to the street. Make no distinction between street and sidewalk. Where houses open off the street, put in more paving stones or gravel to let cars turn onto their own land.

### Related Patterns
... this pattern helps to give the character of local roads. Even though it only defines the surface of the road, and the position of parking, the gradual emergency of this pattern in an area, can be used, piecemeal, to create [[Looped Local Roads (49)]], [[T Junctions (50)]], and [[Common Land (67)]]. This pattern was inspired by a beautiful road in the north of Denmark, built by Anne-Marie Rubin.

When a road is a green street, it so pleasant that it naturally tends to attract activity to it. In this case, the paths and the green streets are one -- [[Common Land (67)]]. However, even when the green street is green, it may be pleasant to put in occasional very small lanes, a few feet wide, at right angles to the green streets, according to the [[Network of Paths and Cars (52)]]. In order to preserve the greenness of the street, it will be essential, too, to keep parked cars in driveways on the individual lots, or in tiny parking lots, at the ends of the street, reserved for the house owners and their visitors -- [[Small Parking Lots (103)]]. Fruit trees and flowers will make the street more beautiful -- [[Fruit Trees (170)]], [[Raised Flowers (245)]] -- and the paving stones which form the beds for cars to drive on, can themselves be laid with cracks between them and with grass and moss and flowers in the cracks between the stones -- [[Paving With Cracks Between the Stones (247)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 266.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/greenhouse-175.md ===== -->

---
title: "Greenhouse (175)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 175
pattern_name: "Greenhouse"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Greenhouse%20%28175%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House Cluster (37)"
  - "Work Community (41)"
  - "Common Land (67)"
  - "Vegetable Garden (177)"
  - "Compost (178)"
  - "Waist-High Shelf (201)"
  - "Bulk Storage (145)"
  - "Garden Seat (176)"
  - "Window Place (180)"
---

# Greenhouse (175)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Many efforts are being made to harness solar energy by converting it into hot water or electric power. And yet the easier way to harness solar energy is the most obvious and the oldest: namely, to trap the heat inside a greenhouse and use it for growing flowers and vegetables.

### Solution
>In temperate climates, build a greenhouse as part of your house or office, so that it is both a “room” of the house which can be reached directly without going outdoors and a part of the garden which can be reached directly from the garden.

### Related Patterns
... to keep a garden alive, it is almost essential that there be a "workshop" - a kind of halfway house between the garden and the house itself, where seedlings grow, and where, in temperate climates, plants can grow in spite of cold. In a [[House Cluster (37)]] or a [[Work Community (41)]], this workshop makes an essential contribution to the [[Common Land (67)]].

Place the greenhouse so that it has easy access to the [[Vegetable Garden (177)]] and the [[Compost (178)]]. Arrange its interior so that it is surrounded with [[Waist-High Shelf (201)]] and plenty of storage space - [[Bulk Storage (145)]]; perhaps give it a special seat, where it is possible to sit comfortably - [[Garden Seat (176)]], [[Window Place (180)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 812.
> #APL/confidence/low
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/ground-floor-slab-215.md ===== -->

---
title: "Ground Floor Slab (215)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 215
pattern_name: "Ground Floor Slab"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Ground%20Floor%20Slab%20%28215%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Connection to the Earth (168)"
  - "Efficient Structure (206)"
  - "Columns at the Corners (212)"
  - "Root Foundations (214)"
  - "Floor Surface (233)"
  - "Soft Tile and Brick (248)"
  - "Floor-Ceiling Vaults (219)"
---

# Ground Floor Slab (215)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The slab is the easiest, cheapest, and most natural way to lay a ground floor.

### Solution
>Build a ground floor slab, raised slightly—six or nine inches above the ground—by first building a low perimeter wall around the building, tied into the column foundations, and then filling it with rubble, gravel, and concrete.

### Related Patterns
... this pattern helps to complete [[Connection to the Earth (168)]], [[Efficient Structure (206)]], [[Columns at the Corners (212)]], and [[Root Foundations (214)]]. It is a simple slab, which forms the ground floor of the building, ties the root foundations to one another, and also allows you to form simple strip foundations as part of the slab, to support the walls.

Finish the public areas of the floor in brick, or tile, or waxed and polished lightweight concrete, or even beaten earth; as for those areas which will be more private, build them one step up or one step down, with a lightweight concrete finish that can be felted and carpeted - [[Floor Surface (233)]].

Build the low wall which forms the edge of the ground floor slab out of brick, and tie it directly into all the terraces and paths around the building - [[Connection to the Earth (168)]], [[Soft Tile and Brick (248)]]. If you are building on a steep sloped site, build part of the ground floor as a vaulted floor instead of excavating to form a slab - [[Floor-Ceiling Vaults (219)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1009.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/half-hidden-garden-111.md ===== -->

---
title: "Half-Hidden Garden (111)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 111
pattern_name: "Half-Hidden Garden"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Half-Hidden%20Garden%20%28111%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House Cluster (37)"
  - "Row Houses (38)"
  - "Work Community (41)"
  - "Your Own Home (79)"
  - "Building Complex (95)"
  - "South Facing Outdoors (105)"
  - "Site Repair (104)"
  - "Main Entrance (110)"
  - "Garden Wall (173)"
  - "Garden Growing Wild (172)"
  - "Entrance Transition (112)"
  - "Courtyards Which Live (115)"
  - "Roof Garden (118)"
  - "Private Terrace on the Street (140)"
---

# Half-Hidden Garden (111)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If a garden is too close to the street, people won’t use it because it isn’t private enough. But if it is too far from the street, then it won’t be used either, because it is too isolated.

### Solution
>Do not place the garden fully in front of the house, nor fully to the back. Instead, place it in some kind of halfway position, side-by-side with the house, in a position which is half-hidden from the street, and half-exposed.

### Related Patterns
... this pattern helps to form the fundamental layout of [[House Cluster (37)]], [[Row Houses (38)]], [[Work Community (41)]], [[Your Own Home (79)]], and [[Building Complex (95)]], because it influences the relative position of the buildings and their gardens. Since it affects the position of the buildings, and the shape and position of the gardens, it can also be used to help create [[South Facing Outdoors (105)]] and to help the general process of [[Site Repair (104)]].

 If possible, use this pattern to influence the shape of house lots too, and make them as near double squares along the street as possible; build a partial wall around the garden, and locate the entrance to the house between the house and the garden, so that people in the garden can be private, yet still aware of the street, and aware of anybody coming up to the house - [[Main Entrance (110)]], [[Garden Wall (173)]]; allow the garden to grow wild [[Garden Growing Wild (172)]], and make the passage through, or alongside it, a major part of the transition between street and house - [[Entrance Transition (112)]]. Half-hidden gardens may be [[Courtyards Which Live (115)]], [[Roof Garden (118)]], or a [[Private Terrace on the Street (140)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 545.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/half-inch-trim-240.md ===== -->

---
title: "Half-Inch Trim (240)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 240
pattern_name: "Half-Inch Trim"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Half-Inch%20Trim%20%28240%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Soft Inside Walls (235)"
  - "Lapped Outside Walls (234)"
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Floor-Ceiling Vaults (219)"
  - "Frames as Thickened Edges (225)"
  - "Ornament (249)"
  - "Warm Colors (250)"
---

# Half-Inch Trim (240)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Totalitarian, machine buildings do not require trim because they are precise enough to do without. But they buy their precision at a dreadful price: by killing the possibility of freedom in the building plan.

### Solution
>Wherever two materials meet, place a piece of trim over the edge of the connection. Choose the pieces of trim so that the smallest piece, in each component, is always of the order of 1/2 inch wide. The trim can be wood, plaster, terracotta…

### Related Patterns
... and this pattern finishes the joints between [[Soft Inside Walls (235)]], or [[Lapped Outside Walls (234)]] and the various floors and vaults and frames and stiffeners and ornaments which are set into the walls: [[Box Columns (216)]], [[Perimeter Beams (217)]], [[Floor-Ceiling Vaults (219)]], [[Frames as Thickened Edges (225)]], and [[Ornament (249)]].

In many cases, you may be able to use the trim to form the ornaments - [[Ornament (249)]]; and trims may occasionally be colored: even tiny amounts can help to make the light in a room warm - [[Warm Colors (250)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1112.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/half-open-wall-193.md ===== -->

---
title: "Half-Open Wall (193)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 193
pattern_name: "Half-Open Wall"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Half-Open%20Wall%20%28193%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Shape of Indoor Space (191)"
  - "Half-Private Office (152)"
  - "Six-Foot Balcony (167)"
  - "Alcoves (179)"
  - "Sitting Circle (185)"
  - "Bed Alcove (188)"
  - "Building Thoroughfare (101)"
  - "Arcades (119)"
  - "The Flow Through Rooms (131)"
  - "Workspace Enclosure (183)"
  - "Interior Windows (194)"
  - "Columns at the Corners (212)"
  - "Column Place (226)"
  - "Column Connections (227)"
  - "Small Panes (239)"
  - "Ornament (249)"
---

# Half-Open Wall (193)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Rooms which are too closed prevent the natural flow of social occasions, and the natural process of transition from one social moment to another. And rooms which are too open will not support the differentiation of events which social life requires.

### Solution
>Adjust the walls, opening, and windows in each indoor space until you reach the right balance between open, flowing space and closed cell-like space. Do not take it for granted that each space is a room; nor, on the other hand, that all spaces must flow into each other. The right balance will always lie between these extremes: no one room entirely enclosed; and no space totally connected to another. Use combinations of columns, half-open walls, porches, indoor windows, sliding doors, low sills, french doors, sitting walls, and so on, to hit the right balance.

### Related Patterns
... [[The Shape of Indoor Space (191)]] defines the shapes of rooms and minor rooms. This pattern gives more detail to the walls between these rooms. Wherever there are [[Half-Private Office (152)]], [[Six-Foot Balcony (167)]], [[Alcoves (179)]], [[Sitting Circle (185)]], [[Bed Alcove (188)]], [[Building Thoroughfare (101)]], [[Arcades (119)]], or [[The Flow Through Rooms (131)]], the spaces must be given a subtle balance of enclosure and openness by partly opening up the walls or keeping them half-open.

Wherever a small space is in a larger space, yet slightly separate from it, make the wall between the two about half-open and half-solid - [[Alcoves (179)]], [[Workspace Enclosure (183)]]. Concentrate the solids and the openings, so that there are essentially a large number of smallish openings, each framed by thick columns, waist high shelves, deep soffits, and arches or braces in the corners with ornament where solids and openings meet - [[Interior Windows (194)]], [[Columns at the Corners (212)]], [[Column Place (226)]], [[Column Connections (227)]], [[Small Panes (239)]], [[Ornament (249)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 893.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/half-private-office-152.md ===== -->

---
title: "Half-Private Office (152)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 152
pattern_name: "Half-Private Office"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Half-Private%20Office%20%28152%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Flexible Office Space (146)"
  - "Small Work Groups (148)"
  - "The Shape of Indoor Space (191)"
  - "Light on Two Sides of Every Room (159)"
  - "Workspace Enclosure (183)"
  - "Windows Overlooking Life (192)"
  - "Sitting Circle (185)"
---

# Half-Private Office (152)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>What is the right balance between privacy and connection in office work?

### Solution
>Avoid closed off, separate, or private offices. Make every workroom, whether it is for a group of two or three people or for one person, half-open to the other workgroups and the world immediately beyond it. At the front, just inside the door, make comfortable sitting space, with the actual workspace(s) away from the door, and further back.

### Related Patterns
... within the overall arrangement of group space and individual working space provided by [[Intimacy Gradient (127)]], [[Flexible Office Space (146)]], and [[Small Work Groups (148)]], this pattern shapes the individual rooms and offices. The pattern also helps to generate the organization of these larger patterns.

Shape each office in detail, according to [[The Shape of Indoor Space (191)]] give it windows on at least two sides - [[Light on Two Sides of Every Room (159)]]; make individual workspaces in the corners - [[Workspace Enclosure (183)]], looking out of windows - [[Windows Overlooking Life (192)]]; make the sitting area toward the door as comfortable as possible - [[Sitting Circle (185)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 717.
> #APL/confidence/low
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/health-center-47.md ===== -->

---
title: "Health Center (47)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 47
pattern_name: "Health Center"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Health%20Center%20%2847%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Life Cycle (26)"
  - "Your Own Home (79)"
  - "House Cluster (37)"
  - "Row Houses (38)"
---

# Health Center (47)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>More than 90 percent of the people walking about in an ordinary neighborhood are unhealthy, judged by simple biological criteria. This ill health cannot be cured by hospitals or medicine.

### Solution
>Gradually develop a network of small health centers, perhaps one per community of 7,000, across the city; each equipped to treat everyday disease—both mental and physical, in children and adults—but organized essentially around a functional emphasis on those recreational activities which keep people in good health, like swimming and dancing.

### Related Patterns
... the explicit recognition of the life cycle as the basis for every individual life will do a great deal to help people's health in the community -- [[Life Cycle (26)]]; this pattern describes the more specific institutions which help people to care for themselves and their health.

Make sure that, in spite of its position in a public area, each still has enough private territory for people to fell at home in it -- [[Your Own Home (79)]]. If there are several houses in one area, treat them as a cluster or as a row -- [[House Cluster (37)]], [[Row Houses (38)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 252.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/hierarchy-of-open-space-114.md ===== -->

---
title: "Hierarchy of Open Space (114)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 114
pattern_name: "Hierarchy of Open Space"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Hierarchy%20of%20Open%20Space%20%28114%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Site Repair (104)"
  - "South Facing Outdoors (105)"
  - "Positive Outdoor Space (106)"
  - "Garden Seat (176)"
  - "Half-Hidden Garden (111)"
  - "Activity Pockets (124)"
  - "Small Public Squares (61)"
  - "Private Terrace on the Street (140)"
  - "Looped Local Roads (49)"
  - "Green Streets (51)"
  - "Accessible Green (60)"
  - "Common Land (67)"
  - "The Countryside (7)"
---

# Hierarchy of Open Space (114)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Outdoors, people always try to find a spot where they can have their backs protected, looking out toward some larger opening, beyond the space immediately in front of them.

### Solution
>Whatever space you are shaping—whether it is a garden, terrace, street, park, public outdoor room, or courtyard, make sure of two things. First, make at least one smaller space, which looks into it and forms a natural back for it. Second, place it, and its openings, so that it looks into at least one larger space.
>When you have done this, every outdoor space will have a natural "back"; and every person who takes up the natural position, with their back to this "back", will be looking out toward some larger distant view.

### Related Patterns
... the main outdoor spaces are given their character by [[Site Repair (104)]], [[South Facing Outdoors (105)]] and [[Positive Outdoor Space (106)]]. But you can refine them, and complete their character by making certain that every space always has a view out into some other larger one, and that all the spaces work together to form hierarchies.

For example: garden seats open to gardens - [[Garden Seat (176)]], [[Half-Hidden Garden (111)]]; activity pockets open to public squares - [[Activity Pockets (124)]], [[Small Public Squares (61)]]; gardens open to local roads - [[Private Terrace on the Street (140)]], [[Looped Local Roads (49)]], roads open to fields - [[Green Streets (51)]], [[Accessible Green (60)]]; fields open to the countryside, on a great vista - [[Common Land (67)]], [[The Countryside (7)]]. Make certain that each piece of the hierarchy is arranged so that people can be comfortably settled within it, oriented out toward the next larger space.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 557.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/high-places-62.md ===== -->

---
title: "High Places (62)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 62
pattern_name: "High Places"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/High%20Places%20%2862%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Four-Story Limit (21)"
  - "Small Public Squares (61)"
  - "Holy Ground (66)"
  - "Community of 7000 (12)"
  - "Stair Seats (125)"
  - "Zen View (134)"
  - "Open Stairs (158)"
---

# High Places (62)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The instinct to climb up to some high place, from which you can look down and survey your world, seems to be a fundamental human instinct.

### Solution
>Build occasional high places as landmarks throughout the city. They can be a natural part of the topography, or towers, or part of the roofs of the highest local building—but, in any case, they should include a physical climb.

### Related Patterns
... according to [[Four-Story Limit (21)]], most roofs in the community are no higher than four stories, about 40 or 50 feet. However, it is very important that this height limit be punctuated, just occasionally, by higher buildings which have special functions. They can help the character of the [[Small Public Squares (61)]] and [[Holy Ground (66)]]; they can give particular identity to their communities, provided that they do not occur more frequently than one in each [[Community of 7000 (12)]] ...

Elaborate the area around the base of the high place -it is a natural position for a [[Small Public Squares (61)]]; give the stair which leads up to the top, openings with views out, so that people can stop on the stair, sit down, look out, and be seen while they are climbing - [[Stair Seats (125)]], [[Zen View (134)]], [[Open Stairs (158)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 315.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/holy-ground-66.md ===== -->

---
title: "Holy Ground (66)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 66
pattern_name: "Holy Ground"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Holy%20Ground%20%2866%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Life Cycle (26)"
  - "Sacred Sites (24)"
  - "Main Gateways (53)"
  - "Zen View (134)"
  - "Pools and Streams (64)"
  - "Tree Places (171)"
---

# Holy Ground (66)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>What is a church or temple? It is a place of worship, spirit, contemplation, of course. But above all, from a human point of view, it is a gateway. A person comes into the world through the church. They leave it through the church. And, at each of the important thresholds of their life, they once again step through the church.

### Solution
>In each community and neighborhood, identify some sacred site as consecrated ground, and form a series of nested precincts, each marked by a gateway, each one progressively more private, and more sacred than the last, the innermost a final sanctum that can only be reached by passing through all of the outer ones.

### Related Patterns
... we have defined the need for a full life cycle, with rites of passage between stages of the cycle - [[Life Cycle (26)]]; and we have recommended that certain pieces of land be set aside because of their importance and meaning - [[Sacred Sites (24)]]. This pattern gives the detailed organization of the space around these places. The organization is so powerful, that to some extent it can itself create the sacredness of sites, perhaps even encourage the slow emergence of coherent rites of passage.

At each threshold between precincts build a gate - [[Main Gateways (53)]] - at each gate, a place to pause with a new view toward the next most inner place - [[Zen View (134)]] and at the innermost sanctum, something very quiet and able to inspire - perhaps a view, or no more than a simple tree, or pool - [[Pools and Streams (64)]], [[Tree Places (171)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 331.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/home-workshop-157.md ===== -->

---
title: "Home Workshop (157)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 157
pattern_name: "Home Workshop"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Home%20Workshop%20%28157%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House Cluster (37)"
  - "Your Own Home (79)"
  - "Scattered Work (9)"
  - "Network of Learning (18)"
  - "Men and Women (27)"
  - "Light on Two Sides of Every Room (159)"
  - "Workspace Enclosure (183)"
  - "Opening to the Street (165)"
  - "Windows Overlooking Life (192)"
  - "Sunny Place (161)"
  - "The Shape of Indoor Space (191)"
---

# Home Workshop (157)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>As the decentralization of work becomes more and more effective, the workshop in the home grows and grows in importance.

### Solution
>Make a place in the home where substantial work can be done; not just a hobby, but a job. Change the zoning laws to encourage modest, quiet work operations to locate in neighborhoods. Give the workshop perhaps a few hundred square feet; and locate it so it can be seen from the street and the owner can hang out a shingle.

### Related Patterns
... at the center of each [[House Cluster (37)]] and in [[Your Own Home (79)]] there needs to be one room or outbuilding, which is freely attached and accessible from the outside. This is the workshop. The following pattern tells us how important workshops are, how widely they ought to be scattered, how omnipresent, and when they are built, how easy to reach, and how public they should always be. It helps to reinforce the patterns of [[Scattered Work (9)]], [[Network of Learning (18)]], and [[Men and Women (27)]].

Give the workshop a corner where it is especially nice to work - [[Light on Two Sides of Every Room (159)]], [[Workspace Enclosure (183)]]; a strong connection to the street - [[Opening to the Street (165)]], [[Windows Overlooking Life (192)]]; perhaps a place to work in the sun on warm days - [[Sunny Place (161)]] For the shape of the workshop and its construction, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 737.
> #APL/confidence/low
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/house-cluster-37.md ===== -->

---
title: "House Cluster (37)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 37
pattern_name: "House Cluster"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/House%20Cluster%20%2837%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Density Rings (29)"
  - "Household Mix (35)"
  - "Degrees of Publicness (36)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "Common Land (67)"
  - "Home Workshop (157)"
  - "Circulation Realms (98)"
  - "Small Parking Lots (103)"
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Your Own Home (79)"
---

# House Cluster (37)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People will not feel comfortable in their houses unless a group of houses forms a cluster, with the public land between them jointly owned by all the householders.

### Solution
>Arrange houses to form very rough, but identifiable clusters of 8 to 12 households around some common land and paths. Arrange the clusters so that anyone can walk through them, without feeling like a trespasser.

### Related Patterns
... the fundamental unit of organization within the neighborhood - [[Identifiable Neighborhood (14)]] - is the cluster of a dozen houses. By varying the density and composition of different clusters, this pattern may also help to generate the [[Density Rings (29)]], [[Household Mix (35)]], and [[Degrees of Publicness (36)]].

Use this pattern as it is for low densities, up to about 15 houses per acre; at higher densities, modify the cluster with the additional structure given by [[Row Houses (38)]] or [[Housing Hill (39)]]. Always provide common land between the houses - [[Common Land (67)]] and a shared common workshop [[Home Workshop (157)]]. Arrange paths clearly - [[Circulation Realms (98)]] - and lay these paths out in such a way that they create busier paths and backwaters, even within the cluster - [[Degrees of Publicness (36)]]; keep parking in [[Small Parking Lots (103)]],and make the houses in the cluster suit the households which will live there - [[The Family (75)]], [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]], [[Your Own Home (79)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 197.
> #APL/confidence/high
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/house-for-a-couple-77.md ===== -->

---
title: "House for a Couple (77)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 77
pattern_name: "House for a Couple"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/House%20for%20a%20Couple%20%2877%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House Cluster (37)"
  - "Your Own Home (79)"
  - "Couple's Realm (136)"
  - "A Room of One's Own (141)"
---

# House for a Couple (77)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In a small household shared by two, the most important problem which arises is the possibility that each may have too little opportunity for solitude or privacy.

### Solution
>Conceive a house for a couple as being made up of two kinds of places—a shared couple’s realm and individual private worlds. Imagine the shared realm as half-public and half-intimate; and the private worlds as entirely individual and private.

### Related Patterns
... again, ideally, every couple is a part of a larger group household - [[The Family (75)]]. If this can not be so, try to build the house for the couple in such a way as to tie it together with some other households, to form the beginnings of a group household, or, if this fails, at least to form the beginnings of a [[House Cluster (37)]].

Again, treat the house as a distinct piece of territory, in some fashion owned by its users - [[Your Own Home (79)]]. Lay out the common part, according to the pattern [[Couple's Realm (136)]], and give both persons an individual world of their own where they can be alone - [[A Room of One's Own (141)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 385.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Families


<!-- ===== pattern-language/wiki/concepts/patterns/house-for-a-small-family-76.md ===== -->

---
title: "House for a Small Family (76)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 76
pattern_name: "House for a Small Family"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/House%20for%20a%20Small%20Family%20%2876%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House Cluster (37)"
  - "Your Own Home (79)"
  - "Common Areas at the Heart (129)"
  - "Couple's Realm (136)"
  - "Bed Cluster (143)"
  - "Children's Realm (137)"
---

# House for a Small Family (76)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In a house for a small family, it is the relationship between children and adults which is most critical.

### Solution
>Give the house three distinct parts: a realm for parents, a realm for the children, and a common area. Conceive these three realms as roughly similar in size, with the commons the largest.

### Related Patterns
... according to [[The Family (75)]], each nuclear family ought to be a member household of a larger group household. If this is not possible, do what you can, when building a house for a small family, to generate some larger, possible group household, by tying it together with the next door households; in any case, at the very least, form the beginning of a [[House Cluster (37)]].

Treat the house, like every house, as a distinct piece of territory - [[Your Own Home (79)]]; build the three main parts according to the specific patterns for those parts - [[Common Areas at the Heart (129)]], [[Couple's Realm (136)]], [[Bed Cluster (143)]] and connect the common areas, and the bed cluster according to the [[Children's Realm (137)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 381.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Families


<!-- ===== pattern-language/wiki/concepts/patterns/house-for-one-person-78.md ===== -->

---
title: "House for One Person (78)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 78
pattern_name: "House for One Person"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/House%20for%20One%20Person%20%2878%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "Your Own Home (79)"
  - "Farmhouse Kitchen (139)"
  - "Bathing Room (144)"
  - "Window Place (180)"
  - "Workspace Enclosure (183)"
  - "Bed Alcove (188)"
  - "Dressing Rooms (189)"
  - "Old Age Cottage (155)"
  - "Teenager's Cottage (154)"
---

# House for One Person (78)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Once a household for one person is part of some larger group, the most critical problem which arises is the need for simplicity.

### Solution
>Conceive a house for one person as a place of the utmost simplicity: essentially a one-room cottage or studio, with large and small alcoves around it. When it is most intense, the entire house may be no more than 300 to 400 square feet.

### Related Patterns
... the households with one person in them, more than any other, need to be a part of some kind of larger household - [[The Family (75)]]. Either build them to fit into some larger group household, or even attach them, as ancillary cottages to other, ordinary family households like [[House for a Small Family (76)]] or [[House for a Couple (77)]].

And again, make the house an individual piece of territory, with its own garden, no matter how small - [[Your Own Home (79)]]; make the main room essentially a kind of farmhouse kitchen - [[Farmhouse Kitchen (139)]], with alcoves opening off it for sitting, working, bathing, sleeping, dressing - [[Bathing Room (144)]], [[Window Place (180)]], [[Workspace Enclosure (183)]], [[Bed Alcove (188)]], [[Dressing Rooms (189)|Dressing Room (189)]]; if the house is meant for an old person, or for someone very young, shape it also according to the pattern for [[Old Age Cottage (155)]] or [[Teenager's Cottage (154)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 389.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Families


<!-- ===== pattern-language/wiki/concepts/patterns/household-mix-35.md ===== -->

---
title: "Household Mix (35)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 35
pattern_name: "Household Mix"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Household%20Mix%20%2835%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "House Cluster (37)"
  - "Work Community (41)"
  - "Life Cycle (26)"
  - "Old People Everywhere (40)"
  - "Connected Play (68)"
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
---

# Household Mix (35)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No one stage in the life cycle is self-sufficient.

### Solution
>Encourage growth toward a mix of household types in every neighborhood, and every cluster, so that one-person households, couples, families with children, and group households are side by side.

### Related Patterns
... the mix of households in an area does almost more than anything else to generate, or destroy, the character of an [[Identifiable Neighborhood (14)]], of a [[House Cluster (37)]], of a [[Work Community (41)]], or, most generally of all, of a [[Life Cycle (26)]]. The question is, what kind of mix should a well-balanced neighborhood contain?

Make especially sure there are provisions for old people in every neighborhood - [[Old People Everywhere (40)]], and that even with this mix, young children will have enough playmates - [[Connected Play (68)]]; and build the details of the different kinds of households, according to the appropriate more detailed patterns to reinforce the mix - [[The Family (75)]], [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]]....

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 188.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/housing-hill-39.md ===== -->

---
title: "Housing Hill (39)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 39
pattern_name: "Housing Hill"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Housing%20Hill%20%2839%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Density Rings (29)"
  - "Four-Story Limit (21)"
  - "Your Own Home (79)"
  - "Roof Garden (118)"
  - "Open Stairs (158)"
  - "Common Land (67)"
  - "Connected Play (68)"
  - "Vegetable Garden (177)"
---

# Housing Hill (39)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Every town has places in it which are so central and desirable that at least 30–50 households per acre will be living there. But the apartment houses which reach this density are almost all impersonal.

### Solution
>To build more than 30 dwellings per net acre, or to build housing three or four stories high, build a hill of houses. Build them to form stepped terraces, sloping toward the south, served by a great central open stair which also faces south and leads toward a common garden.

### Related Patterns
... at the still higher densities required in the inner ring of the community's [[Density Rings (29)]], and wherever densities rise above 30 houses per acre or are more than four stories high - [[Four-Story Limit (21)]], the house clusters become like hills.

Let people lay out their own houses individually, upon the terraces, just as if they were land - [[Your Own Home (79)]]. Since each terrace overlaps the one below it, each house has its garden on the house below [[Roof Garden (118)]]. Leave the the central stair open to the air, but give it a roof, in wet or snowy climates - perhaps a glass roof - [[Open Stairs (158)]]; and place the common land right at the bottom of the stair with playgrounds, flowers and vegetables for everyone - [[Common Land (67)]], [[Connected Play (68)]], [[Vegetable Garden (177)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 209.
> #APL/confidence/low
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/housing-in-between-48.md ===== -->

---
title: "Housing In Between (48)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 48
pattern_name: "Housing In Between"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Housing%20In%20Between%20%2848%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "House Cluster (37)"
  - "Subculture Boundary (13)"
  - "Neighborhood Boundary (15)"
  - "Work Community (41)"
  - "Your Own Home (79)"
  - "Row Houses (38)"
---

# Housing In Between (48)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Wherever there is a sharp separation between residential and nonresidential parts of town, the nonresidential areas will quickly turn to slums.

### Solution
>Build houses into the fabric of shops, small industry, schools, public services, universities—all those parts of cities which draw people in during the day, but which tend to be "nonresidential". The houses may be in rows or “hills” with shops beneath, or they may be free-standing, so long as they mix with the other functions, and make the entire area "lived-in".

### Related Patterns
... most housing is in residential neighborhoods, and in the clusters within neighborhoods -- [[Identifiable Neighborhood (14)]], [[House Cluster (37)]]; and according to our patterns these housing areas need to be separated by boundaries which contain public land and work communities -- [[Subculture Boundary (13)]], [[Neighborhood Boundary (15)]], [[Work Community (41)]]. But even these work communities, and boundaries, and shopping streets, must contain houses which have people living in them.

Make sure that, in spite of its position in a public area, each house still has enough private territory for people to feel at home in it -- [[Your Own Home (79)]]. If there are several houses in one area, treat them as a cluster or as a row -- [[House Cluster (37)]], [[Row Houses (38)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 256.
> #APL/confidence/high
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/identifiable-neighborhood-14.md ===== -->

---
title: "Identifiable Neighborhood (14)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 14
pattern_name: "Identifiable Neighborhood"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Identifiable%20Neighborhood%20%2814%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Community of 7000 (12)"
  - "Main Gateways (53)"
  - "Neighborhood Boundary (15)"
  - "Accessible Green (60)"
  - "Small Public Squares (61)"
  - "House Cluster (37)"
  - "Work Community (41)"
---

# Identifiable Neighborhood (14)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People need an identifiable spatial unit to belong to.

### Solution
>Help people to define the neighborhoods they live in, not more than 300 yards across, with no more than 400 or 500 inhabitants. In existing cities, encourage local groups to organize themselves to form such neighborhoods. Give the neighborhoods some degree of autonomy as far as taxes and land controls are concerned. Keep major roads outside these neighborhoods.

### Related Patterns
... the [[Mosaic of Subcultures (8)]] and the [[Community of 7000 (12)]] are made up of neighborhoods. This pattern defines the neighborhoods. It defines those small human groups which create the energy and character which can bring the larger [[Community of 7000 (12)]] and the [[Mosaic of Subcultures (8)]] to life.

Mark the neighborhood, above all, by gateways wherever main paths enter it -- [[Main Gateways (53)]] -- and by modest boundaries of non-residential land between the neighborhoods -- [[Neighborhood Boundary (15)]]. Keep major roads within these boundaries perhaps a common or a green -- [[Accessible Green (60)]] -- or a [[Small Public Squares (61)]]; and arrange houses and workshops within the neighborhood in clusters of about a dozen at a time -- [[House Cluster (37)]], [[Work Community (41)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 80
> #APL/confidence/high
>
> #APL/Town-Patterns/Communities


<!-- ===== pattern-language/wiki/concepts/patterns/independent-regions-1.md ===== -->

---
title: "Independent Regions (1)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 1
pattern_name: "Independent Regions"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Independent%20Regions%20%281%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Distribution of Towns (2)"
---

# Independent Regions (1)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Metropolitan regions will not come to balance until each one is small and autonomous enough to be an independent sphere of culture.

### Solution
>Wherever possible, work toward the evolution of independent regions in the world; each with a population between 2 and 10 million; each with its own natural and geographic boundaries; each with its own economy; each a world government, without the intervening power of larger states or countries.

### Related Patterns
... within each region encourage the population to distribute itself as widely as possible across the region -- [[The Distribution of Towns (2)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 10.
> #APL/confidence/high
>
> #APL/Town-Patterns/Network-of-Lattices


<!-- ===== pattern-language/wiki/concepts/patterns/individually-owned-shops-87.md ===== -->

---
title: "Individually Owned Shops (87)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 87
pattern_name: "Individually Owned Shops"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Individually%20Owned%20Shops%20%2887%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Street Cafe (88)"
  - "Corner Grocery (89)"
  - "Shopping Street (32)"
  - "Market of Many Shops (46)"
  - "Building Complex (95)"
  - "Opening to the Street (165)"
  - "The Shape of Indoor Space (191)"
  - "Thick Walls (197)"
  - "Open Shelves (200)"
---

# Individually Owned Shops (87)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When shops are too large, or controlled by absentee owners, they become plastic, bland, and abstract.

### Solution
>Do what you can to encourage the development of individually owned shops. Approve applications for business licenses only if the business is owned by those people who actually work and manage the store. Approve new commercial building permits only if the proposed structure includes many very very small rental spaces.

### Related Patterns
... the [[Street Cafe (88)]] and [[Corner Grocery (89)]] and all the individual shops and stalls in [[Shopping Street (32)]] and [[Market of Many Shops (46)]] must be supported by an ordinance which guarantees that they will stay in local private hands, and not be owned by absentee landlords, or chain stores, or giant franchise operations.

Treat each individual shop as an identifiable unit of a larger [[Building Complex (95)]]; make at least some part of the shop part of the sidewalk, so that people walk through the shop as they are going down the street - [[Opening to the Street (165)]] ; and build the inside of the shop with all the goods as open and available as possible - [[The Shape of Indoor Space (191)]], [[Thick Walls (197)]], [[Open Shelves (200)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 432.
> #APL/confidence/high
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/indoor-sunlight-128.md ===== -->

---
title: "Indoor Sunlight (128)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 128
pattern_name: "Indoor Sunlight"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Indoor%20Sunlight%20%28128%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "South Facing Outdoors (105)"
  - "Intimacy Gradient (127)"
  - "Sunny Place (161)"
  - "Outdoor Room (163)"
  - "Windows Which Open Wide (236)"
  - "Sleeping to the East (138)"
  - "North Face (162)"
  - "Sunny Counter (199)"
  - "Home Workshop (157)"
  - "Workspace Enclosure (183)"
---

# Indoor Sunlight (128)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If the right rooms are facing south, a house is bright and sunny and cheerful; if the wrong rooms are facing south, the house is dark and gloomy.

### Solution
>Place the most important rooms along the south edge of the building, and spread the building out along the east-west axis.
>Fine-tune the arrangement so that the proper rooms are exposed to the southeast and the southwest sun. For example: give the common area a full southern exposure, bedrooms southeast, porch southwest. For most climates, this means the shape of the building is elongated east-west.


### Related Patterns
... according to [[South Facing Outdoors (105)]], the building is placed in such a way as to allow the sun to shine directly into it, across its gardens. From [[Intimacy Gradient (127)]], You have some idea of the overall distribution of public and private rooms within the building. This pattern marks those rooms and areas along the intimacy gradient which need the sunlight most, and helps to place them so that the indoor sunlight can be made to coincide with the rooms in the gradient which are most used.

When you can, open up these indoor sunny rooms to the outdoors, and build a sunny place and outdoor rooms directly outside - [[Sunny Place (161)]], [[Outdoor Room (163)]], [[Windows Which Open Wide (236)]]. Give the bedrooms eastern exposure - [[Sleeping to the East (138)]], and put storage and garages to the north - [[North Face (162)]]. Where there is a kitchen, try to put its work counter toward the sun - [[Sunny Counter (199)]]; perhaps do the same for any work bench or desk in a [[Home Workshop (157)]], [[Workspace Enclosure (183)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 614.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/industrial-ribbon-42.md ===== -->

---
title: "Industrial Ribbon (42)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 42
pattern_name: "Industrial Ribbon"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Industrial%20Ribbon%20%2842%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Scattered Work (9)"
  - "Work Community (41)"
  - "Subculture Boundary (13)"
  - "Ring Roads (17)"
  - "Positive Outdoor Space (106)"
  - "Building Fronts (122)"
---

# Industrial Ribbon (42)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Exaggerated zoning laws separate industry from the rest of urban life completely, and contribute to the plastic unreality of sheltered residential neighborhoods.

### Solution
>Place industry in ribbons, between 200 and 500 feet wide, which form the boundaries between communities. Break these ribbons into long blocks, varying in area between 1 and 25 acres; and treat the edge of every ribbon as a place where people from nearby communities can benefit from the offshoots of the industrial activity.

### Related Patterns
... in a city where work is decentralized by [[Scattered Work (9)]], the placing of industry is of particular importance since it usually needs a certain amount of concentration. Like [[Work Community (41)]], the industry can easily be placed to help in the formation of the larger boundaries between subcultures -- [[Subculture Boundary (13)]].

Place the ribbons near enough to [[Ring Roads (17)]] so that trucks can pass directly from the ribbons to the ring road, without having to pass through any other intermediate areas. Develop the internal layout of the industrial ribbon like any other work community, though slightly more spread out -- [[Work Community (41)]]. Place the important buildings of each industry, the "heart" of the plant, toward the edge of the ribbon to form usable streets and outdoor space -- [[Positive Outdoor Space (106)]], [[Building Fronts (122)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 227.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/interchange-34.md ===== -->

---
title: "Interchange (34)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 34
pattern_name: "Interchange"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Interchange%20%2834%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Web of Public Transport (16)"
  - "Local Transport Areas (11)"
  - "Scattered Work (9)"
  - "Housing Hill (39)"
  - "Old People Everywhere (40)"
  - "Work Community (41)"
  - "Activity Nodes (30)"
  - "Arcades (119)"
  - "Bus Stop (92)"
  - "Mini-Buses (20)"
---

# Interchange (34)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Interchanges play a central role in public transportation. Unless the interchanges are working properly, the public transportation system will not be able to sustain itself.

### Solution
>At every interchange in the web of transportation follow these principles:

>1. Surround the interchange with workplaces and housing types which specially need public transportation.
>2. Keep the interior of the interchange continuous with the exterior pedestrian network, and maintain this continuity by building in small shops and kiosks and by keeping parking to one side.
>3. Keep the transfer distance between different modes of transport down to 300 feet wherever possible, with an absolute maximum of 600 feet.

### Related Patterns
... this pattern defines the points which generate the [[Web of Public Transport (16)]]. It also helps to complete [[Local Transport Areas (11)]] by guaranteeing the possibility of interchanges at the center of each transport area, where people can change from their bikes, or local mini-buses, to the long distance transit lines that connect different transport areas to one another.

Recognize that the creation of workplaces around every interchange contributes to the development of [[Scattered Work (9)]]. Place [[Housing Hill (39)]], [[Old People Everywhere (40)]], and [[Work Community (41)]] round the interchange; treat the outside of the interchange as an [[Activity Nodes (30)]]; treat the transfers as [[Arcades (119)]] where necessary to keep them under cover; give every interchange a [[Bus Stop (92)]] on the [[Mini-Buses (20)]] network ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 183.
> #APL/confidence/low
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/interior-windows-194.md ===== -->

---
title: "Interior Windows (194)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 194
pattern_name: "Interior Windows"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Interior%20Windows%20%28194%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Thoroughfare (101)"
  - "Entrance Room (130)"
  - "The Flow Through Rooms (131)"
  - "Short Passages (132)"
  - "Tapestry of Light and Dark (135)"
  - "Sequence of Sitting Spaces (142)"
  - "Half-Open Wall (193)"
  - "Small Panes (239)"
  - "Solid Doors with Glass (237)"
---

# Interior Windows (194)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Windows are most often used to create connections between the indoor and the outdoors. But there are many cases when an indoor space needs a connecting window another indoor space.

### Solution
>Put in fully glazed fixed windows between rooms which tend to be dead because they have too little action in them or where inside rooms are unusually dark.

### Related Patterns
... at various places in the building, there are walls between rooms where windows would help the rooms to be more alive by creating more views of people and by letting extra light into the darkest corners. For instance, between passages and rooms or between adjacent living rooms, or between adjacent work rooms - [[Building Thoroughfare (101)]], [[Entrance Room (130)]], [[The Flow Through Rooms (131)]], [[Short Passages (132)]], [[Tapestry of Light and Dark (135)]], [[Sequence of Sitting Spaces (142)]], [[Half-Open Wall (193)]].

Make the windows the same as any other windows, with small panes of glass - [[Small Panes (239)]]. In some case it may be right to build interior windows in the doors - [[Solid Doors with Glass (237)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 897.
> #APL/confidence/low
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/intimacy-gradient-127.md ===== -->

---
title: "Intimacy Gradient (127)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 127
pattern_name: "Intimacy Gradient"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Intimacy%20Gradient%20%28127%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wings of Light (107)"
  - "Number of Stories (96)"
  - "Main Entrance (110)"
  - "Common Areas at the Heart (129)"
  - "Entrance Room (130)"
  - "A Room of One's Own (141)"
  - "Bathing Room (144)"
  - "Sequence of Sitting Spaces (142)"
  - "Reception Welcomes You (149)"
  - "Half-Private Office (152)"
---

# Intimacy Gradient (127)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Unless the spaces in a building are arranged in a sequence which corresponds to their degrees of privateness, the visits made by strangers, friends, guests, clients, family, will always be a little awkward.

### Solution
>Lay out the spaces of a building so that they create a sequence which begins with the entrance and the most public parts of the building, then leads into the slightly more private areas, and finally to the most private domains.

### Related Patterns
... if you know roughly where you intend to place the building wings - [[Wings of Light (107)]], and how many stories they will have - [[Number of Stories (96)]], and where the [[Main Entrance (110)]] is, it is time to work out the rough disposition of the major areas on every floor. In every building the relationship between the public areas and private areas is most important.

At the same time that common areas are to the front, make sure that they are also at the heart and soul of the activity, and that all paths between more private rooms pass tangent to the common ones - [[Common Areas at the Heart (129)]]. In private houses make the [[Entrance Room (130)]] the most formal and public place and arrange the most private areas so that each person has a room of his own, where he can retire to be alone - [[A Room of One's Own (141)]]. Place bathing rooms and toilets half-way between the common areas and the private ones, so that people can reach them comfortably from both - [[Bathing Room (144)]]; and place sitting areas at all the different degrees of intimacy, and shape them according to their position in the gradient - [[Sequence of Sitting Spaces (142)]]. In offices put [[Reception Welcomes You (149)]] at the front of the gradient and [[Half-Private Office (152)]] at the back ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 610.
> #APL/confidence/high
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/lace-of-country-streets-5.md ===== -->

---
title: "Lace of Country Streets (5)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 5
pattern_name: "Lace of Country Streets"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Lace%20of%20Country%20Streets%20%285%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "City Country Fingers (3)"
  - "The Countryside (7)"
  - "Identifiable Neighborhood (14)"
  - "House Cluster (37)"
---

# Lace of Country Streets (5)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The suburb is an obsolete and contradictory form of human settlement.

### Solution
>In the zone where city and country meet, place country roads at least a mile apart, so that they enclose squares of countryside and farmland at least one square mile in area. Build homesteads along these roads, one lot deep, on lots of at least half an acre, with the square mile of open countryside or farmland behind the houses.

### Related Patterns
... according to the pattern [[City Country Fingers (3)]], there is a rather sharp division between city and rural land. But at the ends of city fingers, where the country fingers open out, there is a need for an additional kind of structure.

Make each square mile of countryside, both farm and park, open to the public -- [[The Countryside (7)]]; arrange the half acre lots to form clusters of houses and neighborhoods, even when they are rather spread out -- [[Identifiable Neighborhood (14)]], [[House Cluster (37)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 29.
> #APL/confidence/low
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/lapped-outside-walls-234.md ===== -->

---
title: "Lapped Outside Walls (234)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 234
pattern_name: "Lapped Outside Walls"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Lapped%20Outside%20Walls%20%28234%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wall Membranes (218)"
  - "Roof Vaults (220)"
---

# Lapped Outside Walls (234)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The main function of a building’s outside wall is to keep weather out. It can only do this if the materials are joined in such a way that they cooperate to make impervious joints.

### Solution
>Build up the exterior wall surface with materials that are lapped against the weather: either "internally lapped", like exterior plaster, or more literally lapped, like shingles and boards and tiles. In either case, choose a material that is easy to repair in little patches, inexpensively, so that little by little, the wall can be maintained in good condition indefinitely.

### Related Patterns
... this pattern finishes the [[Wall Membranes (218)]], and [[Roof Vaults (220)]]. It defines the character of their outside surfaces.

In making our filled lightweight concrete structures, we have used lapped boards as the exterior formwork for the lightweight concrete fill. And it is, of course, possible to use many other kinds of external cladding if they are available and if one can afford them. Slate, corrugated iron, ceramic tiles will produce excellent shingled wall claddings, and can all be placed in such a way as to provide exterior formwork for the pouring of a wall. It is also conceivable (though we have no evidence for it), that scientists might be able to create an oriented material whose internal crystal or fiber structure is in effect "lapped," because all the split lines run diagonally outward and downward.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1093.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/life-cycle-26.md ===== -->

---
title: "Life Cycle (26)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 26
pattern_name: "Life Cycle"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Life%20Cycle%20%2826%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "Holy Ground (66)"
  - "Household Mix (35)"
  - "Old People Everywhere (40)"
  - "Work Community (41)"
  - "Local Town Hall (44)"
  - "Children in the City (57)"
  - "Birth Places (65)"
  - "Grave Sites (70)"
  - "The Family (75)"
  - "Your Own Home (79)"
  - "Master and Apprentices (83)"
  - "Teenage Society (84)"
  - "Shopfront Schools (85)"
  - "Children's Home (86)"
  - "Rooms to Rent (153)"
  - "Teenager's Cottage (154)"
  - "Old Age Cottage (155)"
  - "Settled Work (156)"
  - "Marriage Bed (187)"
---

# Life Cycle (26)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem

    “All the world’s a stage,
    And all the men and women merely players:
    They have their exits and their entrances;
    And one man in his time plays many parts,
    His acts being seven ages.”

    — Shakespeare, As You Like It

### Solution

Make certain that the full cycle of life is represented and balanced in each community. Set the ideal of a balanced life cycle as a principal guide for the evolution of communities. This means:

>1. That each community include a balance of people at every stage of the life cycle, from infants to the very old; and include the full slate of settings needed for all these stages of life;
>2. That the community contain the full slate of settings which best mark the ritual crossing of life from one stage to the next.

### Related Patterns
... a real community provides, in full, for the balance of human experience and human life -- [[Community of 7000 (12)]]. To a lesser extent, a good neighborhood will do the same -- [[Identifiable Neighborhood (14)]]. To fulfill this promise, communities and neighborhoods must have the range of things which life can need, so that a person can experience the full breadth and depth of life in their community.

The rites of passage are provided for, most concretely, by [[Holy Ground (66)]]. Other specific patterns which especially support the seven ages of man and the ceremonies of transition are [[Household Mix (35)]], [[Old People Everywhere (40)]], [[Work Community (41)]], [[Local Town Hall (44)]], [[Children in the City (57)]], [[Birth Places (65)]], [[Grave Sites (70)]], [[The Family (75)]], [[Your Own Home (79)]], [[Master and Apprentices (83)]], [[Teenage Society (84)]], [[Shopfront Schools (85)]], [[Children's Home (86)]], [[Rooms to Rent (153)]], [[Teenager's Cottage (154)]], [[Old Age Cottage (155)]], [[Settled Work (156)]], [[Marriage Bed (187)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 139.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/light-on-two-sides-of-every-room-159.md ===== -->

---
title: "Light on Two Sides of Every Room (159)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 159
pattern_name: "Light on Two Sides of Every Room"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Light%20on%20Two%20Sides%20of%20Every%20Room%20%28159%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Long Thin House (109)"
  - "Cascade of Roofs (116)"
  - "Roof Layout (209)"
  - "Windows Overlooking Life (192)"
  - "Natural Doors and Windows (221)"
  - "Window Place (180)"
  - "Deep Reveals (223)"
  - "Filtered Light (238)"
---

# Light on Two Sides of Every Room (159)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When they have a choice, people will always gravitate to those rooms which have light on two sides, and leave the rooms which are lit only from one side unused and empty.

### Solution
>Locate each room so that it has outdoor space outside it on at least two sides, and then place windows in these outdoor walls so that natural light falls into every room from more than one direction.

### Related Patterns
... once the building's major rooms are in position, we have to fix its actual shape: and this we do essentially with the position of the edge. The edge has got its rough position already from the overall form of the building - [[Wings of Light (107)]], [[Positive Outdoor Space (106)]], [[Long Thin House (109)]], [[Cascade of Roofs (116)]]. This pattern now completes the work of [[Wings of Light (107)]], by placing each individual room exactly where it needs to be to get the light. It forms the exact line of the building edge, according to the position of these individual rooms. The next pattern starts to shape the edge.

 Don't let this pattern make your plans too wild - otherwise you will destroy the simplicity of [[Positive Outdoor Space (106)]], and you will have a terrible time roofing the building - [[Roof Layout (209)]]. Remember that it is possible to keep the essence of the pattern with windows on one side, if the room is unusually high, if it is shallow compared with the length of the window wall, the windows large, the walls of the room white, and massive deep reveals on the windows to make quite certain that the big windows, bright against the sky, do not create glare.

Place the individual windows to look onto something beautiful - [[Windows Overlooking Life (192)]], [[Natural Doors and Windows (221)]]; and make one of the windows in the room a special one, so that a place gathers itself around it - [[Window Place (180)]]. Use [[Deep Reveals (223)]] and [[Filtered Light (238)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 746.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/local-sports-72.md ===== -->

---
title: "Local Sports (72)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 72
pattern_name: "Local Sports"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Local%20Sports%20%2872%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Work Community (41)"
  - "Health Center (47)"
  - "Building Complex (95)"
  - "Bathing Room (144)"
  - "Still Water (71)"
  - "Building Thoroughfare (101)"
  - "Opening to the Street (165)"
  - "Seat Spots (241)"
  - "Sitting Wall (243)"
---

# Local Sports (72)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The human body does not wear out with use. On the contrary, it wears down when it is not used.

### Solution
>Scatter places for team and individual sports through every work community and neighborhood: tennis, squash, table tennis, swimming, billiards, basketball, dancing, gymnasium…and make the action visible to passers-by, as an invitation to participate.

### Related Patterns
... all the areas where people live and work - especially the [[Work Community (41)]] and the areas looked after by the preventive programs of the [[Health Center (47)]] - need to be completed by provisions for sports and exercise. This pattern defines the nature and distribution of this exercise.

Treat the sports places as a special class of recognizable simple buildings, which are open, easy to get into, with changing rooms and showers - [[Building Complex (95)]], [[Bathing Room (144)]]; combine them with community swimming pools, where they exist - [[Still Water (71)]] ; keep them open to people passing - [[Building Thoroughfare (101)]], [[Opening to the Street (165)]],and provide places where people can stop and watch - [[Seat Spots (241)]], [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 363.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/local-town-hall-44.md ===== -->

---
title: "Local Town Hall (44)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 44
pattern_name: "Local Town Hall"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Local%20Town%20Hall%20%2844%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Community of 7000 (12)"
  - "Activity Nodes (30)"
  - "Small Public Squares (61)"
  - "Pedestrian Density (123)"
  - "Small Services Without Red Tape (81)"
  - "Necklace of Community Projects (45)"
---

# Local Town Hall (44)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Local government of communities and local control by the inhabitants, will only happen if each community has its own physical town hall which forms the nucleus of its political activity.

### Solution
>To make the political control of local functions real, establish a small town hall for each community of 7,000, and even for each neighborhood; locate it near the busiest intersection in the community. Give the building three parts: an arena for public discussion, public services around the arena, and space to rent out to ad hoc community projects.

### Related Patterns
... according to [[Community of 7000 (12)]], the political and economic life of the city breaks down into small, self-governing communities. In this case, the process of local government needs a physical place of work; and the design and placing of this physical space of work can help to create and to sustain the [[Community of 7000 (12)]] by acting as its physical and social focus.

Arrange the arena so that it forms the heart of the community crossroads; and make it small, so that a crowd can easily gather there -- [[Activity Nodes (30)]], [[Small Public Squares (61)]], [[Pedestrian Density (123)]]. Keep all the public services around this square as small as possible -- [[Small Services Without Red Tape (81)]]; and provide ample space for the community projects, in a ring around the building, so that they form the outer face of the town hall -- [[Necklace of Community Projects (45)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 236.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/local-transport-areas-11.md ===== -->

---
title: "Local Transport Areas (11)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 11
pattern_name: "Local Transport Areas"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Local%20Transport%20Areas%20%2811%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "City Country Fingers (3)"
  - "Magic of the City (10)"
  - "Parallel Roads (23)"
  - "Green Streets (51)"
  - "Network of Paths and Cars (52)"
  - "Bike Paths and Racks (56)"
  - "Ring Roads (17)"
  - "Nine Per Cent Parking (22)"
  - "Shielded Parking (97)"
  - "Interchange (34)"
---

# Local Transport Areas (11)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Cars give people wonderful freedom and increase their opportunities. But they also destroy the environment, to an extent so drastic that they kill all social life.

### Solution
>Break the urban area down into local transport areas, each one between 1 and 2 miles across, surrounded by a ring road. Within the local transport area, build minor local roads and paths for internal movements on foot, by bike, on horseback, and in local vehicles; build major roads which make it easy for cars and trucks to get to and from the ring roads, but place them to make internal local trips slow and inconvenient.

### Related Patterns
... superimposed over the [[Mosaic of Subcultures (8)]], there is a need for a still larger cellular structure: the local transport areas. These areas, 1-2 mile across, not only help to form subcultures, by creating natural boundaries in the city, but they can also help to generate the individual city fingers in the [[City Country Fingers (3)]], an they can help to circumscribe each downtown area too, as a special self-contained area of local transportation -- [[Magic of the City (10)]].

To keep main roads for long distance traffic, but not for internal local traffic, lay them out as they parallel one way roads, and keep these parallel roads away from the center of the area, so that they are very good for getting to the ring roads, but inconvenient for short local trips -- [[Parallel Roads (23)]]. Lay out abundant footpaths and bike paths and green streets at right angles to the main roads, and make these paths for local traffic go directly through the center -- [[Green Streets (51)]], [[Network of Paths and Cars (52)]], [[Bike Paths and Racks (56)]]; sink the ring roads around the outside of each area, or shield the noise they make some other way -- [[Ring Roads (17)]]; keep parking to a minimum within the area, and keep all major parking garages near the ring roads -- [[Nine Per Cent Parking (22)]], [[Shielded Parking (97)]]; and build a major interchange within the center of the area -- [[Interchange (34)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 63
> #APL/confidence/high
>
> #APL/Town-Patterns/City-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/long-thin-house-109.md ===== -->

---
title: "Long Thin House (109)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 109
pattern_name: "Long Thin House"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Long%20Thin%20House%20%28109%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Intimacy Gradient (127)"
  - "Cascade of Roofs (116)"
  - "Common Areas at the Heart (129)"
---

# Long Thin House (109)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The shape of a building has a great effect on the relative degrees of privacy and overcrowding in it, and this in turn has a critical effect on people’s comfort and well-being.

### Solution
>In small buildings, don’t cluster all the rooms together around each other; instead string out the rooms one after another, so that distance between each room is as great as it can be. You can do this horizontally—so that the plan becomes a thin, long rectangle; or you can do it vertically—so that the building becomes a tall narrow tower. In either case, the building can be surprisingly narrow and still work—8, 10, and 12 feet are all quite possible.

### Related Patterns
... for a very small house or office the pattern of [[Wings of Light (107)]] is almost automatically solved - no one would imagine that the house should be more than 25 feet wide. But in such a house or office there are strong reasons to make the building even longer and thinner still. This pattern was originally formulated by Christie Coffin.

Use the long thin plan to help shape outdoor space on the site - [[Positive Outdoor Space (106)]]; the long perimeter of the building sets the stage for [[Intimacy Gradient (127)]] and for the [[Cascade of Roofs (116)]]. Make certain that the privacy which is achieved with the thinness of the building is balanced with the communality at the crossroads of the house - [[Common Areas at the Heart (129)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 535.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/looped-local-roads-49.md ===== -->

---
title: "Looped Local Roads (49)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 49
pattern_name: "Looped Local Roads"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Looped%20Local%20Roads%20%2849%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Identifiable Neighborhood (14)"
  - "Parallel Roads (23)"
  - "House Cluster (37)"
  - "Work Community (41)"
  - "T Junctions (50)"
  - "Green Streets (51)"
  - "Small Parking Lots (103)"
  - "Car Connection (113)"
  - "Network of Paths and Cars (52)"
---

# Looped Local Roads (49)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Nobody wants fast through-traffic going by their homes.

### Solution
>Lay out local roads so that they form loops. A loop is defined as any stretch of road which makes it impossible for cars that don’t have destinations on it to use as a shortcut. Do not allow any one loop to serve more than 50 cars, and keep the road really narrow—17 to 20 feet is quite enough.

### Related Patterns
... assume that neighborhoods, house clusters, work communities, and major roads are more or less defined -- [[Local Transport Areas (11)]], [[Identifiable Neighborhood (14)]], [[Parallel Roads (23)]], [[House Cluster (37)]], [[Work Community (41)]]. Now, for, the layout of the local roads.

Make all the junctions between the local roads three-way T junctions, never four-way intersections -- [[T Junctions (50)]]; wherever there is any possibility of life from buildings be oriented towards the road, give the road a very rough surface of grass and gravel, with paving stones for wheels of cars -- [[Green Streets (51)]]; keep parking off the road in driveways -- [[Small Parking Lots (103)]] and [[Car Connection (113)]]; except where the roads are very quiet, run pedestrian paths at right angles to them, not along them, and make buildings open off these paths, not off the roads -- [[Network of Paths and Cars (52)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 260.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/low-doorway-224.md ===== -->

---
title: "Low Doorway (224)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 224
pattern_name: "Low Doorway"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Low%20Doorway%20%28224%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "The Flow Through Rooms (131)"
  - "Corner Doors (196)"
  - "Natural Doors and Windows (221)"
  - "Frames as Thickened Edges (225)"
  - "Ornament (249)"
  - "Solid Doors with Glass (237)"
---

# Low Doorway (224)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>High doorways are simple and convenient. But a lower door is often more profound.

### Solution
>Instead of taking it for granted that your doors are simply 6’ 8" rectangular openings to pass through, make at least some of your doorways low enough that the act of going through the door is a deliberate thoughtful passage from one place to another. Especially at the entrance to a house, at the entrance to a private room, or a fire corner—make the doorway lower than usual, perhaps even as low as 5’ 8".

### Related Patterns
... some of the doors in a building play a special role in creating transitions and maintaining privacy: it may be any of the doors governed by [[Family of Entrances (102)]], or [[Main Entrance (110)]], or [[The Flow Through Rooms (131)]] or [[Corner Doors (196)]], or [[Natural Doors and Windows (221)]]. This pattern helps to complete these doors by giving them a special height and shape.

Test the height before you build it, in place - [[Natural Doors and Windows (221)]]. Build the door frame as part of the structure - [[Frames as Thickened Edges (225)]], and make it beautiful with [[Ornament (249)]] around the frame. If there is a door, glaze it, at least partially - [[Solid Doors with Glass (237)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1056.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Fenestration


<!-- ===== pattern-language/wiki/concepts/patterns/low-sill-222.md ===== -->

---
title: "Low Sill (222)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 222
pattern_name: "Low Sill"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Low%20Sill%20%28222%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Natural Doors and Windows (221)"
  - "Zen View (134)"
  - "Window Place (180)"
  - "Windows Overlooking Life (192)"
  - "Waist-High Shelf (201)"
  - "Frames as Thickened Edges (225)"
  - "Windows Which Open Wide (236)"
  - "Raised Flowers (245)"
---

# Low Sill (222)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>One of a window’s most important functions is to put you in touch with the outdoors. If the sill is too high, it cuts you off.

### Solution
>When determining exact location of windows also decide which windows should have low sills. On the first floor, make the sills of windows which you plan to sit by between 12 and 14 inches high. On the upper stories, make them higher, around 20 inches.

### Related Patterns
... this pattern helps to complete [[Natural Doors and Windows (221)]], and the special love for the view, and for the earth outside, which [[Zen View (134)]], [[Window Place (180)]] and [[Windows Overlooking Life (192)]] all need.

Make the sill part of the frame, and make it wide enough to put things on - [[Waist-High Shelf (201)]], [[Frames as Thickened Edges (225)]], [[Windows Which Open Wide (236)]]. Make the window open outward, so that you can use the sill as a shelf, and so that you can lean out and tend the flowers. If you can, put flowers right outside the window, on the ground or raised a little, too, so that you can always see the flowers from inside the room - [[Raised Flowers (245)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1050.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Fenestration


<!-- ===== pattern-language/wiki/concepts/patterns/magic-of-the-city-10.md ===== -->

---
title: "Magic of the City (10)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 10
pattern_name: "Magic of the City"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Magic%20of%20the%20City%20%2810%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "City Country Fingers (3)"
  - "Local Transport Areas (11)"
  - "Promenade (31)"
  - "Web of Public Transport (16)"
  - "Night Life (33)"
  - "Carnival (58)"
  - "Dancing in the Street (63)"
---

# Magic of the City (10)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There are few people who do not enjoy the magic of a great city. But urban sprawl takes it away from everyone except the few who are lucky enough, or rich enough, to live close to the largest centers.

### Solution
>Put the magic of the city within reach of everyone in a metropolitan area. Do this by means of collective regional policies which restrict the growth of downtown areas so strongly that no one downtown can grow to serve more than 300,000 people. With this population base, the downtowns will be between two and nine miles apart.

### Related Patterns
... next to the [[Mosaic of Subcultures (8)]], perhaps the most important structural feature of a city is the pattern of those centers where the city life is most intense. These centers can help form the mosaic of subcultures by their variety; and they can also help to form [[City Country Fingers (3)]], if each of the centers is at a natural meeting point of several fingers. This pattern was first written by Luis Racionero under the name "Downtown of 300,000".

Treat each downtown as a pedestrian and local transport area -- [[Local Transport Areas (11)]], [[Promenade (31)]], with good transit connections from the outlying areas -- [[Web of Public Transport (16)]]; encourage a rich concentration of night life within each downtown -- [[Night Life (33)]], and set aside at least some part of it for the wildest kind of street life -- [[Carnival (58)]], [[Dancing in the Street (63)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 58
> #APL/confidence/low
>
> #APL/Town-Patterns/City-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/main-building-99.md ===== -->

---
title: "Main Building (99)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 99
pattern_name: "Main Building"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Main%20Building%20%2899%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Number of Stories (96)"
  - "Circulation Realms (98)"
  - "Common Areas at the Heart (129)"
  - "Cascade of Roofs (116)"
  - "Structure Follows Social Spaces (205)"
---

# Main Building (99)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A complex of buildings with no center is like a person without a head.

### Solution
>For any collection of buildings, decide which building in the group houses the most essential function—which building is the soul of the group, as a human institution. Then form this building as the main building, with a central position, higher roof.
>Even if the building complex is so dense that it is a single building, build the main part of it higher and more prominent than the rest, so that the eye goes immediately to the part which is the most important.

### Related Patterns
... once you have decided more or less how people will move around within the [[Building Complex (95)]], and roughly how high the buildings will be - [[Number of Stories (96)]] - it is time to try and find the natural heart or center of the building complex, to help complete its [[Circulation Realms (98)]].

Build all the main paths tangent to the main building, in arcades or glazed corridors, with a direct view into its main functions - [[Common Areas at the Heart (129)]]. Make the roof cascade down from the high roof over the main building to lower roofs over the smaller buildings - [[Cascade of Roofs (116)]]. And for the load bearing structure, engineering, and construction, begin with [[Structure Follows Social Spaces (205)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 485.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/main-entrance-110.md ===== -->

---
title: "Main Entrance (110)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 110
pattern_name: "Main Entrance"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Main%20Entrance%20%28110%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Site Repair (104)"
  - "South Facing Outdoors (105)"
  - "Wings of Light (107)"
  - "Circulation Realms (98)"
  - "Family of Entrances (102)"
  - "Entrance Room (130)"
  - "Entrance Transition (112)"
  - "Shielded Parking (97)"
  - "Car Connection (113)"
---

# Main Entrance (110)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Placing the main entrance (or main entrances) is perhaps the single most important step you take during the evolution of a building plan.

### Solution
>Place the main entrance of the building at a point where it can be seen immediately from the main avenues of approach and give it a bold, visible shape which stands out in front of the building.

### Related Patterns
... you have a rough position for your building on the site - [[Site Repair (104)]], [[South Facing Outdoors (105)]], [[Wings of Light (107)]]. You also have an idea of the major circulation in the building complex and the lines of approach which lead toward the building - [[Circulation Realms (98)]], [[Family of Entrances (102)]]. Now it is time to fix the entrance of the building.

 If possible, make the entrance one of a family of similar entrances, so that they all stand out as visibly as possible within the street or building complex - [[Family of Entrances (102)]]; build that part of the entrance which sticks out, as a room, large enough to be a pleasant, light, and beautiful place - [[Entrance Room (130)]] and bring the path between the street and this entrance room through a series of transitions of light and level and view - [[Entrance Transition (112)]]. Make sure that the entrance has the proper relationship to parking - [[Shielded Parking (97)]], [[Car Connection (113)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 540.
> #APL/confidence/high
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/main-gateways-53.md ===== -->

---
title: "Main Gateways (53)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 53
pattern_name: "Main Gateways"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Main%20Gateways%20%2853%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "House Cluster (37)"
  - "Work Community (41)"
  - "Building Complex (95)"
  - "Circulation Realms (98)"
  - "Main Entrance (110)"
  - "Entrance Transition (112)"
---

# Main Gateways (53)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Any part of town—large or small—which is to be identified by its inhabitants as a precinct of some kind, will be reinforced, helped in its distinctness, marked, and made more vivid, if the paths which enter it are marked by gateways where they cross the boundary.

### Solution
>Mark every boundary in the city which has important human meaning—the boundary of a building cluster, a neighborhood, a precinct—by great gateways where the major entering paths cross the boundary.

### Related Patterns
... at various levels in the structure of the town, there are identifiable units. There are neighborhoods -- [[Identifiable Neighborhood (14)]], clusters -- [[House Cluster (37)]], communities of work -- [[Work Community (41)]]; and there are many smaller building complexes ringed around some realms of circulation -- [[Building Complex (95)]], [[Circulation Realms (98)]]. All of them get their identity most clearly from the fact that you pass through a defined gateway to enter them -- it is this gateway acting as a threshold which creates the unit.

Make the gateways solid elements, visible from every line of approach, enclosing the paths, punching a hole through a building, creating a bridge or a sharp change of level -- but above all make them "things", in just the same way specified for [[Main Entrance (110)]], but make them larger. Whenever possible, emphasize the feeling of transition for the person passing through the gateway, by allowing change of light, or surface, view, crossing water, a change of level -- [[Entrance Transition (112)]]. In every case, treat the main gateway as a starting point of the pedestrian circulation inside the precinct -- [[Circulation Realms (98)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 276.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/market-of-many-shops-46.md ===== -->

---
title: "Market of Many Shops (46)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 46
pattern_name: "Market of Many Shops"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Market%20of%20Many%20Shops%20%2846%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Web of Shopping (19)"
  - "Shopping Street (32)"
  - "Building Thoroughfare (101)"
  - "Individually Owned Shops (87)"
  - "Columns at the Corners (212)"
  - "Canvas Roofs (244)"
  - "Pedestrian Street (100)"
---

# Market of Many Shops (46)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>It is natural and convenient to want a market where all the different foods and household goods you need can be bought under a single roof. But when the market has a single management, like a supermarket, the foods are bland, and there is no joy in going there.

### Solution
>Instead of modern supermarkets, establish frequent marketplaces, each one made up of many smaller shops which are autonomous and specialized (cheese, meat, grain, fruit, and so on). Build the structure of the market as a minimum, which provides no more than a rood, columns which define aisles, and basic services. Within this structure allow the different shops to create their own environment, according to their individual taste and needs.

### Related Patterns
... we have a proposed that shops be widely decentralized and placed in such a way that they are most accessible to the communities which use them -- [[Web of Shopping (19)]]. The largest groups of shops are arranged to form pedestrian streets or [[Shopping Street (32)]] which will almost need a market to survive. This pattern describes the form and economic character of markets.

Make the aisles wide enough for small delivery carts and for a a dense throng of pedestrians -- perhaps 6 to 12 feet wide -- [[Building Thoroughfare (101)]]; keep the stalls extremely small so that the rent is low -- perhaps no more than six by nine feet -- [[Individually Owned Shops (87)]]; define the stalls with columns at the corners only -- [[Columns at the Corners (212)]]; perhaps even let the owners make roofs for themselves -- [[Canvas Roofs (244)]]; connect the aisles with the outside so that the market is a direct continuation of the pedestrian paths in the city just around it -- [[Pedestrian Street (100)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 246.
> #APL/confidence/high
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/marriage-bed-187.md ===== -->

---
title: "Marriage Bed (187)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 187
pattern_name: "Marriage Bed"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Marriage%20Bed%20%28187%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Couple's Realm (136)"
  - "Dressing Rooms (189)"
  - "Bed Alcove (188)"
  - "Ceiling Height Variety (190)"
  - "Ornament (249)"
  - "The Shape of Indoor Space (191)"
---

# Marriage Bed (187)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The bed is the center of a couple’s life together: the place where they lie together, talk, make love, sleep, sleep late, take care of each other during illness. But beds and bedrooms are not often made in ways which intensity their meaning, and these experiences cannot take hold.

### Solution
>At the right moment in a couple’s life, it is important that they make for themselves a special bed—an intimate anchor point for their lives; slightly enclosed, with a low ceiling or a canopy, with the room shapes to it; perhaps a tiny room build around the bed with many windows. Give the bed some shape of its own, perhaps as a four-poster with head board that can be hand carved or painted over the years.

### Related Patterns
... the pattern [[Couple's Realm (136)]] gives emphasis to the importance of the couple's private life together within a household. Within that couple's realm, the placing and nature of the bed is naturally the most important thing.

Make two separate dressing rooms or alcoves near the bed - [[Dressing Rooms (189)]]; for more details on the space around the bed, see [[Bed Alcove (188)]]; lower the ceiling over the bed - [[Ceiling Height Variety (190)]], and provide some way of creating special ornament all around it - [[Ornament (249)]]. For the detailed shape of the space around the bed, see [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 864.
> #APL/confidence/low
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/master-and-apprentices-83.md ===== -->

---
title: "Master and Apprentices (83)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 83
pattern_name: "Master and Apprentices"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Master%20and%20Apprentices%20%2883%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Network of Learning (18)"
  - "Self-Governing Workshops and Offices (80)"
  - "Half-Private Office (152)"
  - "Workspace Enclosure (183)"
  - "Common Areas at the Heart (129)"
  - "Communal Eating (147)"
  - "Small Work Groups (148)"
  - "Small Meeting Rooms (151)"
---

# Master and Apprentices (83)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The fundamental learning situation is one in which a person learns by helping someone who really knows what they are doing.

### Solution
>Arrange the work in every workgroup, industry, and office, in such a way that work and learning go forward hand in hand. Treat every piece of work as an opportunity for learning. To this end, organize work around a tradition of masters and apprentices: and support this form of social organization with a division of the workspace into spatial clusters—one for each master and their apprentices—where the group can work and meet together.

### Related Patterns
... the [[Network of Learning (18)]] in the community relies on the fact that learning is decentralized, and part and parcel of every activity - not just a classroom thing. In order to realize this pattern, it is essential that the individual workgroups, through- out industry, offices, workshops, and work communities, are all set up to make the learning process possible. This pattern, which shows the arrangement needed, therefore helps greatly to form [[Self-Governing Workshops and Offices (80)]] as well as the [[Network of Learning (18)]].

Arrange the workspaces as [[Half-Private Office (152)]] or [[Workspace Enclosure (183)]]. Keep workgroups small, and give every group a common area, a common meeting space, and a place where they can eat together - [[Common Areas at the Heart (129)]], [[Communal Eating (147)]], [[Small Work Groups (148)]], [[Small Meeting Rooms (151)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 412.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/men-and-women-27.md ===== -->

---
title: "Men and Women (27)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 27
pattern_name: "Men and Women"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Men%20and%20Women%20%2827%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "Life Cycle (26)"
  - "Scattered Work (9)"
  - "A Room of One's Own (141)"
---

# Men and Women (27)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The world of a town in the 1970’s is split along sexual lines. Suburbs are for women, workplaces for men; kindergartens are for women, professional schools for men; supermarkets are for women, hardware stores for men.

### Solution
>Make certain that each piece of the environment—each building, open space, neighborhood, and work community—is made with a blend of both men’s and women’s instincts. Keep this balance of masculine and feminine in mind for every project at every scale, from the kitchen to the steel mill.

### Related Patterns
... and just as a community or neighborhood must have a proper balance of activities for people of all different ages -- [[Community of 7000 (12)]], [[Identifiable Neighborhood (14)]], [[Life Cycle (26)]] -- so it must also adjust itself and its activities to the balance of the sexes, and provide, in equal part, the things which reflect the masculine and feminine sides of life.

No large housing areas without workshops for men; no work communities which do not provide for women with part-time jobs and child care -- [[Scattered Work (9)]]. Within each place which has a balance of the masculine and feminine, make sure that individual men and women also have room to flourish, in their own right, distinct and separate from their opposites -- [[A Room of One's Own (141)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 146.
> #APL/confidence/low
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/mini-buses-20.md ===== -->

---
title: "Mini-Buses (20)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 20
pattern_name: "Mini-Buses"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Mini-Buses%20%2820%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Web of Public Transport (16)"
  - "Parallel Roads (23)"
  - "Interchange (34)"
  - "Bus Stop (92)"
---

# Mini-Buses (20)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Public transportation must be able to take people from any point to any other point within the metropolitan area.

### Solution
>Establish a system of small taxi-like buses, carrying up to six people each, radio-controlled, on call by telephone, able to provide point-to-point service according to the passengers’ needs, and supplemented by a computer system which guarantees minimum detours, and minimum waiting times. Make bus stops for the mini-buses every 600 feet in each direction, and equip these bus stops with a phone for dialing a bus.

### Related Patterns
... this pattern helps complete the [[Local Transport Areas (11)]] and the [[Web of Public Transport (16)]]. The local transport areas rely heavily on foot traffic, and on bikes and carts and horses. The web of public transportation relies on trains and planes and buses. Both of these patterns need a more flexible form of public transportation to support them.

Place the stops mainly along major roads, as far as this can be consistent with the fact that no one ever has to walk more than 600 feet to the nearest one -- [[Parallel Roads (23)]]; put one in every [[Interchange (34)]]; and make each one a place where a few minutes' wait is pleasant -- [[Bus Stop (92)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 110
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/mosaic-of-subcultures-8.md ===== -->

---
title: "Mosaic of Subcultures (8)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 8
pattern_name: "Mosaic of Subcultures"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Mosaic%20of%20Subcultures%20%288%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "City Country Fingers (3)"
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "House Cluster (37)"
  - "Subculture Boundary (13)"
---

# Mosaic of Subcultures (8)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The homogeneous and undifferentiated character of modern cities kills all variety of life styles and arrests the growth of individual character.

### Solution
>Do everything possible to enrich the cultures and subcultures of the city, by breaking the city, as far as possible, into a vast mosaic of small and different subcultures, each with its own spatial territory, and each with the power to create its own distinct life style. Make sure that the subcultures are small enough, so that each person has access to the full variety of life styles in the subcultures near his own.

### Related Patterns
... the most basic structure of a city is given by the relation of urban land to open country -- [[City Country Fingers (3)]]. Within the swaths of urban land the most important structure must from from the great variety of human groups and subcultures which can co-exist there.

We imagine that the smallest subcultures will be no bigger than 150 feet across; the largest perhaps as much as a quarter of a mile -- [[Community of 7000 (12)]], [[Identifiable Neighborhood (14)]], [[House Cluster (37)]]. To ensure that the life cycles of each subculture can develop freely, uninhibited by those which are adjacent, it is essential to create substantial boundaries of nonresidential land between adjacent subcultures -- [[Subculture Boundary (13)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 42
> #APL/confidence/high
>
> #APL/Town-Patterns/City-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/natural-doors-and-windows-221.md ===== -->

---
title: "Natural Doors and Windows (221)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 221
pattern_name: "Natural Doors and Windows"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Natural%20Doors%20and%20Windows%20%28221%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Box Columns (216)"
  - "Perimeter Beams (217)"
  - "Zen View (134)"
  - "Street Windows (164)"
  - "Window Place (180)"
  - "Windows Overlooking Life (192)"
  - "Corner Doors (196)"
  - "Low Sill (222)"
  - "Deep Reveals (223)"
  - "Small Panes (239)"
---

# Natural Doors and Windows (221)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Finding the right position for a window or a door is a subtle matter. But there are very few ways of building which take this into consideration.

### Solution
>On no account use standard doors or windows. Make each window a different size, according to its place.
>Do not fix the exact position or size of the door and window frames until the rough framing of the room has actually been built, and you can really stand inside the room and judge, eye by eye, exactly where you want to put them, and how big you want them. When you decide, mark the openings with strings.
>Make the windows smaller and smaller, as you go higher in the building.

### Related Patterns
... imagine that you are now standing in the built-up frame of a partly constructed building, with the columns and beams in place - [[Box Columns (216)]], [[Perimeter Beams (217)]]. You know roughly where you want doors and windows from [[Zen View (134)]], [[Street Windows (164)]], [[Window Place (180)]], [[Windows Overlooking Life (192)]], [[Corner Doors (196)]]. Now you can settle on the exact positions of the frames.

Fine tune the exact position of each edge, and mullion, and sill, according to your comfort in the room, and the view that the window looks onto - [[Low Sill (222)]], [[Deep Reveals (223)]]. As a result, each window will have a different size and shape, according to its position in the building. This means that it is obviously impossible to use standard windows and even impossible to make each window a simple multiple of standard panes. But it will still be possible to glaze each window, since the procedure for building the panes makes them divisions of the whole, instead of making up the whole as a multiple of standard panes - [[Small Panes (239)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1046.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Fenestration


<!-- ===== pattern-language/wiki/concepts/patterns/necklace-of-community-projects-45.md ===== -->

---
title: "Necklace of Community Projects (45)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 45
pattern_name: "Necklace of Community Projects"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Necklace%20of%20Community%20Projects%20%2845%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Town Hall (44)"
  - "University as a Marketplace (43)"
  - "Health Center (47)"
  - "Individually Owned Shops (87)"
  - "Public Outdoor Room (69)"
  - "Building Fronts (122)"
  - "Building Edge (160)"
  - "Opening to the Street (165)"
---

# Necklace of Community Projects (45)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The local town hall will not be an honest part of the community which lives around it, unless it is itself surrounded by all kinds of small community activities and projects, generated by the people for themselves.

### Solution
>Allow the growth of shop-size spaces around the local town hall, and any other appropriate community building. Front these shops on a busy path, and lease them for a minimum rent to ad hoc community groups for political work, trial services, research, and advocate groups. No ideological restrictions.

### Related Patterns
... [[Local Town Hall (44)]] calls for small centers of local government at the heart of every community. This pattern embellishes the local town hall and other public institutions like it -- [[University as a Marketplace (43)]] and [[Health Center (47)]] -- with a ground for community action.

Make each shop small, compact, and easily accessible like [[Individually Owned Shops (87)]]; build small public spaces for loitering amongst them -- [[Public Outdoor Room (69)]]. Use them to form the building edge -- [[Building Fronts (122)]], [[Building Edge (160)]], and keep them open to the street -- [[Opening to the Street (165)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 242.
> #APL/confidence/low
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/neighborhood-boundary-15.md ===== -->

---
title: "Neighborhood Boundary (15)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 15
pattern_name: "Neighborhood Boundary"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Neighborhood%20Boundary%20%2815%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Community of 7000 (12)"
  - "Subculture Boundary (13)"
  - "Identifiable Neighborhood (14)"
  - "Main Gateways (53)"
  - "Parallel Roads (23)"
  - "Work Community (41)"
  - "Quiet Backs (59)"
  - "Accessible Green (60)"
  - "Shielded Parking (97)"
  - "Small Parking Lots (103)"
  - "Shopping Street (32)"
  - "Pools and Streams (64)"
  - "Public Outdoor Room (69)"
  - "Grave Sites (70)"
  - "Local Sports (72)"
  - "Adventure Playground (73)"
---

# Neighborhood Boundary (15)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The strength of the boundary is essential to a neighborhood. If the boundary is too weak the neighborhood will not be able to maintain its own identifiable character.

### Solution
>Encourage the formation of a boundary around each neighborhood, to separate it from the next door neighborhoods. Form this boundary by closing down streets and limiting access to the neighborhood—cut the normal number of streets at least in half. Place gateways at those points where the restricted access paths cross the boundary; and make the boundary zone wide enough to contain meeting places for the common functions shares by several neighborhoods.

### Related Patterns
... the physical boundary needed to protect subcultures from one another, and to allow their ways of life to be unique and idiosyncratic, is guaranteed, for a [[Community of 7000 (12)]], by the pattern [[Subculture Boundary (13)]]. But a second smaller kind of boundary is needed to create the smaller [[Identifiable Neighborhood (14)]].

The easiest way of all to form a boundary around a neighborhood is by turning buildings inward, and by cutting off the paths which cross this boundary, except for one or two at special points which become gateways -- [[Main Gateways (53)]]; the public land of the boundary may include a park, collector roads, small parking lots, and work communities -- anything which forms a natural edge -- [[Parallel Roads (23)]], [[Work Community (41)]], [[Quiet Backs (59)]], [[Accessible Green (60)]], [[Shielded Parking (97)]], [[Small Parking Lots (103)]]. As for meeting places in the boundary, they can be any of those neighborhood functions which invite gathering: a park, a shared garage, an outdoor room, a shopping street, a playground -- [[Shopping Street (32)]], [[Pools and Streams (64)]], [[Public Outdoor Room (69)]], [[Grave Sites (70)]], [[Local Sports (72)]], [[Adventure Playground (73)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 86
> #APL/confidence/medium
>
> #APL/Town-Patterns/Communities


<!-- ===== pattern-language/wiki/concepts/patterns/network-of-learning-18.md ===== -->

---
title: "Network of Learning (18)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 18
pattern_name: "Network of Learning"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Network%20of%20Learning%20%2818%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Home Workshop (157)"
  - "Children in the City (57)"
  - "Children's Home (86)"
  - "Shopfront Schools (85)"
  - "Teenage Society (84)"
  - "University as a Marketplace (43)"
  - "Master and Apprentices (83)"
---

# Network of Learning (18)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In a society which emphasizes teaching, children and students—and adults—become passive and unable to think or act for themselves. Creative, active individuals can only grow up in a society which emphasizes learning instead of teaching.

### Solution
>Instead of the lock-step of compulsory schooling in a fixed place, work in piecemeal ways to decentralize the process of learning and enrich it through contact with many places and people all over the city: workshops, teachers at home or walking through the city, professionals teaching younger children, museums, youth groups traveling, scholarly seminars, industrial workshops, old people, and so on.
>Conceive of all these situations as forming the backbone of the learning process; survey all these situations, describe them, and publish them as the city’s "curriculum"; then let students, children, their families and neighborhoods weave together for themselves the situations that comprise their “school” by paying as they go with standard vouchers, raised by community tax.
>Build new educational facilities in a way which extends and enriches this network.

### Related Patterns
... another network, not physical like transportation, but conceptual and equal in importance, is the network of learning: the thousands of interconnected situations that occur all over the city, and which in fact compromise the city's "curriculum": the way of life it teaches to its young.

Above all, encourage the formation of seminars and workshops in people's homes -- [[Home Workshop (157)]]; make sure that each city has a "path" where young children can safely wander on their own -- [[Children in the City (57)]]; build extra public "homes" for children, one to every neighborhood at least -- [[Children's Home (86)]]; create a large number of work-oriented small schools in those parts of town dominated by work and commercial activity -- [[Shopfront Schools (85)]]; encourage teenagers to work out a self-organized learning society of their own -- [[Teenage Society (84)]]; treat the university as scattered adult learning for all the adults in the region -- [[University as a Marketplace (43)]]; and use the real work of professionals and tradesmen as the basic nodes in the network -- [[Master and Apprentices (83)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 99
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/network-of-paths-and-cars-52.md ===== -->

---
title: "Network of Paths and Cars (52)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 52
pattern_name: "Network of Paths and Cars"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Network%20of%20Paths%20and%20Cars%20%2852%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Parallel Roads (23)"
  - "Looped Local Roads (49)"
  - "Green Streets (51)"
  - "Activity Nodes (30)"
  - "Promenade (31)"
  - "Paths and Goals (120)"
  - "Raised Walk (55)"
  - "Path Shape (121)"
  - "Road Crossing (54)"
---

# Network of Paths and Cars (52)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Cars are dangerous to pedestrians; yet activities occur just where cars and pedestrians meet.

### Solution
>Except where traffic densities are very high or very low, lay out pedestrian paths at right angles to roads, not along them, so that the paths gradually begin to form a second network, distinct from the road system, and orthogonal to it. This can be done quite gradually—even if you put in one path at a time, but always put them in the middle of the "block", so that they run across the roads.

### Related Patterns
... roads may be governed by [[Parallel Roads (23)]], [[Looped Local Roads (49)]], [[Green Streets (51)]]; major paths by [[Activity Nodes (30)]], [[Promenade (31)]], and [[Paths and Goals (120)]]. This pattern governs the interaction between the two.

Where paths have to run along major roads -- as they do occasionally -- build them 18 inches higher than the road, on one side of the road only, and twice the usual width -- [[Raised Walk (55)]]; on [[Green Streets (51)]] the paths can be in the road since there is nothing but grass and paving stones there; but even then, occasional narrow paths at right angles to the green streets are very beautiful. Place the paths in detail according to [[Path Shape (121)]]. Finally, treat the important street crossings and crosswalks, raised to the level of the pedestrian path -- so cars have to slow as they go over them -- [[Road Crossing (54)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 270.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/night-life-33.md ===== -->

---
title: "Night Life (33)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 33
pattern_name: "Night Life"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Night%20Life%20%2833%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Magic of the City (10)"
  - "Community of 7000 (12)"
  - "Promenade (31)"
  - "Activity Nodes (30)"
  - "Local Town Hall (44)"
  - "Carnival (58)"
  - "Dancing in the Street (63)"
  - "Street Cafe (88)"
  - "Beer Hall (90)"
  - "Traveler's Inn (91)"
---

# Night Life (33)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Most of the city’s activities close down at night; those which stay open won’t do much for the night life of the city unless they are together.

### Solution
>Knit together shops, amusements, and services which are open at night, along with hotels, bars, and all-night diners to form centers of night life: well-lit, safe, and lively places that increase the intensity of pedestrian activity at night by drawing all the people who are out at night to the same few spots in the town. Encourage these evening centers to distribute themselves evenly across the town.

### Related Patterns
... every community has some kind of public night life -- [[Magic of the City (10)]], [[Community of 7000 (12)]]. If there is a promenade in the community, the night life is probably along the promenade, at least in part -- [[Promenade (31)]]. This pattern describes the details of the concentration of night time activities.

Treat the physical layout of the night life area exactly like any other [[Activity Nodes (30)]], except that *all* of its establishments are open at night. The evening establishments might include [[Local Town Hall (44)]], [[Carnival (58)]], [[Dancing in the Street (63)]], [[Street Cafe (88)]], [[Beer Hall (90)]], [[Traveler's Inn (91)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 179.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/nine-per-cent-parking-22.md ===== -->

---
title: "Nine Per Cent Parking (22)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 22
pattern_name: "Nine Per Cent Parking"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Nine%20Per%20Cent%20Parking%20%2822%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "Shielded Parking (97)"
  - "Small Parking Lots (103)"
---

# Nine Per Cent Parking (22)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Very simply—when the area devoted to parking is too great, it destroys the land.

### Solution
>Do not allow more than 9 percent of the land in any given area to be used for parking. In order to prevent the “bunching” of parking in huge neglected areas, it is necessary for a town or a community to subdivide its land into “parking zones” no larger than 10 acres each and to apply the same rule in each zone.

### Related Patterns
... the integrity of local transport areas and the tranquility of local communities and neighborhoods depend very much on the amount of parking they provide. The more parking they provide, the less possible it will be to maintain these patterns, because the parking spaces will attract cars, which in turn violate the local transport areas and neighborhoods -- [[Local Transport Areas (11)]], [[Community of 7000 (12)]], [[Identifiable Neighborhood (14)]]. This pattern proposes radical limits on the distribution of parking spaces, to protect communities.

Two later patterns say that parking must take one of two forms: tiny, surface parking lots, or shielded parking structures -- [[Shielded Parking (97)]], [[Small Parking Lots (103)]]. If you accept these patterns the 9 per cent rule will put an effective upper limit of 30 parking spaces per acre, on every part of the environment. Present-day on-street parking, with driveways, which provides space for about 35 cars per acre on the ground is ruled out. And those present-day high density business developments which depend on the car are also ruled out ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 120.
> #APL/confidence/high
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/north-face-162.md ===== -->

---
title: "North Face (162)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 162
pattern_name: "North Face"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/North%20Face%20%28162%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "South Facing Outdoors (105)"
  - "Indoor Sunlight (128)"
  - "Sunny Place (161)"
  - "Car Connection (113)"
  - "Bulk Storage (145)"
  - "Compost (178)"
  - "Closets Between Rooms (198)"
  - "Light on Two Sides of Every Room (159)"
  - "Garden Wall (173)"
---

# North Face (162)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Look at the north sides of the buildings which you know. Almost everywhere you will find that these are the spots which are dead and dank, gloomy and useless. Yet there are hundreds of acres in a town on the north sides of buildings; and it is inevitable that there must always be land in this position, wherever there are buildings.

### Solution
>Make the north face of the building a cascade which slopes down to the ground, so that the sun which normally casts a long shadow to the north strikes the ground immediately beside the building.

### Related Patterns
... even if the building has been correctly placed according to [[South Facing Outdoors (105)]] and there is little outdoor space toward the north, there is usually still some kind of area or volume on the north face of the building. It is necessary to take care of this north-facing place to supplement the work of [[Indoor Sunlight (128)]] and [[Sunny Place (161)]].

Use the triangle inside this north cascade for car, garbage, storage, shed, a studio which requires north light, closets - those parts of the building which can do very well without interior sunlight - [[Car Connection (113)]], [[Bulk Storage (145)]], [[Compost (178)]], [[Closets Between Rooms (198)]]. If it is at all practical, use a white or yellow wall to the north of the building to reflect sunlight into the north-facing rooms - [[Indoor Sunlight (128)]], [[Light on Two Sides of Every Room (159)]], [[Garden Wall (173)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 761.
> #APL/confidence/low
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/number-of-stories-96.md ===== -->

---
title: "Number of Stories (96)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 96
pattern_name: "Number of Stories"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Number%20of%20Stories%20%2896%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Four-Story Limit (21)"
  - "Main Building (99)"
  - "Cascade of Roofs (116)"
  - "Site Repair (104)"
  - "South Facing Outdoors (105)"
  - "Tree Places (171)"
  - "Sheltering Roof (117)"
  - "Roof Garden (118)"
  - "Final Column Distribution (213)"
  - "Structure Follows Social Spaces (205)"
---

# Number of Stories (96)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Within the four-story height limit, just exactly how high should your buildings be?

### Solution
>First, decide how many square feet of built space you need, and divide by the area of the site to get the floor area ratio. Then choose the height of your buildings according to the floor area ratio and the height of the surrounding buildings from the following table. In no case build on more than 50 percent of the land.

### Related Patterns
... assume now, that you know roughly how the parts of the building complex are to be articulated - [[Building Complex (95)]], and how large they are. Assume, also, that you have a site. In order to be sure that your building complex is workable within the limits of the site, you must decide how many stories its different parts will have. The height of each part must be constrained by the [[Four-Story Limit (21)]]. Beyond that, it depends on the area of your site, and the floor area which each part needs.

Once you have the number of stories and the area of each part clear, decide which building or which part of the building will be the [[Main Building (99)]]. Vary the number of floors within the building - [[Cascade of Roofs (116)]]. Place the buildings on the site, with special reverence for the land, and trees, and sun - [[Site Repair (104)]], [[South Facing Outdoors (105)]], [[Tree Places (171)]]. In your calculations, remember that the effective area of the top story will be no more than three quarters of the area of lower floors if it is in the roof, according to [[Sheltering Roof (117)]].

If the density is so high all around, that it is quite impossible to leave 50 per cent of the site open (as might be true in central London or New York), then cover the ground floor completely, but devote at least 50 per cent of the upper floors to open gardens - [[Roof Garden (118)]].

Give each story a different ceiling height - bottom story biggest, top story smallest - and vary the column spacings accordingly - [[Final Column Distribution (213)]]. The same building system applies, whether there are 1, 2, 3 or 4 stories - [[Structure Follows Social Spaces (205)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 473.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/office-connections-82.md ===== -->

---
title: "Office Connections (82)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 82
pattern_name: "Office Connections"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Office%20Connections%20%2882%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Work Community (41)"
  - "Self-Governing Workshops and Offices (80)"
  - "Small Services Without Red Tape (81)"
---

# Office Connections (82)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If two parts of an office are too far apart, people will not move between them as often as they need to; and if they are more than one floor apart, there will be almost no communication between the two.

### Solution
>To establish distances between departments, calculate the number of trips per day made between each two departments; get the “nuisance distance” from the graph above; then make sure that the physical distance between the two departments is less than the nuisance distance. Reckon one flight of stairs as about 100 feet, and two flights of stairs as about 300 feet.

### Related Patterns
... in any work community or any office, there are always various human groups - and it is always important to decide how these groups shall be placed, in space. Which should be near each other, which ones further apart? This pattern gives the answer to this question, and in doing so, helps greatly to construct the inner layout of a [[Work Community (41)]] or of [[Self-Governing Workshops and Offices (80)]] or of [[Small Services Without Red Tape (81)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 408.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/old-age-cottage-155.md ===== -->

---
title: "Old Age Cottage (155)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 155
pattern_name: "Old Age Cottage"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Old%20Age%20Cottage%20%28155%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Old People Everywhere (40)"
  - "The Family (75)"
  - "Rooms to Rent (153)"
  - "Teenager's Cottage (154)"
  - "Private Terrace on the Street (140)"
  - "Front Door Bench (242)"
  - "House for One Person (78)"
  - "Settled Work (156)"
  - "Street Windows (164)"
  - "The Shape of Indoor Space (191)"
  - "Structure Follows Social Spaces (205)"
---

# Old Age Cottage (155)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Old people, especially when they are alone, face a terrible dilemma. On the one hand, there are inescapable forces pushes them toward independence: their children move away; the neighborhood changes; their friends and wives and husbands die. On the other hand, by the very nature of aging, old people become dependent on simple conveniences, simple connections to society about them.

### Solution
>Build small cottages specifically for old people. Build some of them on the land of larger houses, for a grandparent; build other on individual lots, much smaller than ordinary lots. In all cases, place these cottage at ground level, right on the street, where people are walking by, and close to neighborhood services and common land.

### Related Patterns
... we have explained, in [[Old People Everywhere (40)]], that it is essential to have a balanced number of old people in every neighborhood, partly centered around a communal place, but largely strung out among the other houses of the neighborhood. This pattern now defines the nature of the houses for old people in more detail: both those which are a part of clusters and those which are tucked, autonomously, between the larger houses. As we shall see, it seems desirable that every family should have a cottage like this, attached to it - [[The Family (75)]]. Like [[Rooms to Rent (153)]] and [[Teenager's Cottage (154)]], this cottage can be rented out or used for other purposes in time of trouble.

Perhaps the most important part of an old age cottage is the front porch and front door bench outside the door, right on the street - [[Private Terrace on the Street (140)]], [[Front Door Bench (242)]]; for the rest, arrange the cottage pretty much according to the layout of any [[House for One Person (78)]]; make provisions for [[Settled Work (156)]]; and give the cottage a [[Street Windows (164)]]. And for the shape of the cottage start with [[The Shape of Indoor Space (191)]] and [[Structure Follows Social Spaces (205)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 729.
> #APL/confidence/high
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/old-people-everywhere-40.md ===== -->

---
title: "Old People Everywhere (40)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 40
pattern_name: "Old People Everywhere"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Old%20People%20Everywhere%20%2840%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Life Cycle (26)"
  - "Household Mix (35)"
  - "Old Age Cottage (155)"
  - "The Family (75)"
  - "Network of Learning (18)"
  - "Children's Home (86)"
  - "Settled Work (156)"
  - "Vegetable Garden (177)"
---

# Old People Everywhere (40)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Old people need old people, but they also need the young, and young people need contact with the old.

### Solution
>Create dwellings for some 50 old people in every neighborhood. Place these dwellings in three rings…
>
>1. A central core with cooking and nursing provided.
>2. Cottages near the core.
>3. Cottages further out from the core, mixed among the other houses of the neighborhood, but never more than 200 yards from the core.
>
>…in such a way that the 50 houses together form a single coherent swarm, with its own clear center, but interlocked at its periphery with other ordinary houses of the neighborhood.

### Related Patterns
... when neighborhoods are properly formed they give the people there a cross section of ages and stages of development - [[Identifiable Neighborhood (14)]], [[Life Cycle (26)]], [[Household Mix (35)]]; however, the old people are so often forgotten and left alone in modern society, that it is necessary to formulate a special pattern which underlines their needs.

Treat the core like any group house; make sure all the cottages, both those close to and those further away, small - [[Old Age Cottage (155)]], some of them perhaps connected to the larger family houses in the neighborhoods - [[The Family (75)]]; provide every second or third core with proper nursing facilities; somewhere in the orbit of the old age pocket, provide the kind of work which old people can manage best - especially teaching and looking after tiny children - [[Network of Learning (18)]], [[Children's Home (86)]], [[Settled Work (156)]], [[Vegetable Garden (177)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 215.
> #APL/confidence/high
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/open-shelves-200.md ===== -->

---
title: "Open Shelves (200)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 200
pattern_name: "Open Shelves"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Open%20Shelves%20%28200%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Thick Walls (197)"
  - "Farmhouse Kitchen (139)"
  - "Workspace Enclosure (183)"
  - "Waist-High Shelf (201)"
  - "Thickening the Outer Walls (211)"
---

# Open Shelves (200)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Cupboards that are too deep waste valuable space, and it always seems that what you want is behind something else.

### Solution
>Cover the walls with narrow shelves of varying depth but always shallow enough so that things can be placed on them one deep—nothing hiding behind anything else.

### Related Patterns
... within the [[Thick Walls (197)]], especially around the [[Farmhouse Kitchen (139)]] and [[Workspace Enclosure (183)]], but possibly throughout the building, there is a need for shelves. This pattern helps you decide exactly where you want them and how they shall be organized. Mary Louise Rogers first made the pattern explicit for us.

At waist height put in an extra deep shelf for plates, phonograph, TV, boxes, displays, treasures - [[Waist-High Shelf (201)]]. Mark the open shelves along with all the other deep spaces in the walls - [[Thickening the Outer Walls (211)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 919.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/open-stairs-158.md ===== -->

---
title: "Open Stairs (158)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 158
pattern_name: "Open Stairs"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Open%20Stairs%20%28158%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Rooms to Rent (153)"
  - "Teenager's Cottage (154)"
  - "Settled Work (156)"
  - "Home Workshop (157)"
  - "Self-Governing Workshops and Offices (80)"
  - "Small Services Without Red Tape (81)"
  - "Small Work Groups (148)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Pedestrian Street (100)"
  - "Family of Entrances (102)"
  - "Roof Garden (118)"
  - "Sunny Place (161)"
  - "Stair Seats (125)"
  - "Staircase Volume (195)"
---

# Open Stairs (158)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Internal staircases reduce the connection between upper stories and the life of the street to such an extend that they can do enormous social damage.

### Solution
>Do away, as far as possible, with internal staircases, in institutions. Connect all autonomous households, public services, and workgroups on the upper floors of buildings directly to the ground. Do this by creating open stairs which are approaches directly from the street. Keep the stair roofed or unroofed, according to climate, but at all events leave the stair open at ground level, without a door, so that the stair is functionally a continuation of the street. And build no upstairs corridors. Instead, make open landings or an open arcade where upstairs units share a single stair.

### Related Patterns
... most of the last patterns - [[Rooms to Rent (153)]], [[Teenager's Cottage (154)]], [[Settled Work (156)]], [[Home Workshop (157)]] - can be upstairs, provided that they have direct connections to the street. Far more generally, it is true that many of the households, public services, and workgroups given by earlier patterns can be successful when they lie upstairs, only if they are given direct connections to the street. For instance, in a work community [[Self-Governing Workshops and Offices (80)]], [[Small Services Without Red Tape (81)]], [[Small Work Groups (148)]] all require direct access to the public street when they are on the upper stories of a building. And in the individual households - [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]] also need direct connections to the street, so people do not need to go through lower floors to get to them. This pattern describes the open stairs which may be used to form these many individual connections to the street. They play a major role in helping to create [[Pedestrian Street (100)]].

Where the stair comes down to the ground, make an entrance which helps to repair the family of entrances that exist already on the street - [[Family of Entrances (102)]]; make the landings and the top of the stair, where it reaches the roof, into gardens where things can grow and where people can sit in the sun - [[Roof Garden (118)]], [[Sunny Place (161)]]. Remember [[Stair Seats (125)]], and build the stair according to [[Staircase Volume (195)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 740.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/opening-to-the-street-165.md ===== -->

---
title: "Opening to the Street (165)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 165
pattern_name: "Opening to the Street"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Opening%20to%20the%20Street%20%28165%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Street Windows (164)"
  - "University as a Marketplace (43)"
  - "Local Town Hall (44)"
  - "Necklace of Community Projects (45)"
  - "Market of Many Shops (46)"
  - "Health Center (47)"
  - "Street Cafe (88)"
  - "Building Thoroughfare (101)"
  - "Sitting Wall (243)"
  - "Path Shape (121)"
  - "Outdoor Room (163)"
---

# Opening to the Street (165)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The sight of action is an incentive for action. When people can see into spaces from the street their world is enlarged and made richer, there is more understanding; and there is possibility for communication, learning.

### Solution
>In any public space which depends for its success on its exposure to the street, open it up, with a fully opening wall which can be thrown wide open, and if it is possible, include some part of the activity on the far side of the pedestrian path, so that it actually straddles the path, and people walk through it as they walk along the path.
>There are dozens of ways to build such an opening. For example, a wall can be made very cheaply with a simply plywood hanging shutter sliding on an overhead rail, which can be removed to open up completely, and locked in place at night.

### Related Patterns
... many places in a town depend for their success on complete exposure to the people passing by - far more exposure than a [[Street Windows (164)]] can provide. [[University as a Marketplace (43)]], [[Local Town Hall (44)]], [[Necklace of Community Projects (45)]], [[Market of Many Shops (46)]], [[Health Center (47)]], [[Street Cafe (88)]], [[Building Thoroughfare (101)]] are all examples. This pattern defines the form of the exposure.

Give the opening a boundary, when it is entirely open, with a low solid wall which people can sit on - [[Sitting Wall (243)]] ; and make an outdoor room out of the part of the path which runs past it - [[Path Shape (121)]], [[Outdoor Room (163)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 773.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/ornament-249.md ===== -->

---
title: "Ornament (249)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 249
pattern_name: "Ornament"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Ornament%20%28249%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Main Entrance (110)"
  - "Building Edge (160)"
  - "Connection to the Earth (168)"
  - "Garden Wall (173)"
  - "Window Place (180)"
  - "Corner Doors (196)"
  - "Frames as Thickened Edges (225)"
  - "Column Place (226)"
  - "Column Connections (227)"
  - "Roof Caps (232)"
  - "Soft Inside Walls (235)"
  - "Sitting Wall (243)"
  - "Wall Membranes (218)"
  - "Lapped Outside Walls (234)"
  - "Soft Tile and Brick (248)"
  - "Warm Colors (250)"
  - "Half-Inch Trim (240)"
  - "Things From Your Life (253)"
---

# Ornament (249)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>All people have the instinct to decorate their surroundings.

### Solution
>Search around the building, and find those edges and transitions which need emphasis or extra binding energy. Corners, places where materials meet, door frames, windows, main entrances, the place where one wall meets another, the garden gate, a fence—all these are natural places which call out for ornament.
>Now find simple themes and apply the elements of the theme over and over again to the edges and boundaries which you decide to mark. Make the ornaments work as seams along the boundaries and edges so that they knit the two sides together and make them one.

### Related Patterns
... once buildings and gardens are finished; walls, columns, windows, doors, and surfaces are in place; boundaries and edges and transitions are defined - [[Main Entrance (110)]], [[Building Edge (160)]], [[Connection to the Earth (168)]], [[Garden Wall (173)]], [[Window Place (180)]], [[Corner Doors (196)]], [[Frames as Thickened Edges (225)]], [[Column Place (226)]], [[Column Connections (227)]], [[Roof Caps (232)]], [[Soft Inside Walls (235)]], [[Sitting Wall (243)]], and so on - it is time to put in the finishing touches, to fill the gaps, to mark the boundaries, by making ornament.

Whenever it is possible, make the ornament while you are building - not after - from the planks and boards and tiles and surfaces of which the building is actually made - [[Wall Membranes (218)]], [[Frames as Thickened Edges (225)]], [[Lapped Outside Walls (234)]], [[Soft Inside Walls (235)]], [[Soft Tile and Brick (248)]]. Use color for ornament - [[Warm Colors (250)]]; use the smaller trims which cover joints as ornament - [[Half-Inch Trim (240)]]; and embellish the rooms themselves with parts of your life which become the natural ornaments around you - [[Things From Your Life (253)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1146.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Ornamentation


<!-- ===== pattern-language/wiki/concepts/patterns/outdoor-room-163.md ===== -->

---
title: "Outdoor Room (163)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 163
pattern_name: "Outdoor Room"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Outdoor%20Room%20%28163%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "Farmhouse Kitchen (139)"
  - "Sequence of Sitting Spaces (142)"
  - "Public Outdoor Room (69)"
  - "Half-Hidden Garden (111)"
  - "Private Terrace on the Street (140)"
  - "Sunny Place (161)"
  - "Column Place (226)"
  - "Garden Wall (173)"
  - "Sitting Wall (243)"
  - "Trellised Walk (174)"
  - "Canvas Roofs (244)"
  - "Connection to the Earth (168)"
  - "The Shape of Indoor Space (191)"
  - "Structure Follows Social Spaces (205)"
---

# Outdoor Room (163)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A garden is the place for lying in the grass, swinging, croquet, growing flowers, throwing a ball for the dog. But there is another way of being outdoors: and its needs are not met by the garden at all.

### Solution
>Build a place outdoors which has so much enclosure round it, that it takes on the feeling of a room, even though it is open to the sky. To do this, define it at the corners with columns, perhaps roof it partially with a trellis or a sliding canvas roof, and create “walls” around it, with fences, sitting walls, screens, hedges, or the exterior walls of the building itself.

### Related Patterns
... every building has rooms where people stay and live and talk together - [[Common Areas at the Heart (129)]], [[Farmhouse Kitchen (139)]], [[Sequence of Sitting Spaces (142)]]. Whenever possible, these rooms need to be embellished by a further "room" outdoors. This kind of outdoor room also helps to form a part of any [[Public Outdoor Room (69)]], [[Half-Hidden Garden (111)]], [[Private Terrace on the Street (140)]], or [[Sunny Place (161)]].

This outdoor room is formed, most often, by free standing columns - [[Column Place (226)]], walls - [[Garden Wall (173)]], low [[Sitting Wall (243)]], perhaps a trellis overhead - [[Trellised Walk (174)]], or a translucent canvas awning - [[Canvas Roofs (244)]], and a ground surface which helps to provide [[Connection to the Earth (168)]]. Like any other room, for its construction start with [[The Shape of Indoor Space (191)]] and [[Structure Follows Social Spaces (205)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 764.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/parallel-roads-23.md ===== -->

---
title: "Parallel Roads (23)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 23
pattern_name: "Parallel Roads"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Parallel%20Roads%20%2823%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Ring Roads (17)"
  - "Local Transport Areas (11)"
  - "Subculture Boundary (13)"
  - "Neighborhood Boundary (15)"
  - "Looped Local Roads (49)"
  - "Green Streets (51)"
  - "T Junctions (50)"
  - "Network of Paths and Cars (52)"
  - "Raised Walk (55)"
  - "Road Crossing (54)"
---

# Parallel Roads (23)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The net-like pattern of streets is obsolete. Congestion is choking cities. Cars can average 60 miles per hour on freeways, but trips across town have an average speed of only 10 to 15 miles per hour.

### Solution
>Within a local transport area build no intersecting major roads at all; instead, build a system of parallel and alternating one-way roads to carry traffic to the [[Ring Roads (17)]]. In existing towns, create this structure piecemeal, by gradually making major streets one-way and closing cross streets. Keep parallel roads at least 100 yards apart (to make room for neighborhoods between them) and no more than 300 or 400 yards apart.

### Related Patterns
... in earlier patterns, we have proposed that cities should be subdivided into local transport areas, whose roads allow cars to move in and out from the ring roads, but strongly discourage internal movement across the area -- [[Local Transport Areas (11)]], [[Ring Roads (17)]] -- and that these transport areas themselves be further subdivided into communities and neighborhoods, with the provision that all major roads are in the boundaries between communities and neighborhoods -- [[Subculture Boundary (13)]], [[Neighborhood Boundary (15)]]. Now, what should the arrangement of these roads be like, to help the flow required by [[Local Transport Areas (11)]], and to maintain the boundaries?

The parallel roads are the only *through* roads in a [[Local Transport Areas (11)]]. For access from the parallel roads to public buildings, house clusters, and individual houses use safe, slow, narrow roads which are not through roads -- [[Looped Local Roads (49)]], [[Green Streets (51)]] -- and make their intersections with parallel roads a "T" -- [[T Junctions (50)]]. Keep the pedestrian path system at right angles to the parallel roads, and raised above them where the two must run parallel -- [[Network of Paths and Cars (52)]], [[Raised Walk (55)]]. Provide a [[Road Crossing (54)]] where paths and roads cross.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 126.
> #APL/confidence/low
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/path-shape-121.md ===== -->

---
title: "Path Shape (121)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 121
pattern_name: "Path Shape"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Path%20Shape%20%28121%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Promenade (31)"
  - "Shopping Street (32)"
  - "Network of Paths and Cars (52)"
  - "Raised Walk (55)"
  - "Pedestrian Street (100)"
  - "Paths and Goals (120)"
  - "Building Fronts (122)"
  - "Pedestrian Density (123)"
  - "Arcades (119)"
  - "Activity Pockets (124)"
  - "Stair Seats (125)"
  - "Public Outdoor Room (69)"
  - "Street Windows (164)"
---

# Path Shape (121)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Streets should be for staying in, and not just for moving through, the way they are today.

### Solution
>Make a bulge in the middle of a public path, and make the ends narrower, so that the path forms an enclosure which is a place to stay, not just a place to pass through.

### Related Patterns
... paths of various kinds have been defined by larger patterns - [[Promenade (31)]], [[Shopping Street (32)]], [[Network of Paths and Cars (52)]], [[Raised Walk (55)]], [[Pedestrian Street (100)]], and [[Paths and Goals (120)]]. This pattern defines their shape: and it can also help to generate these larger patterns piecemeal, through the very process of shaping parts of the path.

Above all, to create the shape of the path, move the building fronts into the right positions, and on no account allow a set-back between the building and the path - [[Building Fronts (122)]]; decide on the appropriate area for the "bulge" by using the arithmetic of [[Pedestrian Density (123)]]; then form the details of the bulge with [[Arcades (119)]], [[Activity Pockets (124)]] and [[Stair Seats (125)]]; perhaps even with a [[Public Outdoor Room (69)]] ; and give as much life as you can to the path all along its length with windows - [[Street Windows (164)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 589.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/paths-and-goals-120.md ===== -->

---
title: "Paths and Goals (120)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 120
pattern_name: "Paths and Goals"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Paths%20and%20Goals%20%28120%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Wings of Light (107)"
  - "Positive Outdoor Space (106)"
  - "Arcades (119)"
  - "Degrees of Publicness (36)"
  - "Network of Paths and Cars (52)"
  - "Circulation Realms (98)"
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Tree Places (171)"
  - "Seat Spots (241)"
  - "Raised Flowers (245)"
  - "Something Roughly in the Middle (126)"
  - "Path Shape (121)"
  - "Paving With Cracks Between the Stones (247)"
---

# Paths and Goals (120)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The layout of paths will seem right and comfortable only when it is compatible with the process of walking. And the process of walking is far more subtle than one might imagine.

### Solution
>To lay out paths, first place goals at natural points of interest. Then connect the goals to one another to form the paths. The paths may be straight, or gently curving between goals; their paving should swell around the goal. The goals should never be more than a few hundred feet apart.

### Related Patterns
... once buildings and arcades and open spaces have been roughly fixed by [[Building Complex (95)]], [[Wings of Light (107)]], [[Positive Outdoor Space (106)]], [[Arcades (119)]] - it is time to pay attention to the paths which run between the buildings. This pattern shapes these paths and also helps to give more detailed form to [[Degrees of Publicness (36)]], [[Network of Paths and Cars (52)]], and [[Circulation Realms (98)]].

All the ordinary things in the outdoors - trees, fountains, entrances, gateways, seats, statues, a swing, an outdoor room - can be the goals. See [[Family of Entrances (102)]], [[Main Entrance (110)]], [[Tree Places (171)]], [[Seat Spots (241)]], [[Raised Flowers (245)]]; build the "goals" according to the rules of [[Something Roughly in the Middle (126)]]; and shape the paths according to [[Path Shape (121)]]. To pave the paths use [[Paving With Cracks Between the Stones (247)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 585.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/paving-with-cracks-between-the-stones-247.md ===== -->

---
title: "Paving With Cracks Between the Stones (247)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 247
pattern_name: "Paving With Cracks Between the Stones"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Paving%20With%20Cracks%20Between%20the%20Stones%20%28247%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Green Streets (51)"
  - "Path Shape (121)"
  - "Private Terrace on the Street (140)"
  - "Outdoor Room (163)"
  - "Connection to the Earth (168)"
  - "Terraced Slope (169)"
  - "Soft Tile and Brick (248)"
---

# Paving With Cracks Between the Stones (247)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Asphalt and concrete surfaces outdoors are easy to wash down, but they do nothing for us, nothing for the paths, and nothing for the rainwater and plants.

### Solution
>On paths and terraces, lay paving stones with a 1 inch crack between the stones, so that grass and mosses and small flowers can grow between the stones. Lay the stones directly into the earth, not into mortar, and, of course, use no cement or mortar in between the stones.

### Related Patterns
... many patterns call for paths and terraces and places where the outdoor areas around a building feel connected to the earth - [[Green Streets (51)]], [[Path Shape (121)]], [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]], [[Connection to the Earth (168)]], [[Terraced Slope (169)]]. This pattern provides a way of building the ground surface that makes these larger patterns come to life.

Use paving with cracks, to help make paths and terraces which change and show the passage of time and so help people feel the earth beneath their feet - [[Connection to the Earth (168)]]; the stones themselves are best if they are simple soft baked tiles - [[Soft Tile and Brick (248)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1138.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/pedestrian-density-123.md ===== -->

---
title: "Pedestrian Density (123)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 123
pattern_name: "Pedestrian Density"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Pedestrian%20Density%20%28123%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Promenade (31)"
  - "Small Public Squares (61)"
  - "Pedestrian Street (100)"
  - "Building Thoroughfare (101)"
  - "Path Shape (121)"
  - "Street Cafe (88)"
  - "Activity Pockets (124)"
  - "Stair Seats (125)"
  - "Private Terrace on the Street (140)"
  - "Building Edge (160)"
  - "Street Windows (164)"
  - "Opening to the Street (165)"
  - "Gallery Surround (166)"
---

# Pedestrian Density (123)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Many of our modern public squares, though intended as lively plazas, are in fact deserted and dead.

### Solution
>For public squares, courts, pedestrian streets, any place where crowds are drawn together, estimate the mean number of people in the place at any given moment (P), and make the area of the place between 150P and 300P square feet.

### Related Patterns
... in various places there are pedestrian areas, paved so that people will congregate there or walk up and down - [[Promenade (31)]], [[Small Public Squares (61)]], [[Pedestrian Street (100)]], [[Building Thoroughfare (101)]], [[Path Shape (121)]]. It is essential to limit the sizes of these places very strictly, especially the size of areas which are paved, so that they stay alive.

Embellish the density and feeling of life with areas at the edge which are especially crowded - [[Street Cafe (88)]], [[Activity Pockets (124)]], [[Stair Seats (125)]], [[Private Terrace on the Street (140)]], [[Building Edge (160)]], [[Street Windows (164)]], [[Opening to the Street (165)]], [[Gallery Surround (166)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 596.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/pedestrian-street-100.md ===== -->

---
title: "Pedestrian Street (100)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 100
pattern_name: "Pedestrian Street"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Pedestrian%20Street%20%28100%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Promenade (31)"
  - "Shopping Street (32)"
  - "Network of Paths and Cars (52)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "University as a Marketplace (43)"
  - "Market of Many Shops (46)"
  - "Building Complex (95)"
  - "Circulation Realms (98)"
  - "Raised Walk (55)"
  - "Pedestrian Density (123)"
  - "Family of Entrances (102)"
  - "Open Stairs (158)"
  - "Private Terrace on the Street (140)"
  - "Street Windows (164)"
  - "Opening to the Street (165)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Arcades (119)"
  - "Path Shape (121)"
---

# Pedestrian Street (100)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The simple social intercourse created when people rub shoulders in public is one of the most essential kinds of social “glue” in society.

### Solution
>Arrange buildings so that they form pedestrian streets with many entrances and open stairs directly from the upper stories to the street, so that even movement between rooms is outdoors, not just movement between buildings.

### Related Patterns
... the earlier patterns - [[Promenade (31)]], [[Shopping Street (32)]] and [[Network of Paths and Cars (52)]], all call for dense pedestrian streets; [[Row Houses (38)]], [[Housing Hill (39)]], [[University as a Marketplace (43)]], [[Market of Many Shops (46)]], all do the same; and within the [[Building Complex (95)]], [[Circulation Realms (98)]] calls for the same. As you build a pedestrian street, make sure you place it so that it helps to generate a [[Network of Paths and Cars (52)]], [[Raised Walk (55)]], and [[Circulation Realms (98)]] in the town around it.

 The street absolutely will not work unless its total area is small enough to be well filled by the pedestrians in it - [[Pedestrian Density (123)]]. Make frequent entrances and open stairs along the street, instead of building indoor corridors, to bring the people out; and give these entrances a family resemblance so one sees them as a system - [[Family of Entrances (102)]], [[Open Stairs (158)]]; give people indoor and outdoor spaces which look on the street - [[Private Terrace on the Street (140)]], [[Street Windows (164)]], [[Opening to the Street (165)]], [[Gallery Surround (166)]], [[Six-Foot Balcony (167)]]; and shape the street to make a space of it - [[Arcades (119)]], [[Path Shape (121)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 488.
> #APL/confidence/high
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/perimeter-beams-217.md ===== -->

---
title: "Perimeter Beams (217)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 217
pattern_name: "Perimeter Beams"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Perimeter%20Beams%20%28217%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Box Columns (216)"
  - "Floor-Ceiling Vaults (219)"
  - "Floor and Ceiling Layout (210)"
  - "Column Connections (227)"
---

# Perimeter Beams (217)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If you conceive and build a room by first placing columns at the corners, and then gradually weaving the walls and ceiling round them, the room needs a perimeter beam around its upper edge.

### Solution
>Build a continuous perimeter beam around the room, strong enough to resist the horizontal thrust of the vault above, to spread the loads from upper stories onto columns, to tie the columns together, and to function as a lintel over openings in the wall. Make this beam continuous with columns, walls, and floor above, and columns and walls below.

### Related Patterns
 ... this pattern helps to complete [[Box Columns (216)]], by tying the tops of the columns together once they are in position. It also helps to form the bearing surface for the edge of the [[Floor-Ceiling Vaults (219)]]. For this reason, the positions of the perimeter beams must correspond exactly to the edges of the vaults laid out in [[Floor and Ceiling Layout (210)]].

Remember to place reinforcing in such a way that the perimeter beam acts in a horizontal direction as well as vertical. When it forms the base for a [[Floor-Ceiling Vaults (219)]] it must be able to act as a ring beam to resist all those residual horizontal outward thrusts not contained by the vault. Strengthen the connection between the columns and the perimeter beam with diagonal braces where the columns are free standing [[Column Connections (227)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1018.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/pools-and-streams-64.md ===== -->

---
title: "Pools and Streams (64)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 64
pattern_name: "Pools and Streams"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Pools%20and%20Streams%20%2864%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sacred Sites (24)"
  - "Access to Water (25)"
  - "Neighborhood Boundary (15)"
  - "Quiet Backs (59)"
  - "Pedestrian Street (100)"
  - "Still Water (71)"
  - "Promenade (31)"
  - "Holy Ground (66)"
  - "Arcades (119)"
---

# Pools and Streams (64)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We came from the water; our bodies are largely water; and water plays a fundamental role in our psychology. We need constant access to water, all around us; and we cannot have it without reverence for water in all its forms. But everywhere in cities water is out of reach.

### Solution
>Preserve natural pools and streams and allow them to run through the city; make paths for people to walk along them and footbridges to cross them. Let the streams form natural barriers in the city, with traffic crossing them only infrequently on bridges.
>Whenever possible, collect rainwater in open gutters and allow it to flow above ground, along pedestrian paths and in front of houses. In places without natural running water, create fountains in the streets.

### Related Patterns
... the land, in its natural state, is hardly ever flat, and was, in its most primitive condition, overrun with rills and streams which carried off the rainwater. There is no reason to destroy this natural feature of the land in a town - [[Sacred Sites (24)]], [[Access to Water (25)]] - in fact, it is essential that it be preserved, or recreated. And in doing so it will be possible to deepen several larger patterns -boundaries between neighborhoods can easily be formed by streams - [[Neighborhood Boundary (15)]], quiet backs can be made more tranquil - [[Quiet Backs (59)]], pedestrian streets can be made more human and more natural - [[Pedestrian Street (100)]].

If at all possible, make all the pools and swimming holes part of the running water - not separate since this is the only way that pools are able to keep alive and clean without the paraphernalia of pumps and chlorine - [[Still Water (71)]]. Sometimes, here and there, give the place immediately around the water the atmosphere of contemplation; perhaps with arcades, perhaps some special common land, perhaps one end of a promenade - [[Promenade (31)]], [[Holy Ground (66)]], [[Arcades (119)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 322.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/pools-of-light-252.md ===== -->

---
title: "Pools of Light (252)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 252
pattern_name: "Pools of Light"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Pools%20of%20Light%20%28252%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Alcoves (179)"
  - "Workspace Enclosure (183)"
  - "Common Areas at the Heart (129)"
  - "Entrance Room (130)"
  - "Flexible Office Space (146)"
  - "Eating Atmosphere (182)"
  - "Sitting Circle (185)"
  - "Different Chairs (251)"
  - "Warm Colors (250)"
---

# Pools of Light (252)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Uniform illumination—the sweetheart of the lighting engineers—serves no useful purpose whatsoever. In fact, it destroys the social nature of space, and makes people feel disoriented and unbounded.

### Solution
>Place the lights low, and apart, to form individual pools of light which encompass chairs and tables like bubbles to reinforce the social character of the spaces which they form. Remember that you can’t have pools of light without the darker places in between.

### Related Patterns
... this pattern helps to finish small social spaces like [[Alcoves (179)]] and [[Workspace Enclosure (183)]], larger places like [[Common Areas at the Heart (129)]], [[Entrance Room (130)]], and [[Flexible Office Space (146)]], and the furnishing of rooms like [[Eating Atmosphere (182)]], [[Sitting Circle (185)]], and [[Different Chairs (251)]]. It even helps to generate [[Warm Colors (250)]].

Color the lampshades and the hangings near the lights to make the light which bounces off them warm in color - [[Warm Colors (250)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1160.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Ornamentation


<!-- ===== pattern-language/wiki/concepts/patterns/positive-outdoor-space-106.md ===== -->

---
title: "Positive Outdoor Space (106)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 106
pattern_name: "Positive Outdoor Space"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Positive%20Outdoor%20Space%20%28106%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "South Facing Outdoors (105)"
  - "Wings of Light (107)"
  - "Tree Places (171)"
  - "Garden Wall (173)"
  - "Trellised Walk (174)"
  - "Hierarchy of Open Space (114)"
  - "Building Fronts (122)"
  - "Building Edge (160)"
  - "Courtyards Which Live (115)"
  - "Roof Garden (118)"
  - "Path Shape (121)"
  - "Outdoor Room (163)"
  - "Garden Growing Wild (172)"
---

# Positive Outdoor Space (106)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Outdoor spaces which are merely “left over” between buildings will, in general, not be used.

### Solution
>Make all outdoor spaces which surround and lie between your buildings positive. Give each one some degree of enclosure; surround each space with wings of buildings, trees, hedges, fences, arcades, and trellised walks, until it becomes an entity with a positive quality and does not spill out indefinitely around corners.

### Related Patterns
... in making [[South Facing Outdoors (105)]] you must both choose the place to build, and also choose the place for the outdoors. You cannot shape the one without the other. This pattern gives you the geometric character of the outdoors; the next one [[Wings of Light (107)]] - gives you the complementary shape of the indoors.

Place [[Wings of Light (107)]] to form the spaces. Use open trellised walks, walls, and trees to close off spaces which are too exposed - [[Tree Places (171)]], [[Garden Wall (173)]] [[Trellised Walk (174)]]; but make sure that every space is always open to some larger space, so that it is not too enclosed - [[Hierarchy of Open Space (114)]]. Use [[Building Fronts (122)]] to help create the shape of space. Complete the positive character of the outdoors by making places all around the edge of buildings, and so make the outdoors as much a focus of attention as the buildings - [[Building Edge (160)]]. Apply this pattern to [[Courtyards Which Live (115)]], [[Roof Garden (118)]], [[Path Shape (121)]], [[Outdoor Room (163)]], [[Garden Growing Wild (172)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 517.
> #APL/confidence/high
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/private-terrace-on-the-street-140.md ===== -->

---
title: "Private Terrace on the Street (140)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 140
pattern_name: "Private Terrace on the Street"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Private%20Terrace%20on%20the%20Street%20%28140%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "Sequence of Sitting Spaces (142)"
  - "Half-Hidden Garden (111)"
  - "Green Streets (51)"
  - "Pedestrian Street (100)"
  - "Terraced Slope (169)"
  - "Sitting Wall (243)"
  - "Garden Wall (173)"
  - "Half-Open Wall (193)"
  - "Outdoor Room (163)"
---

# Private Terrace on the Street (140)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The relationship of a house to a street is often confused: either the house opens entirely to the street and there is no privacy; or the house turns its back on the street, and communion with street life is lost.

### Solution
>Let the common rooms open onto a wide terrace of a porch which looks into the street. Raise the terrace slightly above street level and protect it with a low wall, which you can see over if you sit near it, but which prevents people on the street from looking into the common rooms.

### Related Patterns
... among the common areas and sitting spaces - [[Common Areas at the Heart (129)]], [[Sequence of Sitting Spaces (142)]] - there is a need for one, at least, which puts the people in the house in touch with the world of the street outside the house. This pattern helps to create the [[Half-Hidden Garden (111)]] and gives life to the street - [[Green Streets (51)]] or [[Pedestrian Street (100)]].

If possible, place the terrace in a position which is also congruent with natural contours - [[Terraced Slope (169)]]. The wall, if low enough, can be a [[Sitting Wall (243)]]; in other cases, where you want more privacy, you can build a full garden wall, with openings in it, almost like windows, which make the connection with the street - [[Garden Wall (173)]], [[Half-Open Wall (193)]]. In any case, surround the terrace with enough things to give it at least the partial feeling of a room - [[Outdoor Room (163)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 664.
> #APL/confidence/high
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/promenade-31.md ===== -->

---
title: "Promenade (31)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 31
pattern_name: "Promenade"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Promenade%20%2831%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Community of 7000 (12)"
  - "Activity Nodes (30)"
  - "Pedestrian Density (123)"
  - "Night Life (33)"
  - "Shopping Street (32)"
  - "Carnival (58)"
  - "Dancing in the Street (63)"
  - "Pedestrian Street (100)"
  - "Path Shape (121)"
---

# Promenade (31)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Each subculture needs a center for its public life: a place where you can go to see people, and to be seen.

### Solution
>Encourage the gradual formation of a promenade at the heart of every community, linking the main activity nodes, and placed centrally, so that each point in the community is within 10 minutes’ walk of it. Put main points of attraction at the two ends, to keep a constant movement up and down.

### Related Patterns
... assume now that there is an urban area, subdivided into subcultures and communities each with its boundaries. Each subculture in the [[Mosaic of Subcultures (8)]], and each [[Community of 7000 (12)]] has a promenade as its backbone. And each promenade helps to form [[Activity Nodes (30)]] along its length, by generating the flow of people which the activity nodes need in order to survive.

No matter how large the promenade is, there must be enough people coming to it to make it dense with action, and this can be precisely calculated by the formula of [[Pedestrian Density (123)]]. The promenade is mainly marked by concentrations of activity along its length -- [[Activity Nodes (30)]]; naturally, some of these will be open at night -- [[Night Life (33)]]; and somewhere on the promenade there will be a concentration of shops -- [[Shopping Street (32)]]. It might also be appropriate to include [[Carnival (58)]] and [[Dancing in the Street (63)]] in very large promenades. The detailed physical character of the promenade is given by [[Pedestrian Street (100)]] and [[Path Shape (121)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 168.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/public-outdoor-room-69.md ===== -->

---
title: "Public Outdoor Room (69)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 69
pattern_name: "Public Outdoor Room"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Public%20Outdoor%20Room%20%2869%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Main Gateways (53)"
  - "Accessible Green (60)"
  - "Small Public Squares (61)"
  - "Common Land (67)"
  - "Pedestrian Street (100)"
  - "Paths and Goals (120)"
  - "Common Areas at the Heart (129)"
  - "Path Shape (121)"
  - "Activity Pockets (124)"
  - "Building Edge (160)"
  - "Outdoor Room (163)"
  - "Courtyards Which Live (115)"
  - "Arcades (119)"
  - "Canvas Roofs (244)"
  - "Stair Seats (125)"
  - "Seat Spots (241)"
---

# Public Outdoor Room (69)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There are very few spots along the streets of modern towns and neighborhoods where people can hang out, comfortable, for hours at a time.

### Solution
>In every neighborhood and work community, make a piece of the common land into an outdoor room—a partly enclosed place, with some roof, columns, without walls, perhaps with a trellis; place it beside an important path and within view of many homes and workshops.

### Related Patterns
... the common land in [[Main Gateways (53)]], [[Accessible Green (60)]], [[Small Public Squares (61)]], [[Common Land (67)]], [[Pedestrian Street (100)]], [[Paths and Goals (120)]] needs at least some place where hanging out and being "out" in public become possible. For this purpose it is necessary to distinguish one part of the common land and to define it with a little more elaboration. Also, if none of the larger patterns exist yet, this pattern can act as a nucleus, and help them to crystallize around it.

Place the outdoor room where several paths are tangent to it, like any other common area - [[Common Areas at the Heart (129)]]; in the bulge of a path - [[Path Shape (121)]]; or around a square - [[Activity Pockets (124)]]; use surrounding [[Building Edge (160)]] to define part of it; build it like any smaller outdoor room, with columns, and half-trellised roofs - [[Outdoor Room (163)]]; perhaps put an open courtyard next to it - [[Courtyards Which Live (115)]], an [[Arcades (119)|Arcade (119)]] around the edge, or other simple cover - [[Canvas Roofs (244)]], and seats for casual sitting - [[Stair Seats (125)]], [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 348.
> #APL/confidence/high
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/quiet-backs-59.md ===== -->

---
title: "Quiet Backs (59)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 59
pattern_name: "Quiet Backs"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Quiet%20Backs%20%2859%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Scattered Work (9)"
  - "Work Community (41)"
  - "Pools and Streams (64)"
  - "Still Water (71)"
  - "Tree Places (171)"
  - "Accessible Green (60)"
  - "Garden Wall (173)"
---

# Quiet Backs (59)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Anyone who has to work in noise, in offices with people all around, needs to be able to pause and refresh themselves with quiet in a more natural situation.

### Solution
>Give the buildings in the busy parts of town a quiet “back” behind them and away from the noise. Build a walk along this quiet back, far enough from the building so that it gets full sunlight, but protected from noise by walls and distance and buildings. Make certain that the path is not a natural shortcut for busy foot traffic, and connect it up with other walks, to form a long ribbon of quiet alleyways which converge on the local pools and streams and the local greens.

### Related Patterns
... the work places are given their general position by [[Scattered Work (9)]] and their detailed organization and distribution by [[Work Community (41)]]. It is essential though, that they be supported by some kind of quiet, which is complementary to the work. This pattern, and the next few patterns, gives the structure of that quiet.

If possible, place the backs where there is water - [[Pools and Streams (64)]], [[Still Water (71)]], and where there are still great trees unharmed by traffic - [[Tree Places (171)]] ; connect them to [[Accessible Green (60)]]; and protect them from noise with walls or buildings - [[Garden Wall (173)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 301.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/radiant-heat-230.md ===== -->

---
title: "Radiant Heat (230)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 230
pattern_name: "Radiant Heat"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Radiant%20Heat%20%28230%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wall Membranes (218)"
  - "Floor-Ceiling Vaults (219)"
  - "Duct Space (229)"
  - "Built-in Seats (202)"
---

# Radiant Heat (230)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>This pattern is a biologically precise formulation of the intuition that sunlight and a hot blazing fire are the best kinds of heat.

### Solution
>Choose a way of heating your space—especially those rooms where people are going to gather when it is cold—that is essentially a radiative process, where the heat comes more from radiation than convection.

### Related Patterns
... to complete [[Wall Membranes (218)]], [[Floor-Ceiling Vaults (219)]] and [[Duct Space (229)]], use a biologically sensible heating system.

If you have followed earlier patterns, you may have rooms which have a vaulted ceiling, with a steeply sloping surface close to the wall, and with the major ducts behind that surface - [[Floor-Ceiling Vaults (219)]], [[Duct Space (229)]]. In this case, it is natural to put the radiant heating panels on that sloping surface.

But it is also very wonderful to make at least some part of the radiant surfaces low enough so that seats can be built round them and against them; on a cold day there is nothing better than a seat against a warm stove - [[Built-in Seats (202)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1078.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/raised-flowers-245.md ===== -->

---
title: "Raised Flowers (245)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 245
pattern_name: "Raised Flowers"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Raised%20Flowers%20%28245%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sitting Wall (243)"
  - "Terraced Slope (169)"
  - "Paths and Goals (120)"
  - "Stair Seats (125)"
  - "Building Edge (160)"
  - "Garden Wall (173)"
---

# Raised Flowers (245)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Flowers are beautiful along the edges of paths, buildings, outdoor rooms—but it is just in these places that they need the most protection from traffic. Without some protection they cannot easily survive.

### Solution
>Soften the edges of buildings, paths, and outdoor areas with flowers. Raise the flower beds so that people can touch the flowers, bend to smell them, and sit by them. And build the flower beds with solid edges, so that people can sit on them, among the flowers too.

### Related Patterns
... outdoors there are various low walls at sitting height - [[Sitting Wall (243)]]; terraced gardens, if the garden has a natural slope in it - [[Terraced Slope (169)]]; and paths and steps and crinkled building edges - [[Paths and Goals (120)]], [[Stair Seats (125)]], [[Building Edge (160)]], [[Garden Wall (173)]]. These are the best spots for flowers, and flowers help to make them beautiful.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1132.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/raised-walk-55.md ===== -->

---
title: "Raised Walk (55)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 55
pattern_name: "Raised Walk"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Raised%20Walk%20%2855%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Network of Paths and Cars (52)"
  - "Road Crossing (54)"
  - "Parallel Roads (23)"
  - "Sitting Wall (243)"
  - "Stair Seats (125)"
---

# Raised Walk (55)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Where fast-moving cars and pedestrians meet in cities, the cars overwhelm the pedestrians. The car is king, and people are made to feel small.

### Solution
>We conclude that any pedestrian path along a road carrying fast-moving cars should be about 18 inches above the road, with a low wall or railing, or balustrade along the edge, to mark the edge. Put the raised walk on only one side of the road—make it as wide as possible.

### Related Patterns
... this pattern helps complete the [[Network of Paths and Cars (52)]] and [[Road Crossing (54)]]. It is true that in most cases, pedestrian paths which follow the path network will be running across roads, not next to them. But still, from time to time, especially along major [[Parallel Roads (23)]], between one road crossing and the next, there is a need for paths along the road. This pattern gives these special paths their character.

Protect the raised walk from the road, by means of a low wall -- [[Sitting Wall (243)]]. An arcade built over the wall, will, with its columns, give an even greater sense of comfort and at special points where a car might pull in t pick up or drop off passengers, build steps into the raised walk, large enough so people can sit here and wait in comfort -- [[Stair Seats (125)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 285.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/reception-welcomes-you-149.md ===== -->

---
title: "Reception Welcomes You (149)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 149
pattern_name: "Reception Welcomes You"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Reception%20Welcomes%20You%20%28149%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Self-Governing Workshops and Offices (80)"
  - "Small Services Without Red Tape (81)"
  - "Traveler's Inn (91)"
  - "Flexible Office Space (146)"
  - "Entrance Room (130)"
  - "The Fire (181)"
  - "Workspace Enclosure (183)"
  - "Light on Two Sides of Every Room (159)"
  - "A Place to Wait (150)"
  - "Alcoves (179)"
  - "Window Place (180)"
  - "Tapestry of Light and Dark (135)"
  - "The Shape of Indoor Space (191)"
---

# Reception Welcomes You (149)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Have you ever walked into a public building and been processed by the receptionist as if you were a package?

### Solution
>Arrange a series of welcoming things immediately inside the entrance—soft chairs, a fireplace, food, coffee. Place the reception desk so that it is not between the receptionist and the welcoming area, but to one side at an angle—so that she, or he, can get up and walk toward the people who come in, greet them, and then invite them to sit down.

### Related Patterns
... in a public building, or an office where there are many people coming in, [[Self-Governing Workshops and Offices (80)]], [[Small Services Without Red Tape (81)]], [[Traveler's Inn (91)]], [[Flexible Office Space (146)]] - the place inside the [[Entrance Room (130)]] plays an essential role; it must be built from the very start with the right atmosphere. This pattern was originally proposed by Clyde Dorsett of the National Institute of Mental Health, in a program for community mental health clinics.

Place the fireplace most carefully, to be a focus - [[The Fire (181)]] give the receptionist a workspace where she can be comfortable in her own work, and still make visitors feel welcome [[Workspace Enclosure (183)]]; give the space [[Light on Two Sides of Every Room (159)]]; perhaps put in an alcove or a window seat for people who are waiting - [[A Place to Wait (150)]], [[Alcoves (179)]], [[Window Place (180)]]. Make sure that the reception point itself is lighter than surrounding areas - [[Tapestry of Light and Dark (135)]]. And for the shape of the reception space start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 705.
> #APL/confidence/low
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/ring-roads-17.md ===== -->

---
title: "Ring Roads (17)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 17
pattern_name: "Ring Roads"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Ring%20Roads%20%2817%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Interchange (34)"
  - "Web of Public Transport (16)"
  - "Subculture Boundary (13)"
  - "Access to Water (25)"
  - "Industrial Ribbon (42)"
  - "Shielded Parking (97)"
---

# Ring Roads (17)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>It is not possible to avoid the need for high-speed roads in modern society; but it is essential to place them and build them in such a way that they do not destroy communities or countryside.

### Solution
>Place high-speed roads (freeways and other major arteries) so that:
>1. At least one high-speed road lies tangent to each local transport area.
>2. Each local transport area has a least one side not bounded by a high-speed road, but directly open to the countryside.
>3. The road is always sunken, or shielded along its length by berms, or earth, or industrial buildings, to protect the nearby neighborhoods from noise.

### Related Patterns
... the ring roads which this pattern specifies, help to define and generate the [[Local Transport Areas (11)]]; if they are placed to make connections between [[Interchange (34)]]; they also help to form the [[Web of Public Transport (16)]].

Always place the high speed roads on boundaries between subcultures -- [[Subculture Boundary (13)]] and never along the waterfronts -- [[Access to Water (25)]]. Place industry and big parking garages next to the roads, and use them, whenever possible, as extra noise shields -- [[Industrial Ribbon (42)]], [[Shielded Parking (97)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 96
> #APL/confidence/low
>
> #APL/Town-Patterns/Community-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/road-crossing-54.md ===== -->

---
title: "Road Crossing (54)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 54
pattern_name: "Road Crossing"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Road%20Crossing%20%2854%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Parallel Roads (23)"
  - "Network of Paths and Cars (52)"
  - "Small Public Squares (61)"
  - "Bus Stop (92)"
  - "Food Stands (93)"
  - "Small Parking Lots (103)"
  - "Raised Walk (55)"
  - "Trellised Walk (174)"
  - "Canvas Roofs (244)"
---

# Road Crossing (54)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Where paths cross roads, the cars have power to frighten and subdue the people walking, even when the people walking have the legal right-of-way.

### Solution
>At any point where a pedestrian path crosses a road that has enough traffic to create more than a two second delay to people crossing, make a “knuckle” at the crossing: narrow the road to the width of the through lanes only; continue the pedestrian path through the crossing about a foot above the roadway; put in islands between lanes; slope the road up toward the crossing (1 in 6 maximum); mark the path with a canopy or shelter to make it visible.

### Related Patterns
... under the impetus of [[Parallel Roads (23)]] and [[Network of Paths and Cars (52)]], paths will gradually grow at right angles of major roads -- not along them as they do now. This is an entirely new kind of situation, and requires an entirely new physical treatment to make it work.

On one side or the other of the road make the pedestrian path swell out to form a tiny square, where food stands cluster round a bus stop -- [[Small Public Squares (61)]], [[Bus Stop (92)]], [[Food Stands (93)]]; provide one or two bays for standing space for buses and cars -- [[Small Parking Lots (103)]], and when a path must run from the road crossing along the side of the road, keep it to one side only, make it as wide as possible, and raised above the roadway -- [[Raised Walk (55)]]. Perhaps build the canopy as a trellis or canvas roof -- [[Trellised Walk (174)]], [[Canvas Roofs (244)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 280.
> #APL/confidence/low
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/roof-caps-232.md ===== -->

---
title: "Roof Caps (232)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 232
pattern_name: "Roof Caps"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Roof%20Caps%20%28232%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Roof Garden (118)"
  - "Roof Vaults (220)"
  - "Ornament (249)"
---

# Roof Caps (232)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There are few cases in traditional architecture where builders have not used some roof detail to cap the building with an ornament.

### Solution
>Choose a natural way to cap the roof—some way which is in keeping with the kind of construction, and the meaning of the building. The caps may be structural; but their main function is decorative—they mark the top—they mark the place where the roof penetrates the sky.

### Related Patterns
... and this pattern finishes the [[Roof Garden (118)]] or the [[Roof Vaults (220)]]. Assume that you have built the roof vaults - or at least that you have started to build up the splines which will support the cloth which forms the vault. Or assume that you have begun to build a roof garden, and have begun to fence it or surround it. In either case - how shall the roof be finished?

Finish the roof caps any way you want, but don't forget them - [[Ornament (249)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1084.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/roof-garden-118.md ===== -->

---
title: "Roof Garden (118)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 118
pattern_name: "Roof Garden"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Roof%20Garden%20%28118%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sheltering Roof (117)"
  - "Wings of Light (107)"
  - "Cascade of Roofs (116)"
  - "Private Terrace on the Street (140)"
  - "Gallery Surround (166)"
  - "Six-Foot Balcony (167)"
  - "Sunny Place (161)"
  - "Canvas Roofs (244)"
  - "Outdoor Room (163)"
  - "Vegetable Garden (177)"
  - "Raised Flowers (245)"
  - "Climbing Plants (246)"
---

# Roof Garden (118)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A vast part of the earth’s surface, in a town, consists of roofs. Couple this with the fact that the total area of a town which can be exposed to the sun is finite, and you will realize that it is natural, and indeed essential, to make roofs which take advantage of the sun and air.

### Solution
>Make parts of almost every roof system usable as roof gardens. Make those parts flat, perhaps terraced for planting, with places to sit and sleep, private places. Place the roof gardens at various stories, and always make it possible to walk directly out onto the roof garden from some lived-in part of the building.

### Related Patterns
... in between the sloping roofs created by [[Sheltering Roof (117)]], the roofs are flat where people can walk out on them. This pattern describes the best position for these roof gardens and specifies their character. If they are correctly placed, they will most often form the ends of [[Wings of Light (107)]] at different stories and will, therefore, automatically help to complete the overall [[Cascade of Roofs (116)]].

Remember to try and put the roof gardens at the open ends of [[Wings of Light (107)]] so as not to take the daylight away from lower stories. Some roof gardens may be like balconies or galleries or terraces - [[Private Terrace on the Street (140)]], [[Gallery Surround (166)]], [[Six-Foot Balcony (167)]]. In any case, place the roof garden so that it is sheltered from the wind - [[Sunny Place (161)]], and give part of the roof some extra kind of shelter - perhaps a canvas awning - so that people can stay on the roof but keep out of the hot sun - [[Canvas Roofs (244)]]. Treat each individual garden much the way as any other garden, with flowers, vegetables, outdoor rooms, canvas awnings, climbing plants - [[Outdoor Room (163)]], [[Vegetable Garden (177)]], [[Raised Flowers (245)]], [[Climbing Plants (246)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 575.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/roof-layout-209.md ===== -->

---
title: "Roof Layout (209)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 209
pattern_name: "Roof Layout"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Roof%20Layout%20%28209%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Cascade of Roofs (116)"
  - "Sheltering Roof (117)"
  - "Roof Garden (118)"
  - "Roof Vaults (220)"
  - "Courtyards Which Live (115)"
  - "Thickening the Outer Walls (211)"
---

# Roof Layout (209)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>What kind of roof plan is organically related to the nature of your building?

### Solution
>Arrange the roofs so that each distinct roof corresponds to an identifiable social entity in the building or building complex. Place the largest roofs—those which are highest and have the largest span—over the largest and most important and most communal spaces; build the lesser roofs off these largest and highest roofs, in the form of half-vaults and sheds over alcoves and thick walls.

### Related Patterns
... assume now that you have a rough plan, to scale, for each floor of the building. In this case you already know roughly how the roofs will go, from [[Cascade of Roofs (116)]] and [[Sheltering Roof (117)]]; and you know exactly where the roof is flat to form roof gardens next to rooms at different floors - [[Roof Garden (118)]]. This pattern shows you how to get a detailed roof plan for the building, which helps those patterns come to life, for any plan which you have drawn.

You can build all these roofs, and the connections between them, by following the instructions for roof vaults - [[Roof Vaults (220)]]. When a wing ends in the open, leave the gable end at full height; when a wing ends in a courtyard, hip the gable, so that the horizontal roof edge makes the courtyard like a room - [[Courtyards Which Live (115)]].

Treat the smallest shed roofs, which cover thick walls and alcoves, as buttresses, and build them to help take the horizontal thrust from floor vaults and higher roof vaults - [[Thickening the Outer Walls (211)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 970.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Structural-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/roof-vaults-220.md ===== -->

---
title: "Roof Vaults (220)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 220
pattern_name: "Roof Vaults"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Roof%20Vaults%20%28220%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Roof Garden (118)"
  - "Floor-Ceiling Vaults (219)"
  - "Sheltering Roof (117)"
  - "Dormer Windows (231)"
  - "Roof Caps (232)"
  - "Lapped Outside Walls (234)"
---

# Roof Vaults (220)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>What is the best shape for a roof?

### Solution
>Build the roof vault either as a cylindrical barrel vault, or like a pitched roof with a slight convex curve in each of the two sloping sides. Put in undulations along the vault, to make the shell more effective. The curvature of the main shell, and of the undulations, can vary with the span; the bigger the span, the deeper the curvature and undulations need to be.

### Related Patterns
... if the roof is a flat [[Roof Garden (118)]], it can be built just like any [[Floor-Ceiling Vaults (219)]]. But when it is a sloping roof, according to the character of [[Sheltering Roof (117)]], it needs a new construction, specifically adapted to the shape which can enclose a volume.

Leave space for dormers at intervals along the vault - [[Dormer Windows (231)]], and build them integral with it. Finish the roof with [[Roof Caps (232)]]. And once the vault is complete, it needs a waterproof paint or skin applied to its outer surface - [[Lapped Outside Walls (234)]]. It can be painted white to protect it against the sun; the undulations will carry the rainwater ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1036.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/rooms-to-rent-153.md ===== -->

---
title: "Rooms to Rent (153)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 153
pattern_name: "Rooms to Rent"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Rooms%20to%20Rent%20%28153%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Necklace of Community Projects (45)"
  - "The Family (75)"
  - "Self-Governing Workshops and Offices (80)"
  - "Small Services Without Red Tape (81)"
  - "Flexible Office Space (146)"
  - "Teenager's Cottage (154)"
  - "Old Age Cottage (155)"
  - "Home Workshop (157)"
  - "Entrance Transition (112)"
  - "Open Stairs (158)"
  - "Light on Two Sides of Every Room (159)"
  - "The Shape of Indoor Space (191)"
---

# Rooms to Rent (153)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>As the life in a building changes, the need for space shrinks and swells cyclically. The building must be able to adapt to this irregular increase and decrease in the need for space.

### Solution
>Make at least some part of the building rentable: give it a private entrance over and above its regular connection to the rest of the house. Make sure that the regular entrance can be easily closed off without destroying the circulation in the house, and make sure that a bathroom can be directly reached from this room without having to go through the main house.

### Related Patterns
... this pattern is the first which sets the framework for the outbuildings. Used properly, it can help to create [[Necklace of Community Projects (45)]], [[The Family (75)]], [[Self-Governing Workshops and Offices (80)]], [[Small Services Without Red Tape (81)]], [[Flexible Office Space (146)]], [[Teenager's Cottage (154)]], [[Old Age Cottage (155)]], [[Home Workshop (157)]]: in general it makes any building flexible, useful in a greater variety of circumstances.

Place the rooms to rent in such a way that they can double as a [[Teenager's Cottage (154)]], or an [[Old Age Cottage (155)]], or a [[Home Workshop (157)]]; give the private entrance an [[Entrance Transition (112)]], and if the space is on an upper floor, give it direct access to the street by means of [[Open Stairs (158)]]. And give the rooms themselves [[Light on Two Sides of Every Room (159)]] and [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 720.
> #APL/confidence/low
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/root-foundations-214.md ===== -->

---
title: "Root Foundations (214)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 214
pattern_name: "Root Foundations"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Root%20Foundations%20%28214%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Columns at the Corners (212)"
  - "Final Column Distribution (213)"
  - "Site Repair (104)"
  - "Connection to the Earth (168)"
  - "Box Columns (216)"
  - "Ground Floor Slab (215)"
---

# Root Foundations (214)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The best foundations of all art the kinds of foundations which a tree has—where the entire structure of a tree simply continues below ground level, and creates a system entirely integral with the ground, in tension and compression.

### Solution
>Try to find a way of making foundations in which the columns themselves go right into the earth, and spread out there—so that the footing is continuous with the material of the column, and the column, with its footing, like a tree root, can resist tension and horizontal shear as well as compression.

### Related Patterns
... once you have a rough column plan for the building - [[Columns at the Corners (212)]], [[Final Column Distribution (213)]] - you are ready to start the site work itself. First, stake out the positions of the ground floor columns, before you do any other earthwork, so that you can move the columns whenever necessary to leave rocks or plants intact - [[Site Repair (104)]], [[Connection to the Earth (168)]]. Then dig the foundation pits and prepare to make the foundations.

To make foundations like this for hollow concrete, filled box columns, start with a pit for each foundation, place the hollow column in the pit, and pour the column and the foundation integrally, in one continuous pour - [[Box Columns (216)]]. Later, when you build the ground floor slab, tie the concrete into the foundations - [[Ground Floor Slab (215)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1006.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/row-houses-38.md ===== -->

---
title: "Row Houses (38)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 38
pattern_name: "Row Houses"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Row%20Houses%20%2838%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House Cluster (37)"
  - "Density Rings (29)"
  - "Degrees of Publicness (36)"
  - "Long Thin House (109)"
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Parallel Roads (23)"
  - "Network of Paths and Cars (52)"
  - "Small Parking Lots (103)"
  - "Building Complex (95)"
---

# Row Houses (38)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>At densities of 15 to 30 houses per acre, row houses are essential. But typical row houses are dark inside, and stamped from an identical mould.

### Solution
>For row houses, place houses along pedestrian paths that run at right angles to local roads and parking lots, and give each house a long frontage and a shallow depth.

### Related Patterns
... in certain parts of a community, the detached homes and gardens of a [[House Cluster (37)]] will not work, because they are not dense enough to generate the denser parts of [[Density Rings (29)]] and [[Degrees of Publicness (36)]]. To help create these larger patterns, it is necessary to build row houses instead.

Make the individual houses and cottages as long and thin as possible - [[Long Thin House (109)]]; vary the houses according to the different household types - [[The Family (75)]], [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]]; build roads across the paths, at right angles to them - [[Parallel Roads (23)]], [[Network of Paths and Cars (52)]], with small parking lots off the roads - [[Small Parking Lots (103)]]. In other respects build row houses in clusters [[House Cluster (37)]], [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 204.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Housing-Clusters


<!-- ===== pattern-language/wiki/concepts/patterns/sacred-sites-24.md ===== -->

---
title: "Sacred Sites (24)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 24
pattern_name: "Sacred Sites"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sacred%20Sites%20%2824%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Quiet Backs (59)"
  - "Zen View (134)"
  - "Tree Places (171)"
  - "Garden Seat (176)"
  - "Holy Ground (66)"
---

# Sacred Sites (24)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People cannot maintain their spiritual roots and their connections to the past if the physical world they live in does not also sustain these roots.

### Solution
>Whether the sacred sites are large or small, whether they are at the center of the towns, in neighborhoods, or in the deepest countryside, establish ordinances which will protect them absolutely—so that our roots in the visible surroundings cannot be violated.

### Related Patterns
... in every region and every town, indeed in every neighborhood, there are special places which have come to symbolize the area, and the people's roots there. These places may be natural beauties or historical landmarks left by ages past. But in some form they are essential.

Give every sacred site a place, or a sequence of places, where people can relax, enjoy themselves, and feel the presence of the place -- [[Quiet Backs (59)]], [[Zen View (134)]], [[Tree Places (171)]], [[Garden Seat (176)]]. And above all, shield the approach to the site, so that it can only be approached on foot, and through a series of gateways and thresholds which reveal it gradually -- [[Holy Ground (66)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 131.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/scattered-work-9.md ===== -->

---
title: "Scattered Work (9)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 9
pattern_name: "Scattered Work"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Scattered%20Work%20%289%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Subculture Boundary (13)"
  - "Industrial Ribbon (42)"
  - "Neighborhood Boundary (15)"
  - "Work Community (41)"
  - "Home Workshop (157)"
  - "Self-Governing Workshops and Offices (80)"
---

# Scattered Work (9)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The artificial separation of houses and work creates intolerable rifts in people’s inner lives.

### Solution
>Use zoning laws, neighborhood planning, tax incentives, and any other means available to scatter workplaces throughout the city. Prohibit large concentrations of work without family life around them. Prohibit large concentrations of family life without workplaces around them.

### Related Patterns
... this pattern helps the gradual evolution of [[Mosaic of Subcultures (8)]], by placing families and work together, and so intensifying the emergence of highly differentiated subcultures, each with its own character...

The scattered work itself can take a great variety of forms. It an occur in belts of industry, where it is essential for an industry to occupy an acre or more between subcultures -- [[Subculture Boundary (13)]], [[Industrial Ribbon (42)]]; it can occur in work communities, which are scattered among the neighborhoods -- [[Neighborhood Boundary (15)]], [[Work Community (41)]]; and it can occur in individual workshops, right among the houses -- [[Home Workshop (157)]]. The size of each workshop is limited only by the nature of human groups and the process of self-governance. It is discussed in detail in [[Self-Governing Workshops and Offices (80)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 51
> #APL/confidence/high
>
> #APL/Town-Patterns/City-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/seat-spots-241.md ===== -->

---
title: "Seat Spots (241)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 241
pattern_name: "Seat Spots"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Seat%20Spots%20%28241%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Path Shape (121)"
  - "Activity Pockets (124)"
  - "Private Terrace on the Street (140)"
  - "Building Edge (160)"
  - "Sunny Place (161)"
  - "Outdoor Room (163)"
  - "Connection to the Earth (168)"
  - "Trellised Walk (174)"
  - "Garden Seat (176)"
  - "Stair Seats (125)"
  - "Front Door Bench (242)"
  - "Sitting Wall (243)"
---

# Seat Spots (241)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Where outdoor seats are set down without regard for view and climate, they will almost certainly be useless.

### Solution
>Choosing good spots for outdoor seats is far more important than building fancy benches. Indeed, if the spot is right, the most simply kind of seat is perfect.
>In cool climates, choose them to face the sun, and to be protected from the wind; in hot climates, put them in shade and open to summer breezes. In both cases, place them to face activities.

### Related Patterns
... assume that the main structure of the building is complete. To make it perfectly complete you need to build in the details of the gardens and the terraces around the building. In some cases, you will probably have laid out the walls and flowers and seats, at least in rough outline; but it is usually best to make the final decisions about them after the building is really there - so that you can make them fit the building and help to tie it into its surroundings - [[Path Shape (121)]], [[Activity Pockets (124)]], [[Private Terrace on the Street (140)]], [[Building Edge (160)]], [[Sunny Place (161)]], [[Outdoor Room (163)]], [[Connection to the Earth (168)]], [[Trellised Walk (174)]], [[Garden Seat (176)]], etc. First, the outdoor seats, public and private.

If these seats can be made continuous with stairs or building entrances or low walls or balustrades, so much the better - [[Stair Seats (125)]], [[Front Door Bench (242)]], [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1118.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/secret-place-204.md ===== -->

---
title: "Secret Place (204)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 204
pattern_name: "Secret Place"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Secret%20Place%20%28204%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Thick Walls (197)"
  - "Ceiling Height Variety (190)"
  - "Closets Between Rooms (198)"
  - "Thickening the Outer Walls (211)"
  - "Floor-Ceiling Vaults (219)"
---

# Secret Place (204)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Where can the need for concealment be expressed; the need to hide; the need for something precious to be lost, and then revealed?

### Solution
>Make a place in the house, perhaps only a few feet square, which is kept locked and secret; a place which is virtually impossible to discover—until you have been shown where it is; a place where the archives of the house, or other more potent secrets, might be kept.

### Related Patterns
... and here is a finishing touch to the thick walls, perhaps even to the low ceilings - [[Thick Walls (197)]], [[Ceiling Height Variety (190)]].

Classic types of secret places are the panel that slides back, revealing the cavity in the wall, the loose board beneath the rug, the trap door - [[Closets Between Rooms (198)]], [[Thickening the Outer Walls (211)]], [[Floor-Ceiling Vaults (219)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 930.
> #APL/confidence/low
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/self-governing-workshops-and-offices-80.md ===== -->

---
title: "Self-Governing Workshops and Offices (80)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 80
pattern_name: "Self-Governing Workshops and Offices"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Self-Governing%20Workshops%20and%20Offices%20%2880%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Scattered Work (9)"
  - "Industrial Ribbon (42)"
  - "Work Community (41)"
  - "Office Connections (82)"
  - "Building Complex (95)"
  - "Small Services Without Red Tape (81)"
  - "Master and Apprentices (83)"
  - "Small Work Groups (148)"
---

# Self-Governing Workshops and Offices (80)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No one enjoys their work if they are a cog in a machine.

### Solution
>Encourage the formation of self-governing workshops and offices of 5 to 20 workers. Make each group autonomous—with respect to organization, style, relation to other groups, hiring and firing, work schedule. Where the work is complicated and requires larger organizations, several of these work groups can federate and cooperate to produce complex artifacts and services.

### Related Patterns
... all kinds of work, office work and industrial work and agricultural work, are radically decentralized by [[Scattered Work (9)]], and [[Industrial Ribbon (42)]] and grouped in small communities - [[Work Community (41)]]. This pattern helps to generate these larger patterns by giving the fundamental nature of all work organizations, no matter what their type.

House the workgroup in a building of its own - [[Office Connections (82)]], [[Building Complex (95)]]; if the workgroup is large enough, and if it serves the public, break it down into autonomous departments, easily identifiable, with no more than a dozen people each - [[Small Services Without Red Tape (81)]] in any case, divide all work into small team work, either directly within the cooperative workgroup or under the departments, with the people of each team in common space - [[Master and Apprentices (83)]] and [[Small Work Groups (148)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 398.
> #APL/confidence/high
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/sequence-of-sitting-spaces-142.md ===== -->

---
title: "Sequence of Sitting Spaces (142)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 142
pattern_name: "Sequence of Sitting Spaces"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sequence%20of%20Sitting%20Spaces%20%28142%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Common Areas at the Heart (129)"
  - "Entrance Room (130)"
  - "Flexible Office Space (146)"
  - "A Place to Wait (150)"
  - "Private Terrace on the Street (140)"
  - "Couple's Realm (136)"
  - "Farmhouse Kitchen (139)"
  - "A Room of One's Own (141)"
  - "Half-Private Office (152)"
  - "The Shape of Indoor Space (191)"
  - "Zen View (134)"
  - "Window Place (180)"
  - "The Fire (181)"
  - "Sitting Circle (185)"
  - "Seat Spots (241)"
---

# Sequence of Sitting Spaces (142)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Every corner of a building is a potential sitting space. But each sitting space has different needs for comfort and enclosure according to its position in the intimacy gradient.

### Solution
>Put in a sequence of graded sitting spaces throughout the building, varying according to their degree of enclosure. Enclose the most formal ones entirely, in rooms by themselves; put the least formal ones in corners of other rooms, without any kind of screen around them; and place the intermediate ones with a partial enclosure round them to keep them connected to some larger space, but also partly separate.

### Related Patterns
... at various points along the [[Intimacy Gradient (127)]] of a house, or office, or a public building, there is a need for sitting space. Some of this space may take the form of rooms devoted entirely to sitting, like the formal sitting rooms of old; others may be simply areas or corners of other rooms. This pattern states the range and distribution of these sitting spaces, and helps create the intimacy gradient by doing so.

Put the most formal sitting spaces in the [[Common Areas at the Heart (129)]] and in the [[Entrance Room (130)]] ; put the intermediate spaces also in the [[Common Areas at the Heart (129)]], in [[Flexible Office Space (146)]], in a [[A Place to Wait (150)]], and on the [[Private Terrace on the Street (140)]] ; and put the most intimate and most informal sitting spaces in the [[Couple's Realm (136)]], the [[Farmhouse Kitchen (139)]], the [[A Room of One's Own (141)]], and the [[Half-Private Office (152)]]. Build the enclosure round each space, according to its position in the scale of sitting spaces - [[The Shape of Indoor Space (191)]]; and make each one, wherever it is, comfortable and lazy by placing chairs correctly with respect to fires and windows - [[Zen View (134)]], [[Window Place (180)]], [[The Fire (181)]], [[Sitting Circle (185)]], [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 673.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/settled-work-156.md ===== -->

---
title: "Settled Work (156)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 156
pattern_name: "Settled Work"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Settled%20Work%20%28156%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "Old Age Cottage (155)"
  - "A Room of One's Own (141)"
  - "Home Workshop (157)"
  - "Private Terrace on the Street (140)"
  - "Opening to the Street (165)"
---

# Settled Work (156)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The experience of settled work is a prerequisite for peace of mind in old age. Yet our society undermines this experience by making a rift between working life and retirement, and between workplace and home.

### Solution
>Give each person, especially as they grow old, the chance to set up a workplace of their own, within or very near their home. Make it a place that can grow slowly, perhaps in the beginning sustaining a weekend hobby and gradually becoming a complete, productive, and comfortable workshop.

### Related Patterns
... as people grow older, simple satisfying work which nourishes, becomes more and more important. This pattern specifies the need for this development to be a part of every family. It helps to form [[The Family (75)]], it helps form [[Old Age Cottage (155)]], and it is a natural embellishment of [[A Room of One's Own (141)]].

Arrange the workshop, physically, along the lines defined by [[Home Workshop (157)]], and make the workshop open to the street, a part of local street life - [[Private Terrace on the Street (140)]], [[Opening to the Street (165)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 733.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/sheltering-roof-117.md ===== -->

---
title: "Sheltering Roof (117)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 117
pattern_name: "Sheltering Roof"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sheltering%20Roof%20%28117%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wings of Light (107)"
  - "Cascade of Roofs (116)"
  - "Roof Vaults (220)"
  - "Bulk Storage (145)"
  - "Arcades (119)"
  - "Gallery Surround (166)"
  - "Roof Garden (118)"
  - "Dormer Windows (231)"
  - "Roof Layout (209)"
---

# Sheltering Roof (117)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The roof plays a primal role in our lives. The most primitive buildings are nothing but a roof. If the roof is hidden, if its presence cannot be felt around the building, or if it cannot be used, then people will lack a fundamental sense of shelter.

### Solution
>Slope the roof or make a vault of it, make its entire surface visible, and bring the eaves of the roof down low, as low as 6’0" or 6’6" at places like the entrance, where people pause. Build the top story of each wing right into the roof, so that the roof does not only cover it, but actually surrounds it.

### Related Patterns
... over the [[Wings of Light (107)]], within the overall [[Cascade of Roofs (116)]], some parts of the cascade are flat and some are steeply pitched or vaulted. This pattern gives the character of those parts which are steeply pitched or vaulted; the next one gives the character of those which must be flat.

Get the exact shape of the cross section from [[Roof Vaults (220)]] ; use the space inside the top of the sloped roof for [[Bulk Storage (145)]]; where the roof comes down low, perhaps make it continuous with an [[Arcades (119)]] or [[Gallery Surround (166)]]. Build the roof flat, not sloped, only where people can get out to it to use it as a garden - [[Roof Garden (118)]]; where rooms are built into the roof, make windows in the roof - [[Dormer Windows (231)]] - If the building plan is complex, get the exact way that different sloped roofs meet from [[Roof Layout (209)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 569.
> #APL/confidence/high
>
> #APL/Building-Patterns/Building-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/shielded-parking-97.md ===== -->

---
title: "Shielded Parking (97)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 97
pattern_name: "Shielded Parking"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Shielded%20Parking%20%2897%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Local Transport Areas (11)"
  - "Nine Per Cent Parking (22)"
  - "Building Complex (95)"
  - "Housing Hill (39)"
  - "Housing In Between (48)"
  - "Individually Owned Shops (87)"
  - "Open Stairs (158)"
  - "Gallery Surround (166)"
  - "Canvas Roofs (244)"
  - "Circulation Realms (98)"
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Tapestry of Light and Dark (135)"
  - "Structure Follows Social Spaces (205)"
---

# Shielded Parking (97)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Large parking structures full of cars are inhuman and dead buildings—no one wants to see them or walk by them. At the same time, if you are driving, the entrance to a parking structure is essentially the main entrance to the building, and it needs to be visible.

### Solution
>Put all large parking lots, or parking garages, behind some kind of natural wall, so that the cars and parking structures cannot be seen from outside. The wall which surrounds the cars may be a building, connected houses, or housing hills, earth berms, or shops.

### Related Patterns
... many patterns we have given discourage dependence on the use of cars; we hope that these patterns will gradually get rid, altogether, of the need for large parking lots and parking structures - [[Local Transport Areas (11)]], [[Nine Per Cent Parking (22)]]. However, in certain cases, unfortunately, large areas of parking are still necessary. Whenever this is so, this parking must be placed very early, to be sure that it does not destroy the [[Building Complex (95)]] altogether.

For shields see [[Housing Hill (39)]], [[Housing In Between (48)]], [[Individually Owned Shops (87)]], [[Open Stairs (158)]], [[Gallery Surround (166)]]. One of the cheapest ways of all to shield a parking lot is with canvas awnings - the canvas can be many colors: underneath, the light is beautiful - [[Canvas Roofs (244)]]. Make certain that the major entrances of buildings are quite clearly visible from the place where you drive into parking lots, and from the places where you leave the parking lots on foot - [[Circulation Realms (98)]], [[Family of Entrances (102)]], [[Main Entrance (110)]]. In covered parking structures, use a huge shaft of daylight as a natural direction which tells people where to walk to leave the parking - [[Tapestry of Light and Dark (135)]] ; and finally, for the load-bearing structure, engineering, and construction, begin with [[Structure Follows Social Spaces (205)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 477.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/shopfront-schools-85.md ===== -->

---
title: "Shopfront Schools (85)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 85
pattern_name: "Shopfront Schools"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Shopfront%20Schools%20%2885%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Children's Home (86)"
  - "Network of Learning (18)"
  - "Pedestrian Street (100)"
  - "Self-Governing Workshops and Offices (80)"
  - "Accessible Green (60)"
  - "Building Complex (95)"
  - "Opening to the Street (165)"
---

# Shopfront Schools (85)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Around the age of 6 or 7, children develop a great need to learn by doing, to make their mark on a community outside the home. If the setting is right, these needs lead children directly to basic skills and habits of learning.

### Solution
>Instead of building large public schools for children 7 to 12, set up tiny independent schools, one school at a time. Keep the school small, so that its overheads are low and a teacher-student ratio of 1:10 can be maintained. Locate it in the public part of the community, with a shopfront and three or four rooms.

### Related Patterns
... the [[Children's Home (86)]] provides the beginning of learning and forms the foundation of the [[Network of Learning (18)]] in a community. As children grow older and more independent, these patterns must be supplemented by a mass of tiny institutions, schools.and yet not schools, dotted among the living functions of the community.

Place the school on a pedestrian street - [[Pedestrian Street (100)]]; near other functioning workshops - [[Self-Governing Workshops and Offices (80)]] and within walking distance of a park - [[Accessible Green (60)]]. Make it an identifiable part of the building it is part of - [[Building Complex (95)]]; and give it a good strong opening at the front, so that it is connected with the street-[[Opening to the Street (165)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 420.
> #APL/confidence/low
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/shopping-street-32.md ===== -->

---
title: "Shopping Street (32)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 32
pattern_name: "Shopping Street"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Shopping%20Street%20%2832%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Magic of the City (10)"
  - "Promenade (31)"
  - "Web of Shopping (19)"
  - "Pedestrian Street (100)"
  - "Network of Paths and Cars (52)"
  - "Parallel Roads (23)"
  - "Individually Owned Shops (87)"
  - "Road Crossing (54)"
  - "Shielded Parking (97)"
  - "Canvas Roofs (244)"
  - "Market of Many Shops (46)"
  - "Housing In Between (48)"
---

# Shopping Street (32)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Shopping centers depend on access: they need locations near major traffic arteries. However, the shoppers themselves don’t benefit from traffic: they need quiet, comfort, and convenience, and access from the pedestrian paths in the surrounding areas.

### Solution
>Encourage local shopping centers to grow in the form of short pedestrian streets, at right angles to major roads and opening off these roads—with parking behind the shops, so that the cars can pull directly off the road, and yet not harm the shopping street.

### Related Patterns
... this pattern helps to complete the [[Magic of the City (10)]] and [[Promenade (31)]]. And, each time a shopping street gets built, it will also help to generate the [[Web of Shopping (19)]].

Treat the physical character of the street like any other [[Pedestrian Street (100)]] on the [[Network of Paths and Cars (52)]], at right angles to major [[Parallel Roads (23)]]; have as many shops as small as possible -- [[Individually Owned Shops (87)]]; where the shopping street crosses the road, make the crossing wide, giving priority to the pedestrians -- [[Road Crossing (54)]]; parking can easily be provided by a single row of parking spaces in an alley lying behind the shops -- all along the backs of the shops, off the alley, with the parking spaces walled, and perhaps even given canvas roofs, so that they don't destroy the area -- [[Shielded Parking (97)]], [[Canvas Roofs (244)]]. Make sure that every shopping street includes a [[Market of Many Shops (46)]], and some [[Housing In Between (48)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 174.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Centers


<!-- ===== pattern-language/wiki/concepts/patterns/short-passages-132.md ===== -->

---
title: "Short Passages (132)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 132
pattern_name: "Short Passages"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Short%20Passages%20%28132%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Flow Through Rooms (131)"
  - "Building Thoroughfare (101)"
  - "Circulation Realms (98)"
  - "Light on Two Sides of Every Room (159)"
  - "Alcoves (179)"
  - "Window Place (180)"
  - "Thick Walls (197)"
  - "Closets Between Rooms (198)"
  - "Outdoor Room (163)"
  - "Gallery Surround (166)"
  - "Low Sill (222)"
  - "Interior Windows (194)"
  - "Solid Doors with Glass (237)"
  - "The Shape of Indoor Space (191)"
---

# Short Passages (132)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>“…long, sterile corridors set the scene for everything bad about modern architecture.”

### Solution
>Keep passages short. Make them as much like rooms as possible, with carpets or wood on the floor, furniture, bookshelves, beautiful windows. Make them generous in shape, and always give them plenty of light; the best corridors and passages of all are those which have windows along an entire wall.

### Related Patterns
... [[The Flow Through Rooms (131)]] describes the generosity of light and movement in the way that rooms connect to one another and recommends against the use of passages. But when there has to be a passage in an office or a house and when it is too small to be a [[Building Thoroughfare (101)]], it must be treated very specially, as if it were itself a room. This pattern gives the character of these smallest passages, and so completes the circulation system laid down by [[Circulation Realms (98)]] and [[Building Thoroughfare (101)]] and [[The Flow Through Rooms (131)]].

Put in windows, bookshelves, and furnishings to make them as much like actual rooms as possible, with alcoves, seats along the edge - [[Light on Two Sides of Every Room (159)]], [[Alcoves (179)]], [[Window Place (180)]], [[Thick Walls (197)]], [[Closets Between Rooms (198)]]; open up the long side into the garden or out onto balconies - [[Outdoor Room (163)]], [[Gallery Surround (166)]], [[Low Sill (222)]]. Make interior windows between the passage and the rooms which open off it - [[Interior Windows (194)]], [[Solid Doors with Glass (237)]]. And finally, for the shape of the passages, in detail, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 632.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/site-repair-104.md ===== -->

---
title: "Site Repair (104)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 104
pattern_name: "Site Repair"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Site%20Repair%20%28104%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Building Complex (95)"
  - "Number of Stories (96)"
  - "Circulation Realms (98)"
  - "Tree Places (171)"
  - "South Facing Outdoors (105)"
  - "Positive Outdoor Space (106)"
  - "Terraced Slope (169)"
  - "Garden Growing Wild (172)"
  - "Wings of Light (107)"
  - "Long Thin House (109)"
---

# Site Repair (104)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Buildings must always be built on those parts of the land which are in the worst condition, not the best.

### Solution
>On no account place buildings in the places which are more beautiful. In fact, do the opposite. Consider the site and its buildings as a single living ecosystem. Leave those areas that are the most precious, beautiful, comfortable, and healthy as they are, and build new structures in those parts of the site which are least pleasant now.

### Related Patterns
... the most general aspects of a building complex are established in [[Building Complex (95)]], [[Number of Stories (96)]], and [[Circulation Realms (98)]]. The patterns which follow, and all remaining patterns in the language, concern the design of one single building and its surroundings. This pattern explains the very first action you must take - the process of repairing the site. Since it tends to identify very particular small areas of any site as promising areas of development, it is greatly supported by [[Building Complex (95)]] which breaks buildings into smaller parts, and therefore makes it possible to tuck them into different corners of the site in the best places.

Above all, leave trees intact and build around them with great care - [[Tree Places (171)]]; keep open spaces open to the south of buildings, for the sun -[[South Facing Outdoors (105)]]; try, generally, to shape space in such a way that each place becomes positive, in its own right - [[Positive Outdoor Space (106)]]. Repair slopes if they need it with [[Terraced Slope (169)]], and leave the outdoors in its natural state as much as possible - [[Garden Growing Wild (172)]]. If necessary, push and shove the building into odd corners to preserve the beauty of an old vine, a bush you love, a patch of lovely grass - [[Wings of Light (107)]], [[Long Thin House (109)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 508.
> #APL/confidence/high
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/sitting-circle-185.md ===== -->

---
title: "Sitting Circle (185)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 185
pattern_name: "Sitting Circle"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sitting%20Circle%20%28185%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Sequence of Sitting Spaces (142)"
  - "Intimacy Gradient (127)"
  - "The Fire (181)"
  - "The Shape of Indoor Space (191)"
  - "Half-Open Wall (193)"
  - "Common Areas at the Heart (129)"
  - "Different Chairs (251)"
  - "Pools of Light (252)"
  - "Window Place (180)"
---

# Sitting Circle (185)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A group of chairs, a sofa and a chair, a pile of cushions—these are the most obvious things in everybody’s life—and yet to make them work, so people become animated and alive in them, is a very subtle business. Most seating arrangements are sterile, people avoid them, nothing ever happens there. Others seem somehow to gather life around them, to concentrate and liberate energy. What is the difference between the two?

### Solution
>Place each sitting space in a position which is protected, not cut by paths or movement, roughly circular, made so that the room itself helps to suggest the circle—not too strongly—with paths and activities around it, so that people naturally gravitate toward the chairs when they get into the mood to sit. Place the chairs and cushions loosely in the circle, and have a few too many.

### Related Patterns
... according to the [[Sequence of Sitting Spaces (142)]], there will be a variety of different kinds of sitting space throughout an office building or a house or workshop - some formal, some informal, some large, some small, laid out in part according to the [[Intimacy Gradient (127)]]. This pattern deals with the actual physical layout of any one of these sitting spaces. And of course, it can be used to help create the sequence of sitting spaces, piecemeal, one space at a time.

Use a fire, and columns, and half-open walls to form the shape of the circle - [[The Fire (181)]], [[The Shape of Indoor Space (191)]], [[Half-Open Wall (193)]]; but do not make it too formal or too enclosed - [[Common Areas at the Heart (129)]], [[Sequence of Sitting Spaces (142)]]. Use [[Different Chairs (251)]], big ones, small ones, cushions, and a few too many, so that they are never too perfectly arranged, but always in a bit of a jumble. Make a [[Pools of Light (252)]] to mark the sitting circle, and perhaps a [[Window Place (180)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 857.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/sitting-wall-243.md ===== -->

---
title: "Sitting Wall (243)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 243
pattern_name: "Sitting Wall"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sitting%20Wall%20%28243%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Positive Outdoor Space (106)"
  - "Green Streets (51)"
  - "Pedestrian Street (100)"
  - "Half-Hidden Garden (111)"
  - "Hierarchy of Open Space (114)"
  - "Path Shape (121)"
  - "Activity Pockets (124)"
  - "Private Terrace on the Street (140)"
  - "Outdoor Room (163)"
  - "Opening to the Street (165)"
  - "Gallery Surround (166)"
  - "Garden Growing Wild (172)"
  - "Seat Spots (241)"
  - "Front Door Bench (242)"
  - "Soft Tile and Brick (248)"
  - "Ornament (249)"
  - "Raised Flowers (245)"
---

# Sitting Wall (243)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In many places, walls and fences between outdoor spaces are too high; but no boundary at all does injustice to the subtlety of the divisions between the spaces.

### Solution
>Surround any natural outdoor area, and make minor boundaries between outdoor areas with low walls, about 16 inches high, and wide enough to sit on, at least 12 inches wide.

### Related Patterns
... if all is well, the outdoor areas are largely made up of positive spaces - [[Positive Outdoor Space (106)]]; in some fashion you have marked boundaries between gardens and streets, between terraces and gardens, between outdoor rooms and terraces, between play areas and gardens - [[Green Streets (51)]], [[Pedestrian Street (100)]], [[Half-Hidden Garden (111)]], [[Hierarchy of Open Space (114)]], [[Path Shape (121)]], [[Activity Pockets (124)]], [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]], [[Opening to the Street (165)]], [[Gallery Surround (166)]], [[Garden Growing Wild (172)]]. With this pattern, you can help these natural boundaries take on their proper character, by building walls, just low enough to sit on, and high enough to mark the boundaries.

If you have also marked the places where it makes sense to build seats - [[Seat Spots (241)]], [[Front Door Bench (242)]] - you can kill two birds with one stone by using the walls as seats which help enclose the outdoor space wherever its positive character is weakest.

Place the walls to coincide with natural seat spots, so that extra benches are not necessary - [[Seat Spots (241)]]; make them of brick or tile, if possible - [[Soft Tile and Brick (248)]]; if they separate two areas of slightly different height, pierce them with holes to make them balustrades - [[Ornament (249)]]. Where they are in the sun, and can be large enough, plant flowers in them or against them - [[Raised Flowers (245)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1124.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/six-foot-balcony-167.md ===== -->

---
title: "Six-Foot Balcony (167)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 167
pattern_name: "Six-Foot Balcony"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Six-Foot%20Balcony%20%28167%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Arcades (119)"
  - "Gallery Surround (166)"
  - "Sitting Wall (243)"
  - "Column Place (226)"
  - "Half-Open Wall (193)"
  - "Sunny Place (161)"
  - "Outdoor Room (163)"
  - "The Shape of Indoor Space (191)"
---

# Six-Foot Balcony (167)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Balconies and porches which are less than six feet deep are hardly ever used.

### Solution
>Whenever you build a balcony, a porch, a gallery, or a terrace always make it at least six feet deep. If possible, recess at least a part of it into the building so that it is not cantilevered out and separated from the building by a simple line, and enclose it partially.

### Related Patterns
... in various places [[Arcades (119)]] and [[Gallery Surround (166)]] have helped you to imagine some kind of a balcony, veranda, terrace, porch, arcade along the building edge or halfway into it. This pattern simply specifies the depth of this arcade or porch or balcony, to make sure that it really works.

Enclose the balcony with a low wall - [[Sitting Wall (243)]], heavy columns - [[Column Place (226)]], and half-open walls or screens - [[Half-Open Wall (193)]]. Keep it open toward the south - [[Sunny Place (161)]]. Treat it as an [[Outdoor Room (163)]], and get the details of its shape and its construction from [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 781.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/sleeping-in-public-94.md ===== -->

---
title: "Sleeping in Public (94)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 94
pattern_name: "Sleeping in Public"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sleeping%20in%20Public%20%2894%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Interchange (34)"
  - "Small Public Squares (61)"
  - "Public Outdoor Room (69)"
  - "Street Cafe (88)"
  - "Pedestrian Street (100)"
  - "Building Thoroughfare (101)"
  - "A Place to Wait (150)"
  - "Building Edge (160)"
  - "Bed Alcove (188)"
  - "Seat Spots (241)"
---

# Sleeping in Public (94)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>It is a mark of success in a park, public lobby, or a porch, when people can come there and fall asleep.

### Solution
>Keep the environment filled with ample benches, comfortable places, corners to sit on the ground, or lie in comfort in the sand. Make these places relatively sheltered, protected from circulation, perhaps up a step, with seats and grass to slump down upon, read the paper and doze off.

### Related Patterns
... this pattern helps to make places like the [[Interchange (34)]], [[Small Public Squares (61)]], [[Public Outdoor Room (69)]], [[Street Cafe (88)]], [[Pedestrian Street (100)]], [[Building Thoroughfare (101)]], [[A Place to Wait (150)]] completely public.

Above all, put the places for sleeping along [[Building Edge (160)]] ; make seats there, and perhaps even a bed alcove or two in public might be a nice touch - [[Bed Alcove (188)]], [[Seat Spots (241)]]; but above all, it will hinge on the attitudes which people have - do anything you can to create trust, so that people feel no fear in going to sleep in public and so that other people feel no fear of people sleeping in the street.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 457.
> #APL/confidence/low
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/sleeping-to-the-east-138.md ===== -->

---
title: "Sleeping to the East (138)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 138
pattern_name: "Sleeping to the East"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sleeping%20to%20the%20East%20%28138%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Couple's Realm (136)"
  - "Children's Realm (137)"
  - "Indoor Sunlight (128)"
  - "Bed Cluster (143)"
  - "Marriage Bed (187)"
  - "Bed Alcove (188)"
  - "Filtered Light (238)"
  - "Window Place (180)"
  - "Natural Doors and Windows (221)"
---

# Sleeping to the East (138)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>This is one of the patterns people most often disagree with. However, we believe they are mistaken.

### Solution
>Give those parts of the house where people sleep, an eastern orientation, so that they wake up with the sun and light. This means, typically, that the sleeping area needs to be on the eastern side of the house; but it can also be on the western side provided there is a courtyard or a terrace to the east of it.

### Related Patterns
... at the back of the [[Intimacy Gradient (127)]], the position of the [[Couple's Realm (136)]] and [[Children's Realm (137)]], give some idea of where bedrooms will be. This pattern settles the position of the bedrooms by placing them to face the east, and thereby complements the effect of [[Indoor Sunlight (128)]], which places the more public rooms toward the south.

Place all the beds with care, so that they get the morning light, not only as a group - [[Couple's Realm (136)]], [[Bed Cluster (143)]], but individually, so that each gets eastern light from some specific window - [[Marriage Bed (187)]], [[Bed Alcove (188)]]. Use [[Filtered Light (238)]] to prevent the sun from shining too directly on the bed. If there is room, make this window function as a [[Window Place (180)]]. Place the window nearest the bed carefully so that it frames a view which tells a person waking what the weather is like - [[Natural Doors and Windows (221)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 656.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Private-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/small-meeting-rooms-151.md ===== -->

---
title: "Small Meeting Rooms (151)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 151
pattern_name: "Small Meeting Rooms"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Meeting%20Rooms%20%28151%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "University as a Marketplace (43)"
  - "Local Town Hall (44)"
  - "Master and Apprentices (83)"
  - "Flexible Office Space (146)"
  - "Small Work Groups (148)"
  - "Light on Two Sides of Every Room (159)"
  - "Sitting Circle (185)"
  - "Different Chairs (251)"
  - "Pools of Light (252)"
  - "The Shape of Indoor Space (191)"
---

# Small Meeting Rooms (151)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The larger meetings are, the less people get out of them. But institutions often put their money and attention into large meeting rooms and lecture halls.

### Solution
>Make at least 70 percent of all meeting rooms really small—for 12 people or less. Locate them in the most public parts of the building, evenly scattered among the workplaces.

### Related Patterns
... within organizations and workplaces - [[University as a Marketplace (43)]], [[Local Town Hall (44)]], [[Master and Apprentices (83)]], [[Flexible Office Space (146)]], [[Small Work Groups (148)]], there will, inevitably, be meeting rooms, group rooms, classrooms, of one kind or another. Investigation of meeting rooms shows that the best distribution - both by size and by position - is rather unexpected.

Shape meeting rooms like any other rooms, perhaps with special emphasis on the fact that there must be no glare - [[Light on Two Sides of Every Room (159)]] - and on the fact that the rooms should be roughly round or square, and not too long or narrow - [[Sitting Circle (185)]]. People will feel best if many of the chairs are different, to suit different temperaments and moods and shapes and sizes - [[Different Chairs (251)]]. A light over the table or over the center of the group will help tie people together - [[Pools of Light (252)]]. For the shape of the room in detail, start with [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 712.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/small-panes-239.md ===== -->

---
title: "Small Panes (239)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 239
pattern_name: "Small Panes"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Panes%20%28239%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Interior Windows (194)"
  - "Natural Doors and Windows (221)"
  - "Windows Which Open Wide (236)"
  - "Solid Doors with Glass (237)"
  - "Frames as Thickened Edges (225)"
  - "Filtered Light (238)"
  - "Half-Inch Trim (240)"
---

# Small Panes (239)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When plate glass windows became possible, people thought that they would put us more directly in touch with nature. In fact, they do the opposite.

### Solution
>Divide each window into small panes. These panes can be very small indeed, and should hardly ever be more than a foot square. To get the exact size of the panes, divide the width and height of the window by the number of panes. Then each window will have different sized panes according to its height and width.

### Related Patterns
... this pattern gives the glazing for the windows in [[Interior Windows (194)]], [[Natural Doors and Windows (221)]], [[Windows Which Open Wide (236)]], and [[Solid Doors with Glass (237)]]. In most cases, the glazing can be built as a continuation of the [[Frames as Thickened Edges (225)]].

In certain cases you may want to make the small panes even finer near the window edge, to filter the light around the upper edge of windows which stand out against the sky - [[Filtered Light (238)]]. As for the muntins, they can be made from the same materials as trim - [[Half-Inch Trim (240)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1108.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/small-parking-lots-103.md ===== -->

---
title: "Small Parking Lots (103)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 103
pattern_name: "Small Parking Lots"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Parking%20Lots%20%28103%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Shopping Street (32)"
  - "House Cluster (37)"
  - "Work Community (41)"
  - "Green Streets (51)"
  - "Main Gateways (53)"
  - "Circulation Realms (98)"
  - "Shielded Parking (97)"
  - "Nine Per Cent Parking (22)"
  - "Positive Outdoor Space (106)"
  - "Tree Places (171)"
  - "Garden Wall (173)"
---

# Small Parking Lots (103)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Vast parking lots wreck the land for people.

### Solution
>Make parking lots small, serving no more than five to seven cars, each lot surrounded by garden walls, hedges, fences, slopes, and trees, so that from outside the cars are almost invisible. Space these small lots so that they are at least 100 feet apart.

### Related Patterns
... since a small parking lot is a kind of gateway - the place - where you leave your car, and enter a pedestrian realm - this pattern helps to complete [[Shopping Street (32)]], [[House Cluster (37)]], [[Work Community (41)]], [[Green Streets (51)]], [[Main Gateways (53)]], [[Circulation Realms (98)]], and any other areas which need small and convenient amounts of parking. But above all, if it, is used correctly, this pattern, together with [[Shielded Parking (97)]], will help to generate [[Nine Per Cent Parking (22)]] gradually, by increments.

Place entrances and exits of the parking lots in such a way that they fit naturally into the pattern of pedestrian movement and lead directly, without confusion, to the major entrances to individual buildings - [[Circulation Realms (98)]]. Shield even these quite modest parking lots with garden walls, and trees, and fences, so that they help to generate the space around them - [[Positive Outdoor Space (106)]], [[Tree Places (171)]], [[Garden Wall (173)]]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 503.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Group-of-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/small-public-squares-61.md ===== -->

---
title: "Small Public Squares (61)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 61
pattern_name: "Small Public Squares"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Public%20Squares%20%2861%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Activity Nodes (30)"
  - "Promenade (31)"
  - "Work Community (41)"
  - "Identifiable Neighborhood (14)"
  - "Pedestrian Density (123)"
  - "Activity Pockets (124)"
  - "Positive Outdoor Space (106)"
  - "Hierarchy of Open Space (114)"
  - "Building Fronts (122)"
  - "Stair Seats (125)"
  - "Something Roughly in the Middle (126)"
---

# Small Public Squares (61)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A town needs public squares; they are the largest, most public, rooms that the town has. But when they are too large, they look and feel deserted.

### Solution
>Make a public square much smaller than you would at first imagine; usually no more than 45 to 60 feet across, never more than 70 feet across. This applies only to its width in the short direction. In the long direction it can certainly be longer.

### Related Patterns
... this pattern forms the core which makes an [[Activity Nodes (30)]]: it can also help to generate a node, by its mere existence, provided that it is correctly placed along the intersection of the paths which people use most often. And it can also help to generate a [[Promenade (31)]], a [[Work Community (41)]], an [[Identifiable Neighborhood (14)]], through the action of the people who gather there. But it is essential, in every case, that it is not too large.

An even better estimate for the size of the square: make a guess about the number of people who will typically be there (say, P), and make the area of the square no greater than 150 to 300P square feet - [[Pedestrian Density (123)]]; ring the square around with pockets of activity where people congregate - [[Activity Pockets (124)]] ; build buildings round the square in such a way that they give it a definite shape, with views out into other larger places - [[Positive Outdoor Space (106)]], [[Hierarchy of Open Space (114)]], [[Building Fronts (122)]], [[Stair Seats (125)]]; and to make the center of the square as useful as the edges, build [[Something Roughly in the Middle (126)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 310.
> #APL/confidence/high
>
> #APL/Town-Patterns/Community-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/small-services-without-red-tape-81.md ===== -->

---
title: "Small Services Without Red Tape (81)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 81
pattern_name: "Small Services Without Red Tape"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Services%20Without%20Red%20Tape%20%2881%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Work Community (41)"
  - "University as a Marketplace (43)"
  - "Local Town Hall (44)"
  - "Health Center (47)"
  - "Teenage Society (84)"
  - "Office Connections (82)"
  - "Building Complex (95)"
  - "Building Thoroughfare (101)"
  - "Family of Entrances (102)"
  - "Necklace of Community Projects (45)"
  - "Flexible Office Space (146)"
  - "Small Work Groups (148)"
---

# Small Services Without Red Tape (81)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Departments and public services don’t work if they are too large. When they are large, their human qualities vanish; they become bureaucratic; red tape takes over.

### Solution
>In any institution whose departments provide public service:

>1. Make each service or department autonomous as far as possible.
>2. Allow no one service more than 12 staff members total.
>3. House each one in an identifiable piece of the building.
>4. Give each one direct access to a public thoroughfare.

### Related Patterns
... all offices which provide service to the public - [[Work Community (41)]], [[University as a Marketplace (43)]], [[Local Town Hall (44)]],[[Health Center (47)]], [[Teenage Society (84)]] need subsidiary departments, where the members of the public go. And of course, piecemeal development of these small departments, one department at a time, can also help to generate these larger patterns gradually.

Arrange these departments in space, according to the prescription of - [[Office Connections (82)]] and [[Building Complex (95)]]; if the public thoroughfare is indoors, make it a [[Building Thoroughfare (101)]], and make the fronts of the services visible as a [[Family of Entrances (102)]]; wherever the services are in any way connected to the political life of the community, mix them with ad hoc groups created by the citizens or users [[Necklace of Community Projects (45)]]; arrange the inside space of the department according to [[Flexible Office Space (146)]]; and provide rooms where people can team up in two's and three's - [[Small Work Groups (148)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 404.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/small-work-groups-148.md ===== -->

---
title: "Small Work Groups (148)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 148
pattern_name: "Small Work Groups"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Small%20Work%20Groups%20%28148%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Self-Governing Workshops and Offices (80)"
  - "Flexible Office Space (146)"
  - "Office Connections (82)"
  - "Common Areas at the Heart (129)"
  - "Master and Apprentices (83)"
  - "Open Stairs (158)"
  - "Half-Private Office (152)"
  - "Workspace Enclosure (183)"
---

# Small Work Groups (148)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When more than half a dozen people work in the same place, it is essential that they not be forced to work in one huge undifferentiated space, but that instead, they can divide their workspace up, and so form smaller groups.

### Solution
>Break institutions into small, spatially identifiable work groups, with less than half a dozen people in each. Arrange these work groups so that each person is in at least partial view of the other members of their own group; and arrange several groups in such a way that they share a common entrance, food, office equipment, drinking fountains, bathrooms.

### Related Patterns
... within the workspace of an institution - [[Self-Governing Workshops and Offices (80)]], [[Flexible Office Space (146)]], there need to be still further subdivisions. Above all, as this pattern shows, it is essential that the smallest human working groups each have their own physical space.

Lay the workgroups out with respect to each other so that the distances between groups is within the constraints of [[Office Connections (82)]], and give each group office space which leaves room to expand and to contract - [[Flexible Office Space (146)]]; provide a common area, either for the group itself or for several groups together or both - [[Common Areas at the Heart (129)]]. Treat each small work group, in every kind of industry and office, as a place of learning - [[Master and Apprentices (83)]]. Give it its own stair, directly to the street - [[Open Stairs (158)]]. Arrange the individual workspaces within the small work group according to [[Half-Private Office (152)]] and [[Workspace Enclosure (183)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 701.
> #APL/confidence/high
>
> #APL/Building-Patterns/Public-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/soft-inside-walls-235.md ===== -->

---
title: "Soft Inside Walls (235)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 235
pattern_name: "Soft Inside Walls"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Soft%20Inside%20Walls%20%28235%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Wall Membranes (218)"
  - "Floor-Ceiling Vaults (219)"
  - "Half-Inch Trim (240)"
---

# Soft Inside Walls (235)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A wall which is too hard or too cold or too solid is unpleasant to touch; it makes decoration impossible, and creates hollow echoes.

### Solution
>Make every inside surface warm to the touch, soft enough to take small nails and tacks, and with a certain slight “give” to the touch. Soft plaster is very good; textile hangings, canework, weavings, also have this character. And wood is fine, where you can afford it.

### Related Patterns
... and this pattern finishes the inner surface of the [[Wall Membranes (218)]], and the under surface of [[Floor-Ceiling Vaults (219)]]. If it is possible to use a soft material for the inner sheet of the wall membrane, then the wall will have the right character built in from the beginning.

In our own building system, we find it is worth putting on a light skim coat of plaster over the inner surfaces of the [[Wall Membranes (218)]] and [[Floor-Ceiling Vaults (219)]]. Wherever finish plaster meets columns, and beams, and doors and window frames, cover the joint with [[Half-Inch Trim (240)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1096.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/soft-tile-and-brick-248.md ===== -->

---
title: "Soft Tile and Brick (248)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 248
pattern_name: "Soft Tile and Brick"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Soft%20Tile%20and%20Brick%20%28248%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Connection to the Earth (168)"
  - "Good Materials (207)"
  - "Floor Surface (233)"
  - "Sitting Wall (243)"
  - "Paving With Cracks Between the Stones (247)"
  - "Warm Colors (250)"
  - "Ornament (249)"
---

# Soft Tile and Brick (248)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>How can a person feel the earth, or time, or any connection with his surroundings, when he is walking on the hard mechanical wash-easy surfaces of concrete, asphalt, hard-fired architectural paving bricks, or artificially concocted mixes like terrazo?

### Solution
>Use bricks and tiles which are soft baked, low fired—so that they will wear with time, and show the marks of use.
>You can make them in a simple mold from local clay, right on the site; surround the stack with twigs and firewood; and fire them, to a soft pink color which will leave them soft enough to wear with time.

### Related Patterns
... several patterns call for the use of tiles and bricks - [[Connection to the Earth (168)]], [[Good Materials (207)]], [[Floor Surface (233)]], [[Sitting Wall (243)]], [[Paving With Cracks Between the Stones (247)]].

The soft pink color helps to create [[Warm Colors (250)]]. Before firing, you may want to give the tiles some [[Ornament (249)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1141.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Outdoor-Details


<!-- ===== pattern-language/wiki/concepts/patterns/solid-doors-with-glass-237.md ===== -->

---
title: "Solid Doors with Glass (237)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 237
pattern_name: "Solid Doors with Glass"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Solid%20Doors%20with%20Glass%20%28237%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Corner Doors (196)"
  - "Low Doorway (224)"
  - "Tapestry of Light and Dark (135)"
  - "Interior Windows (194)"
  - "Small Panes (239)"
  - "Wall Membranes (218)"
---

# Solid Doors with Glass (237)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>An opaque door makes sense in a vast house of palace, where every room is large enough to be a world unto itself; but in a small building, with small rooms, the opaque door is only very rarely useful.

### Solution
>As often as possible build doors with glazing in them, so that the upper half at least, allows you to see through them. At the same time, build the doors solid enough, so that they give acoustic isolation and make a comfortable “thunk” when they are closed.

### Related Patterns
... this pattern finishes the doors defined by [[Corner Doors (196)]] and [[Low Doorway (224)]]. It also helps to finish [[Tapestry of Light and Dark (135)]] and [[Interior Windows (194)]], since it requires glazing in the doors, and can help to create daylight in the darker parts of indoor places.

Glaze the door with small panes of glass - [[Small Panes (239)]] and make the doors more solid, by building them like [[Wall Membranes (218)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1103.
> #APL/confidence/low
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/something-roughly-in-the-middle-126.md ===== -->

---
title: "Something Roughly in the Middle (126)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 126
pattern_name: "Something Roughly in the Middle"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Something%20Roughly%20in%20the%20Middle%20%28126%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Small Public Squares (61)"
  - "Common Land (67)"
  - "Courtyards Which Live (115)"
  - "Path Shape (121)"
  - "Activity Pockets (124)"
  - "Stair Seats (125)"
  - "Paths and Goals (120)"
  - "High Places (62)"
  - "Dancing in the Street (63)"
  - "Pools and Streams (64)"
  - "Public Outdoor Room (69)"
  - "Still Water (71)"
  - "Tree Places (171)"
  - "Sitting Wall (243)"
---

# Something Roughly in the Middle (126)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A public space without a middle is quite likely to stay empty.

### Solution
>Between the natural paths which cross a public square or courtyard or a piece of common land, choose something to stand roughly in the middle: a fountain, a tree, a statue, a clock-tower with seats, a windmill, a bandstand. Make it something which gives a strong and steady pulse to the square, drawing people in toward the center. Leave it exactly where it falls between the paths; resist the impulse to put it exactly in the middle.

### Related Patterns
... [[Small Public Squares (61)]], [[Common Land (67)]], [[Courtyards Which Live (115)]], [[Path Shape (121)]] all draw their life from the activities around their edges - [[Activity Pockets (124)]] and [[Stair Seats (125)]]. But even then, the middle is still empty, and it needs embellishment.

Connect the different "somethings" to one another with the path system - [[Paths and Goals (120)]]. They may include [[High Places (62)]], [[Dancing in the Street (63)]], [[Pools and Streams (64)]], [[Public Outdoor Room (69)]], [[Still Water (71)]], [[Tree Places (171)]]; make sure that each one has a [[Sitting Wall (243)]] around it ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 606.
> #APL/confidence/low
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/south-facing-outdoors-105.md ===== -->

---
title: "South Facing Outdoors (105)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 105
pattern_name: "South Facing Outdoors"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/South%20Facing%20Outdoors%20%28105%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Site Repair (104)"
  - "Half-Hidden Garden (111)"
  - "Positive Outdoor Space (106)"
  - "Wings of Light (107)"
  - "Indoor Sunlight (128)"
  - "North Face (162)"
  - "Sunny Place (161)"
---

# South Facing Outdoors (105)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People use open space if it is sunny, and do not use it if it isn’t, in all but desert climates.

### Solution
>Always place buildings to the north of the outdoor spaces that go with them, and keep the outdoor spaces to the south. Never leave a deep band of shade between the building and the sunny part of the outdoors.

### Related Patterns
... within the general ideas of location which [[Site Repair (104)]] creates, this pattern governs the fundamental placing of the building and the open space around it with respect to sun.

Let [[Half-Hidden Garden (111)]] influence the position of the outdoors too. Make the outdoor spaces positive - [[Positive Outdoor Space (106)]] - and break the building into narrow wings - [[Wings of Light (107)]]. Keep the most important rooms to the south of these wings - [[Indoor Sunlight (128)]] and keep storage, parking, etc, to the north - [[North Face (162)]]. When the building is more developed, you can concentrate on the special sunny areas where the outdoors and building meet, and make definite places there, where people can sit in the sun - [[Sunny Place (161)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 513.
> #APL/confidence/high
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/stair-seats-125.md ===== -->

---
title: "Stair Seats (125)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 125
pattern_name: "Stair Seats"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Stair%20Seats%20%28125%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Small Public Squares (61)"
  - "Positive Outdoor Space (106)"
  - "Path Shape (121)"
  - "Family of Entrances (102)"
  - "Main Entrance (110)"
  - "Open Stairs (158)"
  - "Seat Spots (241)"
  - "Soft Tile and Brick (248)"
  - "Connection to the Earth (168)"
---

# Stair Seats (125)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Wherever there is action in a place, the spots which are the most inviting are those high enough to give people a vantage point, and low enough to put them in action.

### Solution
>In any public place where people loiter, add a few steps at the edge where stairs come down or where there is a change of level. Make these raised areas immediately accessible from below, so that people may congregate and sit to watch the goings-on.

### Related Patterns
... we know that paths and larger public gathering places need a definite shape and a degree of enclosure, with people looking into them, not out of them - [[Small Public Squares (61)]], [[Positive Outdoor Space (106)]], [[Path Shape (121)]]. Stairs around the edge do it just perfectly; and they also help embellish [[Family of Entrances (102)]], [[Main Entrance (110)]], and [[Open Stairs (158)]].

Give the stair seats the same orientation as [[Seat Spots (241)]]. Make the steps out of wood or tile or brick so that they wear with time, and show the marks of feet, and are soft to the touch for people sitting on them - [[Soft Tile and Brick (248)]]; and make the steps connect directly to surrounding buildings - [[Connection to the Earth (168)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 603.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Between-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/stair-vault-228.md ===== -->

---
title: "Stair Vault (228)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 228
pattern_name: "Stair Vault"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Stair%20Vault%20%28228%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Floor-Ceiling Vaults (219)"
  - "Staircase as a Stage (133)"
  - "Staircase Volume (195)"
  - "Efficient Structure (206)"
  - "Good Materials (207)"
  - "Floor Surface (233)"
  - "Soft Tile and Brick (248)"
  - "Alcoves (179)"
  - "Child Caves (203)"
  - "Closets Between Rooms (198)"
---

# Stair Vault (228)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Within a building technology which uses compressive materials as much as possible, and excludes the use of wood, it is natural to build stairs over a vaulted void, simply to save weight and materials.

### Solution
>Build a curved diagonal vault in the same way that you build your [[Floor-Ceiling Vaults (219)]]. Once the vault hardens, cover it with steps of lightweight concrete, trowel-formed into position.

### Related Patterns
... this pattern helps complete the rough shape and location of stairs given by [[Staircase as a Stage (133)]] and by [[Staircase Volume (195)]]. If you want to build a conventional stair, you can find what you need in any handbook. But how to build a stair in a way which is consistent with the compressive structure of [[Efficient Structure (206)]], without using wood or steel or concrete - [[Good Materials (207)]]?

A lightweight concrete tread, colored, waxed, and polished can be quite beautiful and soft enough to be comfortable - see [[Floor Surface (233)]] - and will eventually take on the patina of wear called for in [[Soft Tile and Brick (248)]].

The vaulted space under the stair can be used as an [[Alcoves (179)]], a [[Child Caves (203)]], or [[Closets Between Rooms (198)]]. If it is plastered, like a regular ceiling - see [[Floor-Ceiling Vaults (219)]], it makes a much more pleasant and useful space than the space under an ordinary stair.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1073.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Frame-Adjustments


<!-- ===== pattern-language/wiki/concepts/patterns/staircase-as-a-stage-133.md ===== -->

---
title: "Staircase as a Stage (133)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 133
pattern_name: "Staircase as a Stage"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Staircase%20as%20a%20Stage%20%28133%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Main Entrance (110)"
  - "The Flow Through Rooms (131)"
  - "Short Passages (132)"
  - "Stair Seats (125)"
  - "Zen View (134)"
  - "Tapestry of Light and Dark (135)"
  - "Staircase Volume (195)"
  - "The Shape of Indoor Space (191)"
---

# Staircase as a Stage (133)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A staircase is not just a way of getting from one floor to another. The stair is itself a space, a volume, a part of the building; and unless this space is made to live, it will be a dead spot, and work to disconnect the building and to tear its processes apart.

### Solution
>Place the main stair in a key position, central and visible. Treat the whole staircase as a room (or if it is outside, as a courtyard). Arrange it so that the stair and the room are one, with the stair coming down around one or two walls of the room. Flare out the bottom of the stair with open windows or balustrades and with wide steps so that the people coming down the stair become part of the action in the room while they are on the stair, and so that people below will naturally use the stair for seats.

### Related Patterns
... if the entrances are in position - [[Main Entrance (110)]]; and the pattern of movement through the building is established - [[The Flow Through Rooms (131)]], [[Short Passages (132)]], the main stairs must be put in and given an appropriate social character.

Treat the bottom steps as [[Stair Seats (125)]]; provide a window or a view half-way up the stair, both to light the stair and to create a natural focus of attention - [[Zen View (134)]], [[Tapestry of Light and Dark (135)]]; remember to calculate the length and shape of the stair while you are working out its position - [[Staircase Volume (195)]]. Get the final shape of the staircase room and the beginnings of its construction from [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 637.
> #APL/confidence/low
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/staircase-volume-195.md ===== -->

---
title: "Staircase Volume (195)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 195
pattern_name: "Staircase Volume"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Staircase%20Volume%20%28195%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Staircase as a Stage (133)"
  - "Open Stairs (158)"
  - "Columns at the Corners (212)"
  - "Stair Vault (228)"
  - "Child Caves (203)"
  - "Stair Seats (125)"
---

# Staircase Volume (195)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We are putting this pattern in the language because our experiments have shown us that lay people often make mistakes about the volume which a staircase needs and therefore make their plans unbuildable.

### Solution
>Make a two story volume to contain the stairs. It may be straight, L-shapes, U-shapes, or C-shapes. The stair may be 2 feet wide (for a very steep stair) or 5 feet wide for a generous shallow stair. But, in all cases, the entire stairwell must form one complete structural bay, two stories high.
>Do not assume that all stairs have to have the “standard” angle of 30 degrees. The steepest stair may almost be a ladder. The most generous stair can be as shallow as a ramp and quite wide. As you work out the exact slope of your stair, bear in mind the relationship: riser + tread = 17 1/2 inches.

### Related Patterns
... [[Staircase as a Stage (133)]] and [[Open Stairs (158)]] will tell you roughly where to place the various stairs, both indoors and outdoors. This pattern gives each stair exact dimensions and treats it like a room so that it becomes realistic in the plan.

Construct the staircase as a vault, within a space defined by columns, just like every other room - [[Columns at the Corners (212)]], [[Stair Vault (228)]]. And make the most of the staircase; underneath it is a place where the children can play and hide - [[Child Caves (203)]]; and it is a place to sit and talk - [[Stair Seats (125)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 900.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/still-water-71.md ===== -->

---
title: "Still Water (71)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 71
pattern_name: "Still Water"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Still%20Water%20%2871%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Access to Water (25)"
  - "Pools and Streams (64)"
  - "House Cluster (37)"
  - "Work Community (41)"
  - "Health Center (47)"
  - "Common Land (67)"
  - "Local Sports (72)"
  - "South Facing Outdoors (105)"
  - "Public Outdoor Room (69)"
  - "Trellised Walk (174)"
  - "Sitting Wall (243)"
---

# Still Water (71)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>To be in touch with water, we must above all be able to swim; and to swim daily, the pools and ponds and holes for swimming must be so widely scattered through the city, that each person can reach one within minutes.

### Solution
>In every neighborhood, provide some still water—a pond, a pool—for swimming. Keep the pool open to the public at all times, but make the entrance to the pool only from the shallow side of the pool, and make the pool deepen gradually, starting from one or two inches deep.

### Related Patterns
... the patterns [[Access to Water (25)]] and [[Pools and Streams (64)]] provide a variety of kinds of water throughout the community. This pattern helps to embellish the still waters - the pools and ponds and, swimming holes - and provide them with a safe edge for children. It also helps to differentiate the public space in [[House Cluster (37)]], [[Work Community (41)]], [[Health Center (47)]], [[Common Land (67)]], [[Local Sports (72)]].

If possible, arrange the pool as part of a system of natural running water, so that it purifies itself, and does not have to be chlorinated - [[Pools and Streams (64)]]. Make sure the pool has southern exposure - [[South Facing Outdoors (105)]]. If possible, embellish the edge of the pool with a small outdoor room or trellis, where people can sit and watch - [[Public Outdoor Room (69)]], [[Trellised Walk (174)]], [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 358.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Recreation


<!-- ===== pattern-language/wiki/concepts/patterns/street-cafe-88.md ===== -->

---
title: "Street Cafe (88)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 88
pattern_name: "Street Cafe"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Street%20Cafe%20%2888%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Identifiable Neighborhood (14)"
  - "Activity Nodes (30)"
  - "Small Public Squares (61)"
  - "Opening to the Street (165)"
  - "A Place to Wait (150)"
  - "Different Chairs (251)"
  - "Stair Seats (125)"
  - "Sitting Wall (243)"
  - "Canvas Roofs (244)"
  - "Building Complex (95)"
---

# Street Cafe (88)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The street cafe provides a unique setting, special to cities: a place where people can sit lazily, legitimately, be on view, and watch the world go by.

### Solution
>Encourage local cafes to spring up in each neighborhood. Make them intimate places, with several rooms, open to a busy path, where people can sit with coffee or a drink and watch the world go by. Build the front of the cafe so that a set of tables stretch out of the cafe, right into the street.

### Related Patterns
... neighborhoods are defined by I[[Identifiable Neighborhood (14)]]; their natural points of focus are given by [[Activity Nodes (30)]] and [[Small Public Squares (61)]]. This pattern, and the ones which follow it, give the neighborhood and its points of focus, their identity.

Build a wide, substantial opening between the terrace and the indoors - [[Opening to the Street (165)]]; make the terrace double as [[A Place to Wait (150)]] for nearby bus stops and offices; both indoors and on the terrace use a great variety of different kinds of chairs and tables - [[Different Chairs (251)]]; and give the terrace some low definition at the street edge if it is in danger of being interrupted by street action - [[Stair Seats (125)]], [[Sitting Wall (243)]], perhaps a [[Canvas Roofs (244)]]. For the shape of the building, the terrace, and the surroundings, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 436.
> #APL/confidence/high
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/street-windows-164.md ===== -->

---
title: "Street Windows (164)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 164
pattern_name: "Street Windows"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Street%20Windows%20%28164%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Green Streets (51)"
  - "Small Public Squares (61)"
  - "Pedestrian Street (100)"
  - "Building Thoroughfare (101)"
  - "Window Place (180)"
  - "Windows Which Open Wide (236)"
  - "Filtered Light (238)"
  - "Climbing Plants (246)"
---

# Street Windows (164)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>A street without windows is blind and frightening. And it is equally uncomfortable to be in a house which bounds a public street with no window at all on the street.

### Solution
>Where buildings run alongside busy streets, build windows with window seats, looking out onto the street. Place them in bedrooms or at some point on a passage or stair, where people keep passing by. On the first floor, keep these windows high enough to be private.

### Related Patterns
... wherever there are [[Green Streets (51)]], [[Small Public Squares (61)]], [[Pedestrian Street (100)]], [[Building Thoroughfare (101)]] - in short, any streets with people in them, these streets will only come to life if they are helped to do so by the people looking out on them, hanging out of windows, laughing, shouting, whistling.

On the inside, give each of these windows a substantial place, so that a person feels encouraged to sit there or stand and watch the street - [[Window Place (180)]]; make the windows open outward - [[Windows Which Open Wide (236)]]; enrich the outside of the window with flower boxes and climbing plants - then people, in the course of caring for the flowers, will have the opportunity for hanging out - [[Filtered Light (238)]], [[Climbing Plants (246)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 769.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/structure-follows-social-spaces-205.md ===== -->

---
title: "Structure Follows Social Spaces (205)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 205
pattern_name: "Structure Follows Social Spaces"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Structure%20Follows%20Social%20Spaces%20%28205%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Columns at the Corners (212)"
  - "Floor-Ceiling Vaults (219)"
  - "Efficient Structure (206)"
  - "Good Materials (207)"
  - "Gradual Stiffening (208)"
---

# Structure Follows Social Spaces (205)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>No building ever feels right to the people in it unless the physical spaces (defined by columns, walls, and ceilings) are congruent with the social spaces (defined by activities and human groups).

### Solution
>A first principle of construction: on no account allow the engineering to dictate the building’s form. Place the load bearing elements—the columns and the walls and floors—according to the social space of the building; never modify the social spaces to conform to the engineering structure of the building.

### Related Patterns
... if you have used the, earlier patterns in the language, your plans are based on subtle arrangements of social spaces. But the beauty and subtlety of all these social spaces will be destroyed, when you start building, unless you find a way of building which is able to follow the social spaces without distorting or rearranging them for engineering reasons.

This pattern gives you the beginning of such a way of building. It is the first of the 49 patterns which deal specifically with structure and construction; it is the bottleneck through which all languages pass from the larger patterns for rooms and building layout to the smaller ones which specify the process of construction. It not only has its own intrinsic arguments about the relation between social spaces and load-bearing structure - it also contains, at the end, a list of all the connections which you need for patterns on structure, columns, walls, floors, roofs, and all the details of construction.

You will be able to guarantee that structure follows social spaces by placing columns at the corner of every social space - [[Columns at the Corners (212)]]; and by building a distinct and separate vault over each room and social space - [[Floor-Ceiling Vaults (219)]].

For the principles of structure which will make it possible to build your building according to this pattern, begin with [[Efficient Structure (206)]]; for the class of compatible materials, see [[Good Materials (207)]]; for the fundamentals of the process of construction, see [[Gradual Stiffening (208)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 940.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Emergent-Structure


<!-- ===== pattern-language/wiki/concepts/patterns/subculture-boundary-13.md ===== -->

---
title: "Subculture Boundary (13)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 13
pattern_name: "Subculture Boundary"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Subculture%20Boundary%20%2813%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Community of 7000 (12)"
  - "Identifiable Neighborhood (14)"
  - "The Countryside (7)"
  - "Sacred Sites (24)"
  - "Access to Water (25)"
  - "Pools and Streams (64)"
  - "Still Water (71)"
  - "Ring Roads (17)"
  - "Parallel Roads (23)"
  - "Work Community (41)"
  - "Industrial Ribbon (42)"
  - "Teenage Society (84)"
  - "Shielded Parking (97)"
  - "Activity Nodes (30)"
  - "Eccentric Nucleus (28)"
---

# Subculture Boundary (13)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The mosaic of subcultures requires that hundreds of different cultures live, in their own way, at full intensity, next door to one another. But subcultures have their own ecology. They can only live at full intensity, unhampered by their neighbors, if they are physically separated by physical boundaries.

### Solution
>Separate neighboring subcultures with a swath of land at least 200 feet wide. Let this boundary be natural—wilderness, farmland, water—or man-made—railroads, major roads, parks, schools, some housing. Along the seam between two subcultures, build meeting places, share functions, touching each community.

### Related Patterns
... the [[Mosaic of Subcultures (8)]] and its individual subcultures, whether they are a [[Community of 7000 (12)]] or an [[Identifiable Neighborhood (14)]], need to be completed by boundaries. In fact, the mere creation of the boundary areas, according to this pattern, will begin to give life to the subcultures between the boundaries, by giving them a chance to be themselves.

Natural boundaries can be things like [[The Countryside (7)]], [[Sacred Sites (24)]], [[Access to Water (25)]], [[Pools and Streams (64)]], [[Still Water (71)]]. Artificial boundaries can include [[Ring Roads (17)]], [[Parallel Roads (23)]], [[Work Community (41)]], [[Industrial Ribbon (42)]], [[Teenage Society (84)]], [[Shielded Parking (97)]]. The interior organization of the subculture boundary should follow two broad principles. It should concentrate the various land uses to form functional clusters around activity -- [[Activity Nodes (30)]], [[Work Community (41)]]. And the boundary should be accessible to both the neighboring communities, so that it is a meeting ground for them. -- [[Eccentric Nucleus (28)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 75
> #APL/confidence/medium
>
> #APL/Town-Patterns/Communities


<!-- ===== pattern-language/wiki/concepts/patterns/sunny-counter-199.md ===== -->

---
title: "Sunny Counter (199)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 199
pattern_name: "Sunny Counter"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sunny%20Counter%20%28199%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Farmhouse Kitchen (139)"
  - "Cooking Layout (184)"
  - "Indoor Sunlight (128)"
  - "Windows Overlooking Life (192)"
  - "Open Shelves (200)"
  - "Thickening the Outer Walls (211)"
  - "Warm Colors (250)"
---

# Sunny Counter (199)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Dark, gloomy kitchens are depressing. The kitchen needs the sun more than the other rooms, not less.

### Solution
>Place the main part of the kitchen counter on the south and southeast side of the kitchen, with big windows around it, so that sun can flood in and fill the kitchen with yellow light both morning and afternoon.

### Related Patterns
... [[Farmhouse Kitchen (139)]] and [[Cooking Layout (184)]] give the overall design of the kitchen, and its workspace. [[Indoor Sunlight (128)]] makes sure of sunshine in the kitchen. But to help create these larger patterns, and to make the kitchen as warm and beautiful as possible, it is worth taking a great deal of care placing the counter and its windows.

Give the windows a view toward a garden or the area where children play - [[Windows Overlooking Life (192)]]. If storage space is tight, you can build open shelves for bowls and plates and plants right across the windows and still let in the sun - [[Open Shelves (200)]]. Build the counter as a special part of the room, integral with the building structure, able to take many modifications later - [[Thickening the Outer Walls (211)]]. Use [[Warm Colors (250)]] around the window to soften and warm the sunlight.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 916.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/sunny-place-161.md ===== -->

---
title: "Sunny Place (161)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 161
pattern_name: "Sunny Place"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Sunny%20Place%20%28161%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "South Facing Outdoors (105)"
  - "Building Edge (160)"
  - "Outdoor Room (163)"
  - "Private Terrace on the Street (140)"
  - "Six-Foot Balcony (167)"
  - "Filtered Light (238)"
  - "Trellised Walk (174)"
  - "Canvas Roofs (244)"
  - "Seat Spots (241)"
---

# Sunny Place (161)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The area immediately outside the building, to the south—that angle between its walls and the earth where the sun falls—must be developed and made into a place which lets people bask in it.

### Solution
>Inside the south-facing court, or garden, or yard, find the spot between the building and the outdoors which gets the best sun. Develop this spot as a special sunny place—make it the important outdoor room, a place to work in the sun, or a place for a swing and some special plants, a place to sunbathe. Be very careful indeed to place the sunny place in a position where it is sheltered from the wind. A steady wind will prevent you from using the most beautiful place.

### Related Patterns
... this pattern helps to embellish and give life to any [[South Facing Outdoors (105)]]; and, in a situation where the outdoors is not to the south, but east or west, it can help to modify the building so that the effective part of the outdoors moves towards the south. It also helps to complete [[Building Edge (160)]], and to place [[Outdoor Room (163)]].

Make the place itself as much as possible like a room - [[Private Terrace on the Street (140)]], [[Outdoor Room (163)]]; always at least six feet deep, no less - [[Six-Foot Balcony (167)]]; perhaps with foliage or a canvas to filter the light on hot days - [[Filtered Light (238)]], [[Trellised Walk (174)]], [[Canvas Roofs (244)]]. Put in seats according to [[Seat Spots (241)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 757.
> #APL/confidence/high
>
> #APL/Building-Patterns/Liminal-Space


<!-- ===== pattern-language/wiki/concepts/patterns/t-junctions-50.md ===== -->

---
title: "T Junctions (50)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 50
pattern_name: "T Junctions"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/T%20Junctions%20%2850%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Parallel Roads (23)"
  - "Looped Local Roads (49)"
  - "Road Crossing (54)"
---

# T Junctions (50)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Traffic accidents are far more frequent where two roads cross than at T Junctions.

### Solution
>Lay out the road system so that any two roads which meet at grade, meet in three-way T junctions as near to 90 degrees as possible. Avoid four-way intersections and crossing movements.

### Related Patterns
... if major roads are in position -- [[Parallel Roads (23)]], and you are in the process of defining the local roads, this pattern gives the nature of the intersections. It will also greatly influence the layout of local roads, and will help to generate their loop-like character -- [[Looped Local Roads (49)]].

At busy junctions, where pedestrian paths converge, make a special raised crossing for pedestrians, something more than the usual crosswalk -- [[Road Crossing (54)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 264.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Local-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/tapestry-of-light-and-dark-135.md ===== -->

---
title: "Tapestry of Light and Dark (135)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 135
pattern_name: "Tapestry of Light and Dark"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Tapestry%20of%20Light%20and%20Dark%20%28135%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Flow Through Rooms (131)"
  - "Short Passages (132)"
  - "Staircase as a Stage (133)"
  - "Zen View (134)"
  - "Window Place (180)"
  - "Warm Colors (250)"
  - "Pools of Light (252)"
---

# Tapestry of Light and Dark (135)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In a building with uniform light level, there are few “places” which function as effective settings for human events. This happens because, to a large extent, the places which make effective settings are defined by light.

### Solution
>Create alternating areas of light and dark throughout the building, in such a way that people naturally walk toward the light, whenever they are going to important places: seats, entrances, stairs, passages, places of special beauty, and make other areas darker, to increase the contrast.

### Related Patterns
... passages, entrances, stairs arc given their rough position by [[The Flow Through Rooms (131)]], [[Short Passages (132)]], [[Staircase as a Stage (133)]], [[Zen View (134)]]. This pattern helps you fine tune their positions by placing light correctly.

Where the light to walk toward is natural light, build seats and alcoves in those windows which attract the movement - [[Window Place (180)]]. If you use skylights, then make the surfaces around the skylight warm in color - [[Warm Colors (250)]]; otherwise the direct light from the sky is almost always cold. At night make pools of incandescent light which guide the movement - [[Pools of Light (252)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 644.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/teenage-society-84.md ===== -->

---
title: "Teenage Society (84)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 84
pattern_name: "Teenage Society"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Teenage%20Society%20%2884%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Life Cycle (26)"
  - "Network of Learning (18)"
  - "Master and Apprentices (83)"
  - "Local Sports (72)"
  - "Communal Eating (147)"
  - "Home Workshop (157)"
  - "Building Complex (95)"
---

# Teenage Society (84)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Teenage is the time of passage between childhood and adulthood. In traditional societies, this passage is accompanied by rites which suit the psychological demands of the transition. But in modern society the “high school” fails entirely to provide this passage.

### Solution
>Replace the “high school” with an institution which is actually a model of adult society, in which the students take on most of the responsibility for learning and social life, with clearly defined roles and forms of discipline. Provide adult guidance, both for the learning, and the social structure of society; but keep them as far as feasible, in the hands of the students.

### Related Patterns
... the balanced [[Life Cycle (26)]] requires that the transition from childhood to adulthood be treated by a far more subtle and embracing kind of teenage institution than a school; this pattern, which begins to define that institution, can take its place in the [[Network of Learning (18)]] and help contribute to the network of [[Master and Apprentices (83)]].

Provide one central place which houses social functions, and a directory of classes in the community. Within the central place, provide communal eating for the students, opportunities for sports and games, a library and counseling for the network of learning which gives the students access to the classes, work communities, and home workshops that are scattered through the town - [[Network of Learning (18)]], [[Local Sports (72)]], [[Communal Eating (147)]], [[Home Workshop (157)]]; for the shape of what buildings there are, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 416.
> #APL/confidence/low
>
> #APL/Town-Patterns/Social-Institutions---Workgroups


<!-- ===== pattern-language/wiki/concepts/patterns/teenagers-cottage-154.md ===== -->

---
title: "Teenager's Cottage (154)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 154
pattern_name: "Teenager's Cottage"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Teenager%27s%20Cottage%20%28154%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "A Room of One's Own (141)"
  - "Rooms to Rent (153)"
  - "Sitting Circle (185)"
  - "Bed Alcove (188)"
  - "Home Workshop (157)"
  - "Open Stairs (158)"
  - "The Shape of Indoor Space (191)"
  - "Structure Follows Social Spaces (205)"
---

# Teenager's Cottage (154)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If a teenager’s place in the home does not reflect their need for a measure of independence, they will be locked in conflict with their family.

### Solution
>To mark a child’s coming of age, transform their place in the home into a kind of cottage that expresses in a physical way the beginnings of independence. Keep the cottage attached to the home, but make it a distinctly visible bulge, far away from the master bedroom, with its own private entrance, perhaps its own roof.

### Related Patterns
...  in any house which has teenagers in it - [[The Family (75)]], [[House for a Small Family (76)]] - it is necessary to give special consideration to their rooms - [[A Room of One's Own (141)]]. If possible, these rooms should be attached but separate, and made to help create the possibility of later being [[Rooms to Rent (153)]].

Arrange the cottage to contain a [[Sitting Circle (185)]] and a [[Bed Alcove (188)]] but not a private bath and kitchen - sharing these is essential: it allows the boy or girl to keep enough connection with the family. Make it a place that can eventually become a guest room, room to rent, workshop, and so on - [[Rooms to Rent (153)]], [[Home Workshop (157)]]. If it is on an upper story, give it a separate private [[Open Stairs (158)]]. And for the shape of the cottage and its construction, start with [[The Shape of Indoor Space (191)]] and [[Structure Follows Social Spaces (205)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 723.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Outbuildings


<!-- ===== pattern-language/wiki/concepts/patterns/terraced-slope-169.md ===== -->

---
title: "Terraced Slope (169)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 169
pattern_name: "Terraced Slope"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Terraced%20Slope%20%28169%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Site Repair (104)"
  - "Building Edge (160)"
  - "Connection to the Earth (168)"
  - "Vegetable Garden (177)"
  - "Fruit Trees (170)"
  - "Raised Flowers (245)"
  - "Sitting Wall (243)"
---

# Terraced Slope (169)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>On sloping land, erosion caused by runoff can kill the soil. It also creates uneven distribution of rainwater over the land, which naturally does less for plant life than it could if it were unevenly distributed.

### Solution
>On all land which slopes—in fields, in parks, in public gardens, even in the private gardens around a house—make a system of terraces and bunds which follow the contour lines. Make them by building low walls along the contour lines, and then backfilling them with earth to form the terraces.

### Related Patterns
... this pattern helps to complete [[Site Repair (104)]]. Where there are buildings, it ties into the [[Building Edge (160)]] and can help form it; and it helps create the [[Connection to the Earth (168)]]. If the ground is sloping at all, this pattern tells you how to handle the slope of the ground in a way that makes sense for the people in the building, and for the plants and grasses on the ground.

Plant vegetables and orchards on the terraces - [[Vegetable Garden (177)]], [[Fruit Trees (170)]]; along the walls which form the terraces, plant flowers high enough to touch and smell - [[Raised Flowers (245)]]. And it is also very natural to make the walls so people can sit on them - [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 790.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/the-countryside-7.md ===== -->

---
title: "The Countryside (7)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 7
pattern_name: "The Countryside"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Countryside%20%287%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Distribution of Towns (2)"
  - "City Country Fingers (3)"
  - "Agricultural Valleys (4)"
  - "Lace of Country Streets (5)"
  - "Country Towns (6)"
  - "House Cluster (37)"
  - "Green Streets (51)"
---

# The Countryside (7)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>I conceive that land belongs for use to a vast family of which many are dead, few are living, and countless members are still unborn.
> -- a Nigerian tribesman

### Solution
>Define all farms as parks, where the public has a right to be; and make all regional parks into working farms.
>Create stewardships among groups of people, families and cooperatives, with each stewardship responsible for one part of the countryside. The stewards are given a lease for one part of the land, and they are free to tend the land and set ground rules for its use -- as a small farm, a forest, marshland, desert, and so forth. The public is free to visit the land, hike there, picnic, explore, boat, so long as they conform to the ground rules. With such a setup, a farm near a city might have picnickers in its fields every day during the summer.

### Related Patterns
... within each region, in between the towns, there are vast areas of countryside -- farmland, parkland, forests, deserts, grazing meadows, lakes, and rivers. The legal and ecological character of this countryside is crucial to the balance of the region. When properly done, this pattern will help to complete [[The Distribution of Towns (2)]], [[City Country Fingers (3)]], [[Agricultural Valleys (4)]], [[Lace of Country Streets (5)]], and [[Country Towns (6)]].

Within each natural preserve, we imagine a limited number of houses -- [[House Cluster (37)]] -- with access on unpaved country lanes -- [[Green Streets (51)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 36.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/the-distribution-of-towns-2.md ===== -->

---
title: "The Distribution of Towns (2)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 2
pattern_name: "The Distribution of Towns"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Distribution%20of%20Towns%20%282%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Independent Regions (1)"
  - "Agricultural Valleys (4)"
  - "Country Towns (6)"
  - "City Country Fingers (3)"
---

# The Distribution of Towns (2)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If the population of a region is weighted too far forward small villages, modern civilization can never emerge; but if the population is weighted too far toward big cities, the earth will go to ruin because the population isn't where it needs to be, to take care of it.

### Solution
>Encourage a birth and death process for towns within the region, which gradually has these effects:
>1. The population is even distributed in terms of different sizes -- for example, one town with 1,000,000 people, 10 towns with 100,000 people each, 100 towns with 10,000 people each, and 1000 towns with 100 people each.
>2. These towns are distributed in space in such a way that within each size category the towns are homogeneously distributed all across the region.

### Related Patterns
... consider now the character of settlements within the region: what balance of villages, towns, cities is in keeping with the independence of the region -- [[Independent Regions (1)]]?

As the distribution evolves, protect the prime agricultural land for farming --[[Agricultural Valleys (4)]]; protect the smaller outlying towns, by establishing belts of countryside around them and by decentralizing industry, so that the towns are economically stable -- [[Country Towns (6)]]. In the larger more central urban areas work toward land policies which maintain open belts of countryside between the belts of city -- [[City Country Fingers (3)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 16.
> #APL/confidence/low
>
> #APL/Town-Patterns/Regional-Policies


<!-- ===== pattern-language/wiki/concepts/patterns/the-family-75.md ===== -->

---
title: "The Family (75)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 75
pattern_name: "The Family"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Family%20%2875%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "House Cluster (37)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "Housing In Between (48)"
  - "Life Cycle (26)"
  - "Household Mix (35)"
  - "Your Own Home (79)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Common Areas at the Heart (129)"
  - "Communal Eating (147)"
  - "Building Complex (95)"
---

# The Family (75)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The nuclear family is not by itself a viable social form.

### Solution
>Set up processes which encourage groups of 8 to 12 people to come together and establish communal households. Morphologically, the important things are:

>1. Private realms for the groups and individuals that make up the extended family: couple realms, private rooms, sub-households for small families.
>2. Common space for shared functions: cooking, working, gardening, child care.
>3. At the important crossroads of the site, a place where the entire group can meet and sit together.

### Related Patterns
... assume now, that you have decided to build a house for yourself. If you place it properly, this house can help to form a cluster, or a row of houses, or a hill of houses - [[House Cluster (37)]], [[Row Houses (38)]], [[Housing Hill (39)]] - or it can help to keep a working community alive - [[Housing In Between (48)]]. This next pattern now gives you some vital information about the social character of the household itself. If you succeed in following this pattern, it will help repair [[Life Cycle (26)]] and [[Household Mix (35)]] in your community.

Each individual household within the larger family must, at all costs, have a clearly defined territory of its own, which it controls - [[Your Own Home (79)]]; treat the individual territories according to the nature of the individual households - [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]]; and build common space between them, where the members of the different smaller households can meet and eat together - [[Common Areas at the Heart (129)]], [[Communal Eating (147)]]. For the shape of the building, gardens, parking, and surroundings, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 376.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Families


<!-- ===== pattern-language/wiki/concepts/patterns/the-fire-181.md ===== -->

---
title: "The Fire (181)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 181
pattern_name: "The Fire"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Fire%20%28181%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Common Areas at the Heart (129)"
  - "Compost (178)"
  - "Sitting Circle (185)"
  - "Window Place (180)"
---

# The Fire (181)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>There is no substitute for fire.

### Solution
>Build the fire in a common space—perhaps in the kitchen—where it provides a natural focus for talk and dreams and thought. Adjust the location until it knits together the social spaces and rooms around it, giving them each a glimpse of the fire; and make a window or some other focus to sustain the place during the times when the fire is out.

### Related Patterns
... this pattern helps to create the spirit of the [[Common Areas at the Heart (129)]], and even helps to give its layout and position, because it influences the way that paths and rooms relate to one another.

Even where the traditional open fireplace is obsolete for heating or where fuel is scarce, find some way of converting refuse, paper, scraps of wood and cardboard into logs which can be burned, and which smell good - perhaps with some kind of natural resin in a home-made press. Burn all the dry organic materials that do not go to the [[Compost (178)]], so that the leftovers from the materials which come into the house all serve a useful function, either as fertilizer or as fuel; indeed, the ashes from the fire may go into the compost. Make a circle of chairs around the fire - [[Sitting Circle (185)]]; perhaps these chairs include a [[Window Place (180)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 838.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/the-flow-through-rooms-131.md ===== -->

---
title: "The Flow Through Rooms (131)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 131
pattern_name: "The Flow Through Rooms"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Flow%20Through%20Rooms%20%28131%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Intimacy Gradient (127)"
  - "Common Areas at the Heart (129)"
  - "Short Passages (132)"
  - "Entrance Room (130)"
  - "Staircase as a Stage (133)"
  - "Zen View (134)"
  - "Tapestry of Light and Dark (135)"
  - "Light on Two Sides of Every Room (159)"
  - "Corner Doors (196)"
---

# The Flow Through Rooms (131)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The movement between rooms is as important as the rooms themselves; and its arrangement has as much effect on social interaction in the rooms, as the interiors of the rooms.

### Solution
>As far as possible, avoid the use of corridors and passages. Instead, use public rooms and common rooms as rooms for movement and for gathering. To do this, place the common rooms to form a chain, or loop, so that it becomes possible to walk from room to room—and so that private rooms open directly off these public rooms. In every case, give this indoor circulation from room to room a feeling of great generosity, passing in a ride and ample loop around the house, with views of fires and great windows.

### Related Patterns
... next to the gradient of spaces created by [[Intimacy Gradient (127)]] and [[Common Areas at the Heart (129)]], the way that rooms connect to one another will play the largest role in governing the character of indoor space. This pattern describes the most fundamental way of linking rooms to one another.

Whenever passages or corridors are unavoidable, make them wide and generous too; and try to place them on one side of the building, so that they can be filled with light - [[Short Passages (132)]]. Furnish them like rooms, with carpets, bookshelves, easy chairs and tables, filtered light, and do the same for [[Entrance Room (130)]] and [[Staircase as a Stage (133)]]. Always make sure that these rooms for movement have plenty of light in them and perhaps a view - [[Zen View (134)]], [[Tapestry of Light and Dark (135)]], and [[Light on Two Sides of Every Room (159)]]. Keep doors which open into rooms, or doors between rooms which create the flow through rooms, in the corners of the rooms - [[Corner Doors (196)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 627.
> #APL/confidence/low
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/patterns/the-shape-of-indoor-space-191.md ===== -->

---
title: "The Shape of Indoor Space (191)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 191
pattern_name: "The Shape of Indoor Space"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/The%20Shape%20of%20Indoor%20Space%20%28191%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Ceiling Height Variety (190)"
  - "Columns at the Corners (212)"
  - "Floor and Ceiling Layout (210)"
  - "Floor-Ceiling Vaults (219)"
  - "Wall Membranes (218)"
  - "Positive Outdoor Space (106)"
  - "Thick Walls (197)"
  - "Closets Between Rooms (198)"
  - "Half-Open Wall (193)"
  - "Structure Follows Social Spaces (205)"
---

# The Shape of Indoor Space (191)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The perfectly crystalline squares and rectangles of ultra-modern architecture make no special sense in human or in structural terms. They only express the rigid desires and fantasies which people have when they get too preoccupied with systems and the means of their production.

### Solution
>With occasional exceptions, make each indoor space or each position of a space, a rough rectangle, with roughly straight walls, near right angles in the corners, and a roughly symmetrical vault over each room.

### Related Patterns
... from [[Ceiling Height Variety (190)]] you have an overall conception of each floor in the building as a cascade of heights, typically highest in the middle where the largest rooms are, lower toward the edge where the small rooms are, and varying with floor also, so that the lower floors will tend to have a higher average ceiling height than upper floors. This pattern takes each individual space, within this overall cascade, and gives it a more definite shape.

You can define the room with columns, one at each corner - [[Columns at the Corners (212)]]; and the shape of the ceiling can be given exactly by the ceiling vault - [[Floor and Ceiling Layout (210)]], [[Floor-Ceiling Vaults (219)]]. Avoid curved walls except where they are strictly necessary - [[Wall Membranes (218)]]. Where occasional curved walls like bay windows do jut out into the outside, place them to help create [[Positive Outdoor Space (106)]]. Make the walls of each room generous and deep - [[Thick Walls (197)]], [[Closets Between Rooms (198)]]; and where it is appropriate, make them [[Half-Open Wall (193)]]. For the patterns on the load-bearing structure, engineering, and construction, begin with [[Structure Follows Social Spaces (205)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 883.
> #APL/confidence/high
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/thick-walls-197.md ===== -->

---
title: "Thick Walls (197)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 197
pattern_name: "Thick Walls"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Thick%20Walls%20%28197%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Shape of Indoor Space (191)"
  - "Alcoves (179)"
  - "Window Place (180)"
  - "Ceiling Height Variety (190)"
  - "Building Edge (160)"
  - "Thickening the Outer Walls (211)"
  - "Open Shelves (200)"
  - "Columns at the Corners (212)"
  - "Closets Between Rooms (198)"
  - "Sunny Counter (199)"
  - "Waist-High Shelf (201)"
  - "Built-in Seats (202)"
  - "Child Caves (203)"
  - "Secret Place (204)"
---

# Thick Walls (197)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Houses with smooth hard walls made of prefabricated panels, concrete, gypsum, steel, aluminum, or glass always stay impersonal and dead.

### Solution
>Open your mind to the possibility that the walls of your building can be thick, can occupy a substantial volume—even actual usable space—and need not be merely thin membranes which have no depth. Decide where these thick walls ought to be.

### Related Patterns
... once the plan is accurate to the nearest 5 or 6 feet, there is a final process in which the smallest spaces - niches, built-in seats, counters, closets and shelves - get built to form the walls. Or of course, you can build this pattern into an existing house. In either case, use the pattern so that it helps to create the proper shapes for rooms - [[The Shape of Indoor Space (191)]], the ceiling heights - [[Alcoves (179)]], [[Window Place (180)]], and [[Ceiling Height Variety (190)]], and, on the outside of the rooms, the nooks and crannies of the [[Building Edge (160)]].

Where the thickness is 3 or 4. feet, build the thickness and the volume of the walls according to the process described in [[Thickening the Outer Walls (211)]]; where it is less, a foot or 18 inches, build it from open shelves stretched between deep vertical columns - [[Open Shelves (200)]], [[Columns at the Corners (212)]]. Get the detailed position of the various things within the wall from the patterns which define them: [[Window Place (180)]], [[Closets Between Rooms (198)]], [[Sunny Counter (199)]], [[Waist-High Shelf (201)]], [[Built-in Seats (202)]], [[Child Caves (203)]], [[Secret Place (204)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 908.
> #APL/confidence/high
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/thickening-the-outer-walls-211.md ===== -->

---
title: "Thickening the Outer Walls (211)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 211
pattern_name: "Thickening the Outer Walls"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Thickening%20the%20Outer%20Walls%20%28211%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Thick Walls (197)"
  - "Alcoves (179)"
  - "Window Place (180)"
  - "Sunny Counter (199)"
  - "Waist-High Shelf (201)"
  - "Built-in Seats (202)"
  - "Cascade of Roofs (116)"
  - "Child Caves (203)"
  - "Secret Place (204)"
  - "Roof Layout (209)"
  - "Floor and Ceiling Layout (210)"
  - "Roof Vaults (220)"
  - "Floor-Ceiling Vaults (219)"
  - "Columns at the Corners (212)"
---

# Thickening the Outer Walls (211)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>We have established in [[Thick Walls (197)]], how important it is for the walls of a building to have “depth” and "volume", so that character accumulates in them, with time. But when it comes to laying out a building and constructing it, this turns out to be quite hard to do.

### Solution
>Mark all those places in the plan where seats and closets are to be. These places are given individually by [[Alcoves (179)]], [[Window Place (180)]], [[Thick Walls (197)]], [[Sunny Counter (199)]], [[Waist-High Shelf (201)]], [[Built-in Seats (202)]], and so on. Lay out a wide swath on the plan to correspond to these positions. Make it two or three feet deep; recognize that it will be outside the main space of the room; your seats, niches, shelves, will feel attached to the main space of rooms but not inside them. Then, when you lay out columns and minor columns, place the columns in such a way that they surround and define these thick volumes of wall, as if they were rooms or alcoves.
>For shelves and counters less than 2 feet deep, there is no need to go to these lengths. The thickening can be built simply by deepening columns and place shelves between them.

### Related Patterns
... the arrangement of roof and floor vaults will generate horizontal outward thrust, which needs to be buttressed - [[Cascade of Roofs (116)]]. It also happens, that in a sensibly made building every floor is surrounded, at various places, by small alcoves, window seats, niches, and counters which form "thick walls" around the outside edge of rooms - [[Window Place (180)]], [[Thick Walls (197)]], [[Sunny Counter (199)]], [[Built-in Seats (202)]], [[Child Caves (203)]], [[Secret Place (204)]]. The beauty of a natural building is that these thick walls - since they need lower ceilings, always, than the rooms they come from - can work as buttresses.

Once the [[Roof Layout (209)]], and the [[Floor and Ceiling Layout (210)]] are clear these thick walls can be laid out in such a way as to form the most effective buttresses, against the horizontal thrust developed by the vaults.

In order to make an alcove or thick wall work as a buttress, build its roof as near as possible to a continuation of the curve of the floor vault immediately inside. Load the roof of the buttress with extra mass to help change the direction of the forces - [[Roof Vaults (220)]]. Recognize that these thick walls must be outside the main space of the room, below the main vault of the room - [[Floor-Ceiling Vaults (219)]], so that they help to buttress the horizontal forces generated by the main vault of the ceiling. When you lay out columns and minor columns, put a column at the corner of every thick wall, so that the wall space, like other social spaces, becomes a recognizable part of the building structure - [[Columns at the Corners (212)]].

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 983.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Structural-Layout


<!-- ===== pattern-language/wiki/concepts/patterns/things-from-your-life-253.md ===== -->

---
title: "Things From Your Life (253)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 253
pattern_name: "Things From Your Life"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Things%20From%20Your%20Life%20%28253%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - none
---

# Things From Your Life (253)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>“Decor” and the conception of “interior design” have spread so widely, that very often people forget their instinct for the things they really want to keep around them.

### Solution
>Do not be tricked into believing that modern decor must be slick or psychedelic, or “natural” or "modern art", or “plants” or anything else that current taste-makers claim. It is most beautiful when it comes straight from your life—the things you care for, the things that tell your story.

### Related Patterns
... lastly, when you have taken care of everything, and you start living in the places you have made, you may wonder what kinds of things to pin up on the walls.

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1164.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Ornamentation


<!-- ===== pattern-language/wiki/concepts/patterns/travelers-inn-91.md ===== -->

---
title: "Traveler's Inn (91)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 91
pattern_name: "Traveler's Inn"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Traveler%27s%20Inn%20%2891%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Magic of the City (10)"
  - "Activity Nodes (30)"
  - "Promenade (31)"
  - "Night Life (33)"
  - "Work Community (41)"
  - "Common Areas at the Heart (129)"
  - "Dancing in the Street (63)"
  - "Beer Hall (90)"
  - "Communal Eating (147)"
  - "Sleeping in Public (94)"
  - "Communal Sleeping (186)"
  - "Building Complex (95)"
---

# Traveler's Inn (91)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Somewhere in the community at least one big place where a few hundred people can gather, with beer and wine, music, and perhaps a half-dozen activities, so that people are continually cross-crossing from one to another.

### Solution
>Make the traveler’s inn a place where travelers can take rooms for the night, but where—unlike most hotels and motels—the inn draws all its energy from the community of travelers that are there any given evening. The scale is small—30 or 40 guests to an inn; meals are offers communally; there is even a large space ringed round with beds in alcoves.

### Related Patterns
... any town or city has visitors and travelers passing through, and these visitors will naturally tend to congregate around the centers of activity - [[Magic of the City (10)]], [[Activity Nodes (30)]], [[Promenade (31)]], [[Night Life (33)]], [[Work Community (41)]]. This pattern shows how the hotels which cater to these visitors can most effectively help to sustain the life of these centers.

The heart of the conviviality is the central area, where everyone can meet and talk and dance and drink - [[Common Areas at the Heart (129)]], [[Dancing in the Street (63)]], and [[Beer Hall (90)]]. Provide the opportunity for communal eating, not a restaurant, but common food around a common table - [[Communal Eating (147)]]; and, over and above the individual rooms there are at least some areas where people can lie down and sleep in public unafraid - [[Sleeping in Public (94)]], [[Communal Sleeping (186)]]. For the overall shape of the inn, its gardens, parking, and surroundings, begin with [[Building Complex (95)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 448.
> #APL/confidence/medium
>
> #APL/Town-Patterns/Social-Institutions---Local-Gathering


<!-- ===== pattern-language/wiki/concepts/patterns/tree-places-171.md ===== -->

---
title: "Tree Places (171)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 171
pattern_name: "Tree Places"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Tree%20Places%20%28171%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Site Repair (104)"
  - "Fruit Trees (170)"
  - "Outdoor Room (163)"
  - "Trellised Walk (174)"
  - "Garden Seat (176)"
  - "Seat Spots (241)"
  - "Sitting Wall (243)"
---

# Tree Places (171)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>When trees are planted or pruned without regard for the special places they can create, they are as good as dead for the people who need them.

### Solution
>If you are planting trees, plant them according to their nature, to form enclosures, avenues, squares, groves, and single spreading trees toward the middle of open spaces. And shape the nearby buildings in response to trees, so that the trees themselves, and the trees and buildings together, form places which people can use.

### Related Patterns
... trees are precious. Keep them. Leave them intact. If you have followed [[Site Repair (104)]], you have already taken care to leave the trees intact and undisturbed by new construction; you may have planted [[Fruit Trees (170)]]; and you may perhaps also have other additional trees in mind. This pattern reemphasizes the importance of leaving trees intact, and shows you how to plant them, and care for them, and use them, in such a way that the spaces which they form are useful as extensions of the building.

Make the trees form "rooms" and spaces, avenues, and squares, and groves, by placing trellises between the trees, and walks, and seats under the trees themselves - [[Outdoor Room (163)]], [[Trellised Walk (174)]], [[Garden Seat (176)]], [[Seat Spots (241)]]. One of the nicest ways to make a place beside a tree is to build a low wall, which protects the roots and makes a seat - [[Sitting Wall (243)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 797.
> #APL/confidence/high
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/trellised-walk-174.md ===== -->

---
title: "Trellised Walk (174)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 174
pattern_name: "Trellised Walk"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Trellised%20Walk%20%28174%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Outdoor Room (163)"
  - "Tree Places (171)"
  - "Greenhouse (175)"
  - "Fruit Trees (170)"
  - "Paths and Goals (120)"
  - "Positive Outdoor Space (106)"
  - "Entrance Transition (112)"
  - "Column Place (226)"
  - "Paving With Cracks Between the Stones (247)"
  - "Filtered Light (238)"
  - "Climbing Plants (246)"
---

# Trellised Walk (174)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Trellised walks have their own special beauty. They are so unique, so different from other ways of shaping a path, that they are almost archetypal.

### Solution
>Where paths need special protection or where they need some intimacy, build a trellis over the path and plant it with climbing flowers. Use the trellis to help shape the outdoor spaces on either side of it.

### Related Patterns
... suppose the main spots of the garden have been defined - [[Outdoor Room (163)]], [[Tree Places (171)]], [[Greenhouse (175)]], [[Fruit Trees (170)]]. Now, where there is a special need to emphasize a path - [[Paths and Goals (120)]] - or, even more important, where the edges between two parts of a garden need to be marked without making a wall, an open trellised walk which can enclose space, is required. Above all, these trellised walks help to form the [[Positive Outdoor Space (106)]] in a garden or a park; and may perhaps help to form an [[Entrance Transition (112)]].

Think about the columns that support the trellis as themselves capable of creating places - seats, bird feeders - [[Column Place (226)]]. Pave the path with loosely set stones - [[Paving With Cracks Between the Stones (247)]] - Use climbing plants and a fine trellis work to create the special quality of soft, filtered light underneath the trellis - [[Filtered Light (238)]], [[Climbing Plants (246)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 809.
> #APL/confidence/high
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/university-as-a-marketplace-43.md ===== -->

---
title: "University as a Marketplace (43)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 43
pattern_name: "University as a Marketplace"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/University%20as%20a%20Marketplace%20%2843%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Network of Learning (18)"
  - "Promenade (31)"
  - "Building Complex (95)"
  - "Pedestrian Street (100)"
  - "Quiet Backs (59)"
  - "Housing In Between (48)"
  - "Master and Apprentices (83)"
---

# University as a Marketplace (43)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Concentrated, cloistered universities, with closed admission policies and rigid procedures which dictate who may teach a course, kill opportunities for learning.

### Solution
>Establish the university as a marketplace of higher education. As a social conception this means that the university is open to people of all ages, on a full-time, part-time, or course-by-course basis. Anyone can offer a class. Anyone can take a class. Physically, the university marketplace has a central crossroads where its main buildings and offices are, and the meeting rooms and labs ripple out from this crossroads—at first concentrated in small buildings along pedestrian streets and then gradually becoming more dispersed and mixed with the town.

### Related Patterns
... the [[Network of Learning (18)]] has established the importance of a while society devoted to the learning process with decentralized opportunities for learning. The network of learning can be greatly helped by building a university, which treats the learning process as a normal part of adult life, for all the people in society.

Give the university a [[Promenade (31)]] as its central crossroads; and around the crossroads cluster the buildings along streets -- [[Building Complex (95)]]; [[Pedestrian Street (100)]]. Give this central area access to quiet green -- [[Quiet Backs (59)]]; and a normal distribution of housing -- [[Housing In Between (48)]]; as for the classes, wherever possible let them follow the model of [[Master and Apprentices (83)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 231.
> #APL/confidence/low
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/vegetable-garden-177.md ===== -->

---
title: "Vegetable Garden (177)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 177
pattern_name: "Vegetable Garden"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Vegetable%20Garden%20%28177%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Fruit Trees (170)"
  - "Common Land (67)"
  - "Half-Hidden Garden (111)"
  - "Compost (178)"
  - "Bathing Room (144)"
---

# Vegetable Garden (177)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In a healthy town every family can grow vegetables for itself. The time is past to think of this as a hobby for enthusiasts; it is a fundamental part of human life.

### Solution
>Set aside one piece of land either in the private garden or on common land as a vegetable garden. About one-tenth of an acre is needed for each family of four. Make sure the vegetable garden is in a sunny place and central to all the households it serves. Fence it in and build a small storage shed for gardening tools beside it.

### Related Patterns
... we have one pattern, already, which brings out the useful character of gardens - both public and private ones - [[Fruit Trees (170)]]; we supplement this with a smaller, but as important aspect of the garden - one which every public and private garden should contain: enhance common land - [[Common Land (67)]] and private gardens - [[Half-Hidden Garden (111)]] with a patch where people can grow vegetables.

To fertilize the vegetables, use the natural compost which is generated by the house and the neighborhood - [[Compost (178)]]; and if possible, try to use water from the sinks and drains to irrigate the soil - [[Bathing Room (144)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 818.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Gardens


<!-- ===== pattern-language/wiki/concepts/patterns/waist-high-shelf-201.md ===== -->

---
title: "Waist-High Shelf (201)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 201
pattern_name: "Waist-High Shelf"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Waist-High%20Shelf%20%28201%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Thick Walls (197)"
  - "Open Shelves (200)"
  - "Thickening the Outer Walls (211)"
  - "Things From Your Life (253)"
---

# Waist-High Shelf (201)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In every house and every workplace there is a daily “traffic” of the objects which are handled most. Unless such things are immediately at hand, the flow of life is awkward, full of mistakes; things are forgotten, misplaced.

### Solution
>Build waist-high shelves around at least a part of the main rooms where people live and work. Make them long, 9 to 15 inches deep, with shelves or cupboard underneath. Interrupt the shelf for seats, windows, and doors.

### Related Patterns
... anywhere where there are open shelves, and around any room which tends to accumulate potted plants, books, plates, bits of paper, boxes, beautiful vases, and little things you have picked up along your travels, there is a need for space where these things can lie undisturbed, without making the room a mess [[Thick Walls (197)]], [[Open Shelves (200)]].

Build the shelf right into the structure of the building - [[Thickening the Outer Walls (211)]]. It is a good place to put your personal treasures - [[Things From Your Life (253)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 922.
> #APL/confidence/low
>
> #APL/Building-Patterns/Thick-Walls


<!-- ===== pattern-language/wiki/concepts/patterns/wall-membranes-218.md ===== -->

---
title: "Wall Membranes (218)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 218
pattern_name: "Wall Membranes"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Wall%20Membranes%20%28218%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Efficient Structure (206)"
  - "Final Column Distribution (213)"
  - "Box Columns (216)"
  - "Soft Inside Walls (235)"
  - "Lapped Outside Walls (234)"
  - "Soft Tile and Brick (248)"
---

# Wall Membranes (218)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>In organic construction the walls must take their share of the loads. They must work continuously with the structure on all four of their sides; and act to resist shear and bending, and take loads in compression.

### Solution
>Build the wall as a membrane which connects the columns and door frames and windows’ frames and is, at least in part, continuous with them. To build the wall, first put up an inner and an outer membrane, which can function as a finished surface; then pour the fill into the wall.

### Related Patterns
... according to [[Efficient Structure (206)]] and [[Final Column Distribution (213)]], the wall is a compressive loadbearing membrane, "stretched" between adjacent columns and continuous with them, the columns themselves placed at frequent intervals to act as stiffeners. The intervals vary from floor to floor, according to column height; and the wall thickness (membrane thickness) varies in a similar fashion. If the column stiffeners are already in place according to [[Box Columns (216)]], this pattern describes the way to stretch the membrane from column to column to form the walls.

Remember that in a stiffened wall, the membranes can be much thinner than you might expect, because the stiffeners prevent buckling. In some cases they can be as thin as two inches in a one story building, three inches at the bottom of a two-story building and so on - see [[Final Column Distribution (213)]].

Membranes can be made from hollow tile, lightweight concrete block, plywood, gypboard, wood planks, or any other sheet type material which would make a nice surface, which is easy to nail into, comfortable to touch, and so on. If the inner sheet is gypsum board, it can be finished with a skim coat of plaster - [[Soft Inside Walls (235)]]. The outer sheet can be made of 1 inch boards, tongue and grooved; or exterior grade plywood; or exterior board hung with tile, shingles, or plastered - [[Lapped Outside Walls (234)]]. It is also possible to build the outer skin of brick or tile: in this case, columns must be of the same material - [[Soft Tile and Brick (248)]]

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1023.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Erecting-the-Frame


<!-- ===== pattern-language/wiki/concepts/patterns/warm-colors-250.md ===== -->

---
title: "Warm Colors (250)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 250
pattern_name: "Warm Colors"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Warm%20Colors%20%28250%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Good Materials (207)"
  - "Floor Surface (233)"
  - "Soft Inside Walls (235)"
  - "Half-Inch Trim (240)"
  - "Ornament (249)"
  - "Pools of Light (252)"
  - "Canvas Roofs (244)"
  - "Soft Tile and Brick (248)"
---

# Warm Colors (250)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The greens and greys of hospitals and office corridors are depressing and cold. Natural wood, sunlight, bright colors are warm. In some way, the warmth of the colors in a room makes a great deal of difference between comfort and discomfort.

### Solution
>Choose surface colors which, together with the color of the natural light, reflected light, and artificial lights, create a warm light in the rooms.

### Related Patterns
... this pattern helps to create and generate the right kind of [[Good Materials (207)]], [[Floor Surface (233)]], [[Soft Inside Walls (235)]]. Where possible leave the materials in their natural state. just add enough color for decoration, and to make the light inside alive and warm.

This means that yellows, reds, and oranges will often be needed to pick out trim and lampshades and occasional details [[Half-Inch Trim (240)]], [[Ornament (249)]], [[Pools of Light (252)]]. Colored [[Canvas Roofs (244)]] and [[Soft Tile and Brick (248)]] also help to make warm colored light. Blues and greens and greys are much harder to use; especially on the north side where the light is cold and grey, but they can always be used for ornament, where they help to set off the warmer colors - [[Ornament (249)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1153.
> #APL/confidence/high
>
> #APL/Construction-Patterns/Ornamentation


<!-- ===== pattern-language/wiki/concepts/patterns/web-of-public-transport-16.md ===== -->

---
title: "Web of Public Transport (16)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 16
pattern_name: "Web of Public Transport"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Web%20of%20Public%20Transport%20%2816%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "City Country Fingers (3)"
  - "Local Transport Areas (11)"
  - "Interchange (34)"
  - "Mini-Buses (20)"
---

# Web of Public Transport (16)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The system of public transportation—the entire web of airplanes, helicopters, hovercraft, trains, boats, ferries, buses, taxis, mini-trains, carts, ski-lifts, moving sidewalks—can only work if all the parts are well-connected. But they usually aren’t, because the different agencies in charge of various forms of public transportation have no incentive to connect to one another.

### Solution
>Treat interchanges as primary and transportation lines as secondary. Create incentives so that all the different modes of public transportation—airplanes, helicopters, ferries, boats, trains, rapid transit, buses, mini-buses, ski-lifts escalators, travelators, elevators—plan the lines to connect the interchanges, with the hope that gradually many different lines, of many different types, will meet at every interchange.
>
>Give the local communities control over their interchanges so that they can implement the pattern by giving contracts only to those transportation companies which are willing to serve these interchanges.


### Related Patterns
... the city, as defined by [[City Country Fingers (3)]], spreads out in a ribbon fashion, throughout the countryside, and is broken into [[Local Transport Areas (11)]]. To connect the transport areas, and to maintain the flow of people and goods along the fingers of the cities, it is now necessary to create a web of public transportation.

Keep all the various lines that converge on a single interchange, and their parking, within 600 feet, so that people can transfer on foot -- [[Interchange (34)]]. It is essential that the major stations are served by a good feeder system, so that people are not forced to use private cars at all -- [[Mini-Buses (20)]] ...

```
The example given at the end references the contrast between the Swiss railways and the French railways. It is clear that the Swiss system is better as it allows the whole of the country to participate in the economy rather than the French model which generates an obligatory relationship to the capital.
```

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 92
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/web-of-shopping-19.md ===== -->

---
title: "Web of Shopping (19)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 19
pattern_name: "Web of Shopping"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Web%20of%20Shopping%20%2819%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Mosaic of Subcultures (8)"
  - "Subculture Boundary (13)"
  - "Scattered Work (9)"
  - "Local Transport Areas (11)"
  - "Magic of the City (10)"
  - "Promenade (31)"
  - "Shopping Street (32)"
  - "Market of Many Shops (46)"
  - "Corner Grocery (89)"
---

# Web of Shopping (19)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Shops rarely place themselves in those positions which best serve the people’s needs, and also guarantee their own stability.

### Solution
>When you locate any individual shop, follow a three-step procedure:
>1. Identify all other shops which offer the service you are interested in; locate them on a map.
>2. Identify and map the location of potential consumers. Wherever possible, indicate the density or total number of potential consumers in any given area.
>3. Look for the biggest gap in the existing web of shops in those areas where there are potential consumers.
>4. Within the gap in the web of similar shops, locate your shop next to the largest cluster of other kinds of shops.

### Related Patterns
... This pattern defines a piecemeal process which can help to locate shops and services where they are needed, in such a way that they will strengthen the [[Mosaic of Subcultures (8)]], [[Subculture Boundary (13)]], and the decentralized economy needed for [[Scattered Work (9)]] and [[Local Transport Areas (11)]].

We estimate, that under the impact of this rule, a web of shopping with the following overall characteristics will emerge:

|                               | Population | Distance Apart* |
|:----------------------------- |:----------:|:---------------:|
| [[Magic of the City (10)]]    |  300,000   |       10        |
| [[Promenade (31)]]            |   50,000   |        4        |
| [[Shopping Street (32)]]      |   10,000   |       1.8       |
| [[Market of Many Shops (46)]] |   4,000    |       1.1       |
| [[Corner Grocery (89)]]       |   1,000    |       0.5       |

``*These distances are calculated for an overall population density of 5000 per square mile. For a population density of D persons/sq.mile, divide the distances by root(D/5000)
``

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 104
> #APL/confidence/medium
>
> #APL/Town-Patterns/Community-Networking


<!-- ===== pattern-language/wiki/concepts/patterns/window-place-180.md ===== -->

---
title: "Window Place (180)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 180
pattern_name: "Window Place"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Window%20Place%20%28180%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Entrance Room (130)"
  - "Zen View (134)"
  - "Light on Two Sides of Every Room (159)"
  - "Street Windows (164)"
  - "Alcoves (179)"
  - "Low Sill (222)"
  - "Built-in Seats (202)"
  - "Natural Doors and Windows (221)"
  - "Deep Reveals (223)"
  - "Dormer Windows (231)"
---

# Window Place (180)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Everybody loves window seats, bay windows, and big windows with low sills and comfortable chairs drawn up to them.

### Solution
>In every room where you spend any length of time during the day, make at least one window into a "window place".

### Related Patterns
... this pattern helps complete the arrangement of the windows given by [[Entrance Room (130)]], [[Zen View (134)]], [[Light on Two Sides of Every Room (159)]], [[Street Windows (164)]]. According to the pattern, at least one of the windows in each room needs to be shaped in such a way as to increase its usefulness as a space.

Make it low and self-contained if there is room for that - [[Alcoves (179)]] keep the sill low - [[Low Sill (222)]]; put in the exact positions of frames, and mullions, and seats after the window place is framed, according to the view outside - [[Built-in Seats (202)]], [[Natural Doors and Windows (221)]]. And set the window deep into the wall to soften light around the edges - [[Deep Reveals (223)]]. Under a sloping roof, use [[Dormer Windows (231)]] to make this pattern ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 833.
> #APL/confidence/high
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/windows-overlooking-life-192.md ===== -->

---
title: "Windows Overlooking Life (192)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 192
pattern_name: "Windows Overlooking Life"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Windows%20Overlooking%20Life%20%28192%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Light on Two Sides of Every Room (159)"
  - "Ceiling Height Variety (190)"
  - "The Shape of Indoor Space (191)"
  - "Natural Doors and Windows (221)"
  - "Small Panes (239)"
  - "Low Sill (222)"
  - "Deep Reveals (223)"
---

# Windows Overlooking Life (192)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Rooms without a view are prisons for the people who have to stay in them.

### Solution
>In each room, place the windows in such a way that their total area conforms roughly to the appropriate figures for your region (25 percent or more of floor area, in the San Francisco Bay Area), and place them in positions which give the best possible views out over life: activities in streets, quiet gardens, anything different from the indoor scene.

### Related Patterns
... this pattern helps to complete the earlier patterns which give each room its shape: [[Light on Two Sides of Every Room (159)]], [[Ceiling Height Variety (190)]], and [[The Shape of Indoor Space (191)]]. Once these patterns are clear, this pattern helps to place the windows rather more precisely in the walls. It defines just how many windows there should be, how far apart, and what their total area should be.

Fine tune the exact positions of the windows at the time that you build them - [[Natural Doors and Windows (221)]]; break the area of each window into [[Small Panes (239)]]; give each window a very [[Low Sill (222)]] to improve the view and [[Deep Reveals (223)]] to make the light as soft as possible inside

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 889.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Shaping-the-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/windows-which-open-wide-236.md ===== -->

---
title: "Windows Which Open Wide (236)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 236
pattern_name: "Windows Which Open Wide"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Windows%20Which%20Open%20Wide%20%28236%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Window Place (180)"
  - "Windows Overlooking Life (192)"
  - "Natural Doors and Windows (221)"
  - "Small Panes (239)"
---

# Windows Which Open Wide (236)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Many buildings nowadays have no opening windows at all; and many of the opening windows that people do build, don’t do the job that opening windows ought to do.

### Solution
>Decide which of the windows will be opening windows. Pick those which are easy to get to, and choose the ones which open onto flowers you want to smell, paths where you might want to talk, and natural breezes. Then put in side-hung casements that open outward. Here and there, go all the way and build full French windows.

### Related Patterns
... this pattern helps to complete [[Window Place (180)]], [[Windows Overlooking Life (192)]], and [[Natural Doors and Windows (221)]].

Complete the subframe of the casement with [[Small Panes (239)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 1100.
> #APL/confidence/medium
>
> #APL/Construction-Patterns/Interior-Details


<!-- ===== pattern-language/wiki/concepts/patterns/wings-of-light-107.md ===== -->

---
title: "Wings of Light (107)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 107
pattern_name: "Wings of Light"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Wings%20of%20Light%20%28107%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "South Facing Outdoors (105)"
  - "Positive Outdoor Space (106)"
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Self-Governing Workshops and Offices (80)"
  - "Small Services Without Red Tape (81)"
  - "Office Connections (82)"
  - "Master and Apprentices (83)"
  - "Individually Owned Shops (87)"
  - "Connected Buildings (108)"
  - "Light on Two Sides of Every Room (159)"
  - "Cascade of Roofs (116)"
  - "Arcades (119)"
  - "Short Passages (132)"
  - "Structure Follows Social Spaces (205)"
---

# Wings of Light (107)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>Modern buildings are often shapes with no concern for natural light—they depend almost entirely on artificial light. But buildings which displace natural light as the major source of illumination are not fit places to spend the day.

### Solution
>Arrange each building so that it breaks down into wings which correspond, approximately, to the most important natural social groups within the building. Make each wing long and as narrow as you can—never more than 25 feet wide.

### Related Patterns
... at this stage, you have a rough position for the building or buildings on the site from [[South Facing Outdoors (105)]] and [[Positive Outdoor Space (106)]]. Before you lay out the interior of the building in detail, it is necessary to define the shapes of roofs and buildings in rather more detail. To do this, go back to the decisions you have already made about the basic social components of the building. In some cases, you will have made these decisions according to the individual case; in other cases you may have used the fundamental social patterns to define the basic entities - [[The Family (75)]], [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]], [[Self-Governing Workshops and Offices (80)]], [[Small Services Without Red Tape (81)]], [[Office Connections (82)]], [[Master and Apprentices (83)]], [[Individually Owned Shops (87)]]. Now it is time to start giving the building a more definite shape based on these social groupings. Start by realizing that the building needn't be a massive hulk, but may be broken into wings.

 Use the wings to form outdoor areas which have a definite shape, like courts and rooms - [[Positive Outdoor Space (106)]]; connect the wings, whenever possible, to the existing buildings round about so that the building takes its place within a long and rambling continuous fabric - [[Connected Buildings (108)]]. When you get further down and start defining individual rooms, make use of the daylight which the wings provide by giving each room [[Light on Two Sides of Every Room (159)]].

Give each wing its own roof in such a way that all the wings together form a great cascade of roofs - [[Cascade of Roofs (116)]]; if the wing contains various houses, or workgroups, or a sequence of major rooms, build access to these rooms and groups of rooms from one side, from an arcade, or gallery, not from a central corridor - [[Arcades (119)]], [[Short Passages (132)]]. For the load bearing structure of the wings, begin with [[Structure Follows Social Spaces (205)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 524.
> #APL/confidence/high
>
> #APL/Building-Patterns/Siting-the-Buildings


<!-- ===== pattern-language/wiki/concepts/patterns/work-community-41.md ===== -->

---
title: "Work Community (41)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 41
pattern_name: "Work Community"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Work%20Community%20%2841%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Scattered Work (9)"
  - "Subculture Boundary (13)"
  - "Neighborhood Boundary (15)"
  - "Activity Nodes (30)"
  - "Small Public Squares (61)"
  - "Local Sports (72)"
  - "Accessible Green (60)"
  - "Courtyards Which Live (115)"
  - "Self-Governing Workshops and Offices (80)"
  - "Street Cafe (88)"
  - "Food Stands (93)"
  - "Communal Eating (147)"
---

# Work Community (41)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>If you spend eight hours of your day at work, and eight hours at home, there is no reason why your workplace should be any less of a community than your home.

### Solution
>Build or encourage the formation of work communities—each one a collection of smaller clusters of workplaces which have their own courtyards, gathered round a larger common square or common courtyard which contains shops and lunch counters. The total work community should have no more than 10 or 20 workplaces in it.

### Related Patterns
... according to the pattern [[Scattered Work (9)]], work is entirely decentralized and woven in and out of the housing areas. The effect of [[Scattered Work (9)]] can be increased piecemeal, by building individual work communities, one by one, in the boundaries between the neighborhoods; these work communities will then help to form the boundaries -- [[Subculture Boundary (13)]], [[Neighborhood Boundary (15)]] -- and above all in the boundaries, they will help to form [[Activity Nodes (30)]].

Make the square at the heart of the community a public square with public paths coming through it [[Small Public Squares (61)]]; either in this square, or in some attached space, place opportunities for sports -- [[Local Sports (72)]]; make sure that the entire community is always within three minutes' walk of an [[Accessible Green (60)]]; lay out the individual smaller courtyards in such a way that people naturally gather there -- [[Courtyards Which Live (115)]]; keep the workshops small -- [[Self-Governing Workshops and Offices (80)]]; encourage communal cooking and eating over and beyond the lunch counters -- [[Street Cafe (88)]], [[Food Stands (93)]], [[Communal Eating (147)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 222.
> #APL/confidence/high
>
> #APL/Town-Patterns/Work-Communities


<!-- ===== pattern-language/wiki/concepts/patterns/workspace-enclosure-183.md ===== -->

---
title: "Workspace Enclosure (183)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 183
pattern_name: "Workspace Enclosure"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Workspace%20Enclosure%20%28183%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Flexible Office Space (146)"
  - "Half-Private Office (152)"
  - "Home Workshop (157)"
  - "Alcoves (179)"
  - "Windows Overlooking Life (192)"
  - "Half-Open Wall (193)"
  - "Thick Walls (197)"
  - "Open Shelves (200)"
  - "Waist-High Shelf (201)"
  - "Pools of Light (252)"
  - "Sitting Circle (185)"
  - "The Shape of Indoor Space (191)"
---

# Workspace Enclosure (183)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People cannot work effectively if their workspace is too enclosed or too exposed. A good workspace strikes the balance.

### Solution
>Give each workspace an area of at least 60 square feet. Build walls and windows round each workspace to such an extent that their total area (counting windows at one-half) is 50 to 75 percent of the full enclosure that would be there if all four walls around the 60 square feet were solid. Let the front of the workspace be open for at least 8 feet in front, always into a larger space. Place the desk so that the person working at it has a view out, either to the front or to the side. If there are other people working nearby, arrange the enclosure so that the person has a sense of connection to two or three others; but never put more than eight workspaces within view or earshot of one another.

### Related Patterns
... this pattern plays a vital role in helping to create an atmosphere in which people can work effectively. You can use it piecemeal to generate the larger patterns for workspace like [[Flexible Office Space (146)]], [[Half-Private Office (152)]], and [[Home Workshop (157)]]. Or, of course, it can be used to help complete these larger patterns, if you have already built them into your design. Even in an alcove off the family commons [[Alcoves (179)]], you can make the workspace more suitable for work, by placing and shaping the enclosure immediately around it according to this pattern.

For the view, give each workspace a window to the outside - [[Windows Overlooking Life (192)]]; surround the space with thick walls which contain shelves and storage space - [[Half-Open Wall (193)]], [[Thick Walls (197)]], [[Open Shelves (200)]], [[Waist-High Shelf (201)]]; arrange a pool of incandescent light over the work table to set it off - [[Pools of Light (252)]]; and try to make a sitting place, next to the workspace, so that the pulse of work, and talk can happen easily throughout the day - [[Sitting Circle (185)]]. For details on the shape of the workspace, see [[The Shape of Indoor Space (191)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 846.
> #APL/confidence/high
>
> #APL/Building-Patterns/Minor-Rooms


<!-- ===== pattern-language/wiki/concepts/patterns/your-own-home-79.md ===== -->

---
title: "Your Own Home (79)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 79
pattern_name: "Your Own Home"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Your%20Own%20Home%20%2879%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "The Family (75)"
  - "House for a Small Family (76)"
  - "House for a Couple (77)"
  - "House for One Person (78)"
  - "Row Houses (38)"
  - "Housing Hill (39)"
  - "Building Complex (95)"
  - "Half-Hidden Garden (111)"
---

# Your Own Home (79)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>People cannot be genuinely comfortable and healthy in a house which is not theirs. All forms of rental—whether from private landlords or public housing agencies—work against the natural processes which allow people to form stable, self-healing communities.

### Solution
>Do everything possible to make the traditional forms of rental impossible, indeed, illegal. Give every household its own home, with space enough for a garden. Keep the emphasis in the definition of ownership on control, not on financial ownership. Indeed, where it is possible to construct forms of ownership which give people control over their houses and gardens, but make financial speculation impossible, choose these forms above all others. In all cases give people the legal power, and the physical opportunity to modify and repair their own places. Pay attention to this rule especially, in the case of high density apartments: build the apartments in such a way that every individual apartment has a garden, or a terrace where vegetables will grow, and that even in this situation, each family can build, and change, and add on to their house as they wish.

### Related Patterns
... according to [[The Family (75)]], each individual household should be a part of a larger family group household. Whether this is so, or not, each individual household, must also have a territory of its own which it controls completely - [[House for a Small Family (76)]], [[House for a Couple (77)]], [[House for One Person (78)]]; this pattern, which simply sets down the need for such a territory, helps especially to form higher density house clusters like [[Row Houses (38)]], [[Housing Hill (39)]], which often do not have well-defined individual territories for the separate households.

For the shape of the house, begin with [[Building Complex (95)]]. For the shape of the lot, do not accept the common notion of a lot which has a narrow frontage and a great deal of depth. Instead, try to make every house lot roughly square, or even long along the street and shallow. All this is necessary to create the right relation between house and garden - [[Half-Hidden Garden (111)]] ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 392.
> #APL/confidence/high
>
> #APL/Town-Patterns/Social-Institutions---Families


<!-- ===== pattern-language/wiki/concepts/patterns/zen-view-134.md ===== -->

---
title: "Zen View (134)"
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
pattern_number: 134
pattern_name: "Zen View"
source_repository: https://github.com/zenodotus280/apl-md
source_url: https://github.com/zenodotus280/apl-md/blob/master/Patterns/Zen%20View%20%28134%29.md
license_note: Non-commercial reuse with attribution; see namespace README and source LICENSE.md.
related_patterns:
  - "Entrance Transition (112)"
  - "Entrance Room (130)"
  - "Short Passages (132)"
  - "Staircase as a Stage (133)"
  - "Paths and Goals (120)"
  - "Natural Doors and Windows (221)"
  - "Tapestry of Light and Dark (135)"
  - "Window Place (180)"
---

# Zen View (134)

> Source pattern from the abridged `apl-md` corpus. Use as a design reference and constraint seed; do not treat as commercial-clean training data.

### Problem
>The archetypal zen view occurs in a famous Japanese house, which gives this pattern its name.

### Solution
>If there is a beautiful view, don’t spoil it by building huge windows that gape incessantly at it. Instead, put the windows which look onto the view at places of transition — along paths, in hallways, in entry ways, on stairs, between rooms.
>If the view window is correctly placed, people will see a glimpse of the distant view as they come up to the window or pass it: but the view is never visible from the places where people stay.

### Related Patterns
... how should we make the most of a view? It turns out that the pattern which answers this question helps to govern not the rooms and windows in a building, but the places of transition. It helps to place and detail [[Entrance Transition (112)]], [[Entrance Room (130)]], [[Short Passages (132)]], [[Staircase as a Stage (133)]] - and outside, [[Paths and Goals (120)]].

Put in the windows to complete the indirectness of the view - [[Natural Doors and Windows (221)]] place them to help the [[Tapestry of Light and Dark (135)]] and build a seat from which a person can enjoy the view - [[Window Place (180)]]. If the view must be visible from inside a room, make a special corner of the room which looks onto the view, so that the enjoyment of the view becomes a definite act in its own right ...

---

> [!cite]- Alexander, Christopher. _A Pattern Language: Towns, Buildings, Construction_. Oxford University Press, 1977, p. 641.
> #APL/confidence/medium
>
> #APL/Building-Patterns/Light-and-Space


<!-- ===== pattern-language/wiki/concepts/spatial-pattern-constraint-layer.md ===== -->

---
title: Spatial Pattern Constraint Layer
created: 2026-07-01
updated: 2026-07-01
type: concept
status: compiled
namespace: pattern-language
sources:
  - README.md
  - wiki/summaries/for-agents-spatial-pattern-retrieval.md
---

# Spatial Pattern Constraint Layer

A spatial pattern constraint layer turns *A Pattern Language* retrieval into concrete design moves and verification checks for agents.

The goal is not to ask an agent to “make a cozy city.” The goal is to retrieve patterns whose Problem/Solution framing can be converted into constraints the agent must satisfy.

## Formula

```text
intent → selected patterns → constraints → layout moves → verifier checklist
```

## Constraint Types

- **Scale:** region, neighborhood, street, building, room, detail.
- **Adjacency:** what should be near, visible, connected, or separated.
- **Gradient:** public/private, quiet/active, open/enclosed, light/dark.
- **Activity:** what people do there and why the space invites it.
- **Verification:** how to tell whether the design move actually satisfied the pattern.

## Guardrail

This namespace is reference material with non-commercial attribution constraints. It should guide internal/private/non-commercial design experiments and evaluation, not unrestricted training-data packaging.


<!-- ===== pattern-language/wiki/index.md ===== -->

---
title: Pattern Language — Master Index
created: 2026-07-01
updated: 2026-07-01
type: index
status: compiled
namespace: pattern-language
---

# Pattern Language — Master Index

> Compiled index for `pattern-language`.

## Agent Entrypoints

- [[summaries/for-agents-spatial-pattern-retrieval|For Agents — Spatial Pattern Retrieval]] — Retrieval and translation contract for using patterns as spatial-design constraints.
- [[syntheses/unreal-mcp-worldbuilding-adapter-deferred|Unreal MCP Worldbuilding Adapter — Deferred Design Space]] — Follow-up adapter design notes; not part of the first namespace implementation.
- [[concepts/spatial-pattern-constraint-layer|Spatial Pattern Constraint Layer]] — Jamie/Pixi interpretation of how the corpus becomes an agentic constraint layer.

## Pattern Corpus

Imported pattern documents: 253.

Representative starting points:

- [[concepts/patterns/independent-regions-1|Independent Regions (1)]] — Wherever possible, work toward the evolution of independent regions in the world; each with a population between 2 and 10 million; each with its own natural and geographic boundaries; each with its own economy; each a world government, without the intervening
- [[concepts/patterns/identifiable-neighborhood-14|Identifiable Neighborhood (14)]] — Help people to define the neighborhoods they live in, not more than 300 yards across, with no more than 400 or 500 inhabitants. In existing cities, encourage local groups to organize themselves to form such neighborhoods. Give the neighborhoods some degree of
- [[concepts/patterns/activity-nodes-30|Activity Nodes (30)]] — Create nodes of activity throughout the community, spread about 300 yards apart. First identify those existing spots in the community where action seems to concentrate itself. Then modify the layout of the paths in the community to bring as many of them throug
- [[concepts/patterns/promenade-31|Promenade (31)]] — Encourage the gradual formation of a promenade at the heart of every community, linking the main activity nodes, and placed centrally, so that each point in the community is within 10 minutes’ walk of it. Put main points of attraction at the two ends, to keep
- [[concepts/patterns/accessible-green-60|Accessible Green (60)]] — Build one open public green within three minutes’ walk—about 750 feet—of every house and workplace. This means that the greens need to be uniformly scattered at 1,500-foot intervals, through the city. Make the greens at least 150 feet across, and at least 60,0
- [[concepts/patterns/small-public-squares-61|Small Public Squares (61)]] — Make a public square much smaller than you would at first imagine; usually no more than 45 to 60 feet across, never more than 70 feet across. This applies only to its width in the short direction. In the long direction it can certainly be longer.
- [[concepts/patterns/street-cafe-88|Street Cafe (88)]] — Encourage local cafes to spring up in each neighborhood. Make them intimate places, with several rooms, open to a busy path, where people can sit with coffee or a drink and watch the world go by. Build the front of the cafe so that a set of tables stretch out
- [[concepts/patterns/building-complex-95|Building Complex (95)]] — Never build monolithic buildings. Whenever possible translate your building program into a building complex, whose parts manifest the actual social facts of the situation. At low densities, a building complex may take the form of a collection of small building
- [[concepts/patterns/arcades-119|Arcades (119)]] — Wherever paths run along the edge of buildings, build arcades, and use the arcades, above all, to connect up the buildings to one another, so that a person can walk from place to place under the cover of the arcades.
- [[concepts/patterns/intimacy-gradient-127|Intimacy Gradient (127)]] — Lay out the spaces of a building so that they create a sequence which begins with the entrance and the most public parts of the building, then leads into the slightly more private areas, and finally to the most private domains.
- [[concepts/patterns/a-place-to-wait-150|A Place to Wait (150)]] — In places where people end up waiting (for a bus, for an appointment, for a plane), create a situation which makes the waiting positive. Fuse the waiting with some other activity—newspaper, coffee, pool tables, horseshoes; something which draws people in who a
- [[concepts/patterns/light-on-two-sides-of-every-room-159|Light on Two Sides of Every Room (159)]] — Locate each room so that it has outdoor space outside it on at least two sides, and then place windows in these outdoor walls so that natural light falls into every room from more than one direction.
- [[concepts/patterns/window-place-180|Window Place (180)]] — In every room where you spend any length of time during the day, make at least one window into a "window place".

## Source Roots

- `https://github.com/zenodotus280/apl-md`
- `https://github.com/zenodotus280/apl-md/blob/master/Patterns/`
- `https://github.com/zenodotus280/apl-md/blob/master/LICENSE.md`

## Maintenance

- Refresh with `scripts/import_apl_md.py` from this namespace directory.
- Preserve `pattern_number`, `pattern_name`, `source_url`, and related-pattern metadata.
- Keep the license/provenance note visible in README and pattern pages.


<!-- ===== pattern-language/wiki/log.md ===== -->

---
title: Pattern Language — Activity Log
created: 2026-07-01
updated: 2026-07-01
type: log
status: active
namespace: pattern-language
---

# Pattern Language — Activity Log

## 2026-07-01

- Created the `pattern-language` namespace for Pixi Wiki issue #42.
- Imported 253 structured pattern documents from `zenodotus280/apl-md`.
- Added provenance/license guardrails for non-commercial reuse with attribution.
- Added agent retrieval/worldbuilding guidance and deferred Unreal MCP adapter design notes.


<!-- ===== pattern-language/wiki/summaries/for-agents-spatial-pattern-retrieval.md ===== -->

---
title: For Agents — Spatial Pattern Retrieval
created: 2026-07-01
updated: 2026-07-01
type: summary
status: compiled
namespace: pattern-language
sources:
  - README.md
  - wiki/concepts/patterns/
---

# For Agents — Spatial Pattern Retrieval

Use this namespace as a spatial-design constraint source, not as generic inspirational prose.

## Retrieval Loop

1. Clarify the design target: room, building, street, neighborhood, town, world zone, or gameplay space.
2. Retrieve 5–12 relevant patterns from `pattern-language` by title, problem, solution, or related-pattern graph.
3. Prefer a mixed scale stack: one or two large-scale patterns, several layout/activity patterns, and a few detailed human-experience patterns.
4. Convert each selected pattern into constraints:
   - spatial relationship
   - adjacency or separation rule
   - scale cue
   - human activity/comfort cue
   - verification question
5. Produce a design brief that cites pattern names and numbers.
6. Verify the output against the selected patterns before calling it coherent.

## Output Shape

```text
Design target:
Selected patterns:
- Pattern Name (N): reason selected
Constraints:
- Pattern Name (N): concrete spatial/action constraint
Scene or layout moves:
- move, placement, zoning, path, view, threshold, activity node
Verification checklist:
- checkable question tied to each pattern
License note:
- source is non-commercial attribution reference material
```

## Worldbuilding and Unreal MCP Use

For Unreal-connected agents, use retrieved patterns to create a scene brief before issuing world-building actions. Examples:

- `Activity Nodes (30)` → place active anchors where paths converge.
- `Promenade (31)` → create a legible walking loop or public edge.
- `Accessible Green (60)` → keep shared green space near dwellings or activity clusters.
- `Small Public Squares (61)` → keep plazas human-scaled rather than oversized.
- `Intimacy Gradient (127)` → order spaces from public to private.
- `Light on Two Sides of Every Room (159)` → prefer room volumes with multi-directional light.
- `Window Place (180)` → create inhabitable view/rest points, not just flat walls.

Do not implement tool calls directly from this document. Treat it as the retrieval-to-constraint contract a future adapter can consume.


<!-- ===== pattern-language/wiki/syntheses/unreal-mcp-worldbuilding-adapter-deferred.md ===== -->

---
title: Unreal MCP Worldbuilding Adapter — Deferred Design Space
created: 2026-07-01
updated: 2026-07-01
type: synthesis
status: deferred
namespace: pattern-language
sources:
  - README.md
  - wiki/summaries/for-agents-spatial-pattern-retrieval.md
  - https://github.com/pixiiidust/pixi-wiki/issues/48
---

# Unreal MCP Worldbuilding Adapter — Deferred Design Space

The first `pattern-language` release publishes the knowledge namespace only. The Unreal MCP adapter is a later design/build slice after live retrieval and search are verified.

## Adapter Question

How should a Hermes agent translate selected spatial patterns into Unreal actions while keeping the design explainable and verifiable?

## Candidate Input Contract

```yaml
design_target: walkable village square
selected_patterns:
  - Activity Nodes (30)
  - Promenade (31)
  - Small Public Squares (61)
  - Accessible Green (60)
  - Intimacy Gradient (127)
constraints:
  - paths should converge at activity anchors
  - square should remain human-scaled
  - public/private transitions should be legible
verification:
  - each selected pattern has at least one scene-level check
```

## Candidate Unreal-Level Actions

- Create or select a terrain/zone boundary.
- Place path network and intersections.
- Place activity nodes at path convergence points.
- Zone public, semi-public, and private gradients.
- Place plazas, greens, thresholds, and view/rest points.
- Add labels or metadata tying generated objects back to pattern IDs.
- Run a verifier that checks the scene graph against selected pattern constraints.

## Open Design Questions

- What schema maps a pattern to one or more Unreal MCP actions?
- Should the adapter act directly or produce a design brief for a separate builder agent?
- How many patterns should one generation pass apply before becoming incoherent?
- Which scene graph facts are needed for verification: distances, visibility, adjacency, path connectivity, scale, object tags?
- How should license/provenance notes appear in generated scene metadata or reports?

## Deferral Rule

Do not start adapter implementation until `pattern-language` is live, searchable, and verified through Pixi Wiki raw/HTML/llms/MCP surfaces.


<!-- ===== software-architecture-metapatterns/CLAUDE.md ===== -->

# Software Architecture Metapatterns Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/software-architecture-metapatterns/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Preserve source provenance and license ambiguity from `denyspoltorak/metapatterns`.
- Treat imported pages as architecture reference material, not as commercial-clean training data.
- Keep this namespace scoped to software architecture metapatterns and architecture-reasoning guidance.
- Do not prescribe architectures by trend; retrieve the relevant source pages and compare forces first.
- Update `wiki/index.md` and `wiki/log.md` whenever compiled pages are added or the import is refreshed.


<!-- ===== software-architecture-metapatterns/README.md ===== -->

---
title: "Software Architecture Metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: namespace-overview
status: active
category: knowledge-systems
namespace: software-architecture-metapatterns
confidence: medium
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_license_note: "Repository root is CC BY-NC-SA 4.0; book/source directory and wiki indicate CC BY 4.0. Preserve attribution and no-endorsement guardrails."
---

# Software Architecture Metapatterns

> Software-architecture pattern-language reference for agents, compiled from Denys Poltorak's *Architectural Metapatterns: The Pattern Language of Software Architecture* GitHub wiki.

## Scope

### Covers

The `software-architecture-metapatterns` namespace covers software architecture metapatterns: system topologies, layers, services, pipelines, proxies, orchestrators, plugins, hexagonal architecture, service-oriented architecture, polyglot persistence, pattern aliases, architectural forces, dependencies, performance tradeoffs, and architecture evolution paths.

### Not Covered

This namespace does not cover every design pattern or programming idiom, prescribe architecture by fashion, replace project-specific code review, or establish commercial-clean training-data clearance. It is a reference and reasoning aid for architecture review, migration planning, and agent retrieval.

### Current As

2026-07-02 — Initial namespace release imports the public GitHub wiki Markdown corpus, preserves source URLs/provenance, adds an agent retrieval contract, and classifies the namespace under Knowledge Systems because it organizes software architecture knowledge into a navigable pattern language.

## Canonical Source Roots

- Source repository: `https://github.com/denyspoltorak/metapatterns`
- Source wiki: `https://github.com/denyspoltorak/metapatterns/wiki`
- Source website: `https://metapatterns.io/`
- Latest release inspected: `https://github.com/denyspoltorak/metapatterns/releases/tag/v1.2`

## Provenance and License Guardrail

The repository root license is **Creative Commons Attribution-NonCommercial-ShareAlike 4.0**. The book/source directory and wiki copyright page indicate **Creative Commons Attribution 4.0**. This namespace keeps the ambiguity visible and follows a conservative public-use stance: preserve attribution, source links, license notes, and no-endorsement boundaries.

Use this corpus for reference, critique, education, architecture review, and non-misleading agent retrieval. Do not present it as unrestricted commercial training data or as Jamie/Pixi-authored source material.

## Agent Use Contract

- Start with [[summaries/for-agents-software-architecture-retrieval|For Agents — Software Architecture Retrieval]].
- Retrieve a bounded set of 3–8 relevant metapattern/source pages before recommending an architecture.
- Compare patterns by structure, dependency direction, communication style, performance, team ownership, and likely evolution path.
- Cite metapattern names and source pages in the recommendation so a human can inspect the reasoning.
- Prefer "what forces are present?" over "what architecture is trendy?" Tiny systems do not need distributed cosplay.

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/software-architecture-metapatterns/README.md
/raw/software-architecture-metapatterns/wiki/index.md
/wiki/software-architecture-metapatterns/README.md.html
/wiki/software-architecture-metapatterns/wiki/index.md.html
/wiki/software-architecture-metapatterns/llms.txt
```


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/ambiguous-patterns.md ===== -->

---
title: "Ambiguous patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Ambiguous patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Ambiguous%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Ambiguous patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Ambiguous patterns.md`.

We’ve seen a single pattern come under many names, as happens with [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], and also one name used for multiple [[wiki/concepts/source/introduction/system-topologies|topologies]], as with [[wiki/concepts/source/basic-metapatterns/services|*Services*]], which may [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrate each other]], make a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], or be components of a [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) (*SOA*). On top of that, there are several pattern names which are often believed to be unambiguous while each of them sees conflicting definitions in books or over the web, thanks to [*Semantic Diffusion*](https://martinfowler.com/bliki/SemanticDiffusion.html) or independent coining of the term by multiple authors. Let’s explore the last kind, which is the most dangerous both for your understanding of other people and for your time wasted in arguments.

### Monolith


![Diagrams of a Monolith as a single component, a co-deployed system, a synchronous distributed system, a Layered Architecture, and modules with a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-Monolith.png)


The old books, namely \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] and \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\], described a *tightly coupled* [[wiki/concepts/source/basic-metapatterns/monolith|*unstructured* system]], where everything depends on everything, as *monolithic*, which matched the meaning of the word in Latin – “single stone”.

Then something evil happened – I believe that the proponents of [*SOA*](<Service-Oriented Architecture (SOA)>), backed by the hype and money which they had earned from corporations, started labeling any *non-distributed* system as *monolithic*, obviously to contrast the negative connotation of that word to their own most progressive design.

It took only a decade for the karma to strike back – when the new generation behind [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] redefined *monolithic* as a *single unit of deployment* – to call the now obsolescent *SOA* systems [*Distributed Monoliths*](<Service-Oriented Architecture (SOA)#distributed-monolith>) \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] because their services used to grow so coupled that they had to be deployed together.

The novel misnomers, [[wiki/concepts/source/basic-metapatterns/layers|*Layered Monolith*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] and [[wiki/concepts/source/basic-metapatterns/services|*Modular Monolith*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], which denote an application partitioned by abstractness or subdomain, respectively, add to the confusion.

### Reactor


![Control flow diagrams for Reactor, Proactor, and Half-Sync/Half-Async.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Subtypes%20of%20Monolith.png)


People [tend to call](http://ithare.com/category/reactors/) any event-driven service a *Reactor*. In fact, there are three patterns that describe different threading models for an event-handling system:

- A [[wiki/concepts/source/basic-metapatterns/monolith|*Reactor*]] \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] runs each task in a dedicated thread and blocks it on any calls outside of the component. That allows for normal *imperative programming* but is resource-consuming and not very responsive or flexible.
- A [[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]] \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] relies on a single thread to serve all the system’s tasks in an interleaved manner, just like an OS uses a single CPU core to run multiple processes. The resulting non-blocking code is fragmented (thus known as *callback hell*) but it can address any incoming event immediately. This suits [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|real-time control systems]].
- [[wiki/concepts/source/basic-metapatterns/monolith|*Half-Sync/Half-Async*]] \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] is what we know better as *coroutines* or *fibers* – there are multiple *Reactor*-like lightweight threads that block on a *Proactor*-like engine which translates between synchronous calls from the user code and asynchronous system events.


In most cases we’ll hear of *Proactor* being called *Reactor* – probably because *Reactor* was historically the first and the simplest of the three patterns, and it is similar in name to *reactive programming* found in *Proactor*.

### Microkernel


![Diagrams of Microkernel according to Pattern-Oriented Software Architecture and of Plugins Architecture](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-Microkernel.png)


*Microkernel* is another notable case. The confusion over it goes all the way back to \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] which used [[wiki/concepts/source/implementation-metapatterns/microkernel|operating systems]] as examples of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugin Architecture*]]. I believe that it was a mismatch:

- An operating system is mainly about sharing the resources of producers among consumers, where both the producers and consumers may be written by external teams. The *kernel* itself does not feature much logic – its role is to connect the other components together.
- *Plugins*, on the other hand, extend or modify the business logic of the *core* – which is the sole reason for the system to exist and is in no way “*micro-*” as it got the bulk of the system’s code. In many such systems *plugins* are utterly optional – which cannot be said of *OS drivers*.


Thus, here we have two architectural patterns of arguably similar structure ([[wiki/concepts/source/implementation-metapatterns/plugins|*Microkernel/Plugins*]] of \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] omit 3 of 5 components of the original [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] of \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\]) but very different intent and action known under the same name.

### Domain Services


![Diagrams of domain services according to Domain-Driven Design and Fundamentals of Software Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-DomainServices.png)


I was told that [[wiki/concepts/source/basic-metapatterns/services|*Domain Services*]] of \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] are an incorrect term – because a *domain service* is always limited to the [[wiki/concepts/source/basic-metapatterns/layers|*domain* layer]] of \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] while those of \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] also cover the [[wiki/concepts/source/basic-metapatterns/layers|*application*]] and, maybe, *infrastructure*.

I believe that both definitions are technically correct, if the difference in the meaning of *domain* is accounted for. In \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] *domain* is almost synonymous with a *bounded context* of \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], while \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] more often uses that word for the name of its [[wiki/concepts/source/basic-metapatterns/layers|middle layer]] which contains *business rules*.

### Service-Based Architecture


![Diagrams of Service-Based Architecture, Microservices, and Service-Oriented Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-ServiceBasedArchitecture.png)


\[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] calls anything made of services a *service-based architecture*.

\[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] differentiates [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] and [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>), leaving whatever remains (large [[wiki/concepts/source/basic-metapatterns/services|subdomain-scale services]]) under the name of [[wiki/concepts/source/basic-metapatterns/services|*Service-Based Architecture*]].

Both definitions are technically correct. One is wider than the other.

### Front Controller


![Diagrams of Front Controller according to Patterns of Enterprise Application Architecture and Software Architecture: the Hard Parts.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-FrontController.png)


\[[wiki/concepts/source/appendices/books-referenced|[PEAA]] and [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] define [*Front Controller*](https://learn.microsoft.com/en-us/previous-versions/msp-n-p/ff648617(v=pandp.10)?redirectedfrom=MSDN) as an [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]] (or, more likely, a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVP*]]) derivative for backend programming. In this pattern multiple web pages share a request processing component which turns the incoming requests into commands and forwards them to appropriate page classes.

The definition from \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] is much more interesting – it describes an [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]] with a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] embedded in the first (client-facing) service. The [[wiki/concepts/source/extension-metapatterns/orchestrator|*Front Controller*]] subscribes to notifications from downstream services to know the status of every request which it has passed to the [[wiki/concepts/source/basic-metapatterns/pipeline|*pipeline*]].

### Cells


![Diagrams of WSO2 Cells and Amazon Cells.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-Cells.png)


The fresh *Cell-Based Architecture* also has multiple definitions.

- [WSO2 defined](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] as a group of services which is encapsulated from the remaining system by a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] (for incoming traffic) and sometimes [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] (for outgoing traffic) and often uses a dedicated [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] – causing each *Cell*, though internally distributed, to be treated by other components as a single service. This makes designing and managing a large system much simpler by introducing a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*hierarchy*]].
- Amazon [promotes](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/what-is-a-cell-based-architecture.html) its [[wiki/concepts/source/basic-metapatterns/shards|*Cells*]] as [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] of the whole system which run in multiple geographic regions. That grants fault tolerance and improves performance as each client has an instance of the system deployed to a nearby datacenter, but it does not have much impact on the organization and complexity of the code.


This case looks like Amazon’s hijacking and redefining a popular emerging technology, though I may be wrong about that as I did not investigate the history of the term.

### Nanoservices


![Diagrams of Nanoservices as an API layer over a shared database, a pipeline, a Space-Based Architecture, actors, and a Service-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Ambiguous-Nanoservices.png)


The *Nanoservices* pattern is another emerging technology and it seems to have never been strictly defined. Most sources agree that a [[wiki/concepts/source/basic-metapatterns/services|*nanoservice*]] is a cloud-based function ([*FaaS*](https://en.wikipedia.org/wiki/Function_as_a_service)), similar to a *service* with a single API method but, just as with the old good [[wiki/concepts/source/basic-metapatterns/services|*services*]], they differ in the ways to use the novel technology:

- Diego Zanon in *Building Serverless Web Applications* proposes a [[wiki/concepts/source/basic-metapatterns/services|single layer of nanoservices]], each implementing a method of the system’s public API, to be used as a thin backend.
- [Here](https://increment.com/software-architecture/the-rise-of-nanoservices/) we have nanoservices [[wiki/concepts/source/basic-metapatterns/pipeline|comprising]] a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], similar to [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]].
- [Another article](https://medium.com/@ido.vapner/unlocking-the-power-of-nano-services-a-new-era-in-microservices-architecture-22647ea36f22) proposes to [(re)use them](<Service-Oriented Architecture (SOA)#nanoservices>) in [*SOA*](<Service-Oriented Architecture (SOA)>) style.


Moreover, there are a couple of sources that call a nanoservice something totally different:

- [There is a concept](https://nanoservices.io/docs/docs/building/introduction/) of nanoservice as a module that can run both as a separate service and as a part of a binary – allowing for a team to choose if they want their system to run as a single process or become distributed. *Nano-* is because an in-process module is more lightweight than a [[wiki/concepts/source/basic-metapatterns/services|*microservice*]]. This idea resembles [[wiki/concepts/source/basic-metapatterns/services|*Modular Monolith*]] and [[wiki/concepts/source/basic-metapatterns/services|*Actor Frameworks*]].
- And [here](https://dev.to/siy/nanoservices-or-alternative-to-monoliths-and-microservices-12bb) we have something akin to [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] but it is also called *Nanoservices* – as the proposed framework makes new components so easy to create that programmers tend to write many smaller *nanoservices* instead of a single [[wiki/concepts/source/basic-metapatterns/services|*microservice*]].


In my opinion, the disarray happened because the notion of *making smaller microservices* got hyped but was never adopted widely enough to become an industry standard, therefore everybody follows their own vision about what “smaller” means.

### Summary

Several names of architectural patterns cause confusion as the meaning of each of them changes from source to source. This book aims at identifying such issues and building a cohesive understanding of software and systems architecture, similar to the *ubiquitous language* of \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/analytics.md ===== -->

---
title: "Analytics"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Analytics.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Analytics
source_license_note: "See namespace README; preserve attribution and source links."
---

# Analytics

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Analytics.md`.

This part is dedicated to analyzing the architectural [[wiki/concepts/source/introduction/metapatterns|metapatterns]], for if this book’s taxonomy of patterns is a step forward from the state of the art, it should bear fruits for us to pick.

I had no time to research every idea collected while the book was being written and its individual chapters published for feedback. A few of those pending topics, which may make additional chapters in the future, are listed below:

- Some architectural patterns (*CQRS*, *Cache*, *Microservices*, etc.) appear under multiple metapatterns. Each individual case makes a story of its own, teaching about both the needs of software systems and uses of metapatterns.
- There are different ways to split a component into subcomponents: [*Layers of Services*](<Service-Oriented Architecture (SOA)>) differ from [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]]. This should be investigated.
- An architectural quality may depend on the structure of the system. For example, a client request may be split into three subrequests to be processed sequentially or in parallel, depending on the [[wiki/concepts/source/introduction/system-topologies|topology]] (e.g. [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated Services*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]]), thus it is topology which defines latency. We can even draw formulas like:
  - L = L1 \+ L2 \+ L3 for *Pipeline*,
  - L = MAX(L1, L2, L3) for *Orchestrated Services* which run in parallel,
  - L = MIN(L1, L2, L3) for *Replicas* with [*Request Hedging*](https://grpc.io/docs/guides/request-hedging/).


Other smaller topics that I was able to look into made the following chapters:

- [[wiki/concepts/source/analytics/comparison-of-architectural-patterns|Comparison]] of the ways different architectures [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|share functionality or data]], [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|build pipelines]], and use [[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|dependency inversion]] and [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|indirection]].
- [[wiki/concepts/source/analytics/ambiguous-patterns|Ambiguous patterns]] whose meaning differs from author to author.
- [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|Evolution of the software architecture]] during a product’s life cycle.
- [[wiki/concepts/source/analytics/real-world-inspirations-for-architectural-patterns|Real-world examples]] that inspire metapatterns.
- [[wiki/concepts/source/analytics/the-heart-of-software-architecture|Cohesion and decoupling]] as the main architectural drivers: their [[wiki/concepts/source/analytics/cohesers-and-decouplers|influence on forces]], [[wiki/concepts/source/analytics/deconstructing-patterns|interplay in patterns]] and, finally, a short guide on [[wiki/concepts/source/analytics/choose-your-own-architecture|choosing an architecture]] suitable for your project.


## Contents:

- [[wiki/concepts/source/analytics/comparison-of-architectural-patterns|Comparison of architectural patterns]]
  - [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|Sharing functionality or data among services]]
  - [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|Pipelines in architectural patterns]]
  - [[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|Dependency inversion in architectural patterns]]
  - [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|Indirection in commands and queries]]
- [[wiki/concepts/source/analytics/ambiguous-patterns|Ambiguous patterns]]
- [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|Architecture and product life cycle]]
- [[wiki/concepts/source/analytics/real-world-inspirations-for-architectural-patterns|Real-world inspirations for architectural patterns]]
- [[wiki/concepts/source/analytics/the-heart-of-software-architecture|The heart of software architecture]]
  - [[wiki/concepts/source/analytics/cohesers-and-decouplers|Cohesers and decouplers]]
  - [[wiki/concepts/source/analytics/deconstructing-patterns|Deconstructing patterns]]
  - [[wiki/concepts/source/analytics/choose-your-own-architecture|Choose your own architecture]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/architecture-and-product-life-cycle.md ===== -->

---
title: "Architecture and product life cycle"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Architecture and product life cycle.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Architecture%20and%20product%20life%20cycle
source_license_note: "See namespace README; preserve attribution and source links."
---

# Architecture and product life cycle

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Architecture and product life cycle.md`.

In my practice, a product’s architecture changes over its lifetime. For a R&D, when there is nobody with relevant experience on the team, it starts small, gradually gains flexibility through fragmentation, grows and restructures itself according to the ever-changing domain knowledge and business requirements, then it solidifies as the project matures, and dies because of performance optimizations and loss of experience as the seasoned programmers leave. In more mundane projects the first stages may be omitted, as little research needs to be done, and oftentimes a project is canceled way before its architecture succumbs under its own weight. Anyway, let’s observe the full life cycle.

### Infancy (proof of concept) – Monolith


![A diagram of a monolith.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-1.png)


A project in an unknown domain starts humble and small, likely as a proof of concept. You need to write quickly to check your ideas about how the domain works without investing much time – as you may oftentimes be wrong here or there, making you rethink and rewrite.

### Childhood (prototype) – Layers


![Diagrams of Layers and Hexagonal Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-2.png)


When you have the thing working, you may start reflecting on the rules and the code which you wrote. What belongs where, what can be subject to change, which tests will you need? At this point you clearly see the levels of abstractness: the high-level [[wiki/concepts/source/basic-metapatterns/layers|*application*]] (integration, orchestration) logic, the lower-level [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] (business) rules, and the generic *infrastructure* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. Now that you know better the whats and the hows, you divide the code (either old or rewritten from scratch) into [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] to make it both structured and flexible, yet still without a heavy development overhead caused by interfaces between subdomains.

### Youth (development of features) – fragmented architectures


![Diagrams of Layered Services, Orchestrated Services, and Top-Down Hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-3.png)


As you acquire domain experience, you start discerning subdomains (or *bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]) and isolating them to reduce the [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|complexity]] of your code. The layered structure turns into a system of subdomain-dedicated components: [[wiki/concepts/source/basic-metapatterns/services|modules]], [[wiki/concepts/source/basic-metapatterns/services|services]], [[wiki/concepts/source/basic-metapatterns/services|device drivers]] – whatever you used to name them throughout your career. The actual architecture follows the structure of the domain, with [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated Services*]], and [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]] among common options. The fragmentation of the system enables development by multiple teams with diverse technologies and styles, reduces the ripple effects of changes, and helps testability. However, use cases for the system as a whole become harder to understand and fix – if only because they traverse the parts of the code owned by multiple teams – which is not extremely bad given you have enough humanpower to do the work.

### Adulthood (production) – ad-hoc composition


![Layered Services evolve into a pragmatic architecture where the application layers of some services are merged while the domain layer of another service is subdivided.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-4.png)


As the product enters the market, its development tends to slow down with more attention given to corner cases and user experience. Some (often the most active) people are going to get bored and leave the project, while your understanding of the domain changes again based on user experience and real-life business needs \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. You may find that some of the components which you have designed as independent become strongly coupled, and you are lucky if they are small enough to be merged together – this is where the fragmentation from the previous stage pays off. Other parts of the system may outgrow the comfort zone of programmers and need to be subdivided. The architecture becomes asymmetrical and pragmatic.

### Old age (support) – back to Layers


![A diagram of Layers with multiple databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-5.png)


When active development ceases, you lose even more people and funding as you drift into the support phase. You are unlikely to retain your best programmers – you’ll get novices or even an outsourced team instead. They will struggle to retain the structure of the system – with its mass of hacks from the previous years – against progressively more weird requests from the business and customers whose natural desires have already been satisfied. That will cause many more hacks to be added – and components coupled or merged for the hacks to land – bringing the architecture back to [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], though this time heavily oversized layers.

### Death (the ultimate release) – Monolith


![A diagram of a monolith with multiple databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Lifecycle-6.png)


If the project is allowed to die, it may still have a chance for a final release which aims at improving performance and leaving a golden standard for the generations of users to come. Heavy optimizations will likely require merging the layers to avoid all kinds of communication overhead, reverting the system back to [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]].

### So it goes

Even though I have observed the cycle of architecture expanding and collapsing in embedded software, I believe that these forces apply to most kinds of systems. First you need to go quickly and interfaces are a burden. Then you need the extra flexibility that they provide to reserve space for future design changes. And as the flow of changes ceases, you may optimize the flexibility away to make programming easier and the code smaller and faster. However, the last transition is not always applicable: a distributed system will oppose compacting if it was written in diverse programming languages or needs specialized hardware setups for proper operation.

### Going back in time

It can happen that you need to step back through the life cycle – for example, when the domain itself changes drastically: a new standard emerges or the management decides that your application for washing machines fits coffee machines pretty well, as they are basically doing the same things: heating water, adding powder, and stirring – yet you have never wrote software for coffee machines before, thus you are back to the R&D phase.

In such cases it may be easier to rewrite the affected components from scratch rather than try to rejuvenate and refit the old code. Remember that you keep your experience – what was originally implemented as an improvised hack will be accounted for in the redesigned architecture. This means that every time a component is rewritten adds to its longevity as its architecture fits the domain more closely and needs fewer hacks (which are inflexible and confusing by definition) to get to production.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/choose-your-own-architecture.md ===== -->

---
title: "Choose your own architecture"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/The heart of software architecture/Choose your own architecture.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/The%20heart%20of%20software%20architecture/Choose%20your%20own%20architecture
source_license_note: "See namespace README; preserve attribution and source links."
---

# Choose your own architecture

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/The heart of software architecture/Choose your own architecture.md`.

Now that we’ve seen patterns decomposed into decoupling and cohesion, we can try reconstructing architecture based on your project’s needs.

## Project size

The project’s expected size is among the main determinants of the project’s architecture as both overgrown components and excessive fragmentation handicap development and maintenance. A moderate number of components of moderate size is the desired zone of comfort.

Therefore, a one day task will likely be [[wiki/concepts/source/basic-metapatterns/monolith|*monolithic*]], a man-month of work needs [[wiki/concepts/source/basic-metapatterns/layers|*layering*]], while anything larger than that calls for at least partial separation into *subdomain* [[wiki/concepts/source/basic-metapatterns/services|*modules*]] or [[wiki/concepts/source/basic-metapatterns/services|*services*]]. Very large projects may require further subdivision into [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]].


![Diagrams of Monolith, Layers, Services, Service-Oriented Architecture, and Cell-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Size-1.png)


Any inherent decoupling within your domain is another factor to consider in the initial design. For example, the layer with [[wiki/concepts/source/basic-metapatterns/layers|*domain* logic]] is very likely to comprise independent subdomains which naturally make modules or services at next to no development or runtime cost (see [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]]). Likewise, [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]] is a good fit for a hierarchical domain. A domain that builds around stepwise processing of data or events may be modeled as a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], which is a very flexible architectural style.


![Diagrams of Sandwich, Top-Down Hierarchy, and Pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Size-2.png)


The number of teams you start the project with is also important. For the teams to be as efficient as possible you want them to be almost independent. As every team gets ownership of one or two components, you must assure that the architecture has enough modules or services for the teams to specialize, because anything shared will likely become a bottleneck. For example, you can hardly employ more than 3 teams with a [[wiki/concepts/source/basic-metapatterns/layers|*layered architecture*]] as there are only so many layers in any system. Thus, having a large number of teams strongly hints at [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], [*SOA*](<Service-Oriented Architecture (SOA)>), or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]].

If not all the teams are available from day one, it is still preferable to initially set up component boundaries for the prospective number of teams because subdividing an already implemented component is a terrible experience. However, it may be [easier and safer](https://martinfowler.com/bliki/MonolithFirst.html) for now to leave all the components running within a single process (as [[wiki/concepts/source/basic-metapatterns/services|*modules*]]) to avoid the overhead of going distributed and have less trouble moving pieces of code around as needed (as new requirements often make a joke of your original design). You should be able to turn *modules* into [[wiki/concepts/source/basic-metapatterns/services|*services*]] through moderate effort once that becomes an imperative.

## Domain features

We have already seen above that hierarchical or pipelined domains enable the use of corresponding architectures. There is more to it.

Sometimes you expect to have many complex use cases which cannot be matched to your subdomains because every scenario involves multiple components, thus spreading over the entire system. You would usually collect the global use cases into a dedicated component – an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]. And if the *Orchestrator* grows out of control, it is [[wiki/concepts/source/extension-metapatterns/orchestrator|subdivided]] into layers or services.


![Diagrams of Services with: a monolithic orchestrator, Backends for Frontends, an orchestrator per use case, a hierarchical orchestrator and a layered orchestrator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Features-1.png)


Other systems are built around data. You cannot split it into private databases because almost every service needs access to the whole, which necessitates a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]], or the highly performant [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]].


![Diagrams of Services with a shared database and Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Features-2.png)


Once you go distributed, you will likely employ a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to centralize the communication between your services. And you will have various [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]], such as a [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]], a [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]], and a [[wiki/concepts/source/extension-metapatterns/proxy|*Response Cache*]]. You may even deploy a *Proxy* per kind of client if the clients vary in their protocols, resulting in [*Backends for Frontends*](<Backends for Frontends (BFF)>) (*BFF*).


![Diagrams of Services with a middleware, Services with a proxy, and Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Features-3.png)


## Runtime performance

Moreover, there are non-functional requirements, such as performance and fault tolerance.

High throughput is achieved by [[wiki/concepts/source/basic-metapatterns/shards|*sharding*]] or [[wiki/concepts/source/basic-metapatterns/shards|*replicating*]] your business logic or even your data. Sharding also helps process huge datasets while replication improves fault tolerance. [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] replicates the entire dataset in memory for faster access.


![Diagrams of stateless instances with a load balancer and a shared database, shards behind a sharding proxy, and replicas behind a load balancer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Performance-1.png)


Alternatively, you may use several specialized databases ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]) or redesign a highly loaded part of your system as a self-scaling [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].


![Diagrams of Services with Polyglot Persistence and a Cell with a scaled pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Performance-2.png)


Scalability under uneven load is achieved through [[wiki/concepts/source/basic-metapatterns/services|*Function as a Service*]] (*Nanoservices*), [[wiki/concepts/source/implementation-metapatterns/mesh|*Service-Mesh*]]-based [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] and, to a greater extent, [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]].


![Diagrams of scaled single-layer Nanoservices, Microservices, and processing units of Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Performance-3.png)


Fault tolerance requires you to have [[wiki/concepts/source/basic-metapatterns/shards|*replicas*]] of every component, including databases, ideally over multiple data centers. If you are not that rich, be content with [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] or [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]].


![Diagrams of whole-system replicas of Services with an API Gateway, actors running in a distributed framework, and a peer-to-peer mesh.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Performance-4.png)


Low latency makes you place simplified first response logic close to your input, leading to:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Presenter*]] or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller*]] pattern families for user interaction.
- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] with [[wiki/concepts/source/basic-metapatterns/layers|*strategy injection*]] for single hardware input.
- A [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] for distributed [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control*]] systems such as [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things).


![Shortcuts in the control flow of Model-View-Presenter, Model-View-Controller, Layers optimized through business logic injection, and Top-Down Hierarchy in a control system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Performance-5.png)


## Flexibility

If your product needs customization, you go for [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].

If it is to survive for a decade, you need [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] to be able to swap vendors.

If you mediate between resource or service providers and consumers, you build a [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


![Diagrams of Plugins, Hexagonal Architecture, and Microkernel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Flexibility-1.png)


When your teams develop services and you want them to be [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|less interdependent]], you insert an [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Open Host Service*]], or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS View*]] between them.


![Diagrams of Anticorruption Layer, Open Host Service, and CQRS View.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Flexibility-2.png)


When you have built a large system and really need that thorough data analytics, consider implementing a [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]].


![Data Mesh builds an extra graph of services that stream and process analytical data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Data%20Mesh.png)


## Every domain is unique

No one-size-fits-all. Embedded projects or single-player games don’t have databases and run in a single process. High Frequency Trading bypasses the OS kernel to save microseconds. *Middleware* and distributed databases care about quorum and leader election. Huge-scale data processing must account for [bit flips](https://en.wikipedia.org/wiki/Soft_error). A medical device should never crash. Banks store their history forever for external audits.

There is no universal architecture. No silver bullet pattern. Patterns are mere tools. Know your tools and choose wisely.

## So it goes

Software architecture lies lifeless in my hands, devoid of its magical colors, *like the dead iguana*.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/cohesers-and-decouplers.md ===== -->

---
title: "Cohesers and decouplers"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/The heart of software architecture/Cohesers and decouplers.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/The%20heart%20of%20software%20architecture/Cohesers%20and%20decouplers
source_license_note: "See namespace README; preserve attribution and source links."
---

# Cohesers and decouplers

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/The heart of software architecture/Cohesers and decouplers.md`.

Any project carries many constraints (*forces*), some of which want for certain parts of its code to be kept together (*cohesive*) while others push to have them torn apart (*decoupled*). Their balance and the resulting optimal architecture is very fluid as each of the forces in action depends on the current circumstances, the project’s history, and its expected evolution.

## Code structure and the level of pain

Let’s explore how a force influences the structure of a project. Consider the *clarity of code* which determines *development velocity*:


![A chart that shows that unstructured code is the least painful solution for a tiny project while something large is unbearable if not decomposed into services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Pain.png)


When you have 10 lines of business logic, you are likely to write them down as a simple script. Separating them into classes or deploying 5 services, each running 2 lines of code, is an overkill which would make the complexity of your infrastructure much higher than that of the task on hand.

At 100 lines of code you are likely to be more comfortable with procedures or even classes to divide the code into, as keeping everything together starts to hurt. You switch from the most cohesive implementation to another one, decoupled to an extent. Though the latter is more complex at its core, it allows for less painful growth because it encompasses smaller components.

A file of 5 000 lines is hard to read – you need to separate it into modules, each of which contains classes, which contain methods, which contain the code. You are building yet another level of the hierarchy to keep the number of items in each piece (lines in a method, methods in a class, classes in a module) comfortably small.

At about 100 000 lines you may start considering further separation of your project into services – as, you know, there are merge conflicts, or it takes a while to compile and test the whole codebase… anyway, at that point very few people comprehend the whole thing in detail, thus the benefits of having the entire codebase co-located ([*monorepo*](https://en.wikipedia.org/wiki/Monorepo)) are diminishing while the new drawbacks emerge.

## Building a hierarchy

As we see from the example above, code clarity favors *cohesiveness* (everything together) for smaller codebases but *decoupling* (parts separated with narrow interfaces) for larger projects. We can state that the direction the force under review (namely, clarity) pushes us in depends on the project’s size. That is not a unique case – many forces work this way, resulting in the famous [*Monolith* vs *Microservices* complexity diagram](https://martinfowler.com/bliki/MicroservicePremium.html).

Such a behavior is common for architectural forces and, by the way, it is also the case with editing sorted data. Array is the most efficient data structure for a small collection (up to about 1 000 elements) while anything larger requires a hash map or [B-tree](https://en.wikipedia.org/wiki/B-tree) (hierarchy of arrays). Just as a database splits oversized arrays because they are too slow to edit, the human mind is inefficient with large collections of similar items and wants them to be restructured into a hierarchy. When we look into a service, we see only the classes it contains. When we examine a class, we check the list of its methods, not those of surrounding classes. And when we open a method, we try to understand how its lines of code work together. This is the way humans fight complexity – by selecting a segment at one level of abstraction and ignoring everything around.


![The hierarchical decomposition of logic into methods of classes in a service is compared to that of data in a B-tree.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Hierarchy.png)


A hierarchy inherently adds some inconvenience – traversing levels of a B-tree slows down operations, and a project with many files takes time to grasp – which is why we avoid deep hierarchies in smaller projects (or datasets) – yet that is still a very low cost for having every individual component (a method, class, or module in a project; an array in a B-tree) stay reasonably small and simple thanks to the distribution of the overall complexity (or data) over the hierarchy.

## Bidirectional forces

Among the forces that lead to a preference for decomposition of a project into segments of certain size are:

- *Clarity* – as discussed above.
- *Development velocity* – programmers are [very productive](https://realmensch.org/2018/05/04/we-are-all-10x-developers/) when they know their code and don’t waste their time on communication. Still, there is a productivity limit for a single person, and if you want your project to be developed faster than that, you need to divide it among several teams, sacrificing individual performance for brute force.
- *Throughput* – on one hand, interservice communication is suboptimal because of the associated networking and serialization. On the other hand, there is a limit for a single server’s performance as more powerful hardware is too expensive. It is cheaper to install several commodity servers and accept a communication penalty than keep the entire system running on a single high-end machine to avoid networking.
- *Latency* – it is poor for a distributed system, but is not much better for a large monolith that may deadlock. Ideally, you should extract the latency-critical part into a dedicated small component placed close to the input and output hardware.
- *Security* – a single process is easier to audit and secure than a system of services. However, as a service grows, it may develop multiple interfaces and assimilate many libraries. Eventually, protecting that mishmash becomes much harder than creating a secure perimeter around a distributed system.


## Cohesers

Other forces predominantly push you towards merging all your code and data together:

- *Debuggability* – it is hard to debug a distributed system. You need to investigate logs and attach your debugger to several services which may be written in different programming languages. Debugging a single process, even 10 MLoC in size, is almost always easier (except when it is poorly documented).
- *Data consistency* – when everything runs in a single thread, you don’t have to care about data races, lost packets, or [idempotence](https://dev.to/woovi/idempotence-what-is-and-how-to-implement-4bmc). The [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem) is on your side.
- *Data analysis* – it is hard to collect data from multiple sources. You cannot use SQL joins. Nevertheless, at some point in the distant future, you may still reach the performance limit of your single database, in theory making data analysis a kind of bidirectional force.


## Decouplers

And there can be forces which try to keep your code fragmented:

- *Variability* – if your project needs to satisfy many [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|conflicting requirements]], it is very hard to achieve that with a uniform codebase running in a single process.
- *Location* – you may need to run parts of your system on [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|its end users’ devices]], in [[wiki/concepts/source/basic-metapatterns/shards|regional data centers]], or even on [[wiki/concepts/source/implementation-metapatterns/microkernel|specialized hardware]].
- *Organizational structure* – according to [Conway’s law](https://en.wikipedia.org/wiki/Conway%27s_law), forcing everyone to work on a shared component is among the top team performance killers, especially when different time zones are involved.


## Expansion and contraction


![A monolith transforming into Layered Services, whose application layers partially merge and domain layers split, only to finally glue into Layers with multiple databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Lifecycle.png)


As was [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|discussed previously]], when you start a project by building a [PoC](https://en.wikipedia.org/wiki/Proof_of_concept#Software_development) or prototype, you have little code and must move quickly. Most of the *decouplers* are not there and the *bidirectional forces* favor cohesion, thus you don’t waste your time on extra interfaces or fine-grained services. You don’t have multiple teams to fall prey to Conway’s law.

As soon as the prototype is approved, it’s time to prepare for iterative development of a project which nobody comprehends in advance. Requirements will change many a time. Libraries and frameworks may not work as expected. The external services which you rely on may die or change. Your team members may leave or, worse, be eager to try a novel technology. You need all the flexibility in the world, and flexibility comes through decoupling. But you also rely on your speed to remain ahead of competitors, therefore you cannot go too far because decoupling is not free. You try to imagine what may change in the future and prepare by isolating the would-be affected parts behind well-defined interfaces.

As your software matures, the flow of changes slows down and the business becomes more predictable or, rather, more familiar. You observe that some of the interfaces which you’ve added have never been put to real use – they just make the project more complex – which means that you pay for decoupling without earning its benefits. Others have been found to be too restrictive and were removed. Thus the system begins to contract, burning the flexibility it no longer needs while also growing in directions that were not originally expected.

Finally, you move to the support phase. The best programmers leave for more active projects. Whoever replaces them does not know the code. The remaining flexibility decomposes in favor of quick hackarounds. What remains is an ugly cohesive [evolutionary-shaped mess](http://www.laputan.org/mud/), created through generations of ad-hoc patches.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/comparison-of-architectural-patterns.md ===== -->

---
title: "Comparison of architectural patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Comparison of architectural patterns/Comparison of architectural patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Comparison%20of%20architectural%20patterns/Comparison%20of%20architectural%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Comparison of architectural patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Comparison of architectural patterns/Comparison of architectural patterns.md`.

This chapter is a compilation of small sections, each of which examines one aspect of the [[wiki/concepts/source/appendices/index-of-patterns|architectural patterns included in this book]]. It shows the value of having the list of metapatterns to iterate over and analyze.

## Contents:

- [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|Sharing functionality or data among services]]
- [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|Pipelines in architectural patterns]]
- [[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|Dependency inversion in architectural patterns]]
- [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|Indirection in commands and queries]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/deconstructing-patterns.md ===== -->

---
title: "Deconstructing patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/The heart of software architecture/Deconstructing patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/The%20heart%20of%20software%20architecture/Deconstructing%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Deconstructing patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/The heart of software architecture/Deconstructing patterns.md`.

Imagine a dungeon with dragons. It is made of halls connected by tunnels. Each hall is *cohesive*. Tunnels are narrow interfaces that *decouple* them. A hall is amorphous – it can have any shape but it cannot open to another hall except through a tunnel – such are the rules of the game. The tunnels both restrict the freedom of the halls and interconnect them.

## SOLID principles

If *cohesion* and *decoupling* dictate software architecture, they should surface in its principles. Let’s take a look at [SOLID](https://en.wikipedia.org/wiki/SOLID):

- The *single responsibility principle*, also known as [*do one thing and do it well*](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well), is a general advice for keeping unrelated functionality decoupled.
- The *open-closed principle* and *Liskov substitution principle* decouple the logic of the parent class or the code that uses it, respectively, from the functionality of its subclasses.
- The *interface segregation principle* decouples independent parts of an object’s interface.
- The *dependency inversion principle* decouples an object’s users from its implementation.


Please beware that each of those principles in and of themselves invokes decoupling which is not free – your software may end up having too many moving parts and strict rules to remain easy to read and support.

> When we choose between cohesion and decoupling, we choose between a single component and a pair of components connected through a constraint rule. The more decoupling, the more components and rules we have to handle. Sooner, rather than later, the number of individual components and rules will overwhelm any developer.

## Gang of Four patterns

Let’s now discuss something more practical, namely the \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] [patterns](https://en.wikipedia.org/wiki/Design_Patterns#Patterns_by_type) which seem to be ingenious, yet hacky, ways for rearranging the roles in your code. They override ordinary OOP rules, which is useful when you need extra flexibility. For example, the *creational patterns* interfere with the normally cohesive *select type – create – initialize – use* sequence of operating an object.

Some patterns provide a basic decoupling:

- [*Adapter*](https://refactoring.guru/design-patterns/adapter) translates between two interacting components so that they may evolve independently.
- [*Observer*](https://refactoring.guru/design-patterns/observer) decouples an event from the reactions which it causes by registering the event handlers at runtime.
- [*Chain of Responsibility*](https://refactoring.guru/design-patterns/chain-of-responsibility) separates the method invocation from the method execution. A client’s calling a method of an object runs the corresponding method of another object.


Others break the functionality or data of a class into two or more parts, juggling them at runtime:

- [*Proxy*](https://refactoring.guru/design-patterns/proxy) separates an object’s representation from its implementation, enabling lazy loading or remote access.
- [*Flyweight*](https://refactoring.guru/design-patterns/flyweight) extracts an immutable data member of a class and merges multiple instances of that identical data to save memory.
- [*Strategy*](https://refactoring.guru/design-patterns/strategy) and [*Decorator*](https://refactoring.guru/design-patterns/decorator) decouple a dimension of an object’s functionality to allow runtime changes in or composition of the object's behavior, respectively.
- [*State*](https://refactoring.guru/design-patterns/state) separates an object’s behavior into multiple classes based on the object’s current state.
- [*Template Method*](https://refactoring.guru/design-patterns/template-method) decouples several aspects of a class’s behavior from its main algorithm and envelops the variations of those aspects into subclasses.
- [*Bridge*](https://refactoring.guru/design-patterns/bridge) separates a high-level hierarchy of classes from their low-level implementation details which may comprise an orthogonal hierarchy.
- [*Memento*](https://refactoring.guru/design-patterns/memento) decouples the lifetime of an object’s state from the object itself.


On the other hand, several patterns gather separate components together:

- [*Command*](https://refactoring.guru/design-patterns/command) collects all the data required to call a method.
- [*Mediator*](https://refactoring.guru/design-patterns/mediator) is a cohesive implementation of multi-object use cases.
- [*Composite*](https://refactoring.guru/design-patterns/composite) and [*Facade*](https://refactoring.guru/design-patterns/facade) represent multiple objects as a cohesive entity. A *Composite* broadcasts a call made to its interface to every object which it contains, while a *Facade* [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrates]] the subsystem which it wraps.
- [*Abstract Factory*](https://refactoring.guru/design-patterns/abstract-factory) and [*Builder*](https://refactoring.guru/design-patterns/builder) encapsulate *type selection* and *initialization* for several related hierarchies, so that the client code gets objects from a consistent set of types. On top of that, a *Builder* cross-links the objects it creates into a cohesive subsystem, which is then returned to the *builder*’s client as a whole.


The remaining patterns pick an aspect or two of an object’s behavior and move them elsewhere:

- [*Iterator*](https://refactoring.guru/design-patterns/iterator) moves the code for traversal of a container’s elements from the container’s clients into the container’s implementation, decoupling the clients from the iteration algorithm.
- [*Visitor*](https://refactoring.guru/design-patterns/visitor) aggregates the actions that a client needs to perform on each kind of object in a hierarchy, decoupling them from the classes that constitute the hierarchy.
- *Interpreter* decouples client scenarios from the rest of the system by having them written in a dedicated language and run in a protected environment.
- [*Prototype*](https://refactoring.guru/design-patterns/prototype) binds the *type selection* and *initialization* together and decouples them from the object *creation*.
- [*Singleton*](https://refactoring.guru/design-patterns/singleton) binds the *creation* and *initialization* of a global object to every call of its methods.
- [*Factory Method*](https://refactoring.guru/design-patterns/factory-method) decouples the *initialization* from *type selection* and hides both from the class’s users.


As we see, every \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] pattern boils down to binding (making *cohesive*) and/or separating (*decoupling*) some kind of functionality or responsibilities.

## Architectural metapatterns

Finally, let’s close the book by iterating over the metapatterns and looking into their roots through the lens of unification and separation.


![Diagrams of Monolith, Shards, Layers, Services, and Pipeline, with cohesive and decoupled components highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Basic.png)


[[wiki/concepts/source/basic-metapatterns/basic-metapatterns|Basic architectures]]:

- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] keeps everything together for quick and dirty projects:
  - Total *cohesiveness* results in low latency, cost-efficient performance, and easy debugging.
- [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] slice a large-scale application into multiple instances:
  - *Decoupling* the instances enables scaling but sacrifices the consistency of shared data.
- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] separate the high-level code from the low-level implementation:
  - *Cohesion* within a layer makes it easy to implement and debug.
  - *Decoupled* layers may vary among themselves in technologies and properties, but are somewhat slower and hard to debug in-depth.
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] divide a complex system into subdomains:
  - *Cohesiveness* within a service keeps it simple and efficient when it does not need to consult with other services.
  - *Decoupling* enables the development of larger codebases by multiple specialized teams but any global use cases become complicated.
- [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] segregates data processing into self-contained steps:
  - *Decoupling* simplifies reassembling or expanding the system but increases its latency.


![Diagrams of Services with a middleware, Services with a shared repository, Services with a proxy, Services with an orchestrator, and Sandwich, with cohesive and decoupled components highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Extension.png)


[[wiki/concepts/source/extension-metapatterns/extension-metapatterns|Grouping related functionality]]:

- [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] separates the implementation of communication and/or instance management from the business logic:
  - The *cohesive* communication layer is not only reliable, but also uniform, which makes it easy to learn.
  - *Decoupling* the communication concerns from the business logic simplifies the latter.
- [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] dissociates data from code, enabling [[wiki/concepts/source/foundations-of-software-architecture/shared-data|data-centric programming]]:
  - *Cohesive* data is consistent and easy to handle.
  - *Decoupled* business logic can be scaled or subdivided [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|independently]] of the data.
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] mediates between a system and its clients, taking care of some aspects of their communication:
  - A *cohesive* edge component is easier to manage and secure.
  - *Decoupling* generic aspects simplifies the business logic but usually increases latency.
- [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] collects a multitude of complex use cases into a dedicated layer:
  - *Cohesive* use cases are easy to comprehend and debug.
  - *Decoupling* the [[wiki/concepts/source/basic-metapatterns/layers|use cases]] from the [[wiki/concepts/source/basic-metapatterns/layers|domain logic]] allows for variation in technologies but increases latency and complicates in-depth debugging.
- [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] distantiates both control and data from the domain rules, which become segmented:
  - *Cohesive* use cases and data integrate the system.
  - *Decoupling* the subdomain components from each other and from the system-wide layers keeps every part of the system reasonably small and independent.


![Diagrams of Layered Services, Services with Polyglot Persistence, Backends for Frontends, Service-Oriented Architecture, and Top-Down Hierarchy, with cohesive and decoupled components highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Fragmented.png)


[[wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns|Decoupled topologies]]:

- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]] first decouple the subdomains, and then the layers within each subdomain:
  - *Decoupled* subdomains allow for multi-team development and large codebases but complicate global use cases. *Decoupled* layers enable variation in technologies within a subdomain and [[wiki/concepts/source/foundations-of-software-architecture/orchestration|limit interdependencies]] between subdomains to a single layer.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] divides data among multiple data stores:
  - *Decoupling* improves performance through data store specialization at the cost of consistency.
- [*Backends for Frontends*](<Backends for Frontends (BFF)>) dedicate one or two components (a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] and/or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) to each kind of client.
  - *Decoupling* allows for customization on a per-client-type basis but makes it hard to share functionality among the clients.
- [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) first segregates a large system into layers, then subdivides each layer into services:
  - *Decoupling* layers strangely enables reuse as any component of an upper layer can access every component below it. *Decoupling* services within the layers allows for multi-team development. Drawbacks include high latency, system complexity, and interdependencies.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] recursively separates general and specialized logic, tackling complexity:
  - *Cohesive* general and subdomain-specific business logic helps readability and debugging.
  - *Decoupled* layers and subdomains allow for modification and expansion of local functionality at the cost of performance.


![Diagrams of Plugins, Hexagonal Architecture, Microkernel, and Mesh, with cohesive and decoupled components highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Heart/Implementation.png)


[[wiki/concepts/source/implementation-metapatterns/implementation-metapatterns|Component implementation]]:

- [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] separate customizable aspects of a system’s behavior:
  - *Decoupling* several aspects of a system allows for it to be fine-tuned but requires careful design and may lower performance.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] isolates the business logic from its external dependencies:
  - *Decoupling* protects from vendor lock-in and supports automatic testing at the cost of lost optimization opportunities.
- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] mediates between resource consumers and resource producers:
  - *Cohesive* resource management optimizes resource usage.
  - *Decoupling* allows for seamless replacement of resource providers.
- [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] aggregates distributed components into a virtual layer:
  - Virtual *cohesion* hides the complexity of distributed communication from the client code.
  - Actual *decoupling* (distribution) of the nodes enables scaling and fault tolerance.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns.md ===== -->

---
title: "Dependency inversion in architectural patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Comparison of architectural patterns/Dependency inversion in architectural patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Comparison%20of%20architectural%20patterns/Dependency%20inversion%20in%20architectural%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Dependency inversion in architectural patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Comparison of architectural patterns/Dependency inversion in architectural patterns.md`.

I am no fan of [*SOLID*](https://en.wikipedia.org/wiki/SOLID) – to the extent of being unable to remember what those five letters mean – thus I was really surprised to notice that one of its principles, namely [*dependency inversion*](https://en.wikipedia.org/wiki/Dependency_inversion_principle), is quite common with architectural patterns, which means that it is much more generic than *OOP* which it is promoted for.

Let’s see how dependency inversion is used at the system level.

## Patterns that build around it


![Plugins depend on the core's SPIs. There are multiple versions of plugins. Adapters of Hexagonal Architecture depend on both the core's SPIs and APIs of the adapted components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/DI-1.png)


Both [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and the derived [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] rely on dependency inversion for the same reason – to protect the *core*, which contains the bulk of the code, from variability in the external components it uses. The *core* operates interfaces ([*SPI*](https://en.wikipedia.org/wiki/Service_provider_interface)s) which it defines so that it may not care exactly what  is behind the interface.

It is the nature of the polymorphic components that distinguishes those patterns:

- [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] allow for small pieces of code, typically contributed by outside developers, to provide customizable parts of the system’s algorithms and decision making. Oftentimes the core team has no idea of how many diverse plugins will be written for their product.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] is about breaking dependency of the core on external libraries or services by employing [[wiki/concepts/source/extension-metapatterns/proxy|*adapters*]]. Each adapter depends both on the core’s SPI and on the API of the component which it adapts. As interfaces and contracts vary among vendors and even versions of software, which we want to be interchangeable, we need adapters to wrap the external components to make them look identical to our core. Besides that, [*stub* or *mock*](https://stackoverflow.com/questions/3459287/whats-the-difference-between-a-mock-stub) adapters help develop and test the core in isolation.


## Patterns that often rely on it


![In an operating system, device drivers depend on the kernel's SPIs. In a hierarchy, child nodes depend on their parent's SPI. Cell-Based Architecture uses adapters to break dependencies between Cells.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/DI-2.png)


A few more patterns tend to use this approach to earn its benefits, even though dependency inversion is not among their integral features:

- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]], yet another metapattern derived from [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]], distributes resources of *providers* among *consumers*. Polymorphism is crucial for some of its variants, including [[wiki/concepts/source/implementation-metapatterns/microkernel|*Operating System*]], but may rarely benefit others, such as [[wiki/concepts/source/implementation-metapatterns/microkernel|*Software Framework*]].
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]] distributes responsibility over a tree of components. If the nodes of the tree are polymorphic, they are easier to operate, and there is dependency inversion. However, in practice, a parent node may often be so strongly coupled to the types of its children that polymorphism becomes impractical.
- In another kind of [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]], namely [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] (aka *Services of Services*), each [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] [may employ](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) a [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]] and outbound [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] or [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]] to isolate its business logic from the environment – just like its parent [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] does for a monolithic core.


## Patterns that may use it


![Standard APIs are used between frontend and backend, and backend and database. CQRS views and adapters protect a service from dependencies on other services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/DI-3.png)


Finally, two basic architectures, [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/services|*Services*]], may resort to something similar to dependency inversion to decouple their constituents:

- We often see a higher layer to depend on, and a lower layer to implement a standardized interface, like POSIX or SQL, to achieve *interoperability* with other implementations (which is yet another wording for polymorphism).
- A service may follow the concept of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] by using an [[wiki/concepts/source/basic-metapatterns/services|*Anti-Corruption Layer*]] or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] as [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] that protect it from changes in other system components.


## Summary

Many architectural patterns employ dependency inversion by adding:

- an *interface* to enable polymorphism of their lower-level components or
- [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] to protect a component from changes in its dependencies.


These two approaches apply in different circumstances:

- If you can enforce your rules of the game on the suppliers of the external components, you merely *define an SPI*, and expect the suppliers to implement and obey it.
- If the suppliers are independent and it is your side that adapts to their rules, you should *add Adapters* to translate between your lovely SPI and their whimsical APIs.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/indirection-in-commands-and-queries.md ===== -->

---
title: "Indirection in commands and queries"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Comparison of architectural patterns/Indirection in commands and queries.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Comparison%20of%20architectural%20patterns/Indirection%20in%20commands%20and%20queries
source_license_note: "See namespace README; preserve attribution and source links."
---

# Indirection in commands and queries

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Comparison of architectural patterns/Indirection in commands and queries.md`.

*We can solve any problem by introducing an extra level of indirection* – states the [old adage](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering). We will not explain how this rule drives [deep learning](https://en.wikipedia.org/wiki/Deep_learning), at least for now. Instead, let’s concentrate our effort on indirection in communication between services.

Each component operates its own [[wiki/concepts/source/basic-metapatterns/layers|*domain model*]] \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] which translates into [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|objects]] and/or [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|procedures]] convenient for use in the component’s subdomain. However, should a system cover multiple subdomains, the best models for its parts to operate start to mismatch. Furthermore, they are likely to diverge progressively over time as requirements heap up and [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|the project matures]].

If we want for each module or service to continue with a model that fits its needs, we have to protect it from the influence of models of its neighbor components by employing indirection – a translator – between them.

> In a system of subdomain-dedicated [[wiki/concepts/source/basic-metapatterns/services|*Services*]] a service may need to operate entities that are defined in another service’s subdomain. For example, the financial and recruiting departments’ software operates employees, but the employee data which each department needs is different. Moreover, it also differs from the employee records in the HR department which is responsible for adding, editing, and discarding the employees. We don’t want our accountants to spend their nights seeking the correlation between salaries, birthday horoscopes from HRs, and MBTI test scores from the recruiters.

## Command (OLTP) systems


![Dependency diagrams for Anticorruption Layer, Open Host Service, and Orchestrated Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Indirection-Command.png)


More often than not our system consists of services that command each other: via [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call)s, requests, or even notifications – no matter how, one component makes a call to action which other(s) should obey.

In such a case we employ an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] between two services, or an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] when cooperation of several services is needed to execute our command:

- An [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]] is an *Adapter* on the dependent service’s side: as soon as we call another service, we start depending on its interface, while it is in our interest to isolate ourselves from its peculiarities and possible future changes. Thus we should better write and maintain a component to translate the foreign interface, defined in terms of the foreign domain model, into terms convenient for use within our code. Even if we subscribe to notifications, we may also want to have an *Adapter* to transform their payload.
- An [[wiki/concepts/source/extension-metapatterns/proxy|*Open Host Service*]] resides on the other side of the connection – it is an *Adapter* that a service provider team installs to hide the implementation details of their service from its users. It will typically translate from the provider’s domain model into a more generic (subdomain-agnostic) interface suitable for use by services that implement other subdomains.
- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] (which can be an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Composer*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Process Manager*]], or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Saga Orchestrator*]]) spreads a command to multiple services, waits for each of them to execute its part, and cleans up after possible failures. It tends to be more complex than other translators because of the coordination logic involved.


## Query (OLAP) systems


![Dependency diagrams for CQRS View, Reporting Database, and Query Service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Indirection-Query.png)


There is often another aspect of communication in a system, namely, information collection and analysis. And it runs into a different set of issues which cannot be helped by mere interface translation.

Each service operates and stores data in its own format and schema which matches its *domain model*, as discussed above. When another service needs to analyze the foreign data according to its own domain model, it encounters the fact that the foreign format(s) and schema(s) don’t allow for efficient processing – in the worst case it would have to read and re-process the entire foreign service’s dataset to execute its query.

The solution employs an intermediate database as a translator from the provider’s to the consumer’s preferred data access mode, format, and schema:

- A [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS View*]] resides in the data consumer and aggregates the stream of changes published by the data provider. This way the consumer can know whatever it needs about the state of the provider without making an interservice call.
- [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]] is about each service exposing a general-use public interface for streaming and/or querying its data. Maintaining one often requires the service to set up an internal [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Reporting Database*]].
- A [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] aggregates streams from multiple services to collect their data together, making it available for efficient queries (joins).


## A mixed case


![A service which injects a plugin into another service and streams data for use by the plugin.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Indirection-Plugin.png)


[[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]] ([called *Extensions* by Uber](https://www.uber.com/en-UA/blog/microservice-architecture/)) employ both logic and data indirection. When a service needs to modify the behavior of another service, it both writes a *Plugin* for the target service and extends its domain events stream with opaque data fields which the newly created *Plugin* can operate without consulting its origin service. The host (*Plugin*’s target) service passes the extra data fields to the *Plugin* which processes them and stores the data it needs in a dedicated table in its host’s database.

When the service with *Plugins* has to make a decision, it calls every registered *Plugin* as a part of its workflow. The *Plugin* reads the data it saved to its host’s database, processes it according to the business rules or its origin subdomain, and returns results – without any slow and failure-prone interservice calls!

## Summary

We see that though command-dominated (*operational* or *transactional*) and query-dominated (*analytical*) systems differ in their problems, the architectural solutions which they employ to decouple their component services match perfectly:

- [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]] or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS View*]] is used on the consumer’s side,
- [[wiki/concepts/source/extension-metapatterns/proxy|*Open Host Service*]] or [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]]’s [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Reporting Database*]] is on the provider’s side,
- [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] coordinates multiple providers.


Which shows that the principles of software architecture are deeper than the [CQRS](https://en.wikipedia.org/wiki/Command_Query_Responsibility_Segregation) dichotomy itself.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/pipelines-in-architectural-patterns.md ===== -->

---
title: "Pipelines in architectural patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Comparison of architectural patterns/Pipelines in architectural patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Comparison%20of%20architectural%20patterns/Pipelines%20in%20architectural%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Pipelines in architectural patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Comparison of architectural patterns/Pipelines in architectural patterns.md`.

Several architectural patterns involve a unidirectional data flow – a [*pipeline*](https://en.wikipedia.org/wiki/Pipeline_(software)). Strictly speaking, every data packet in a pipeline should:

- Move through the system over the same *route* with no loops.
- Be of the same *type*, as a part of a *data stream*.
- Retain its *identity* on the way.
- Retain *temporal order* – the sequence of packets remains the same over the entire pipeline.


Staying true to all of these points makes *Pipes and Filters* – one of the oldest known architectures. Yet there are other architectures that discard one or more of those conditions:

## [[wiki/concepts/source/basic-metapatterns/pipeline|Pipes and Filters]]


![Pipes and Filters where a data stream originates with the source, passes several filters, and ends in a sink.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Pipelineliness-PipesAndFilters.png)


[[wiki/concepts/source/basic-metapatterns/pipeline|*Pipes and Filters*]] is about stepwise [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|processing of a data stream]]. Each piece of data (a video frame, a line of text, or a database record) passes through the entire system.

This architecture is easy to build and it has a wide range of applications, from hardware to data analytics. Though each pipeline specializes in a single use case, it is often possible to build many different pipelines from the same set of generic components, which is actually practiced by Linux admins in their use of shell scripts \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\].

## [[wiki/concepts/source/basic-metapatterns/pipeline|Choreographed Event-Driven Architecture]]


![Parcel delivery example with different pipelines for individual parcels and trucks of parcels.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Pipelineliness-EventDrivenArchitecture.png)


Relaxing the *type* and loosening the *identity* criteria opens the way to [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]], in which a service publishes notifications about everything it does which may be of interest to other services. In such a system:

- There are multiple kinds of events going in different directions, as if several branched pipelines were built over the same set of services.
- A service may aggregate multiple incoming events to publish a single, seemingly unrelated, event later, when a certain condition is met. For example, a warehouse delivery collects individual orders till it gets a truckload of them, or until the evening comes and no new orders are accepted.


This architecture covers way more complex use cases than [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipes and Filters*]], because multiple pipelines are present in the system and because processing an event is allowed to have loosely related consequences (as with the parcel and truck).

## [[wiki/concepts/source/fragmented-metapatterns/layered-services|Command Query Responsibility Segregation]] (CQRS)


![In CQRS data passes through a pipeline formed of the command backend, OLTP database, OLAP database, and the query backend.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Pipelineliness-CQRS.png)


When data from events is stored for a future use (as with the aggregation above), both the *type* and the *temporal order* are ignored, but the data *identity* may be retained. A [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*-based system]] separates the paths for write (*command*) and read (*query*) requests, making a kind of data processing pipeline with the database, which stores events for an indeterminate amount of time, in the middle. It is the database that reshuffles the order of events, as a record it stores may be queried at any time, maybe in a year from its addition – or never at all.

## [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-Controller]] (MVC)


![Events from the mouse pass to the controller and the model, and those from the model - to the view and display.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Pipelineliness-MVC.png)


[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller*]] completely neglects the *type* and *identity* limitations. It is a coarse-grained pattern where the input source produces many kinds of events that go to the main module which does something and outputs another stream of events which have no obvious relation to the input. A mouse click does not necessarily result in a screen redraw, while a redraw may happen on timer without any user actions. In fact, this pattern conjoins two separate, short pipelines.

## Summary

There are four architectures with unidirectional data flow, which is characteristic of [[wiki/concepts/source/basic-metapatterns/pipeline|*pipelines*]]:

- [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipes and Filters*]],
- [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture* (*EDA*)]],
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Command (and) Query Responsibility Segregation* (*CQRS*)]],
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller* (*MVC*)]].


The first two, being true pipelines, are built around data processing and transformation, while for the others it is just an aspect of implementation – their separation of input and output yields pairs of streams.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/real-world-inspirations-for-architectural-patterns.md ===== -->

---
title: "Real world inspirations for architectural patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Real-world inspirations for architectural patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Real-world%20inspirations%20for%20architectural%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Real world inspirations for architectural patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Real-world inspirations for architectural patterns.md`.

As architectural patterns are generally technology-independent, they must mostly be shaped by the foundational principles of software engineering. And because the same principles are likely at work at every level of a software system, we may expect similar structures to appear on many levels of software, given similar circumstances – which are not always attainable, for the system-wide scope (which means that there are multiple clients and libraries) and distributed nature (which deals with faults of individual components) of many patterns of systems architecture don’t have direct counterparts in smaller single-process software. Thus we expect to observe the fractal nature for the more generic patterns while narrowly specialized ones are present at only one or two scopes of software design.

Another thought to consider is that it’s not in human nature to invent something entirely new – we are much more adept in imitating and combining whatever we see around us. That is why it’s so hard to find a genuine xenopsychology in literature or movies – to the extent that the eponymous Alien is just an overgrown [parasitoid wasp](https://en.wikipedia.org/wiki/Parasitoid_wasp). Hence there is another pathway to pursue – identifying the patterns which we know from software engineering in the world around us, as the authors of \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] did decades ago.

Let’s go!

## [[wiki/concepts/source/basic-metapatterns/basic-metapatterns|Basic metapatterns]]

The [[wiki/concepts/source/basic-metapatterns/basic-metapatterns|basic topologies]] lay the foundation for any system by paving ways to *divide* it into components to *conquer* its [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|complexity]]. We are going to observe them everywhere around us:

### [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]]


![A diagram of Monolith, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Monolith.png)


[[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] stands for encapsulation – we use the thing without looking inside:

- You interact with your dog (or your smartphone) through their interface without thinking of their internals.
- A function exposes its name, arguments and, probably, some comments. The implementation is hidden from its users.
- An object has a set of public methods.
- A module or a library exports several functions for use by its clients.
- A program is configured through its command line parameters and managed through its [CLI](https://en.wikipedia.org/wiki/Command-line_interface). We don’t care how the Linux utilities (e.g. *top* or *cat*) work – we just run them.
- A whole distributed system may be [hidden behind](https://comic.browserling.com/full-stack.png) a web page in your browser – and you never imagine its complexity unless you have worked on something of a kind.


### [[wiki/concepts/source/basic-metapatterns/shards|Shards]]


![A diagram of Shards, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Shards.png)


[[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] is about having multiple instances of something, which often differ in their data:

- A company employs many programmers to accelerate development of its projects.
- Carrying two mobile phones from different operators fits this pattern as well.
- This is how they make modern processors more powerful: by adding more cores, not by clocking them faster.
- Objects in OOP are the perfect example of having multiple instances that vary in their data.
- Running several shells in Linux is a kind of sharding.
- A client application of a multi-user online game is a shard as well.


### [[wiki/concepts/source/basic-metapatterns/layers|Layers]]


![A diagram of Layered Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Layers.png)


[[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] is the separation of responsibilities between external and internal components:

- In winter we wear soft clothes on our body, a warm sweater over them, and a wind-proof jacket as the external layer.
- An object comprises high-level public methods, low-level privates, and data.
- An OS has a UI which runs over user-space software over an OS kernel over device drivers over the hardware.
- Your web browser executes a frontend which communicates to a backend which uses a database.


### [[wiki/concepts/source/basic-metapatterns/services|Services]]


![A diagram of Services, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Services.png)


[[wiki/concepts/source/basic-metapatterns/services|*Services*]] boil down to composition and [separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns):

- We have legs, arms, and other narrowly specialized members.
- A gadget contains specialized chips for the activities which it supports.
- \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] advocates for an object to incorporate smaller, specialized objects (*composition over inheritance*).
- Applications often delegate parts of their logic to specialized modules or libraries.
- An OS dedicates a driver for each piece of hardware installed. Moreover, it provides many tools to its users – instead of tackling all the user needs within the kernel.
- \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] describes the way to subdivide a large system into (hopefully) loosely coupled components.


### [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]]


![A diagram of Pipeline, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Pipeline.png)


[[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] is about the stepwise transformation of data:

- The pattern got its name from real-world plumbing.
- You’ll see similar arrangements in [cellular metabolism](https://en.wikipedia.org/wiki/Metabolism).
- It is the foundation of [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|functional programming]].
- Linux command line tools are often skillfully chained into pipelines.
- Hardware is full of pipelines: from [CPU](https://en.wikipedia.org/wiki/Instruction_pipelining) and [GPU](https://en.wikipedia.org/wiki/Graphics_pipeline) to audio and video processing.
- Finally, a UI wizard passes its users through a series of screens.


## [[wiki/concepts/source/extension-metapatterns/extension-metapatterns|Extension metapatterns]]

An [[wiki/concepts/source/extension-metapatterns/extension-metapatterns|extension pattern]] encapsulates one or two aspects of the system’s implementation. It may appear only at the design levels which have those particular aspects:

### [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]


![A diagram of Services with a middleware, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Middleware.png)


A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] abstracts scaling and/or intercommunication:

- The network of post offices is a middleware – you push a letter into a mailbox and it automagically appears at its destination’s door.
- A [bus depot](https://en.wikipedia.org/wiki/Bus_depot) may mean a bus garage which deploys as many buses as needed to service the traffic or a bus station where people come to have a ride, regardless of the exact vehicle model they’ll take.
- Hardware is full of another kind of [buses](https://en.wikipedia.org/wiki/Bus_(computing)) that unify means of communication.
- TCP and UDP sockets hide the details of the underlying network.
- A distributed [[wiki/concepts/source/basic-metapatterns/services|actor framework]] allows an actor to address another actor without knowing where it is deployed.


### [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]


![A diagram of Services with a shared repository, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Shared%20Repository.png)


A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] provides data storage and/or data change notifications:

- Everybody in the room may use a ~black~whiteboard to express and exchange their ideas.
- An Internet forum works in a similar way – people post their arguments there for others to see them and get notified on answers.
- RAM and CPU caches are kinds of shared repositories. CPU caches are [kept synchronized through notifications](https://en.wikipedia.org/wiki/Cache_coherency_protocols_(examples)).
- [*Observer*](https://refactoring.guru/design-patterns/observer) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] is about getting notified when a shared object changes.
- Services or service instances may share a database.


### [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]


![A diagram of Services with a proxy, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Proxy.png)


A [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] isolates a system from its environment by translating between the internal and external protocols and/or implementing generic aspects of communication:

- You may need a translator to understand foreign people or have a secretary to deal with routine tasks. A local guide combines both roles.
- An adapter makes several hardware plugs (or software frameworks) mutually interoperable.
- Your Wi-Fi router is a proxy between your laptop and the Internet.
- A compiler is a kind of a proxy between source code and bytecode.


### [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]


![A diagram of Services with an orchestrator, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Orchestrator.png)


An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] integrates several components by implementing high-level use cases and/or keeping the components in sync:

- A taxi driver orchestrates their car’s internals.
- A [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] provides a high-level interface for a system while a [*Mediator*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] integrates a system by spreading the changes initiated by the system’s components.
- A linker composes a working program out of disjunct modules.


### [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]]


![A diagram of Sandwich Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Sandwich.png)


In [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] a varied and segmented layer with the most valuable code is operated and held in place by other, cohesive layers:

- A sandwich is an obvious example.
- This is how we make down jackets and thermal insulation in general.
- A [cell membrane](https://en.wikipedia.org/wiki/Cell_membrane) which includes many transporters and receptors looks exactly like that.


## [[wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns|Fragmented metapatterns]]

A [[wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns|fragmented topology]] uses small specialized components to approach a case which is hard to resolve with more generic means. The high degree of specialization limits the number of available examples:

### [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]]


![A diagram of Services with Polyglot Persistence, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Polyglot%20Persistence.png)


[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] is about having multiple containers for data:

- A warehouse or a cargo ship has dedicated storage areas with separate facilities for combustible, toxic, and frozen goods.
- A computer has CPU caches, RAM, flash, and hard drives for temporary or permanent data storage.
- There are map, list, and array – each with its pros and cons. A large class would often use two or three kinds of containers, and not without reason.


### [Backends for Frontends](<Backends for Frontends (BFF)>)


![A diagram of Services with Backends for Frontends, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Backends%20for%20Frontends.png)


[*Backends for Frontends*](<Backends for Frontends (BFF)>) is about treating different kinds of clients individually:

- A bank is likely to reserve a couple of employees to serve rich clients.
- A Wi-Fi router has many management interfaces: web, mobile application, CLI, and probably [TR-069](https://en.wikipedia.org/wiki/TR-069).
- A multiplayer game may provide both desktop and mobile client applications.


### [Service-Oriented Architecture](<Service-Oriented Architecture (SOA)>)


![A diagram of Service-Oriented Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Service-Oriented%20Architecture.png)


[*SOA*](<Service-Oriented Architecture (SOA)>) applies OOP techniques, including component reuse, to deal with complex systems:

- That’s what you have inside your car. Many of its internals rely on the car’s battery for power supply instead of having a small battery installed inside every component.
- Cities are built in the same way – schools, markets, and railways serve multiple houses.
- It’s the same with user space of operating systems: there is a shared UI framework which interfaces with as-many-as-needed applications, each of which calls shared libraries (DLLs).


### [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]


![A diagram of Hierarchy, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Hierarchy.png)


[[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] distributes system’s complexity over multiple levels:

- This is how large companies and armies are managed.
- Large projects [[wiki/concepts/source/analytics/cohesers-and-decouplers|are made]] of services which contain modules which contain classes which contain methods.


## [[wiki/concepts/source/implementation-metapatterns/implementation-metapatterns|Implementation metapatterns]]

An [[wiki/concepts/source/implementation-metapatterns/implementation-metapatterns|implementation metapattern]] highlights the peculiar internal arrangements of a component. Such patterns are deeply specialized:

### [[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]]


![A diagram of Plugins Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Plugins.png)


[[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] make a component’s behavior flexible through delegating its parts to small external additions:

- This is how we use tools for our work – a man becomes a digger when given a shovel.
- [*Strategy*](https://refactoring.guru/design-patterns/strategy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] is the thing.


### [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]


![A diagram of Hexagonal Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Hexagonal%20Architecture.png)


[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] protects the internals of a system from its environment:

- A drill or a screwdriver has replaceable bits.
- A living cell is encapsulated by its [membrane](https://en.wikipedia.org/wiki/Cell_membrane) and relies on [protein adapters](https://en.wikipedia.org/wiki/Membrane_protein) for interactions with its environment. [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|A kind of *Hexagonal Architecture*]] was named after it.
- [[wiki/concepts/source/extension-metapatterns/proxy|*OS Abstraction Layer* and *Hardware Abstraction Layer*]] in embedded systems or [[wiki/concepts/source/extension-metapatterns/proxy|*Anti-Corruption Layer*]] in \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] are all about that.
- The [*impure/pure/impure sandwich*](https://blog.ploeh.dk/2020/03/02/impureim-sandwich/) of functional programming is closely related. Here also, the core of the system cannot change anything outside of itself directly (any external communication relies on *adapters*) and it is [deterministic if single-threaded](http://ithare.com/chapter-vc-modular-architecture-client-side-on-debugging-distributed-systems-deterministic-logic-and-finite-state-machines/).


### [[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]]


![A diagram of Microkernel, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Microkernel.png)


[[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] shares the goods of resource providers among resource users:

- It’s like a bank that takes money from the rich to distribute them among the poor.
- This is what an OS is for. Its scheduler shares the CPU, the memory subsystem shares RAM, while the device drivers provide access to the peripherals.
- Cloud services are based on sharing computational resources among clients.


### [[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]]


![A diagram of Services over a mesh, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Mesh.png)


[[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] resembles grassroots movements – self-organization and survival through redundancy:

- Ants and bees are small, autonomous, and efficient. Their strength comes from their numbers.
- Road networks and power grids don’t collapse if some of their components are damaged as they are highly redundant.
- Torrents, mobile communications, and the Internet infrastructure are known for their robustness.


## Summary

Architectural patterns have parallels in the natural world, our society and/or different levels of computer hardware and software. Learning about them helps us feel the driving forces behind the patterns and be more flexible and creative in both using the patterns which we already know and in devising new ones.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/sharing-functionality-or-data-among-services.md ===== -->

---
title: "Sharing functionality or data among services"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/Comparison of architectural patterns/Sharing functionality or data among services.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/Comparison%20of%20architectural%20patterns/Sharing%20functionality%20or%20data%20among%20services
source_license_note: "See namespace README; preserve attribution and source links."
---

# Sharing functionality or data among services

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/Comparison of architectural patterns/Sharing functionality or data among services.md`.

Architectural patterns manifest several ways of sharing functionality or data among their components. Let’s consider a basic example: calls to two pieces of business logic need to be logged, while the logger is doing something more complex than mere console prints. Additionally, the business logic also needs to access a system-wide counter.

## Direct call

The simplest way to use a shared functionality (an *aspect*) is to call the module which implements it directly. This is possible if the users and the provider of the aspect reside in the same process, as in a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or module-based (single application) [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].

Sharing data inside a process is similar, but usually requires some kind of protection, such as an [RW lock](https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock), around it to serialize access from multiple threads.


![A logger and counter accessible for direct calls inside a monolith or in an infrastructure layer of Layered Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Sharing-DirectCall.png)


## Make a dedicated service

In a distributed system you can place the functionality or data to share into a separate service to be accessed over the network, yielding [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) for shared utilities or a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] / [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] for shared data.


![A shared logger deployed as a service in Service-Oriented Architecture. A shared counter deployed as a stand-alone shared database in Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Sharing-DedicatedService.png)


## Delegate the aspect

A less obvious solution is [delegating](https://datatracker.ietf.org/doc/html/rfc1925) our needs to another layer of the system. To continue our example of logging, a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] may log the user requests and a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] – the interservice communication. In many cases one of these generic components is configurable to record every call to the methods which we need to log – with no changes to the code!

In a similar way a service may [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|behave as a function]]: receive all the data it needs in an input message and send back all its work as an output – and let the database access remain the responsibility of its caller.


![Message loggers in a proxy and middleware. A request counter in a gateway of a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Sharing-Delegate.png)


## Replicate it

Finally, each user of a component can get its own replica. This is done implicitly in [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], and explicitly in [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] of [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] for libraries or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]] of [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] for data.

Another case of replication is importing the same code in multiple services, which happens in [[wiki/concepts/source/basic-metapatterns/services|single-layer *Nanoservices*]].


![Replicated loggers in each instance of a service in Shards, in code imported by every Nanoservice, and in sidecars of Microservices. A replicated counter in a Data Grid.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Conclusion/Sharing-Duplicate.png)


## Summary

There are four basic ways to share functionality or data in a system:

- Deploy everything together – messy yet fast and simple.
- Place the component in question into a shared service to be accessed over the network – slow and less reliable.
- Let another layer of the system both implement and use the needed function on your behalf – easy but generic, thus it may not always fit your code’s needs.
- Make a copy of the component for each of its users – fast and reliable, but the copies are hard to keep in sync.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/analytics/the-heart-of-software-architecture.md ===== -->

---
title: "The heart of software architecture"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Analytics/The heart of software architecture/The heart of software architecture.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Analytics/The%20heart%20of%20software%20architecture/The%20heart%20of%20software%20architecture
source_license_note: "See namespace README; preserve attribution and source links."
---

# The heart of software architecture

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Analytics/The heart of software architecture/The heart of software architecture.md`.

As the visible world boils down to protons and neutrons which stick together in various combinations, so too does the entirety of software architecture as a field of endeavor grow from an interplay of *cohesion* and *decoupling*.

## Contents:

- [[wiki/concepts/source/analytics/cohesers-and-decouplers|Cohesers and decouplers]]
- [[wiki/concepts/source/analytics/deconstructing-patterns|Deconstructing patterns]]
- [[wiki/concepts/source/analytics/choose-your-own-architecture|Choose your own architecture]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/acknowledgements.md ===== -->

---
title: "Acknowledgements"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Acknowledgements.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Acknowledgements
source_license_note: "See namespace README; preserve attribution and source links."
---

# Acknowledgements

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Acknowledgements.md`.

I remember Avraham Fraenkel of DSPG who showed me what a true manager is like.

Thanks to Alexey Nikitin and Maxim Medvedev of Keenetic who let me design a subsystem from scratch and see how it fared through years of heavy changes.

It was from discussion with Sherry Ignatchenko aka [IT Hare](http://ithare.com/) that I learned the difference between [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control]] and [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|data processing]] systems. Mark Richards read my [previous series of articles](https://medium.com/itnext/introduction-to-software-architecture-with-actors-part-1-89de6000e0d3) and encouraged me to press on with the classification of patterns. Kiarash Irandoust noticed [my articles on Medium](https://medium.com/@denyspoltorak) and invited me to publish them in [ITNEXT](https://itnext.io/) where many more people could see them.

Thanks to Max Grom and other participants of the Ukrainian software architecture chat for hours of heated discussions about the meaning of patterns, which resulted in several analytical chapters of the book, and also for guiding me through the intricacies of DDD. Thanks to Vitaliy Ovetskyy for reviewing this book.

Many thanks to Lars Noodén for editing the entire book and all its new chapters.

I must thank my mother and our neighbor Halyna for helping me throughout the war. Thanks to Yaroslav for his support.

I want to thank everybody who prayed for me.

This book was made possible by many people who sacrificed their happy years, their limbs, and their lives to protect those who stayed behind.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/appendices.md ===== -->

---
title: "Appendices"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Appendices.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Appendices
source_license_note: "See namespace README; preserve attribution and source links."
---

# Appendices

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Appendices.md`.

Though I don’t think that you should be reading this, this book contains a few useful appendices:

- The [[wiki/concepts/source/appendices/books-referenced|list of books referenced]] in the text. Many of them are actually good to read.
- The [[wiki/concepts/source/appendices/evolutions-of-architectures|list of evolutions]] of architectures. It is very boring to read and should rather be consulted as need arises.
- A short [[wiki/concepts/source/appendices/format-of-a-metapattern|description of the structure of the metapattern chapters]].
- The [[wiki/concepts/source/appendices/glossary|glossary]], probably redundant.
- The [[wiki/concepts/source/appendices/history-of-changes|history of changes]] (revisions).
- The [[wiki/concepts/source/appendices/index-of-patterns|index of patterns]] described in the book. This one may be handy.


## Contents:

- [[wiki/concepts/source/appendices/acknowledgements|Acknowledgements]]
- [[wiki/concepts/source/appendices/books-referenced|Books referenced]]
- [[wiki/concepts/source/appendices/copyright|Copyright]]
- [[wiki/concepts/source/appendices/disclaimer|Disclaimer]]
- [[wiki/concepts/source/appendices/evolutions-of-architectures|Evolutions of architectures]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-lead-to-shards|Evolutions of a Monolith that lead to Shards]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers|Evolutions of a Monolith that result in Layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-make-services|Evolutions of a Monolith that make Services]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins|Evolutions of a Monolith that rely on Plugins]]
  - [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|Evolutions of Shards that share data]]
  - [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-logic|Evolutions of Shards that share logic]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-that-make-more-layers|Evolutions of Layers that make more layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-that-help-large-projects|Evolutions of Layers that help large projects]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-to-improve-performance|Evolutions of Layers to improve performance]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility|Evolutions of Layers to gain flexibility]]
  - [[wiki/concepts/source/appendices/evolutions-of-services-that-restructure-services|Evolutions of Services that restructure services]]
  - [[wiki/concepts/source/appendices/evolutions-of-services-that-add-layers|Evolutions of Services that add layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-pipeline|Evolutions of a Pipeline]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-middleware|Evolutions of a Middleware]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|Evolutions of a Shared Repository]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-proxy|Evolutions of a Proxy]]
  - [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|Evolutions of an Orchestrator]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Evolutions of a Sandwich]]
- [[wiki/concepts/source/appendices/format-of-a-metapattern|Format of a metapattern]]
- [[wiki/concepts/source/appendices/glossary|Glossary]]
- [[wiki/concepts/source/appendices/history-of-changes|History of changes]]
- [[wiki/concepts/source/appendices/index-of-patterns|Index of patterns]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/books-referenced.md ===== -->

---
title: "Books referenced"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Books referenced.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Books%20referenced
source_license_note: "See namespace README; preserve attribution and source links."
---

# Books referenced

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Books referenced.md`.

<a name="ddd"></a>
**DDD** – Domain-Driven Design: Tackling Complexity in the Heart of Software. *Eric Evans. Addison-Wesley (2003).* (Most of these patterns are also well-described in \[[LDDD](#lddd)\])

<a name="ddia"></a>
**DDIA** – Designing Data-Intensive Applications: The Big Ideas Behind Reliable, Scalable, and Maintainable Systems. *Martin Kleppmann. O’Reilly Media, Inc. (2017).*

<a name="dds"></a>
**DDS** – Designing Distributed Systems: Patterns and Paradigms for Scalable, Reliable Services. *Brendan Burns. O’Reilly Media, Inc. (2018).*

<a name="deds"></a>
**DEDS** – Designing Event-Driven Systems: Concepts and Patterns for Streaming Services with Apache Kafka. *Ben Stopford. O’Reilly Media, Inc. (2018).*

<a name="eip"></a>
**EIP** – Enterprise Integration Patterns. *Gregor Hohpe and Bobby Woolf. Addison-Wesley (2003).*

<a name="fsa"></a>
**FSA** – Fundamentals of Software Architecture: An Engineering Approach. *Mark Richards and Neal Ford. O’Reilly Media, Inc. (2020).*

<a name="gof"></a>
**GoF** – Design Patterns: Elements of Reusable Object-Oriented Software. *Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides. Addison-Wesley (1994).*

<a name="lddd"></a>
**LDDD** – Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy. *Vlad Khononov. O’Reilly Media, Inc. (2021).* (Duplicates \[[DDD](#ddd)\] thus I marked as \[LDDD\] only patterns not covered by \[[DDD](#ddd)\])

<a name="mp"></a>
**MP** – Microservices Patterns: With Examples in Java. *Chris Richardson. Manning Publications (2018)*.

<a name="peaa"></a>
**PEAA** – Patterns of Enterprise Application Architecture. *Martin Fowler. Addison-Wesley Professional (2002).*

<a name="posa1"></a>
**POSA1** – Pattern-Oriented Software Architecture Volume 1: A System of Patterns. *Frank Buschmann, Regine Meunier, Hans Rohnert, Peter Sommerlad and Michael Stal. John Wiley & Sons, Inc. (1996).*

<a name="posa2"></a>
**POSA2** – Pattern-Oriented Software Architecture Volume 2: Patterns for Concurrent and Networked Objects. *Douglas C. Schmidt, Michael Stal, Hans Rohnert, Frank Buschmann. John Wiley & Sons, Inc. (2000).*

<a name="posa3"></a>
**POSA3** – Pattern-Oriented Software Architecture Volume 3: Patterns for Resource Management. *Michael Kircher, Prashant Jain. John Wiley & Sons, Inc. (2004).*

<a name="posa4"></a>
**POSA4** – Pattern-Oriented Software Architecture Volume 4: A Pattern Language for Distributed Computing. *Frank Buschmann, Kevlin Henney, Douglas C. Schmidt. John Wiley & Sons, Ltd. (2007).*

<a name="posa5"></a>
**POSA5** – Pattern Oriented Software Architecture Volume 5: On Patterns and Pattern Languages. *Frank Buschmann, Kevlin Henney, Douglas C. Schmidt*. *John Wiley & Sons, Ltd. (2007).*

<a name="sahp"></a>
**SAHP** – Software Architecture: The Hard Parts: Modern Trade-Off Analyses for Distributed Architectures. *Neal Ford, Mark Richards, Pramod Sadalage, and Zhamak Dehghani. O’Reilly Media, Inc. (2021).*

<a name="sap"></a>
**SAP** – Software Architecture Patterns. *Mark Richards. O’Reilly Media, Inc. (2015).* (All of the architectures referenced here are in \[[FSA](#fsa)\] as well, but \[SAP\] is free)


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/copyright.md ===== -->

---
title: "Copyright"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Copyright.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Copyright
source_license_note: "See namespace README; preserve attribution and source links."
---

# Copyright

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Copyright.md`.

## Attribution 4.0 International

By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.

### Section 1 – Definitions.

Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.

Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.

Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.

Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.

Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.

Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.

Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.

Licensor means the individual(s) or entity(ies) granting rights under this Public License.

Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.

Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.

You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.

### Section 2 – Scope.

License grant .

 -- Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:

 --  -- reproduce and Share the Licensed Material, in whole or in part; and

 --  -- produce, reproduce, and Share Adapted Material.

 -- Exceptions and Limitations . For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.

 -- Term . The term of this Public License is specified in Section 6(a) .

 -- Media and formats; technical modifications allowed . The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.

 -- Downstream recipients .

 --  -- Offer from the Licensor – Licensed Material . Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.

 --  -- No downstream restrictions . You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.

 -- No endorsement . Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i) .

Other rights .

 -- Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.

 -- Patent and trademark rights are not licensed under this Public License.

 -- To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.

### Section 3 – License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the following conditions.

Attribution .

 -- If You Share the Licensed Material (including in modified form), You must:

 --  -- retain the following if it is supplied by the Licensor with the Licensed Material:

 --  --  -- identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);

 --  --  -- a copyright notice;

 --  --  -- a notice that refers to this Public License;

 --  --  -- a notice that refers to the disclaimer of warranties;

 --  --  -- a URI or hyperlink to the Licensed Material to the extent reasonably practicable;

 --  -- indicate if You modified the Licensed Material and retain an indication of any previous modifications; and

 --  -- indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.

 -- You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.

 -- If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.

 -- If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.

### Section 4 – Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:

for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;

if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and

You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.

### Section 5 – Disclaimer of Warranties and Limitation of Liability.

Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.

To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.

The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

### Section 6 – Term and Termination.

This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.

Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:

 -- automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or

 -- upon express reinstatement by the Licensor.

For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.

For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.

Sections 1 , 5 , 6 , 7 , and 8 survive termination of this Public License.

### Section 7 – Other Terms and Conditions.

The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.

Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.

### Section 8 – Interpretation.

For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.

To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.

No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.

Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/disclaimer.md ===== -->

---
title: "Disclaimer"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Disclaimer.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Disclaimer
source_license_note: "See namespace README; preserve attribution and source links."
---

# Disclaimer

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Disclaimer.md`.

THIS BOOK IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, FAILING AN INTERVIEW, BEING RIDICULED, OR LOSING YOUR JOB) ARISING IN ANY WAY OUT OF THE USE OF THIS BOOK, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-middleware.md ===== -->

---
title: "Evolutions of a Middleware"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Middleware.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Middleware
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Middleware

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Middleware.md`.

A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] is unlikely to be removed (though it still may be replaced) once it is built into a system. There are few evolutions as a *Middleware* is a third-party product and is unlikely to be messed with:

- If the *Middleware* in use does not fit the preferred mode of communication between some of your services, there is an option to deploy a second specialized *Middleware*.
- If several existing systems need to be merged, that is accomplished by adding yet another layer of *Middleware*, resulting in a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Bottom-Up Hierarchy (Bus of Buses)*]].


## Add a secondary Middleware


![A specialized middleware added to a system that already has a generic middleware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Middleware%20add%20Middleware.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]].

<ins>Goal</ins>: support specialized communication between [[wiki/concepts/source/basic-metapatterns/shards|scaled]] services.

<ins>Prerequisite</ins>: the system relies on a *Middleware* for scaling.

If the current *Middleware* is too generic for the system’s needs, you can add another one for specialized communication. The new *Middleware* does not manage the instances of the services.

<ins>Pros</ins>:

- Supports specialized communication with no need to write code for tracking the instances of services.


<ins>Cons</ins>:

- You still need to notify the new *Middleware* when an instance of a service is created or dies.
- There is an extra component to administer.


## Merge two systems by building a Bottom-Up Hierarchy


![A low-level middleware interconnects several higher-level middlewares.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Middleware%20to%20Bus%20of%20Buses.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Bottom-up Hierarchy]] ([[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]], [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]).

<ins>Goal</ins>: integrate two systems without a heavy refactoring.

<ins>Prerequisite</ins>: both systems use *Middleware*s.

If we cannot change the way each subsystem’s services use its *Middleware*, we should add a new *Middleware* to connect the existing *Middleware*s.

<ins>Pros</ins>:

- No need to touch anything in the existing services.


<ins>Cons</ins>:

- Performance suffers from the double conversion between protocols.
- There is a new component to fail (miserably).


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-monolith-that-lead-to-shards.md ===== -->

---
title: "Evolutions of a Monolith that lead to Shards"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Monolith that lead to Shards.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Monolith%20that%20lead%20to%20Shards
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Monolith that lead to Shards

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Monolith that lead to Shards.md`.

One of the main drawbacks of the monolithic architecture is its lack of scalability – a single running instance of your system may not be enough to serve all its clients no matter how many resources you add in. If that is the case, you should consider [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] – *multiple instances* of a monolith. There are following options:

- Self-managed [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] – each instance owns a part of the system’s data and may communicate with every other instance (forming a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]).
- *Shards* with a [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] – each instance owns a part of the system’s data and relies on the external component to choose the right shard for the client.
- A [[wiki/concepts/source/basic-metapatterns/shards|*Pool of stateless instances*]] with a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] and a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] – any instance can process any request, but the database limits the throughput.
- A [[wiki/concepts/source/basic-metapatterns/shards|*stateful instance per client*]] with an external persistent storage – each instance owns the data related to its client and runs in a virtual environment (i.e. web browser or an [[wiki/concepts/source/basic-metapatterns/services|actor framework]]).


## Implement a Mesh of self-managed shards


![Several instances of a monolith are run as intercommunicating shards, each of which holds a subset of the system's data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Mesh%20of%20Shards.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Sharding]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]].

<ins>Goal</ins>: scale a low-latency application with weakly coupled data.

<ins>Prerequisite</ins>: the application’s data can be split into semi-independent parts.

It is possible to run several instances of an application (*shards*), with each instance owning a part of the data. For example, a chat may deploy 16 servers, each responsible for a subset of users whose hashed names end in specific 4 bits (0 to 15). However, some scenarios (e.g. renaming a user or adding a contact) may require the shards to intercommunicate. And the more coupled the shards become, the more complex a *mesh engine* is required to support their interactions, up to implementing distributed transactions, at which point you will have written a distributed database.

<ins>Pros</ins>:

- The system scales to a predefined number of instances.
- Perfect fault tolerance if [[wiki/concepts/source/basic-metapatterns/shards|replication]] and error recovery are implemented.
- Latency is kept low.


<ins>Cons</ins>:

- Direct communication between the shards (the mesh engine logic) is likely to be quite complex.
- Intershard transactions are slow and/or complicated and may corrupt the data if undertested.
- A client must know which shard owns its data to benefit from low latency. An [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]] [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] may be used on the client’s side.


## Split the data into isolated shards and add a Sharding Proxy


![Multiple instances of a monolith, each a subset of the system's data, are run behind a sharding proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Isolated%20Shards%20with%20Load%20Balancer.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Sharding]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/extension-metapatterns/proxy|Sharding Proxy]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: scale an application with sliceable data.

<ins>Prerequisite</ins>: the application’s data can be sliced into independent, self-sufficient parts.

If all the data a user operates on, directly or indirectly, is never accessed by other users, then multiple independent instances (*shards*) of the application can be deployed, each owning an instance of a database with data for a subset of the system’s users. A special kind of *Proxy*, called *Sharding Proxy*, redirects a user request to a shard that has the user’s data.

<ins>Pros</ins>:

- Perfect static (predefined number of instances) scalability.
- Failure of one shard does not affect the users of the other shards.
- [*Canary Release*](https://martinfowler.com/bliki/CanaryRelease.html) is supported.


<ins>Cons</ins>:

- The *Sharding Proxy* is a single point of failure unless [[wiki/concepts/source/basic-metapatterns/shards|*replicated*]], and it also increases latency unless deployed as an [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]].


## Separate the data layer and add a Load Balancer


![A monolith is transformed into stateless instances which run behind a load balancer and access a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Stateless%20Shards%20with%20Shared%20DB.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Pool]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]], [[wiki/concepts/source/extension-metapatterns/proxy|Load Balancer]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: achieve limited scalability and elasticity with little effort.

<ins>Prerequisite</ins>: the persistent data is of manageable size.

As data moves into a dedicated layer ([[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared File System*]]), the application becomes stateless and instances of it can be created and destroyed dynamically depending on the system’s load. However, the *Shared Repository* becomes the system’s bottleneck unless [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] is used.

<ins>Pros</ins>:

- Easy to implement.
- Dynamic scalability.
- Failure of a single instance only affects a few users transiently.
- [*Canary Release*](https://martinfowler.com/bliki/CanaryRelease.html) is supported.


<ins>Cons</ins>:

- The database limits the system’s scalability and performance.
- The *Load Balancer* and *Shared Repository* increase latency and are single points of failure.


## Dedicate an instance to each client


![Each user is allocated a temporary instance of a subsystem which loads their data at the start of the session and persists any changes to the database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Instance%20per%20Client.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Create on Demand]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]], [[wiki/concepts/source/implementation-metapatterns/microkernel|Virtualizer]] ([[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: very low latency, dynamic scalability, and failure isolation.

<ins>Prerequisite</ins>: each client’s data is small and independent of other clients.

Each client gets an instance of the application which preloads their data into memory. This way all the data is instantly accessible and a processing fault associated with one client never affects the other clients. As systems tend to have thousands to millions of clients, it is inefficient to spawn a process per client. Instead, more lightweight entities are used: a web app in a browser or an *actor* in a [[wiki/concepts/source/basic-metapatterns/services|distributed framework]].

<ins>Pros</ins>:

- Nearly perfect dynamic scalability (limited by the persistence layer).
- Good latency as everything happens in memory.
- Fault isolation is one of the features of distributed frameworks.
- The frameworks are available out of the box.


<ins>Cons</ins>:

- Virtualization frameworks tend to introduce a performance penalty.
- You may need to learn an uncommon technology.
- Scalability and performance are still limited by the shared persistence layer.


## Further steps

In most cases *sharding* does not change much inside the application, thus the common evolutions for [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] (to [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], [[wiki/concepts/source/basic-metapatterns/services|*Services*]], and [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]]) remain applicable after sharding. We’ll focus on the scalability of the resulting architectures:

- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] can be scaled (often to a dramatic extent) and deployed individually, as [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|exemplified by the *Three-Tier Architecture*]].
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] allow for subdomains to scale independently with the help of [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancers*]] or a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]. They also improve performance of the data storage as each service uses its own database which is often chosen to best fit its specific needs.
- Granular scaling also applies to [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]], but in many cases it does not make much sense because pipeline components tend to be lightweight and stateless, making it easy to scale the pipeline as a whole.


![Diagrams of Layers with individual scaling, Services with a middleware and individual scaling, and pipeline scaled as a whole.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Shards%20-%20Further%201.png)


A few specific evolutions of [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] deal with the drawbacks:

- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] reimplements [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] with a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]. Its main goal is to make the [[wiki/concepts/source/basic-metapatterns/layers|data layer]] dynamically scalable, but the results are limited by the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem) thus, depending on the mode of action, it can either provide very high performance with no consistency guarantees for a small dataset, or reasonable performance for a huge dataset. It blends the best features of stateful [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] (being an option for either pattern to evolve to) but may be quite expensive to run and lacks support for analytical queries.
- [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], a mirror image of [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]], is another option for implementing use cases that deal with data of multiple shards without the need for the shards to intercommunicate. Stateless *Orchestrators* scale perfectly but may corrupt the data if two of them write to an overlapping set of records.


![Diagrams of Space-Based Architecture that replicates data and Shards with multiple orchestrators.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Shards%20-%20Further%202.png)


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-monolith-that-make-services.md ===== -->

---
title: "Evolutions of a Monolith that make Services"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Monolith that make Services.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Monolith%20that%20make%20Services
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Monolith that make Services

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Monolith that make Services.md`.

The final major drawback of [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] is the cohesiveness of its code. The rapid start of development begets a major obstacle for project growth: every developer needs to know the entire codebase to be productive, and changes made by individual developers overlap and may break each other. Such distress is usually solved by dividing the project into components along *subdomain boundaries* (which tend to match [*bounded contexts*](https://martinfowler.com/bliki/BoundedContext.html) \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]). However, that requires a lot of work, and good boundaries and APIs are [hard to design](https://martinfowler.com/bliki/MonolithFirst.html). Thus many organizations prefer a slower iterative transition.

- A *Monolith* can be split into [[wiki/concepts/source/basic-metapatterns/services|*Services*]] right away.
- Or only the new features may be added as new services.
- Or the weakly coupled parts of existing functionality may be separated, one at a time.
- Some domains allow for sequential [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|data processing]] best described by [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]].


![In Services a single component executes a client request while in Pipeline there is no use case owner.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith_%20Services%20and%20Pipeline.png)


## Divide into Services


![A monolith is subdivided into services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: facilitate development by multiple teams, improve the code, and decouple the qualities of subdomains.

<ins>Prerequisite</ins>: there is a natural way to split the business logic into loosely coupled subdomains, and the subdomain boundaries are sure to never change in the future.

Splitting a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] into *Services* by subdomain [is risky in the early stages of a project](https://martinfowler.com/bliki/MonolithFirst.html) while the domain understanding is evolving ([[wiki/concepts/source/basic-metapatterns/services|in-process *modules*]] are less risky but provide fewer benefits). However, this is the way to go as soon as the codebase becomes unwieldy due to its size.

<ins>Pros</ins>:

- Supports multiple, relatively independent and specialized development teams.
- Lowers the penalty imposed by the project’s size and complexity on the velocity of development and product quality.
- Each team may choose the best fitting technologies for its component.
- The services can differ in their [qualities](https://en.wikipedia.org/wiki/List_of_system_quality_attributes).
- Flexible deployment and scaling.
- A certain degree of error tolerance for asynchronous systems.


<ins>Cons</ins>:

- It takes a lot of work to split a *Monolith*.
- Any future changes to the overall structure of the domain will be hard to implement.
- Sharing data between services is complicated and error-prone.
- System-wide use cases are hard to understand and debug.
- There is a moderate performance penalty for system-wide use cases.


## Add or split a service


![A service is split from a monolith.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20Split%20Service.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: [stop digging](https://en.wikipedia.org/wiki/Law_of_holes), get some work for novices who don’t know the entire project.

<ins>Prerequisite</ins>: the new functionality you are adding or the part you are splitting is weakly coupled to the bulk of the existing *Monolith*.

If your [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] is already hard to manage, but a new functionality is needed, you can try dedicating a separate service to the new feature(s). This way the *Monolith* does not become larger – it is even possible that you will move a part of its code to the newly established service.

If you are not adding a new feature but need to change an old one – use the chance to make the existing *Monolith* smaller by first separating the functionality which you are going to change from its bulk. At the very minimum this two-step process lowers the probability of breaking something unrelated to the required changes of behavior.

<ins>Pros</ins>:

- The legacy code does not increase in size and complexity.
- The new service is transferred to a dedicated team which does not need to know the legacy system or use the old technologies.
- The new service can be experimented with and even rewritten from scratch.
- The likely faults of the new service won’t crash the main application.
- The new service can be tested and deployed in isolation.
- The new service can be scaled independently.


<ins>Cons</ins>:

- The new service will have a hard time sharing data or code with the main application.
- Use cases that involve both the new service and the old application are hard to debug.
- There is a moderate performance penalty for using the service.


<ins>Further steps</ins>:

- [Continue disassembling](https://martinfowler.com/bliki/StranglerFigApplication.html) the *Monolith*.


## Divide into a Pipeline


![A Monolith is transformed into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Pipeline.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]] ([[wiki/concepts/source/basic-metapatterns/services|Services]]).

<ins>Goal</ins>: decrease the complexity of the code, make it easy to experiment with the steps of data processing, and distribute the task over multiple CPU cores, processors, or computers.

<ins>Prerequisite</ins>: the domain can be represented as a sequence of coarse-grained data processing steps.

If you can treat your application as a chain of independent steps that transform the input data, you can rely on the OS to schedule them, and you can also dedicate a development team to each of the steps. This is the default solution for a system that [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|processes a stream]] of a single type of data (video, audio, or measurements). It has excellent flexibility.

<ins>Pros</ins>:

- Nearly abolishes the influence of the project size on development velocity.
- The project’s teams become almost independent.
- Flexible deployment and scaling.
- Naturally supports event replay for reproducing bugs, testing, or benchmarking individual components.
- It is possible to have multiple implementations for each of the steps of data processing.
- Does not require any manual scheduling or thread synchronization.


<ins>Cons</ins>:

- Latency may skyrocket.
- As the number of supported scenarios grows, so does the number of components and *pipelines*. Soon there’ll be nobody who understands the system as a whole.


## Further steps

As your knowledge of the domain and your business requirements change, you may need to move some functionality between the services to keep them loosely coupled. Sometimes you have to merge two or three services together. So it goes.

Systems of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] are quite often extended with special kinds of [[wiki/concepts/source/basic-metapatterns/layers|*layers*]]:

- [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] takes care of deployment, [[wiki/concepts/source/basic-metapatterns/layers|intercommunication]], and scaling of services.
- [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] lets services operate on and communicate through [[wiki/concepts/source/foundations-of-software-architecture/shared-data|shared data]].
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] are ready-to-use components that add generic functionality to the system.
- [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] encapsulates [[wiki/concepts/source/basic-metapatterns/layers|use cases]] that involve multiple services, so that the services don’t need to know about each other.


![Diagrams of Services with a proxy, Services with an orchestrator, Services with a middleware, and Services with a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Services%20-%20Further%201.png)


Each service, being a smaller *Monolith*, may evolve on its own. Most of the evolutions of [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] are applicable. The most common examples include:

- [[wiki/concepts/source/basic-metapatterns/services|*Scaled (Sharded) Service*]] with a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] to support high load.
- [[wiki/concepts/source/basic-metapatterns/services|*Layered Service*]] to improve the code structure and decouple the deployment of parts of the service.
- [[wiki/concepts/source/basic-metapatterns/services|*Cell*]] (*Service of Services*) to involve multiple teams and technologies within a single subdomain.
- [[wiki/concepts/source/basic-metapatterns/services|*Hexagonal Service*]] to escape vendor lock-in.


![Diagrams of a scaled service, layered service, Cell, and a service that implements Hexagonal Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Services%20-%20Further%202.png)


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins.md ===== -->

---
title: "Evolutions of a Monolith that rely on Plugins"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Monolith that rely on Plugins.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Monolith%20that%20rely%20on%20Plugins
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Monolith that rely on Plugins

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Monolith that rely on Plugins.md`.

The last group of evolutions which we will review does not really change the monolithic nature of the application. Instead, its goal is to improve the *customizability* of the [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]]:

- Vanilla [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] are the most direct approach which relies on tailorable bits of logic.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] is a subtype of *Plugins* which is all about isolating the main code from any third-party components which it uses.
- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]] is a kind of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] – yet another subtype of *Plugins* – which gives users of the system full control over its behavior.


## Support plugins


![Plugins customize the monolith's behavior.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Plugins.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]].

<ins>Goal</ins>: simplify the customization of the application’s behavior.

<ins>Prerequisite</ins>: several aspects need to vary from customer to customer.

*Plugins* create points of access to the system that allow engineers to collect data and govern select aspects of the system’s behavior without having to learn the system’s implementation.

<ins>Pros</ins>:

- The system’s behavior can be modified by internal and external programmers who don’t know its internal details.
- Customized versions become much easier to release and support.


<ins>Cons</ins>:

- Extensive changes in the code may be required to expose the tunable aspects of the system.
- Testability becomes poor because of the large number of possible variants.
- Performance is likely to degrade.


## Isolate dependencies with Hexagonal Architecture


![The database, external libraries, and a protocol support component are separated from the business logic and isolated with adapters.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Hexagonal.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]] ([[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]]).

<ins>Goal</ins>: isolate the business logic from its external dependencies.

<ins>Prerequisite</ins>: there are third-party or frequently changing components in the system.

The main business logic will communicate with any external component through an API or SPI defined in the terms of the business logic itself. This way it will not depend on anything at all, and any component will be replaceable with another implementation or a [stub/mock](https://stackoverflow.com/questions/3459287/whats-the-difference-between-a-mock-stub).

<ins>Pros</ins>:

- Vendor lock-in is ruled out.
- A component may be replaced through to the very end of the system’s life cycle.
- Stubs and mocks are supported for testing and local or early development.
- It is possible to provide multiple implementations of a component.


<ins>Cons</ins>:

- Some extra effort is required to define and use the interfaces.
- There is performance degradation, mostly due to lost optimization opportunities.


## Add an Interpreter (support Scripts)


![The high-level logic is rewritten as scripts which are run by an interpreter.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Interpreter.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/microkernel|Scripts aka Interpreter]] ([[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]] ([[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]])).

<ins>Goal</ins>: allow the system’s users to implement their own business logic.

<ins>Prerequisite</ins>: the domain is representable in high-level terms.

*Interpreter* lets the users develop high-level business logic from scratch by programming interactions of pre-defined building blocks, which are implemented in the core of the system. That provides unparalleled flexibility at the cost of degraded performance and design complexity.

<ins>Pros</ins>:

- Perfect flexibility and customizability for every user.
- The high-level business logic is written in high-level terms, making it fast to develop and easy to grasp.


<ins>Cons</ins>:

- Requires much effort to design correctly.
- There may be a heavy performance penalty if the API is overly fine-grained.
- Testability may be an issue.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers.md ===== -->

---
title: "Evolutions of a Monolith that result in Layers"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Monolith that result in Layers.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Monolith%20that%20result%20in%20Layers
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Monolith that result in Layers

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Monolith that result in Layers.md`.

Another drawback of [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] is its … er … monolithism. The entire application exposes a single set of qualities and all its parts (if they ever emerge) are deployed together. However, life awards flexibility: parts of a system may benefit from being written in varying languages and styles, and deployed with different frequency and amount of testing, sometimes to specific hardware or end users’ devices. They may need to [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|vary in security and scalability]] as well. Enter [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] – the subdivision by the *level of abstractness*:

- Most *Monoliths* can be divided into three or four [[wiki/concepts/source/basic-metapatterns/layers|*layers*]].
- It is common to see the database separated from the main application.
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] (e.g. [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Cache*]], and [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]]) are common additions to the system.
- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] adds a layer of indirection to simplify the system’s API for its clients.


## Divide into Layers


![A monolith is split into application, domain and database layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: let parts of the system vary in qualities, improve the structure of the code.

<ins>Prerequisite</ins>: there is a natural way to separate the high-level logic from the low level implementation details and dependencies.

Most systems apply *layering* by default as it grants a lot of flexibility at very little cost. [[wiki/concepts/source/basic-metapatterns/layers|Common sets of layers]] are: [[wiki/concepts/source/basic-metapatterns/layers|UI]], [[wiki/concepts/source/basic-metapatterns/layers|tasks]] (orchestration), [[wiki/concepts/source/basic-metapatterns/layers|domain]] (detailed business rules) and infrastructure (database and libraries) or [[wiki/concepts/source/basic-metapatterns/layers|frontend, backend and data]].

<ins>Pros</ins>:

- It is a natural way to specialize and decouple two or three development teams.
- The layers may vary in virtually any quality:
  - They are deployed and scaled independently.
  - They may run on different hardware, including client devices.
  - They may vary in programming language, paradigm, and release cycle.
- Most changes are isolated to a single layer.
- Layering opens a way to many evolutions of the system.
- The code [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|becomes easier to read]].


<ins>Cons</ins>:

- Dividing an existing application into *Layers* may take some effort.
- There is a small performance penalty.


## Use a database


![The data of a monolithic system is moved to a database, leaving the business logic stateless.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Database.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]).

<ins>Goal</ins>: avoid implementing a database.

<ins>Prerequisite</ins>: the system needs to query (and maybe also edit) a large amount of data.

A database is non-trivial to implement. While ordinary files are good for small volumes of data, as your needs grow so needs to grow your technology. Deploy a database.

<ins>Pros</ins>:

- A well-known database is sure to be more reliable than any in-house implementation.
- Many databases provide heavily optimized algorithms for querying data.
- You can choose specific hardware to deploy the database to.
- Your (now stateless) application will be easy to scale.


<ins>Cons</ins>:

- Databases are complex and require fine-tuning.
- You cannot adapt the database engine to your evolving needs.
- Most databases do not scale.
- You are stepping right into [vendor lock-in](https://en.wikipedia.org/wiki/Vendor_lock-in).


<ins>Further steps</ins>:

- Deploy multiple [[wiki/concepts/source/basic-metapatterns/shards|*instances*]] of your application behind a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]].
- Continue the transition to [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] by separating the high-level and low-level business logic.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] improves performance of the data layer.
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]] handles read and write requests in separate services.
- [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] has low latency and allows for dynamic scalability of the whole system, including the data layer.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] will allow you to switch to another database in the future.


## Add a Proxy


![A part of generic functionality of a monolith is moved to a proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Proxy.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]].

<ins>Goal</ins>: avoid implementing generic functionality.

<ins>Prerequisite</ins>: Your system serves clients (as opposed to [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|controlling hardware]]).

A *Proxy* is placed between your system and its clients to provide generic functionality that otherwise would have to be implemented by the system. The kinds of *Proxy* to use with [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] are: [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Cache*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]], and [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]]. Multiple *Proxies* can be deployed.

<ins>Pros</ins>:

- You save some time (and money) on development.
- A well-known *Proxy* is likely to be more secure and reliable than an in-house implementation.
- You can choose the hardware to deploy the *Proxy* to.


<ins>Cons</ins>:

- Latency degrades, except for [[wiki/concepts/source/extension-metapatterns/proxy|*Response Cache*]] where it depends on frequency of identical requests.
- The *Proxy* may fail, which increases the chance of total failure of your system.
- Beware of [vendor lock-in](https://en.wikipedia.org/wiki/Vendor_lock-in).


<ins>Further steps</ins>:

- Another kind of *Proxy* may be added.
- Some systems employ a *Proxy* per client, leading to [*Backends for Frontends*](<Backends for Frontends (BFF)>).


## Add an Orchestrator


![An orchestrator is added to a monolithic system, allowing for higher-level client requests.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Orchestrator.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]].

<ins>Goal</ins>: provide a high-level public API with improved developer experience and performance.

<ins>Prerequisite</ins>: the API of your system is fine-grained and there are common [[wiki/concepts/source/basic-metapatterns/layers|use cases]] which repeat certain sequences of calls to your API.

A well-designed *Orchestrator* should provide a high-level API which is intuitive, easy to use, and coarse-grained to minimize the number of interactions between the system and its clients. An old way to access the original system’s API may still be maintained for uncommon use cases or legacy client applications ([[wiki/concepts/source/extension-metapatterns/orchestrator|*open* orchestration]]). As a matter of fact, you program the common application logic on behalf of your clients.

<ins>Pros</ins>:

- Client applications become easier to write.
- Latency improves.


<ins>Cons</ins>:

- You get yet another moving part to design, test, deploy, and observe; and lots of design meetings between the development teams for a bonus.
- The new coarse-grained interface will likely be less powerful than the original one.


<ins>Further steps</ins>:

- [*Backends for Frontends*](<Backends for Frontends (BFF)>) use an *Orchestrator* per client type.


## Further steps

Applying one of the evolutions discussed above does not prevent you from following another one of them, or even the same one for a second time:

- A layer can sometimes be split into two layers.
- A database can be added.
- Multiple kinds of *Proxies* are OK.
- If you don’t have an *orchestration layer* yet, you may add one.


Those were evolutions from *Layers* to [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].

Another set of evolutions stems from splitting one or more *layers* into [[wiki/concepts/source/basic-metapatterns/services|*Services*]]:

- Splitting a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] and/or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] yields [*Backends for Frontends*](<Backends for Frontends (BFF)>) where requests from each kind of client are processed by a dedicated component.
- Splitting the layer with the main business logic results in [[wiki/concepts/source/basic-metapatterns/services|*Services*]], possibly augmented with layers of [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] and/or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]. If all the other layers beside the business logic layer remain monolithic, it is a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].
- Splitting the [[wiki/concepts/source/basic-metapatterns/layers|*database layer*]] leads to [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] with specialized storages.
- If all the layers share the domain dimension and are split along it, [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]] (or its subtype [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]]) emerge.
- If each layer is split along its own domain, the system follows [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) that is built around component reuse.
- Finally, some domains support [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] – a tree-like architecture where each layer takes a share of the system’s functionality.


![Diagrams of Backends for Frontends over Layers, Service-Oriented Architecture, Sandwich, Layered Services, Hierarchy, and Layers with Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers%20-%20Further%201.png)


In addition,

- Distributed systems usually allow for the [[wiki/concepts/source/basic-metapatterns/shards|scaling]] of one or more layers.
- A layer may employ [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] for better customizability.
- The UI and infrastructure layers may be split and abstracted according to the rules of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] (or its subtype [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Separated Presentation*]]).
- The system can often be extended with [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]], resulting in a kind of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


![Diagrams of Layers with plugins, Layers with scripts, and Hexagonal Architecture with a layered core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers%20-%20Further%202.png)


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-pipeline.md ===== -->

---
title: "Evolutions of a Pipeline"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Pipeline.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Pipeline
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Pipeline

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Pipeline.md`.

[[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] [[wiki/concepts/source/basic-metapatterns/services|inherits its set of evolutions from *Services*]]. Components can be added, split in two, merged or replaced. Many systems employ a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] (pub/sub or pipeline framework), [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] (which may be a database or file system), or [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]].

There are a couple of *Pipeline*-specific evolutions:

- The first service of the *Pipeline* can be promoted to [[wiki/concepts/source/extension-metapatterns/orchestrator|*Front Controller*]] which tracks status updates for every request it handles.
- Adding an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] turns a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] into [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. As the high-level business logic moves to the [[wiki/concepts/source/basic-metapatterns/layers|orchestration layer]], the services don’t need to interact directly anymore, the interservice communication channels disappear, and the system turns into ordinary [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated Services*]].


## Promote a service to Front Controller


![The first service of a pipeline subscribes to notifications from other services and thus becomes a Front Controller.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Pipeline%20promote%20Front%20Controller.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Front Controller]] ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]], [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]), [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]] ([[wiki/concepts/source/basic-metapatterns/services|Services]]).

<ins>Goal</ins>: allow for clients to query the state of their requests.

<ins>Prerequisite</ins>: request processing steps are slow (may depend on human action).

If the request processing steps require heavy calculations or manual action, then clients may want to query the status of their requests, and analysts may want to see bottlenecks in the *Pipeline*. Let the first service in the *Pipeline* track the state of all the running requests by subscribing to status notifications from other services.

<ins>Pros</ins>:

- The state of each running request is readily available.


<ins>Cons</ins>:

- The first service in the pipeline becomes more complex and starts depending on every other service.


<ins>Further steps</ins>:

- The *Front Controller* may be further promoted to [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] if there is a need to support many complex scenarios.


## Add an Orchestrator


![Adding an orchestrator transforms a pipeline into Orchestrated Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Pipeline%20use%20Orchestrator.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]], [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: support many use cases.

<ins>Prerequisite</ins>: performance degradation is acceptable.

When a [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] system is gradually extended with more and more use cases, it is very likely to fall into integration hell where nobody understands how its components interrelate. Extract the [[wiki/concepts/source/basic-metapatterns/layers|workflow logic]] into a dedicated service.

<ins>Pros</ins>:

- New use cases are easy to add.
- Complex scenarios are supported.
- Error handling becomes trivial.
- The services don’t depend on each other.
- There is a single client-facing team, other teams are not under pressure from the business.
- It is easier to run actions in parallel.
- Global scenarios become debuggable.
- The services don’t need to be redeployed when the high-level logic changes.


<ins>Cons</ins>:

- The number of messages in the system doubles, thus its performance may degrade.
- The *Orchestrator* may become a development and performance bottleneck, or a single point of failure.


<ins>Further steps</ins>:

- If there are several clients that strongly vary in their workflows, you can apply [*Backends for Frontends*](<Backends for Frontends (BFF)>) with an *Orchestrator* per client.
- If the *Orchestrator* grows too large, it can be [[wiki/concepts/source/extension-metapatterns/orchestrator|divided]] into layers, services, or both, with the latter option resulting in a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].
- The *Orchestrator* can be [[wiki/concepts/source/extension-metapatterns/orchestrator|scaled]] and can have its own database.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-proxy.md ===== -->

---
title: "Evolutions of a Proxy"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Proxy.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Proxy
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Proxy

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Proxy.md`.

It usually makes little sense to get rid of a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] once it is integrated into the system. Its only real drawback is a slight increase in latency for user requests which may be helped through creation of [[wiki/concepts/source/extension-metapatterns/proxy|bypass channels]] between the clients and a service which needs low latency. The other drawback of the pattern, namely the *Proxy*’s being a single point of failure, is countered by deploying multiple instances of the *Proxy*.

As *Proxies* are usually third-party products, there is very little we can change about them:

- We can add another kind of a *Proxy* on top of the existing one.
- We can use a stack of *Proxies* per client, making [*Backends for Frontends*](<Backends for Frontends (BFF)>).


## Add another Proxy


![A proxy is added on top of an existing proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Proxy%20add%20Proxy.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: avoid implementing generic functionality.

<ins>Prerequisite</ins>: you don't have this kind of *Proxy* yet.

A system is not limited to a single kind of *Proxies*. As a *Proxy* represents your system without changing its function, *Proxies* are transparent, thus they are stackable.

It often makes sense to colocate software *Proxies* or use a multifunctional *Proxy* to reduce the number of network hops between the clients and the system. However, in a highly loaded system *Proxies* may be resource-hungry, thus in some cases colocation strikes back.

<ins>Pros</ins>:

- You get another aspect of your system implemented for you.


<ins>Cons</ins>:

- Latency degrades.
- More work for admins.
- Another point of possible failure.


## Deploy a Proxy per client type


![A proxy is subdivided into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Proxy%20to%20Backends%20for%20Frontends.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]], [Backends for Frontends](<Backends for Frontends (BFF)>).

<ins>Goal</ins>: let the aspects of communication vary among kinds of clients.

<ins>Prerequisite</ins>: your system serves several kinds of clients.

If you have internal and external clients, or admins and users, you may want to vary the setup of *Proxies* for each kind of client, sometimes to the extent of physically separating network communication paths, so that each kind of client is treated according to its bandwidth, priority, and permissions.

<ins>Pros</ins>:

- It is easy to set up various aspects of communication for a group of clients.


<ins>Cons</ins>:

- More work for admins as the *Proxies* are duplicated.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-sandwich.md ===== -->

---
title: "Evolutions of a Sandwich"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Sandwich.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Sandwich
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Sandwich

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Sandwich.md`.

Unique evolutions of a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] involve the system’s domain logic or its topology:

- The [[wiki/concepts/source/basic-metapatterns/layers|*domain-level*]] *services* are independent enough to be easily added or removed.
- In most cases they share technologies, allowing for splitting or merging of the services.
- If the services are found to be strongly coupled, they can be merged into a monolithic layer, likely to be subdivided in a better way later on.
- Alternatively, the subdomains can be further decoupled.


## Add or remove a domain-level service


![One of the domain-level services is removed and another one is added.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20add%20remove%20Service.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]].

<ins>Goal</ins>: maintain effective development.

<ins>Prerequisite</ins>: a new subdomain emerges or an old one becomes obsolete.

Though the *Sandwich* architecture allows for subdomains to be pretty independent in their logic, you should update your system’s high-level structure whenever there are drastic changes in the domain knowledge or functional requirements. Creation or deletion of a component often means forming or disbanding a team (see [*Inverse Conway Maneuver*](https://martinfowler.com/bliki/ConwaysLaw.html)).

<ins>Pros</ins>:

- The system’s architecture remains clear as it follows the domain knowledge.
- The development teams remain narrowly specialized, thus effective.
- Dead domain-level code is easily identified and removed.


<ins>Cons</ins>:

- You may need to update your database schema.
- A newly established team takes time to learn its area of responsibility, while disbanding an old team disrupts almost everyone on the project.


## Split or merge domain-level services


![One domain-level service is split in half while two other services are merged together.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20split%20merge%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]].

<ins>Goal</ins>: maintain effective development.

<ins>Prerequisite</ins>: the business requirements gradually diverge from your original vision.

[[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|Ideally]], each service should be kept cohesive, while the services should be decoupled from each other. However, business likes to mess up your plans. If you ignore the results, your teams will be slowed down by mutual dependencies or become overburdened by the size of the components which they maintain. Therefore, restructure both the system and teams once the divergence between the domain knowledge and system’s architecture starts to negatively impact development.

> If an architecture is misaligned with the domain which it models, some components implement functions which don’t properly belong to them, while others need a lot of help from their neighbors. Many unnecessary dependencies emerge between components and that both increases complexity (you cannot develop a component without knowing other components) and slows down the system (calls between components tend to be inefficient).

<ins>Pros</ins>:

- The system’s architecture is realigned with the domain knowledge.
- The system components remain internally cohesive and decoupled from each other.
- The development teams stay narrowly specialized, thus effective.


<ins>Cons</ins>:

- You will have to update the database schema and integration logic ([[wiki/concepts/source/basic-metapatterns/layers|use cases]]).
- Splitting or merging teams disrupts them.


## Merge all the domain-level services together


![The entire domain layer is merged, resulting in Layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20to%20Layers.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: improve the system performance and, possibly, development efficiency.

<ins>Prerequisite</ins>: the project is small but found to be strongly coupled.

Often the project grows in an unexpected manner. If you see that the domain-level services interact intensely, that likely means that you chose a wrong architecture. Revert to *Layers* to remove the artificial interfaces. You may also consider merging the domain-level teams if there are not too many people in them.

<ins>Pros</ins>:

- Less indirection and boilerplate code.
- Improved performance which can be further optimized.


<ins>Cons</ins>:

- Now all the teams face higher system complexity.
- The teams will share the codebase which means a high level of interdependency.


## Subdivide both shared layers


![The integration and data layers are divided into subdomains, producing Three-Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20to%20Layered%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/layered-services|Three-Layered Services]] ([[wiki/concepts/source/fragmented-metapatterns/layered-services|Layered Services]]).

<ins>Goal</ins>: fine-grained scalability, database performance optimization, and limited fault tolerance.

<ins>Prerequisite</ins>: the subdomains are loosely coupled in both [[wiki/concepts/source/basic-metapatterns/layers|use cases]] and [[wiki/concepts/source/basic-metapatterns/layers|data]].

It is natural to divide a *Sandwich* into [[wiki/concepts/source/basic-metapatterns/services|*Services*]], but only if your domain is not [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|data-centric]] (built around a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]) and your use cases are not too complex (requiring an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]).

<ins>Pros</ins>:

- Independent scaling and deployment of the services.
- Database technologies can be chosen on a per service basis.
- Simpler application and database components.
- Limited fault tolerance – if one of the services fails, others may still respond to clients.


<ins>Cons</ins>:

- Complex use cases are hard to implement or debug.
- Poor latency for use cases that involve multiple subdomains.
- Any coupling in the data impairs performance and increases costs.
- Now you’ll have much more work for your DevOps.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-a-shared-repository.md ===== -->

---
title: "Evolutions of a Shared Repository"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of a Shared Repository.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20a%20Shared%20Repository
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of a Shared Repository

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of a Shared Repository.md`.

Once a database appears, it is unlikely to go away. I see the following evolutions to improve performance of the data layer:

- [[wiki/concepts/source/basic-metapatterns/shards|*Shard*]] the database.
- Use [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] for dynamic scalability.
- Divide the data into a private database per service.
- Deploy specialized databases ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).


## Shard the database


![The shared database is sharded so that each database instance holds a subset of data,](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database_%20Shard.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Sharding]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]], maybe [[wiki/concepts/source/extension-metapatterns/proxy|Sharding Proxy]].

<ins>Goal</ins>: increase capacity and performance of the database.

<ins>Prerequisite</ins>: the data is shardable (consists of independent records).

If your database is overloaded and the data which it contains describes independent entities (users, companies, or sales) you can deploy multiple instances of the database with subsets of the data distributed among them. You will need to deploy a *Sharding Proxy* or the services will have to find out which database *shard* to access by themselves, likely through hashing the record’s *primary key* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] or with the help of an [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]]. There is also a good chance that several smaller tables will have to be replicated to all the shards or moved to a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|dedicated *Shared Database*]] (resulting in [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).

Modern distributed databases support sharding out of the box, but an overgrown table may still impact the performance of the database.

<ins>Pros</ins>:

- Unlimited scalability.
- You don’t need to change your database vendor.
- Failure of a single database instance affects few users.


<ins>Cons</ins>:

- You will need to manage many instances of the database.
- The application or a custom script may have to synchronize shared tables among the instances.
- There is no way to do joins or run aggregate functions (such as *sum* or *count*) over multiple shards – all that logic moves to the services that use the database.


<ins>Further steps</ins>:

- [[wiki/concepts/source/basic-metapatterns/shards|*Replicate*]] each shard to improve fault tolerance and, possibly, read throughput.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] or [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]] describe pre-calculating aggregates into another analytical database ([*Reporting Database*](https://martinfowler.com/bliki/ReportingDatabase.html)).
- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] may be cheaper as it scales dynamically. However, in its default and highly performant configuration it is prone to write collisions.


## Use Space-Based Architecture


![The shared database is migrated to a Data Grid, resulting in Space-Based Architecture](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Space-Based%20Architecture.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/mesh|Space-Based Architecture]] ([[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]], [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]).

<ins>Goal</ins>: dynamically scale throughput of the database.

<ins>Prerequisite</ins>: data collisions are acceptable.

*Space-Based Architecture* (SBA) duplicates the contents of a persistent database to a distributed in-memory *cache* co-located with the services managed by the *SBA*’s *Middleware*. That makes most data access operations very fast unless one needs to avoid write collisions. The [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh Middleware*]] autoscales both the services and the associated data cache under load, granting nearly perfect scalability. However, this architecture is costly because of the amount of traffic and CPU time spent on replicating the data between the *Mesh nodes*.

<ins>Pros</ins>:

- Nearly unlimited dynamic scalability.
- Off-the-shelf solutions are available.
- Very high fault tolerance.


<ins>Cons</ins>:

- Choose one: data collisions or mediocre performance.
- Low latency is guaranteed only when the entire dataset fits in the memory of a node.
- High operational cost because the nodes will send each other lots of data.
- No support for analytical queries.


## Move the data to private databases of services


![The shared database is split into databases dedicated to subdomains, resulting in Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: decouple the services, remove the performance bottleneck (*Shared Database*).

<ins>Prerequisite</ins>: the domain data is weakly coupled.

If the data clearly follows subdomains, it may be possible to subdivide it accordingly. The services will become [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] (or [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrated*]] if they have an [[wiki/concepts/source/extension-metapatterns/orchestrator|*integration layer*]]) instead of communicating through the [[wiki/concepts/source/foundations-of-software-architecture/shared-data|shared data]].

<ins>Pros</ins>:

- The services become independent in their persistence and data processing technologies.
- Performance of the [[wiki/concepts/source/basic-metapatterns/layers|*data layer*]], which tends to limit the scalability of the system, will likely improve thanks to the use of smaller specialized databases.


<ins>Cons</ins>:

- The communication between the services and the synchronization of their data becomes a major issue.
- Joins of the data from different subdomains will not be available.
- Costs are likely to increase because of data transfer and duplication between the services.
- You will have to administrate multiple databases.


<ins>Further steps</ins>:

- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] or a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] help a service access and join data that belongs to other services.


## Deploy specialized databases


![The shared database is migrated to specialized databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Polyglot%20Persistence.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]].

<ins>Goal</ins>: improve performance and maybe fault tolerance of the data layer.

<ins>Prerequisite</ins>: there are diverse data types or patterns of data access.

It is very likely that you can either use [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*specialized databases*]] for various data types or deploy [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*read-only replicas*]] of your data for queries.

<ins>Pros</ins>:

- You can choose one of the many specialized databases available on the market.
- There is a good chance to significantly improve performance.
- Replication improves fault tolerance of your data layer.


<ins>Cons</ins>:

- It may take effort to learn the new technologies and use them efficiently.
- Someone needs to see to the new database(s).
- You’ll likely need to work around *replication lag* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\].


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-an-orchestrator.md ===== -->

---
title: "Evolutions of an Orchestrator"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of an Orchestrator.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20an%20Orchestrator
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of an Orchestrator

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of an Orchestrator.md`.

Employing an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] has two pitfalls:

- The system becomes slower because too much communication is involved.
- A single *Orchestrator* may be found to be too large and rigid.


There is one way to counter the first point and more ways to solve the second one:

- Subdivide the *Orchestrator* by the system’s subdomains, forming [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]] and minimizing network communication.
- Subdivide the *Orchestrator* by the type of client, forming [*Backends for Frontends*](<Backends for Frontends (BFF)>).
- Add another [[wiki/concepts/source/basic-metapatterns/layers|*layer*]] of orchestration.
- Build a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].


## Subdivide to form Layered Services


![An orchestrator is subdivided into subdomain components which become the application layers of respective services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Layered%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/layered-services|Orchestrated Three-Layered Services]] ([[wiki/concepts/source/fragmented-metapatterns/layered-services|Layered Services]] ([[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]])).

<ins>Goal</ins>: simplify the *Orchestrator*, let the service teams own orchestration, decouple forces for the services, and improve performance.

<ins>Prerequisite</ins>: the high-level ([[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestration]]) logic is weakly coupled between the subdomains.

If the [[wiki/concepts/source/basic-metapatterns/layers|*orchestration* logic]] mostly follows the subdomains, it may be possible to partition it accordingly. Each service gets a part of the *Orchestrator* that mostly deals with its subdomain but may call other services when needed. As a result, [[wiki/concepts/source/foundations-of-software-architecture/orchestration|each service orchestrates every other service]]. Still, a large part of orchestration becomes internal to each service, meaning that fewer calls over the network are involved.

<ins>Pros</ins>:

- You subdivide the large *Orchestrator* codebase.
- Performance is improved.
- The services become more independent in their quality attributes.


<ins>Cons</ins>:

- You lose the client-facing *orchestration team* – now each service’s team will need to face its clients.
- Service teams become interdependent (while having equal rights), which may result in slow development and [suboptimal decisions](https://en.wikipedia.org/wiki/Design_by_committee).
- There is no way to share code between different use cases or even take a look at all of the scenarios at once.


<ins>Further steps</ins>:

- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] or a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] help a service access and join data that belongs to other services, further reducing the need for interservice communication.


## Subdivide to form Backends for Frontends


![An orchestrator is subdivided into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Backends%20for%20Frontends.png)


<ins>Patterns</ins>: [Backends for Frontends](<Backends for Frontends (BFF)>), [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]].

<ins>Goal</ins>: simplify the *Orchestrator*, employ a team per client type, and decouple the quality attributes for clients.

<ins>Prerequisite</ins>: clients vary in workflows and forces.

When use cases for clients vary, it makes sense for each kind of client to have a dedicated *Orchestrator*.

<ins>Pros</ins>:

- The smaller *Orchestrators* are independent in qualities, technologies, and teams.
- The smaller *Orchestrators* are … well, smaller.


<ins>Cons</ins>:

- There is no good way to [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|share code]] between the *Orchestrators*.
- There are more system components.


<ins>Further steps</ins>:

- You may want to add client-specific [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] and, maybe, co-locate them with the *Orchestrators* to avoid the extra network hop.
- Adding another shared [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] below the ones dedicated to clients creates a place for sharing functionality among the *Orchestrators*.
- If you are running [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] over a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] may help to share [[wiki/concepts/source/basic-metapatterns/layers|generic code]].


## Add a layer of orchestration


![An orchestrator is subdivided into a pair of simple and complex orchestrators.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20add%20Orchestrator.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: implement simple use cases quickly, while still supporting complex ones.

<ins>Prerequisite</ins>: use cases vary in their complexity.

You may use two or three *orchestration frameworks* (engines) which differ in complexity. A simple declarative tool may be enough for the majority of user requests, and falling back to the custom-tailored code would be needed in rare complex cases.

<ins>Pros</ins>:

- Simple scenarios are easy to write.
- You retain good flexibility with hand-written code when it is needed.


<ins>Cons</ins>:

- Requires learning multiple technologies.
- More components mean more failures and more administration.
- Performance of complex requests may suffer from more indirection.


<ins>Further steps</ins>:

- Subdivide one or more of the resulting *orchestration layers* to form [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]], [*Backends for Frontends*](<Backends for Frontends (BFF)>), [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]], or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]].


## Form a Hierarchy


![An orchestrator is subdivided into a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Hierarchy.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Top-Down Hierarchy]] ([[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]).

<ins>Goal</ins>: simplify the *Orchestrator* and, if possible, the services.

<ins>Prerequisite</ins>: the domain is hierarchical.

If an *Orchestrator* becomes too complex, some domains (e.g. IIoT or telecom) encourage the use of a tree of *Orchestrators*. The most generic functionality is processed by its root and each additional layer takes care of one aspect of the domain.

<ins>Pros</ins>:

- Multiple specialized teams and technologies.
- Small codebase per team.
- Reasonable testability.
- Some decoupling of quality attributes.


<ins>Cons</ins>:

- Hard to debug.
- Poor latency in global scenarios unless several layers of the *hierarchy* are colocated.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-architectures.md ===== -->

---
title: "Evolutions of architectures"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of architectures.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20architectures
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of architectures

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of architectures.md`.

This appendix details dozens of evolutions of [[wiki/concepts/source/introduction/metapatterns|metapatterns]] to show how they connect together. The evolutions probably have practical value through listing prerequisites, benefits, and drawbacks, but I am not sure that many readers will get through them without becoming bored to death. The metapattern chapters in the main parts of the book include abridged versions of the sections below.

Duplicate and similar evolutions are omitted, and I did not write any evolutions for [[wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns|fragmented metapatterns]] as you should be able to infer them on your own after having read the book. Furthermore, for some reason I don’t know of any evolutions for the [[wiki/concepts/source/implementation-metapatterns/implementation-metapatterns|implementation metapatterns]], except for those that re-integrate the custom parts of the system into its core, mostly to improve the system’s performance. However, such evolutions are trivial, thus omitted.

## Contents:

- [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-lead-to-shards|Evolutions of a Monolith that lead to Shards]]
- [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers|Evolutions of a Monolith that result in Layers]]
- [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-make-services|Evolutions of a Monolith that make Services]]
- [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins|Evolutions of a Monolith that rely on Plugins]]
- [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|Evolutions of Shards that share data]]
- [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-logic|Evolutions of Shards that share logic]]
- [[wiki/concepts/source/appendices/evolutions-of-layers-that-make-more-layers|Evolutions of Layers that make more layers]]
- [[wiki/concepts/source/appendices/evolutions-of-layers-that-help-large-projects|Evolutions of Layers that help large projects]]
- [[wiki/concepts/source/appendices/evolutions-of-layers-to-improve-performance|Evolutions of Layers to improve performance]]
- [[wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility|Evolutions of Layers to gain flexibility]]
- [[wiki/concepts/source/appendices/evolutions-of-services-that-restructure-services|Evolutions of Services that restructure services]]
- [[wiki/concepts/source/appendices/evolutions-of-services-that-add-layers|Evolutions of Services that add layers]]
- [[wiki/concepts/source/appendices/evolutions-of-a-pipeline|Evolutions of a Pipeline]]
- [[wiki/concepts/source/appendices/evolutions-of-a-middleware|Evolutions of a Middleware]]
- [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|Evolutions of a Shared Repository]]
- [[wiki/concepts/source/appendices/evolutions-of-a-proxy|Evolutions of a Proxy]]
- [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|Evolutions of an Orchestrator]]
- [[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Evolutions of a Sandwich]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-layers-that-help-large-projects.md ===== -->

---
title: "Evolutions of Layers that help large projects"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Layers that help large projects.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Layers%20that%20help%20large%20projects
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Layers that help large projects

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Layers that help large projects.md`.

The main drawback (and benefit) of [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] is that much or all of the business logic is kept together in one or two components. That allows for easy debugging and fast development in the initial stages of the project but slows down and complicates work as the project [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|grows in size]]. The only way for a growing project to continue evolving at a reasonable speed is to subdivide its business logic into several smaller, thus less [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|complex]], components that match subdomains (*bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]). There are several options for such a change with their applicability depending on the domain:

- In a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] the middle layer with the bulk of business logic is divided into [[wiki/concepts/source/basic-metapatterns/services|*Services*]], leaving the upper [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and lower [[wiki/concepts/source/extension-metapatterns/shared-repository|*database*]] layers intact for possible future evolutions.
- Sometimes the business logic can be represented as a set of directed graphs which is known as [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]].
- If you are lucky, your domain is naturally a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].


## Divide the domain layer into Services


![The domain layer is split into subdomain components, making a Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20Domain%20to%20Services.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]] ([[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]), [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]).

<ins>Goal</ins>: make the code simpler and let several teams work on the project efficiently.

<ins>Prerequisite</ins>: the low-level business logic comprises loosely coupled subdomains.

It is very common for a system’s domain to comprise weakly interacting *bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. They are integrated through high-level use cases and/or [[wiki/concepts/source/foundations-of-software-architecture/shared-data|relations in data]]. For such a system it is relatively easy to subdivide the [[wiki/concepts/source/basic-metapatterns/layers|domain logic]] into *Services* while leaving the integration and data layers shared, yielding a *Sandwich*.

<ins>Pros</ins>:

- You get multiple specialized development teams.
- The largest and most complex piece of code is split into several smaller components.
- There is more flexibility with deployment and scaling.


<ins>Cons</ins>:

- Future changes in the overall structure of the domain will be harder to implement.
- System-wide use cases become somewhat harder to debug as they span over many components.
- Performance will degrade as soon as the *Services* and their *Orchestrator* become distributed.


<ins>Further steps</ins>:

- Continue by subdividing the *Orchestrator* and *database*, turning the system into [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Orchestrated Three-Layered Services*]].
- Divide the *Orchestrator* (by type of client) into [*Backends for Frontends*](<Backends for Frontends (BFF)>).
- Use multiple databases ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).
- Scale well with [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]].


## Build an Event-Driven Architecture over a Shared Database


![A backend is subdivided into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20to%20Event-Driven%20Architecture.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/pipeline|Event-Driven Architecture]] ([[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]] ([[wiki/concepts/source/basic-metapatterns/services|Services]])), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]).

<ins>Goal</ins>: untangle the code, support multiple teams, and improve scalability.

<ins>Prerequisite</ins>: the use cases are trivial sequences of loosely coupled, coarse-grained steps.

If your system features well-defined and simple workflows for processing every kind of input request, then it can be divided into several [[wiki/concepts/source/basic-metapatterns/services|*subdomain services*]], each hosting a few related steps of multiple use cases. Each service subscribes to inputs from other services and/or system’s clients and publishes output events.

<ins>Pros</ins>:

- The code is divided into much smaller (and simpler) segments.
- It is easy to add new steps or use cases as this structure is quite flexible.
- You open a way to having several almost independent teams, one per service.
- You can achieve flexible deployment and scaling as the services are stateless, but you need to add a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for that.
- This architecture naturally supports event replay as the means of reproducing bugs or testing / benchmarking individual components.
- There is no need for explicit scheduling or thread synchronization.


<ins>Cons</ins>:

- The system as a whole is hard to debug.
- You will have to live with high latency.
- You may end up with too many components which are interconnected in too many ways.


<ins>Further steps</ins>:

- Add a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] that supports scaling and failure recovery.
- Split the *Shared Database* by subdomain, yielding [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Choreographed Two-Layered Services*]].
- Scale with [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]].
- Extract the logic of use cases into an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]].


## Build a Top-Down Hierarchy


![The lower layers of a system are subdivided, resulting in a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Hierarchy.png)


<ins>Patterns</ins>: [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Top-Down Hierarchy]] ([[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]).

<ins>Goal</ins>: untangle the code, support multiple teams, and achieve fine-grained scalability.

<ins>Prerequisite</ins>: the domain is hierarchical.

Splitting the lower layers into independent components with identical interfaces simplifies the managing code and allows the managed components to be deployed, developed, and run independently of each other. Ideally, the mid-layer components should participate in decision-making so that the uppermost component is kept relatively simple.

<ins>Pros</ins>:

- Hierarchy is easy to develop and support with multiple teams.
- Individual components are straightforward to add, modify, or replace.
- The components scale, deploy, and run independently.
- The system is quite fault tolerant.


<ins>Cons</ins>:

- It takes time and skill to figure out good interfaces.
- There are many components to administer.
- Latency is suboptimal for system-wide use cases.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-layers-that-make-more-layers.md ===== -->

---
title: "Evolutions of Layers that make more layers"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Layers that make more layers.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Layers%20that%20make%20more%20layers
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Layers that make more layers

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Layers that make more layers.md`.

Not all the layered architectures are equally layered. A [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] or [[wiki/concepts/source/basic-metapatterns/layers|database]] has already stepped into the realm of [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] but is still far from reaping all of its benefits. It may continue its journey in a few ways that [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers|were earlier discussed]] for *Monolith*:

- Employing a [[wiki/concepts/source/basic-metapatterns/layers|*database*]] (if you don’t use one) lets you rely on a thoroughly optimized state-of-the-art subsystem for data processing and storage.
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] are similarly reusable generic components to be added at will.
- Implementing an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] on top of your system may improve the programming experience and runtime performance for your clients.


![A diagram of calls in a layered system. A single request from a client is translated by an Orchestrator into multiple calls to lower layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Layers.png)


It is also common to:

- Segregate the business logic into two [[wiki/concepts/source/basic-metapatterns/layers|*layers*]].


## Split the business logic into two layers


![A backend is subdivided into application and domain layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20in%20Two.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: let parts of the business logic vary in their qualities, improve the structure of the code.

<ins>Prerequisite</ins>: the high-level and low-level parts of the business logic are loosely coupled.

It is often possible to split a backend into [[wiki/concepts/source/basic-metapatterns/layers|integration]] ([[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestration]]) and [[wiki/concepts/source/basic-metapatterns/layers|domain]] layers. That allows for one team to specialize in customer use cases while the other one delves deep into the domain knowledge and infrastructure.

<ins>Pros</ins>:

- You get an extra development team.
- The high-level use cases may be deployed separately from business rules.
- The layers may diverge in technologies and styles.
- The code may [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|become less complex]].


<ins>Cons</ins>:

- There is a small performance penalty.
- In-depth debugging becomes harder.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility.md ===== -->

---
title: "Evolutions of Layers to gain flexibility"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Layers to gain flexibility.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Layers%20to%20gain%20flexibility
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Layers to gain flexibility

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Layers to gain flexibility.md`.

The last group of evolutions to consider is about making the system more adaptable. We have [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins|already discussed]] the following evolutions for [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]]:

- The behavior of the system may be modified through [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] protects the business logic from dependencies on libraries and data stores.
- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]] allow for customization of the system’s logic on a per client basis.


![Diagrams of Layers with plugins, Layers with scripts, and Hexagonal Architecture with a layered core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers%20-%20Further%202.png)


There is also a new evolution that modifies the upper (orchestration) layer:

- The [[wiki/concepts/source/basic-metapatterns/layers|*orchestration layer*]] may be split into [*Backends for Frontends*](<Backends for Frontends (BFF)>) to match the needs of several kinds of clients.


## Divide the orchestration layer into Backends for Frontends


![The application layer is split into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Backends%20for%20Frontends.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [Backends for Frontends aka BFFs](<Backends for Frontends (BFF)>).

<ins>Goal</ins>: let each kind of client get a dedicated development team.

<ins>Prerequisite</ins>: no high-level logic is shared between client types.

It is possible that your system has different kinds of users, e.g. buyers, sellers, and admins; or web and mobile applications. It may be easier to support a separate integration module for each kind of client than to keep all the unrelated code together in a single integration layer.

<ins>Pros</ins>:

- Each kind of client gets a dedicated team which may choose best fitting technologies.
- You get rid of the single large codebase of the integration layer.


<ins>Cons</ins>:

- There is no good way to share code between the *BFFs* (in the [[wiki/concepts/source/extension-metapatterns/orchestrator|naive implementation]]).
- There are new components to administer.


<ins>Further steps</ins>:

- [Evolve the *BFFs*](<Backends for Frontends (BFF)#evolutions>) through adding a shared *layer* or [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] for the common functionality.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-layers-to-improve-performance.md ===== -->

---
title: "Evolutions of Layers to improve performance"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Layers to improve performance.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Layers%20to%20improve%20performance
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Layers to improve performance

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Layers to improve performance.md`.

There are several ways to improve the performance of a [[wiki/concepts/source/basic-metapatterns/layers|*layered system*]]. One we have [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|already discussed]] for [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]]:

- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] co-locates the data store and business logic and scales both dynamically.


![The database is migrated to a Data Grid, resulting in a scalable Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Space-Based%20Architecture.png)


Others are new and thus deserve more attention:

- Merging several layers improves latency by eliminating the communication overhead.
- Scaling some of the layers may improve throughput but degrade latency.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] is the name for using multiple specialized data stores.


## Merge several layers


![The application and domain layers are merged.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Merge.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]] or [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]].

<ins>Goal</ins>: improve performance.

<ins>Prerequisite</ins>: the layers share programming language, hardware setup, and qualities.

If your system’s development [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|is finished]] (no changes are expected) and you really need that extra 5% performance improvement, then you can try merging everything back into a *Monolith* or a [[wiki/concepts/source/basic-metapatterns/layers|*3-Tier*]] system (front, back, data).

<ins>Pros</ins>:

- Enables aggressive performance optimizations.
- The system may become easier to debug.


<ins>Cons</ins>:

- The code is frozen – it will be much harder to evolve.
- Your teams lose the ability to work independently.


<ins>Further steps</ins>:

- [[wiki/concepts/source/basic-metapatterns/shards|*Shard*]] the entire system.


## Scale individual layers


![The application and domain layers are independently sharded.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers_%20Shard.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/basic-metapatterns/shards|Shards]], often [[wiki/concepts/source/extension-metapatterns/proxy|Load Balancer]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]).

<ins>Goal</ins>: scale the system.

<ins>Prerequisite</ins>: some layers are [[wiki/concepts/source/basic-metapatterns/shards|stateless]] or limited to the [[wiki/concepts/source/basic-metapatterns/shards|data of a single client]].

Multiple instances or layers can be created, with their number and deployment [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|varying from layer to layer]]. That may work seamlessly if each instance of the layer which receives an event which can start a use case knows the instance of the next layer to communicate to. Otherwise you will need a *Load Balancer*.

<ins>Pros</ins>:

- Flexible scalability.
- Better fault tolerance.
- Co-deployment with clients is possible.


<ins>Cons</ins>:

- More complex operations (more parts to keep an eye on).


<ins>Further steps</ins>:

- [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] scales the data layer.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] improves performance of the data layer.


## Use multiple databases


![The database layer is subdivided into specialized databases, resulting in Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Polyglot%20Persistence.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]].

<ins>Goal</ins>: optimize performance of data processing.

<ins>Prerequisite</ins>: there are isolated use cases for or subsets of the data.

If you have separated *commands* (write requests) from *queries* (read requests), you can serve the queries with [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|read-only replicas]] of the database while the main database is reserved for the commands.

If your types of data or data processing algorithms vary, you may deploy several [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|specialized databases]], each matching some of your needs. That lets you achieve the best performance in a wide range of cases.

<ins>Pros</ins>:

- The best performance for all the use cases.
- Specialized data processing algorithms out of the box.
- Replication may help with error recovery.


<ins>Cons</ins>:

- Someone will need to learn and administer all those databases.
- Keeping the databases consistent takes effort and the replication delay may negatively affect the UX.


<ins>Further steps</ins>:

- Serve the read and write requests with different backends in accordance with [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Command-Query Responsibility Segregation (CQRS)*]].
- Separate the backend into [[wiki/concepts/source/basic-metapatterns/services|*services*]] which match the already separated databases.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-services-that-add-layers.md ===== -->

---
title: "Evolutions of Services that add layers"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Services that add layers.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Services%20that%20add%20layers
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Services that add layers

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Services that add layers.md`.

The most common modifications to a [[wiki/concepts/source/basic-metapatterns/services|system of *Services*]] involve supplementary system-wide *layers* which compensate for the inability of the *services* to share anything among themselves:

- A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] knows of all the deployed service [[wiki/concepts/source/basic-metapatterns/shards|instances]]. It mediates [[wiki/concepts/source/basic-metapatterns/layers|communication]] between them and may manage their scaling and failure recovery.
- The [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] of a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] make a virtual layer of [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|shared libraries]] for the [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] it hosts.
- A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] simplifies the initial phases of development and provides data consistency and [[wiki/concepts/source/foundations-of-software-architecture/shared-data|interservice communication]].
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] stand between the system and its clients and take care of shared aspects that otherwise would need to be implemented by every service.
- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] is the single place for the high-level logic of every [[wiki/concepts/source/basic-metapatterns/layers|use case]].
- Transforming *Services* into a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] greatly simplifies their integration.


## Add a Middleware


![The communication aspect of services can be covered by a dedicated middleware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20add%20Middleware.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]], [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: take care of scaling, recovery, and interservice communication without programming it.

<ins>Prerequisite</ins>: communication between the services is uniform.

Distributed systems may fail in a zillion ways. You want to ruminate neither on that nor on [heisenbugs](https://en.wikipedia.org/wiki/Heisenbug). And you probably want to have a framework for scaling the services and restarting them after failure. Get a third-party *Middleware*! Let your programmers write the business logic, not infrastructure.

<ins>Pros</ins>:

- You don't invest your time in infrastructure.
- Scaling and error recovery are made easy.


<ins>Cons</ins>:

- There may be a performance penalty which becomes worse for uncommon patterns of communication.
- The *Middleware* may become a single point of failure.


<ins>Further steps</ins>:

- Use a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] for dynamic scaling and as a way to implement [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|shared aspects]].


## Use a Service Mesh


![Scaled services reside on a shared layer of sidecars which is placed on top of a shared mesh engine. All instances of each service access the service's database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Multifunctional%20-%20Service%20Mesh.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/mesh|Service Mesh]] ([[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]], [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]), [[wiki/concepts/source/extension-metapatterns/proxy|Sidecar]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]), [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: support dynamic scaling and interservice communication out of the box; share libraries among the services.

<ins>Prerequisite</ins>: service instances are mostly [[wiki/concepts/source/basic-metapatterns/shards|stateless]].

The [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] architecture boasts dynamic scaling under load thanks to its *Mesh*-based *Middleware*. It also allows for the services to share libraries via their *Sidecars* – additional containers co-located with each service instance – to avoid duplication of [[wiki/concepts/source/basic-metapatterns/layers|generic code]] among the services.

<ins>Pros</ins>:

- Dynamic scaling and error recovery.
- Available out of the box.
- Provides a way to implement shared aspects (cross-cutting concerns) once and use the resulting libraries in every service.


<ins>Cons</ins>:

- Performance degrades because of the complex distributed infrastructure.
- You may suffer vendor lock-in.


## Use a Shared Repository


![The data of individual services is merged into a shared repository.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20to%20Shared%20Database.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]], [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: let the services [[wiki/concepts/source/foundations-of-software-architecture/shared-data|share data]], don’t invest in operating multiple databases.

<ins>Prerequisite</ins>: the services use a uniform approach to persisting their data.

You don’t really need every service to have a private database. A shared one is enough in many cases.

<ins>Pros</ins>:

- It is easy for the services to share and synchronize data.
- Lower operational complexity.
- No data duplication.


<ins>Cons</ins>:

- All the services depend on the database schema which becomes hard to alter.
- The single database will limit performance of the system.
- It may also become a single point of failure.


<ins>Further steps</ins>:

- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] scales the [[wiki/concepts/source/basic-metapatterns/layers|data layer]] but it is a simple key-value store.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] is about having multiple specialized data stores.


## Add a Proxy


![Generic aspects of services move to a shared proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20add%20Proxy.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]], [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: use a standard infrastructure component on behalf of your entire system.

<ins>Prerequisite</ins>: the system serves its clients in a uniform way.

Putting a generic component between the system and its clients helps the programmers concentrate on business logic rather than protocols, infrastructure, or even security.

<ins>Pros</ins>:

- You get a choice of generic functionality without investing development time.
- It is an additional layer that isolates your system from both its clients and attackers.


<ins>Cons</ins>:

- There is a latency penalty caused by the extra network hop.
- Each *Proxy* may be a single point of failure, or at least needs some admin oversight.


<ins>Further steps</ins>:

- You can always add another kind of [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]].
- If there are multiple clients that differ in their protocols, you can employ a stack of *Proxies* per client, resulting in [*Backends for Frontends*](<Backends for Frontends (BFF)>).


## Use an Orchestrator


![The application logic is extracted from individual services into a shared orchestrator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20use%20Orchestrator.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]], [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: have the high-level logic of use cases distilled as intelligible code.

<ins>Prerequisite</ins>: the use cases comprise sequences of high-level steps (which is very likely to be true for a system of [[wiki/concepts/source/basic-metapatterns/services|*subdomain services*]]).

When a use case jumps over several services in a dance of [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]], there is no easy way to understand it as there is no single place to see it in the code. It may be even worse with [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelined*]] systems where the use cases are embodied in the structure of event channels between the components.

Extract the [[wiki/concepts/source/basic-metapatterns/layers|high-level business logic]] from the choreographed services or their interconnections and put it into a dedicated component.

<ins>Pros</ins>:

- You are not limited in the number and complexity of use cases anymore.
- The global use cases become much easier to debug.
- You have a new team dedicated to the interaction with customers, freeing the other teams to study their parts of the domain or work on code improvements.
- Many changes in the high-level logic can be implemented and deployed without touching the main services.
- The extra layer decouples the main services from the system’s clients and from each other.


<ins>Cons</ins>:

- There is a performance penalty because the number of messages per use case doubles.
- The *Orchestrator* may become a single point of failure.
- Some flexibility is lost as the *Orchestrator* couples the services’ qualities.


<ins>Further steps</ins>:

- If there are several clients that strongly vary in workflows, you can apply [*Backends for Frontends*](<Backends for Frontends (BFF)>) with an *Orchestrator* per client.
- If the *Orchestrator* grows too large, it [[wiki/concepts/source/extension-metapatterns/orchestrator|can be divided]] into layers, services, or both; the latter option resulting in a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].
- The *Orchestrator* can be [[wiki/concepts/source/extension-metapatterns/orchestrator|scaled]] and can have its own database.


## Make a Sandwich


![The application and data parts of services are separated from the domain logic and merged into system-wide layers, resulting in a Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20to%20Sandwich.png)


<ins>Patterns</ins>: [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]] ([[wiki/concepts/source/basic-metapatterns/layers|Layers]], [[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]), [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]).

<ins>Goal</ins>: simplify the integration of tightly coupled services.

<ins>Prerequisite</ins>: the services use compatible technologies in their application and data layers.

Tightly coupled services waste a lot of programming effort and performance on boilerplate communication and data transfer. At the same time, their [[wiki/concepts/source/basic-metapatterns/layers|*domain* logic]] remains fairly independent, making full merge into a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] impractical.

Try merging only the [[wiki/concepts/source/basic-metapatterns/layers|*use cases*]] and [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] while leaving the *domain* layer subdivided.

<ins>Pros</ins>:

- *Use cases* become much easier to debug.
- No boilerplate code for communication between the services.
- No data duplication or data transfer among the services.
- You have a new team dedicated to use cases and interaction with the customers.
- Many changes in *use cases* can be implemented and deployed without touching the *domain* logic.


<ins>Cons</ins>:

- The services are coupled in their properties.
- There are now single points of failure that leave the system totally inoperational.
- The *Shared Database* limits the system’s performance.


<ins>Further steps</ins>:

- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] scales the *data* layer.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-services-that-restructure-services.md ===== -->

---
title: "Evolutions of Services that restructure services"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Services that restructure services.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Services%20that%20restructure%20services
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Services that restructure services

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Services that restructure services.md`.

[[wiki/concepts/source/basic-metapatterns/services|*Services*]] work well when each service matches a subdomain and is developed by a dedicated team. If those premises change, you’ll need to restructure the system:

- A new feature request may emerge outside of any of the existing subdomains, creating a new service.
- A service may grow too large to be developed by a single team, calling for division.
- Two services may become so strongly coupled that they fare better when merged together.
- The entire system may need to be glued back into a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] if the domain knowledge changes or interservice communication strongly degrades performance.
- Alternatively, coupled services may be clustered into co-deployed [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]] to reduce operational complexity.


## Add or split a service


![A service is split in half.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Split.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]].

<ins>Goal</ins>: get one more team to work on the project, decrease the size of an existing service.

<ins>Prerequisite</ins>: there is a loosely coupled (new or existing) subdomain that does not have a dedicated service (yet).

If you need to add a new functionality that does not naturally fit into one of the existing services, you may create a new service and, maybe, get a new team for it.

If one of your services has grown too large, you should look for a way to subdivide it (likely through a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] stage with a shared [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*database*]]) to decrease the size and, correspondingly, complexity of its code and get multiple teams to work on the resulting (sub)services. However, that makes sense only if the old service is not highly cohesive – otherwise [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|the resulting subsystem may be more complex]] than the original service.

<ins>Pros</ins>:

- You get an extra development team.
- The complexity of the code decreases (splitting an existing service) or does not increase (adding a new one).
- The new service is independently scalable.


<ins>Cons</ins>:

- You add to the operations complexity by creating a new system component and several inter-component dependencies.
- There is a new point of failure, which means that bugs and outages become more likely.
- Performance (or at least the latency and cost efficiency) of the system will deteriorate because interservice communication is slow.
- You may have a hard time debugging use cases that involve both the old and new service.


## Merge services


![Two services are merged.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Merge.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]] or [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: accept the coupling of subdomains and improve performance.

<ins>Prerequisite</ins>: the services use compatible technologies.

If you see that several services communicate with each other almost as intensely as they call their internal methods, then they probably belong together.

If your use cases have too high a latency or you pay too much for CPU and traffic, the issue may originate with the interservice communication, and merging the services should help. No services, no headache.

Alternatively, as the domain knowledge changes \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], you may have to merge much of the code together only to subdivide it later along the updated subdomain boundaries. Which means that you face [lots of work for no reason](https://martinfowler.com/bliki/MonolithFirst.html).

<ins>Pros</ins>:

- Improved performance.
- It becomes easy for parts of the merged code to access each other and share data.
- The new merged *service* or *Monolith* is easier to debug than the original *Services*.


<ins>Cons</ins>:

- The development teams become even more interdependent.
- There is no good way to vary qualities by subdomain.
- You lose granular scalability by subdomain.
- The merged codebase may be too large for comfortable development.
- If anything fails, everything fails.


## Cluster services


![Services are grouped into Cells, reducing their interdependencies.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Cluster.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Cell]] ([[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]], [[wiki/concepts/source/basic-metapatterns/services|Services]]).

<ins>Goal</ins>: reduce operational complexity, decouple subdomains, and improve performance.

<ins>Prerequisite</ins>: there are distinct subdomains.

When there are too many services, none sees the big picture: which components are involved in a use case and why the system works the way it does. Moreover, managing tens to hundreds of different services with their databases is hard and error-prone.

Therefore, cluster the services which share a subdomain into a co-deployed cohesive *Cell*.

<ins>Pros</ins>:

- Managing ten *Cells* is much easier than managing a hundred services.
- More clear and independent subdomains as their interdependencies become explicit.
- Lower traffic because the closely communicating services are now co-located.
- Lower data storage requirements as the contents of the *Cell* may [[wiki/concepts/source/extension-metapatterns/shared-repository|share a database]].
- No boilerplate code for versioning or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|data views]] inside the *Cell*.


<ins>Cons</ins>:

- The development teams that work on services that belong to a single *Cell* need to synchronize their actions.
- A *Cell* is usually scaled as a whole.


<ins>Further steps</ins>:

- Complete the *Cell* encapsulation through the use of [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] and [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]].
- Transform any strongly coupled *Cells* into [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwiches*]].


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-shards-that-share-data.md ===== -->

---
title: "Evolutions of Shards that share data"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Shards that share data.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Shards%20that%20share%20data
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Shards that share data

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Shards that share data.md`.

One issue peculiar to [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] is that of coordinating the instances deployed, especially if their data become coupled. The most direct solution is to let the instances operate a component that wraps the shared data:

- If the whole dataset needs to be shared, it can be extracted into a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] layer.
- If data collisions are tolerated, [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] promises low latency and dynamic scalability.
- If a part of the system’s data becomes coupled, only that part can be moved to a *Shared Repository*, causing each instance to manage two data stores: [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|private and shared]].
- Another option is to split out a [[wiki/concepts/source/basic-metapatterns/services|*service*]] to own the coupled data and always deploy it as a single instance. The remaining parts of the system become coupled to that service, not to each other.


## Move all the data to a Shared Repository


![The data of shards moves to a shared database. The shards become stateless and are deployed behind a load balancer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20to%20Shared%20DB.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Pool]] ([[wiki/concepts/source/basic-metapatterns/shards|Shards]]), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]), [[wiki/concepts/source/extension-metapatterns/proxy|Load Balancer]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: don’t struggle against the coupling of the shards, keep it simple and stupid.

<ins>Prerequisite</ins>: the system is not under pressure for data size or latency (which can be addressed by the further evolutions).

In case a shard needs to access data owned by any other shard, the prerequisite of the independence of shards starts to fall apart. Grab all the data of all the shards and push it into a *Shared Database*, if you can (there may be too much data or the database access may be too slow). As all the shards become identical, you’ll likely add a *Load Balancer*.

<ins>Pros</ins>:

- You can choose one of the many specialized databases available.
- The stateless instances of the main application become dynamically scalable.
- Failure of a single instance affects a few users for a short time.
- [*Canary Release*](https://martinfowler.com/bliki/CanaryRelease.html) is supported.


<ins>Cons</ins>:

- The database limits the system’s scalability and performance.
- The *Load Balancer* and *Shared Database* increase latency and are single points of failure.


<ins>Further steps</ins>:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] will let you change your database in the future.
- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] decreases latency by co-locating subsets of the data and the instances of your application.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] uses multiple specialized databases, often discerning between commands and queries. That may greatly relieve the primary (write) database.
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]] goes even further by processing read and write requests with dedicated *services*.


## Use Space-Based Architecture


![The data of the shards moves to a Data Grid, resulting in a Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20to%20Space-Based%20Architecture.png)


<ins>Patterns</ins>: [[wiki/concepts/source/implementation-metapatterns/mesh|Space-Based Architecture]] ([[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]], [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]), [[wiki/concepts/source/basic-metapatterns/shards|Shards]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: don’t struggle against the coupling between the shards, maintain high performance.

<ins>Prerequisite</ins>: data collisions are acceptable.

*Space-Based Architecture* is a *Mesh* of nodes which comprise the application and a cached subset of the system’s data. A node broadcasts any changes to its data to other nodes, and it may request any data that it needs from the other nodes. Collectively, the nodes of the *Mesh* keep the entire system’s data cached in memory.

Though *Space-Based Architecture* may provide several modes of action, including [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|single write / multiple read]] replicas, it is most efficient when there is no write synchronization between its nodes, in which case data consistency is sacrificed for performance and scalability.

<ins>Pros</ins>:

- Unlimited dynamic scalability.
- Off-the-shelf solutions are available.
- Failure of a single instance affects few users.


<ins>Cons</ins>:

- Choose one: data collisions or mediocre performance.
- Low latency is supported only for datasets that fit in memory of a single node.
- High operational costs because the nodes exchange huge amounts of data.
- No support for analytical queries.


## Use a Shared Repository for the coupled subset of data


![A coupled subset of the system's data is stored in a shared repository, while the bulk of the data is sharded.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Shared%20DB.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Shards]], [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Private and Shared Databases]] ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]]), [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]] ([[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: solve the coupling between shards without losing performance.

<ins>Prerequisite</ins>: the shards are coupled through a small subset of data.

If a subset of the data is accessed by all the shards, that subset can be moved into a dedicated database, which is likely to be fast if only because it is small. Using a distributed database that keeps its data synchronized among all the shards may be even faster.

This approach resembles [*Shared Kernel*](https://ddd-practitioners.com/home/glossary/bounded-context/bounded-context-relationship/shared-kernel/) \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].

<ins>Pros</ins>:

- You can choose one of the many specialized databases available.


<ins>Cons</ins>:

- The *Shared Database* increases latency and is the single point of failure.


## Split a service with the coupled data


![Coupled business logic and data is separated from shards into a shared singletone service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20split%20Shared%20Service.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/services|Services]], [[wiki/concepts/source/basic-metapatterns/shards|Shards]].

<ins>Goal</ins>: solve the coupling between the shards in an honorable way.

<ins>Prerequisite</ins>: the part of the domain which causes coupling between the shards is weakly coupled to the remaining domain.

If a part of the domain is too cohesive to be sharded, we can often extract it from the main application into a dedicated service. That way the main application remains sharded while the new service exists as a single instance. In rare cases there is a chance to re-shard the new service with a sharding key which is different from the one used for sharding the main application.

This approach resembles [*Shared Kernel*](https://ddd-practitioners.com/home/glossary/bounded-context/bounded-context-relationship/shared-kernel/) \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].

<ins>Pros</ins>:

- The main code should become a little bit simpler.
- The new service can be given to a new team.
- The new service may choose a database which best fits its needs.


<ins>Cons</ins>:

- Now it’s hard to share data between the new service and the main application.
- Scenarios that use the new service are harder to debug.
- There is a moderate performance penalty for using the extra service.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/evolutions-of-shards-that-share-logic.md ===== -->

---
title: "Evolutions of Shards that share logic"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Evolutions of architectures/Evolutions of Shards that share logic.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Evolutions%20of%20architectures/Evolutions%20of%20Shards%20that%20share%20logic
source_license_note: "See namespace README; preserve attribution and source links."
---

# Evolutions of Shards that share logic

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Evolutions of architectures/Evolutions of Shards that share logic.md`.

Other cases are better solved by extracting the logic that manipulates multiple [[wiki/concepts/source/basic-metapatterns/shards|*shards*]]:

- Splitting a [[wiki/concepts/source/basic-metapatterns/services|*service*]] (as discussed [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|above]]) yields a component that represents both shared data and shared logic.
- Adding a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] lets the shards communicate with each other without keeping direct connections. It also may do housekeeping: error recovery, replication, and scaling.
- A [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] hides the existence of the shards from clients.
- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] calls (or messages) multiple shards to serve a user request. That relieves the shards of the need to coordinate their states and actions by themselves.


## Add a Middleware


![A middleware manages shards and lets them communicate to each other.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Middleware.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Shards]], [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: simplify the communication between shards, their deployment, and recovery.

<ins>Prerequisite</ins>: many shards need to exchange information, some may fail.

A *Middleware* transports messages between shards, checks their health, and recovers ones which have crashed. It may manage data replication and deployment of software updates as well.

<ins>Pros</ins>:

- The shards become simpler because they don’t need to track each other.
- Many good third-party implementations are readily available.


<ins>Cons</ins>:

- Performance may degrade.
- The components of the *Middleware* are new points of failure.


## Add a Sharding Proxy


![A sharding proxy relieves clients from the need to find the appropriate shard.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Load%20Balancer.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Shards]], [[wiki/concepts/source/extension-metapatterns/proxy|Sharding Proxy]] ([[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]), [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: simplify the code on the client side, hide your implementation from clients.

<ins>Prerequisite</ins>: each client connects directly to the shard which owns their data.

The client application may know the address of the shard which serves it and connect to it without intermediaries. That is the fastest means of communication, but it prevents you from changing the number of shards or other details of your implementation without updating all the clients, which may be unachievable. An intermediary may help.

<ins>Pros</ins>:

- Your system becomes isolated from its clients.
- You can put generic aspects into the *Proxy* instead of implementing them in the shards.
- *Proxies* are readily available.


<ins>Cons</ins>:

- The extra network hop increases latency unless you deploy the *Sharding Proxy* as an [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]] co-located with every client which, however, brings back the issue of client software updates.
- The *Sharding Proxy* is a single point of failure unless [[wiki/concepts/source/basic-metapatterns/shards|*replicated*]].


## Move the integration logic into an Orchestrator


![The high-level logic of shards moves to a shared orchestrator which integrates the data stored within and processed by individual shards.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20use%20Orchestrator.png)


<ins>Patterns</ins>: [[wiki/concepts/source/basic-metapatterns/shards|Shards]], [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]], [[wiki/concepts/source/basic-metapatterns/layers|Layers]].

<ins>Goal</ins>: isolate the shards and eliminate their awareness of each other.

<ins>Prerequisite</ins>: the shards are coupled through their high-level logic.

When a high-level scenario uses multiple shards ([[wiki/concepts/source/extension-metapatterns/orchestrator|*Scatter-Gather* and *MapReduce*]] are the simplest examples), the way to follow is to extract all such scenarios into a dedicated stateless component. That makes the shards independent of each other.

<ins>Pros</ins>:

- The shards don’t need to be aware of each other.
- The high-level logic can be written in a high-level language by a dedicated team.
- The high-level logic can be deployed independently.
- The main bulk of the code should become much simpler.


<ins>Cons</ins>:

- Latency will increase.
- The *Orchestrator* becomes a single point of failure which has a good chance to corrupt your data.


<ins>Further steps</ins>:

- [[wiki/concepts/source/extension-metapatterns/orchestrator|*Shard* or *replicate* the *Orchestrator*]] to support higher load and to remain online if it fails.
- *Persist* the *Orchestrator* (give it a dedicated database) to make sure that it does not leave half-committed transactions upon failure.
- *Divide* the *Orchestrator* [[wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility|into *Backends for Frontends*]] or a [[wiki/concepts/source/extension-metapatterns/orchestrator|*SOA*-style layer]] if you have multiple kinds of clients or workflows, respectively.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/format-of-a-metapattern.md ===== -->

---
title: "Format of a metapattern"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Format of a metapattern.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Format%20of%20a%20metapattern
source_license_note: "See namespace README; preserve attribution and source links."
---

# Format of a metapattern

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Format of a metapattern.md`.

The descriptions of most [[wiki/concepts/source/introduction/metapatterns|metapatterns]] follow the same format:

### Diagram

The structural diagram (in *abstractness-subdomain-sharding* [[wiki/concepts/source/introduction/metapatterns|coordinates]]) of a typical application of the metapattern. Please note that in practice the number and types of components and their interactions may vary:

- Even though most diagrams show 3 *layers* or *services*, there are many 2-layered or 4-layered systems, while the number of services may often be greater than 10.
- [[wiki/concepts/source/extension-metapatterns/extension-metapatterns|*Extension metapatterns*]] add a *layer* (or a *layer of services*) to an existing system, which is shown as [[wiki/concepts/source/basic-metapatterns/services|*Services*]], but may instead comprise [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or even a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]].
- Subtypes of [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] or [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] differ in their [[wiki/concepts/source/introduction/system-topologies|topologies]]. Only one is shown.
- Components of metapatterns may communicate in various ways that include in-process calls, RPC, asynchronous messaging, or streams. Only one of them is shown. Optional communication pathways may appear as dashed arrows.


Most diagrams feature the following colors:

- [[wiki/concepts/source/basic-metapatterns/layers|*Use cases*]] (aka integration, orchestration, workflow or application logic) are shown in green. Those are high-level scenarios executed by user actions or signals from hardware which keep the system acting as a whole. Use cases are *what* your software does.
- [[wiki/concepts/source/basic-metapatterns/layers|*Domain logic*]] (business rules), shown in blue, is the set of algorithms that models the real-world system which your software describes. It is *how* your system solves its tasks.
- [[wiki/concepts/source/basic-metapatterns/layers|*Generic code*]] is white. It stands for tools and libraries unrelated to your business. Examples include communication protocols, data compression, and common maths.
- [[wiki/concepts/source/basic-metapatterns/layers|*Data*]] is gray. It includes business-critical in-memory state (e.g. user’s session) and persistent storage (in a database or files).


*Use cases* and *domain logic* comprise *business logic* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] – the code that makes your software different from whatever else is available on the market. It is this part of the system which your customers pay for, and it usually is much larger than the other parts, which makes business logic the primary focus of development.

In [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] systems use cases are defined by the web of communication channels instead of the code inside the system’s components. That is represented by green arrows and the overall lack of green areas on the diagrams of system components.

### Abstract

*Motto* and the design goal.

<ins>Known as:</ins> the list of aliases for the general metapattern.

<ins>Structure:</ins> a short description of the structure of the metapattern.

<ins>Type:</ins> system topology, extension component, or implementation.

- A *system topology* ([[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], [[wiki/concepts/source/basic-metapatterns/services|*Services*]] and few others derived from them) makes the backbone of any system.
- An *extension component* is an addition to a *system topology* which modifies its properties.
- An *implementation* shows the internal structure of a component, usually hidden from its clients.


A short *table of benefits and drawbacks*.

<ins>References:</ins> select articles and books that describe the topic.

After that, there follow two or three paragraphs of facts and ideas about the metapattern.

### Performance

This section discusses the performance of the subject metapattern in scenarios of various scope: simple requests or events that relate to a single subsystem are usually processed much faster than those that touch multiple components.

There are two kinds of performance: latency and throughput. Low latency is possible only if few components are involved because inter-component communication, especially in distributed systems, increases latency. Contrariwise, throughput depends on the number of components that work in parallel, thus it scales together with the system.

This section may also discuss optimization techniques that apply to the metapattern.

### Dependencies

Some components of the metapattern depend on other components. If a component changes, everything that depends on it may need to be re-tested with the updated version. If a component’s interface changes, all the components that depend on it must be updated. Therefore, components that evolve quickly should depend on others, not the other way around.

Some patterns, such as [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], use [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] to [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|break dependencies]]. An *Adapter* depends on components on both sides of itself, making those components independent of each other. The *Adapters* are small enough to update quickly, and may easily be replaced with stubs for testing or running a component in isolation.

### Applicability

Here follows a list of types of projects which may benefit from applying the architecture under review, and another list of those which it is more likely to hurt.

### Relations

These are illustrated through an optional sequence of diagrams, showing the (*extension* or *implementation*) metapattern applied to various kinds of architectures, followed by a list of relations between the current and other metapatterns.

### Variants and examples

A metapattern usually unites many variations of several patterns. Here we may have a section per dimension of variability, and often another section with well-known patterns and architectures that match the metapattern.

When a pattern is listed under several metapatterns (as often seen with *extension components*), the headers of the multiple pattern descriptions cross-link to each other.

In other cases I had to include several variants that do not properly belong to the metapattern under review, just to avoid confusion with terminology and point the reader to the right chapter. For example, [[wiki/concepts/source/basic-metapatterns/monolith|*Modular Monolith*]] has a module per subdomain, thus it belongs to [[wiki/concepts/source/basic-metapatterns/services|*Services*]] rather than [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]]. Still, when the chapter on *Monolith* was not mentioning it, I was blamed for misunderstanding the *Monolithic Architecture*. Such patterns are marked as (misapplied) or (inexact).

I tried to show the difference between synonymous names for every variant or example whenever I could identify one.

### Evolutions

This section covers a brief summary of possible changes to the architecture under review. Each change leads to a new architecture which usually belongs to another metapattern.

[[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]] discusses many evolutions in greater detail:

- A diagram that shows the original and resulting structures.
- The list of patterns, present in the resulting architecture. More general forms of each pattern are given in parentheses, i.e. Pattern (Metapattern (Parent Metapattern)).
- The goal(s) of the transition.
- The prerequisites that enable the change.
- A short description of the change and the resulting system.
- Lists of pros and cons of the evolution.
- An optional list of metapatterns that the resulting system may evolve into and their benefits in the context of the current evolution.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/glossary.md ===== -->

---
title: "Glossary"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Glossary.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Glossary
source_license_note: "See namespace README; preserve attribution and source links."
---

# Glossary

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Glossary.md`.

*Abstractness* – the scope of information that a *concept* operates. Highly abstract *concepts* describe the *system’s* behavior in less words.

*Action* – an act of a *system* that changes its environment.

[[wiki/concepts/source/basic-metapatterns/layers|*API*]] (*application programming interface*) – a set of *methods* or *messages* that a *component* exposes to its *clients*.

[[wiki/concepts/source/basic-metapatterns/layers|*Application*]] – the most *abstract* layer that usually *integrates components* of a less *abstract* layer.

*Architectural pattern* – a way to structure a *system* or a part of a *system* to achieve desirable properties (address a set of *forces*).

*Architectural style* – see *architecture*.

*Architecture* – the structure (*components* and their *interactions*) of a system which follows a certain framework or guidelines.

*ASS diagram* – a *structural diagram* with *abstraction*, *subdomain* and *sharding* for coordinates.

*Asynchronous communication* – the mode of *communication* when the sender of the *request message* does not stop the execution of its *scenario* to wait for the confirmation message.

*Attack surface* – the amount of *components* and functionality that faces an external network (potentially exposed to hackers).

*Availability* – the percentage of time that the *system* is operational (satisfies its *users*).

*Bounded context* – a subset of *requirements* and code that shares a set of *concepts*. Usually consists of internals of a *component* and *APIs* of all the *components* it uses.

*Business logic* – the thing that *users* pay for. It is the heart of the business and is usually the largest part of the *project*. You cannot buy *business logic*, only *implement* it. *Business logic* comprises *use cases* and *business rules*.

*Business rules* – *domain concepts* and their relations. They make the low-level half of *business logic*.

*Choreography* – a kind of *workflow* in which *components* that belong to the same level of *abstractness* cooperate to implement a *use case*.

*Client* – an external *component* or *system* that makes use of a *component* or *system* in question.

*Cohesion* – the density of logical connections between entities inside a *component*.

*Colocated* – running in the same address space (process) on the same hardware.

*Communication* – transfer of data or signals in a *system*.

*Complexity* – the cognitive load caused by the quantity of entities (*concepts* or *modules*) and their relations that a programmer needs to operate.

*Component* – an encapsulated part of a *system*. It exposes an *API* to the system's *clients* and/or other *components* of the *system*.

*Concept* – a notion of an element of a *system's* behavior, usually present in *requirements*.

*Contract* – the informal rules for the behavior of a *component* expected by its *clients*.

*Control* – a kind of system that supervises physical entities or external programs.

*Coupling* – the density of logical connections between *components*.

*Cross-cutting concern* – a functionality that should be present in multiple *components*.

*Data store* – anything where data can be placed or retrieved. Includes *databases*, file systems, and cloud storage.

*Database* – a service for storing, retrieving, and analyzing data.

*Debugging* – trying to force the *system* to behave correctly from the user’s point of view.

*Deployment* – uploading a *component* to the hardware that will execute it.

*Design* – planning for the best way to write code.

*Design* – see *architecture*.

*Design space* – the multitude of possible ways to *design* a given project.

*Development* – building a *project* for its *users*. Usually involves intermixed *design*, *implementation*, *debugging* and *testing* phases.

*Distributed* – spread over multiple computers that *communicate* via a network.

*Domain* – the whole of knowledge (including *requirements*) that is needed to build a *system*.

[[wiki/concepts/source/basic-metapatterns/layers|*Domain*]] – the middle layer of a *system* that contains its *business rules*.

*Event* – a signal that carries some meaning for a *system* or *component*. *Events* may carry data.

*Fault tolerance* – the ability of a *system* to remain (at least partially) operational if one or more of its *components* fail (become inaccessible due to a hang, crash or a hardware failure).

*Forces* – restrictions on the design and development of a system based on the *qualities* it should meet (see *non-functional requirements*) and organizational limitations (such as time, budget and skills).

*Functional requirements* – the *requirements* that describe *inputs* and *outputs* of a *system*, but not its *performance* or stability.

*Global use case* – a *use case* that involves most of the *components* of a *system*. Such *scenarios* are strongly affected by the *system’s* structure.

*Implementation* – the process of writing code.

*Implementation* – internals of a *component*.

*Infrastructure* – the lowest layer of a *system* that provides general-purpose functionality (tools) to its upper layers.

*Input* – *events* or data that a *system* reacts to.

*Integration* – see *orchestration*.

*Integration complexity* – the *complexity* of understanding how individual *components interact* to make a *system*.

*Interactions* – the kinds and routes of *communication* between *components* of a *system*.

*Interface* – see *API*.

*Latency* – the delay between a *system’s* receiving *input* and producing a corresponding *output*.

*Layers* – *components* of a *system* partitioned by the level of *abstraction*.

*Messaging* – communication by sending short pieces of data.

*Method call* – invocation of an *interface* method (or procedure) of a *component* by another *component*.

*Metapattern* – a cluster of *patterns* that have similar *topologies* and address related issues.

*Module* – a *colocated* (in-process) *component*.

*Non-functional requirements* (*NFR*s) – expected properties of a *system* (such as its stability or response time) which are crucial for the *system* to be built, *deployed*, and used successfully. Closely related to *qualities* and *forces*.

*Notification* – an *event* that one *component* sends to another *component*(s) to inform them of some change.

*Operational complexity* – see *integration complexity*.

*Orchestration* – a kind of *workflow* where a single dedicated *component* (*Orchestrator*) makes use of (usually multiple) less *abstract components*. *Facade* \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] is a good example.

*Output* – *actions* or data that a *system* produces.

*Pattern* – a documented approach (blueprint) for solving a recurrent programming issue.

*Pattern Language* – a set of interrelated *patterns* intended to cover most aspects of *designing systems* in a target *domain*.

*Performance* – a measure of a *system*’s *throughput*, *latency* and *resource* consumption.

*Persistent data* – data which survives rebooting the software.

*Pipeline* – a set of *components* for stepwise *processing* of data.

*Processing* – transformation of *input* data into *output* data.

*Project* – the process of making a *system*.

*Pub/sub (publish/subscribe)* – a mode of *communication* when one *component* (*subscriber*) receives a subset of *notifications* from another *component* (*publisher*). It is the *subscriber* that chooses which *notifications* it is interested in.

*Qualities* – the properties which a *component* or (sub)*system* manifests to satisfy *forces*.

*Real-time* – a *force* that requires the *system* to respond to incoming *events* immediately.

*Request/confirmation* – a pair of *messages* between two *components* (Requestor and Executor). The *request* describes an *action* that the requestor wants the executor to run (R =\> E). The *confirmation* describes the results of the execution (R \<= E).

*Requirements* – a set of rules that describe the correct (expected) behavior of the *system*.

*Resources* – CPU, memory, network bandwidth and other stuff that costs money.

*Scaling* – ability to increase *throughput* of a system by providing it with more *resources*.

*Scenario* – see *use case*.

*Service* – a *distributed component*.

*Services* – *components* of a *system* partitioned by *subdomain*.

*Sharding* – deploying multiple instances of a *component*.

*Single point of failure* – a software or hardware *component* which if fails makes the entire *system* non-operational. High-*availability systems* should avoid *single points of failure*.

[[wiki/concepts/source/basic-metapatterns/layers|*SPI*]] (*service provider interface*) – a set of *methods* or *messages* that a *component* expects to be supported by the *components* it uses.

*State* – data that a *component* keeps between processing its *inputs*.

*Structural diagram* – a graphical representation of the structure of a (sub-)*system* that shows *components* and their *interactions*.

*Stub* – a very simple *implementation* of a *module* that allows other *components* that use it to run without starting the original *module*. *Stubs* are used to *implement modules* concurrently or *test* them in isolation.

*Subdomain* – a distinct *cohesive* part of *domain* knowledge.

*Synchronous communication* – the mode of communication when the *requesting component* waits for results of its *request* to another *component* before continuing to run its *task*.

*System* – a self-sufficient set of *communicating components* that were brought together or *implemented* to satisfy its *users* (by running *use cases*).

*Task* – a high-level sequence of execution steps. Similar to *use case* or *scenario*.

*Team* – a few programmers and testers that work on a *component*. Teams of more than 5 members lose productivity to communication overhead.

*Testing* – checking how satisfactorily the *system* behaves.

*Throughput* – the amount of data a *system* can *process* per unit of time.

*Topology* – A map of system components and their relations, similar to a *structural diagram*.

*Use case* – a behavior expected by *system*’s users. A *system* is *implemented* to run *use cases*. *Use cases* are the high-level half of *business logic*.

*User* – a human that uses a *system* and usually pays well if satisfied with its behavior.

*Vendor lock-in* – a pitfall when a *system* relies on an external provider so much that it is impossible to change the provider. It is similar to falling prey to a monopoly.

*Workflow* – a sequence of actions (*messages* or *method calls*) required to *implement* a *use case*.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/history-of-changes.md ===== -->

---
title: "History of changes"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/History of changes.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/History%20of%20changes
source_license_note: "See namespace README; preserve attribution and source links."
---

# History of changes

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/History of changes.md`.

0.1 (2020) – Description of my semisynchronous *Proactor* architecture for a VoIP gateway, published by dou.ua. It received very positive feedback and lots of comments from the community.

0.2 (2020) – [The same in a more official style](http://www.hillside.net/plop/2020/papers/poltorak.pdf) for the (Corona-)PLoP’20 conference.

0.3 (2021) – Comparison of choreography and orchestration for dou.ua. No impact.

0.4 (2022) – A series of 5 articles that looked into local and distributed architectures by applying the actor model. Positive feedback from dou.ua, but the series was interrupted by the war.

0.5 (2023) – [The same series in English](https://medium.com/itnext/introduction-to-software-architecture-with-actors-part-1-89de6000e0d3), published by ITNEXT and upvoted by r/softwarearchitecture.

0.6 (2023) – I attempted to rebuild the series for InfoQ but the first article was rejected as impractical (technology-agnostic).

0.7 (09-2024) – [Chapters from this book](https://medium.com/itnext/the-list-of-architectural-metapatterns-ed64d8ba125d), published by ITNEXT. Some of them were boosted by Medium.

0.8 (11-2024) – The complete book as a pdf. Clients were changed to mid-brown. Detailed evolutions were moved to the appendix. Rejected by Manning (the free license and color diagrams make the book unprofitable) and O’Reilly (it would get in the way of their bestsellers). Ignored by Addisson-Wesley.

0.9 (12-2024) – Integrated patterns from \[[wiki/concepts/source/appendices/books-referenced|[DDS]], [[wiki/concepts/source/appendices/books-referenced|LDDD]], [[wiki/concepts/source/appendices/books-referenced|SAHP]]\] and Internet sources, mostly affecting [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]. Added diagrams for [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence* with derived storage]] and detailed evolutions for [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]]. Downgraded [[wiki/concepts/source/analytics/comparison-of-architectural-patterns|analytical chapters]] to sections and added a couple of new ones. Extended the [[wiki/concepts/source/analytics/ambiguous-patterns|ambiguous patterns chapter]]. Improved the structure of the variants sections of metapatterns: now each synonym has a short description. Fixed alignment of text and figures. Liked by [r/softwarearchitecture](https://www.reddit.com/r/softwarearchitecture/comments/1hi377v/free_book_architectural_metapatterns_the_pattern/). Rejected by The Pragmatic Programmer (they want “hands-on, actionable content”). Ignored by No Starch Press and Packt.

1.0 (04-2025) – Integrated \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\]. Integration logic (use cases) is now in green. Added [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]]- and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVP*]]-related patterns and a section on [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|Programming and architectural paradigms]]. Replaced the chapter on [control and processing](https://medium.com/itnext/control-and-processing-software-9011fee8bc66) with a new one about [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|Four kinds of software]] and added another one called [[wiki/concepts/source/analytics/the-heart-of-software-architecture|The heart of software architecture]]. Made minor changes all over the book. Now I know how to [generate a table of contents for both EPUB and PDF versions](https://medium.com/@denyspoltorak/guide-on-converting-a-google-docs-text-into-an-ebook-5b1abc65f69d). Ignored by Wikibooks.

1.1 (07-2025) – Lars Noodén edited the book, fixing my poor English. Patterns are now in *Title Case Italics*. [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) was added. There are now short explanation sections (in gray) throughout the book. Rejected by [EuroPLoP](https://www.europlop.net/) and [AsianPLoP](https://plopcon.org/asianplop2026/) because I was unable to attend the conferences in person. Ignored by the [main PLoP](https://plopcon.org/).

1.2 (05-2026) – New chapters: [[wiki/concepts/source/introduction/system-topologies|System topologies]] and [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] (replaced the boring *Combined Component*). Added [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]], [[wiki/concepts/source/basic-metapatterns/layers|*ECB*]], [[wiki/concepts/source/extension-metapatterns/proxy|*User Interface*]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Pedestals*]], [[wiki/concepts/source/implementation-metapatterns/plugins|examples of *Plugins*]], and [[wiki/concepts/source/basic-metapatterns/layers|descriptions of layer roles]]. Changed the diagram for [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]. Made many minor alterations. The book passed another cycle of editing.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/appendices/index-of-patterns.md ===== -->

---
title: "Index of patterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Appendices/Index of patterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Appendices/Index%20of%20patterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Index of patterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Appendices/Index of patterns.md`.

[[wiki/concepts/source/extension-metapatterns/proxy|Abstraction Layer]] (as a Proxy)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Abstraction Layer]] (as a part of Hexagonal Architecture)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Action-Domain-Responder]] (ADR)

[[wiki/concepts/source/basic-metapatterns/services|Actors]] (architecture)

[[wiki/concepts/source/implementation-metapatterns/mesh|Actors]] (as Mesh)

[[wiki/concepts/source/basic-metapatterns/services|Actors]] (backend)

[[wiki/concepts/source/basic-metapatterns/shards|Actors]] (create on demand)

[[wiki/concepts/source/basic-metapatterns/services|Actors]] (embedded systems)

[[wiki/concepts/source/basic-metapatterns/services|Actors]] (scope)

[[wiki/concepts/source/extension-metapatterns/proxy|Adapter]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Add-in]] (component)

[[wiki/concepts/source/implementation-metapatterns/plugins|Addon]] (component)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Aggregate Data Product Quantum]] (Data Mesh)

[[wiki/concepts/source/extension-metapatterns/proxy|Ambassador]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Ambassador Plugin]]

[[wiki/concepts/source/extension-metapatterns/proxy|Anticorruption Layer]] (as a Proxy)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Anticorruption Layer]] (as a part of Hexagonal Architecture)

[[wiki/concepts/source/extension-metapatterns/orchestrator|API Composer]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|API Gateway]] (as an Orchestrator)

[[wiki/concepts/source/extension-metapatterns/proxy|API Gateway]] (as a Proxy)

[[wiki/concepts/source/extension-metapatterns/proxy|API Rate Limiter]]

[[wiki/concepts/source/extension-metapatterns/proxy|API Service]] (adapter)

[[wiki/concepts/source/extension-metapatterns/proxy|API Throttling]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Application Layer]] (Orchestrator)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Application Service]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Aspects]] (Plugins)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Atomically Consistent Saga]]

[Automotive SOA](<Service-Oriented Architecture (SOA)#misapplied-automotive-soa>) (as Service-Oriented Architecture)

[[wiki/concepts/source/implementation-metapatterns/microkernel|AUTOSAR Classic Platform]] (as Microkernel)

[[wiki/concepts/source/extension-metapatterns/proxy|Backend for Frontend]] (adapter)

[Backends for Frontends](<Backends for Frontends (BFF)>) (BFF)

[[wiki/concepts/source/basic-metapatterns/pipeline|Batch Processing]]

[[wiki/concepts/source/basic-metapatterns/monolith|Big Ball of Mud]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Blackboard]]

[[wiki/concepts/source/extension-metapatterns/sandwich|Blackboard System]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Bottom-Up Hierarchy]]

[[wiki/concepts/source/basic-metapatterns/layers|Boundary-Control-Entity]] (BCE)

[[wiki/concepts/source/extension-metapatterns/middleware|Broker]] (Middleware)

[[wiki/concepts/source/basic-metapatterns/pipeline|Broker Topology Event-Driven Architecture]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Bus of Buses]]

[[wiki/concepts/source/extension-metapatterns/proxy|Cache]] (read-through)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Cache-Aside]]

[[wiki/concepts/source/extension-metapatterns/proxy|Caching Layer]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Cell]] (WSO2 definition)

[[wiki/concepts/source/extension-metapatterns/proxy|Cell Gateway]] (WSO2 Cell-Based Architecture)

[[wiki/concepts/source/extension-metapatterns/proxy|Cell Router]] (Amazon Cell-Based Architecture)

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Cell-Based Architecture]] (WSO2 version)

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Cell-Based Microservice Architecture]] (WSO2 version)

[[wiki/concepts/source/basic-metapatterns/shards|Cells]] (Amazon definition)

[[wiki/concepts/source/basic-metapatterns/pipeline|Choreographed Event-Driven Architecture]]

[[wiki/concepts/source/fragmented-metapatterns/layered-services|Choreographed Two-Layered Services]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Clean Architecture]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Cluster]] (group of services)

[[wiki/concepts/source/extension-metapatterns/proxy|Command Line Interface]] (CLI)

[[wiki/concepts/source/fragmented-metapatterns/layered-services|Command Query Responsibility Segregation]] (CQRS)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Composed Message Processor]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Configuration File]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Configurator]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Container Orchestrator]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Content Delivery Network]] (CDN)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Control]] (Orchestrator)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Coordinator]] (Saga)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|CQRS View Database]]

[[wiki/concepts/source/basic-metapatterns/shards|Create on Demand]] (temporary instances)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Data Archiving]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Data Domain]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Data File]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Data Grid]] (Space-Based Architecture)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Data Lake]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Data Mesh]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Data Product Quantum]] (DPQ)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Data Warehouse]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Database Cache]]

[[wiki/concepts/source/extension-metapatterns/proxy|Database Abstraction Layer]] (DBAL or DAL)

[[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|Dependency Inversion]]

[[wiki/concepts/source/extension-metapatterns/middleware|Deployment Manager]]

[[wiki/concepts/source/basic-metapatterns/services|Device Drivers]]

[[wiki/concepts/source/extension-metapatterns/proxy|Direct Server Return]]

[[wiki/concepts/source/extension-metapatterns/proxy|Dispatcher]] (Proxy)

[[wiki/concepts/source/extension-metapatterns/proxy|Distributed Cache]]

[[wiki/concepts/source/extension-metapatterns/middleware|Distributed Middleware]]

[Distributed Monolith](<Service-Oriented Architecture (SOA)#distributed-monolith>)

[[wiki/concepts/source/basic-metapatterns/services|Distributed Runtime]] (client point of view)

[[wiki/concepts/source/implementation-metapatterns/microkernel|Distributed Runtime]] (internals)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Document-View]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Domain]] (Uber definition for WSO2-style Cell)

[[wiki/concepts/source/basic-metapatterns/layers|Domain-Driven Design]] (layers)

[Domain-Oriented Microservice Architecture](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) (DOMA)

[[wiki/concepts/source/basic-metapatterns/services|Domain Services]] (scope)

[[wiki/concepts/source/implementation-metapatterns/microkernel|Domain-Specific Language]] (DSL)

[[wiki/concepts/source/extension-metapatterns/proxy|Driver]]

[[wiki/concepts/source/extension-metapatterns/proxy|Edge Service]]

[[wiki/concepts/source/basic-metapatterns/layers|Embedded systems]] (layers)

[[wiki/concepts/source/extension-metapatterns/middleware|Enterprise Service Bus]] (as Middleware)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Enterprise Service Bus]] (as Orchestrator)

[Enterprise Service-Oriented Architecture](<Service-Oriented Architecture (SOA)#enterprise-soa>)

[[wiki/concepts/source/basic-metapatterns/layers|Entity-Boundary-Control]] (EBC)

[[wiki/concepts/source/basic-metapatterns/layers|Entity-Control-Boundary]] (ECB)

[[wiki/concepts/source/basic-metapatterns/pipeline|Event Collaboration]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Event-Driven Architecture]] (EDA)

[[wiki/concepts/source/extension-metapatterns/middleware|Event Mediator]] (as Middleware)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Event Mediator]] (as Orchestrator)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Event-Sourced View]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Eventually Consistent Saga]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Extension]] (component)

[[wiki/concepts/source/implementation-metapatterns/plugins|Extension Architecture]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|External Search Index]]

[[wiki/concepts/source/basic-metapatterns/services|FaaS]] (nanoservices)

[[wiki/concepts/source/basic-metapatterns/pipeline|FaaS]] (pipelined)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Facade]]

[[wiki/concepts/source/extension-metapatterns/proxy|Firewall]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Flavors]] (Plugins)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Front Controller]] (query service of a pipeline)

[[wiki/concepts/source/extension-metapatterns/proxy|Frontend]]

[[wiki/concepts/source/extension-metapatterns/proxy|Full Proxy]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Game Development Engine]]

[[wiki/concepts/source/extension-metapatterns/proxy|Gateway]] (adapter)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Gateway Aggregation]]

[[wiki/concepts/source/extension-metapatterns/proxy|Graphical User Interface]] (GUI)

[[wiki/concepts/source/implementation-metapatterns/mesh|Grid]]

[[wiki/concepts/source/extension-metapatterns/proxy|Half-Proxy]]

[[wiki/concepts/source/basic-metapatterns/monolith|Half-Sync/Half-Async]]

[[wiki/concepts/source/extension-metapatterns/proxy|Hardware Abstraction Layer]] (HAL)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]

[[wiki/concepts/source/basic-metapatterns/services|Hexagonal Service]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchical Model-View-Controller]] (HMVC)

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Historical Data]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Hooks]] (Plugins)

[[wiki/concepts/source/extension-metapatterns/proxy|Human-Machine Interface]] (HMI)

[[wiki/concepts/source/implementation-metapatterns/microkernel|Hypervisor]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|In-Depth Hierarchy]]

[[wiki/concepts/source/extension-metapatterns/proxy|Ingress Controller]]

[[wiki/concepts/source/basic-metapatterns/shards|Instances]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Integration Database]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Integration Service]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Integration Microservice]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Interpreter]]

[[wiki/concepts/source/basic-metapatterns/monolith|Lambda Monolith]]

[[wiki/concepts/source/basic-metapatterns/monolith|Lambdalith]]

[[wiki/concepts/source/basic-metapatterns/shards|Lambdas]]

[[wiki/concepts/source/basic-metapatterns/layers|Layered Architecture]]

[Layered Microservice Architecture](<Backends for Frontends (BFF)>) (Backends for Frontends)

[[wiki/concepts/source/basic-metapatterns/layers|Layered Monolith]]

[[wiki/concepts/source/basic-metapatterns/services|Layered Service]]

[[wiki/concepts/source/fragmented-metapatterns/layered-services|Layered Services]] (architecture)

[[wiki/concepts/source/basic-metapatterns/layers|Layers]]

[[wiki/concepts/source/implementation-metapatterns/mesh|Leaf-Spine Architecture]]

[[wiki/concepts/source/extension-metapatterns/proxy|Load Balancer]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Logic Extension]]

[[wiki/concepts/source/basic-metapatterns/services|Macroservices]]

[[wiki/concepts/source/extension-metapatterns/proxy|Man-Machine Interface]] (MMI)

[[wiki/concepts/source/extension-metapatterns/orchestrator|MapReduce]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Materialized View]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Mediator]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Memory Image]]

[[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]]

[[wiki/concepts/source/extension-metapatterns/middleware|Message Broker]]

[[wiki/concepts/source/extension-metapatterns/middleware|Message Bus]]

[[wiki/concepts/source/extension-metapatterns/proxy|Message Translator]] (adapter)

[[wiki/concepts/source/extension-metapatterns/proxy|Messaging Grid]] (Space-Based Architecture)

[[wiki/concepts/source/extension-metapatterns/proxy|Microgateway]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Microkernel]] (Plugins)

[[wiki/concepts/source/implementation-metapatterns/plugins|Microkernel Architecture]] (Plugins)

[[wiki/concepts/source/basic-metapatterns/services|Microservices]] (architecture)

[[wiki/concepts/source/basic-metapatterns/services|Microservices]] (scope)

[[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model 1]] (MVC1)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model 2]] (MVC2)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-Adapter]] (MVA)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-Controller]] (MVC)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-Presenter]] (MVP)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-ViewModel]] (MVVM)

[[wiki/concepts/source/basic-metapatterns/services|Modular Monolith]]

[[wiki/concepts/source/basic-metapatterns/services|Modules]]

[[wiki/concepts/source/basic-metapatterns/services|Modulith]]

[[wiki/concepts/source/basic-metapatterns/monolith|Monolambda]] (lambda Monolith)

[[wiki/concepts/source/basic-metapatterns/monolith|Monolith]]

[[wiki/concepts/source/basic-metapatterns/monolith|Monolithic Architecture]]

[[wiki/concepts/source/basic-metapatterns/services|Monolithic Service]]

[[wiki/concepts/source/basic-metapatterns/shards|Multitenancy]]

[[wiki/concepts/source/basic-metapatterns/layers|Multitier Architecture]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Multi-Worker]]

[[wiki/concepts/source/basic-metapatterns/services|Nanoservices]] (API layer)

[[wiki/concepts/source/basic-metapatterns/services|Nanoservices]] (as runtime)

[[wiki/concepts/source/extension-metapatterns/sandwich|Nanoservices]] (as a Sandwich)

[[wiki/concepts/source/basic-metapatterns/pipeline|Nanoservices]] (pipelined)

[[wiki/concepts/source/basic-metapatterns/services|Nanoservices]] (scope)

[Nanoservices](<Service-Oriented Architecture (SOA)#nanoservices>) (SOA)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Native Data Product Quantum]] (sDPQ)

[[wiki/concepts/source/basic-metapatterns/pipeline|Nearline System]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Network of Networks]]

[[wiki/concepts/source/basic-metapatterns/layers|N-Tier Architecture]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Offline System]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Onion Architecture]]

[[wiki/concepts/source/extension-metapatterns/proxy|Open Host Service]] (as a Proxy)

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Open Host Service]] (as a part of Hexagonal Architecture)

[[wiki/concepts/source/implementation-metapatterns/microkernel|Operating System]]

[[wiki/concepts/source/extension-metapatterns/proxy|Operating System Abstraction Layer]] (OSAL or OAL)

[[wiki/concepts/source/extension-metapatterns/proxy|Operator Interface]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrated Saga]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrated Services]]

[[wiki/concepts/source/fragmented-metapatterns/layered-services|Orchestrated Three-Layered Services]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Orchestrator of Orchestrators]]

[[wiki/concepts/source/basic-metapatterns/shards|Partition]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Pedestal]]

[[wiki/concepts/source/implementation-metapatterns/mesh|Peer-to-Peer Networks]]

[[wiki/concepts/source/extension-metapatterns/middleware|Persistent Event Log]] (as Middleware)

[[wiki/concepts/source/extension-metapatterns/shared-repository|Persistent Event Log]] (as Shared Repository)

[[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Pipes and Filters]]

[[wiki/concepts/source/extension-metapatterns/proxy|Platform Abstraction Layer]] (PAL)

[[wiki/concepts/source/implementation-metapatterns/microkernel|Pluggable Component Framework]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Plug-In Architecture]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Plugin]] (component)

[[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Ports and Adapters]]

[[wiki/concepts/source/basic-metapatterns/shards|Pool]] (stateless instances)

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Presentation-Abstraction-Control]] (PAC)

[[wiki/concepts/source/extension-metapatterns/proxy|Presentation Layer]]

[[wiki/concepts/source/basic-metapatterns/monolith|Proactor]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Process Manager]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Processing Grid]] (Space-Based Architecture)

[[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]

[[wiki/concepts/source/extension-metapatterns/proxy|Published Language]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Query Service]]

[[wiki/concepts/source/extension-metapatterns/proxy|Rate Limiter]]

[[wiki/concepts/source/basic-metapatterns/monolith|Reactor]] (multi-threaded)

[[wiki/concepts/source/basic-metapatterns/monolith|Reactor]] (single-threaded)

[[wiki/concepts/source/basic-metapatterns/monolith|(Re)Actor-with-Extractors]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Read-Only Replicas]]

[[wiki/concepts/source/extension-metapatterns/proxy|Read-Through Cache]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Reflection]] (Plugins)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Remote Facade]]

[[wiki/concepts/source/basic-metapatterns/shards|Replica]]

[[wiki/concepts/source/extension-metapatterns/proxy|Replicated Cache]]

[[wiki/concepts/source/basic-metapatterns/shards|Replicated Load-Balanced Services]] (instances)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Reporting Database]]

[[wiki/concepts/source/extension-metapatterns/proxy|Repository]]

[[wiki/concepts/source/basic-metapatterns/shards|Request Hedging]]

[[wiki/concepts/source/extension-metapatterns/proxy|Response Cache]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Resource-Method-Representation]] (RMR)

[[wiki/concepts/source/extension-metapatterns/proxy|Reverse Proxy]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Saga Engine]] (Microkernel)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Saga Execution Component]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Saga Orchestrator]]

[[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]]

[[wiki/concepts/source/basic-metapatterns/services|Scaled Service]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Scatter-Gather]]

[[wiki/concepts/source/extension-metapatterns/proxy|Scheduler]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Script]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Segmented Microservice Architecture]]

[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Separated Presentation]]

[[wiki/concepts/source/basic-metapatterns/services|Service-Based Architecture]] (architecture)

[[wiki/concepts/source/extension-metapatterns/shared-repository|Service-Based Architecture]] (shared database)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Service Layer]] (Orchestrator)

[[wiki/concepts/source/implementation-metapatterns/mesh|Service Mesh]] (as Mesh)

[[wiki/concepts/source/extension-metapatterns/middleware|Service Mesh]] (as Middleware)

[[wiki/concepts/source/basic-metapatterns/services|Service of Services]]

[Service-Oriented Architecture](<Service-Oriented Architecture (SOA)>) (SOA)

[[wiki/concepts/source/basic-metapatterns/services|Services]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Services of Services]]

[[wiki/concepts/source/basic-metapatterns/shards|Sharding]] (persistent slices of data)

[[wiki/concepts/source/extension-metapatterns/proxy|Sharding Proxy]]

[[wiki/concepts/source/basic-metapatterns/shards|Shards]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Database]]

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Shared Databases]] (Polyglot Persistence)

[[wiki/concepts/source/extension-metapatterns/middleware|Shared Event Store]] (as Middleware)

[[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Event Store]] (as Shared Repository)

[[wiki/concepts/source/extension-metapatterns/shared-repository|Shared File System]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Memory]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]

[[wiki/concepts/source/extension-metapatterns/proxy|Sidecar]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Software Framework]] (Microkernel)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Source-Aligned Data Product Quantum]] (Data Mesh)

[[wiki/concepts/source/implementation-metapatterns/mesh|Space-Based Architecture]] (as Mesh)

[[wiki/concepts/source/extension-metapatterns/sandwich|Space-Based Architecture]] (as Sandwich)

[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Specialized Databases]]

[[wiki/concepts/source/implementation-metapatterns/mesh|Spine-Leaf Architecture]]

[[wiki/concepts/source/extension-metapatterns/shared-repository|Stamp Coupling]]

[[wiki/concepts/source/implementation-metapatterns/plugins|Strategy]] (Plugins)

[[wiki/concepts/source/basic-metapatterns/pipeline|Stream Processing]]

[[wiki/concepts/source/basic-metapatterns/layers|Three-Tier Architecture]]

[[wiki/concepts/source/basic-metapatterns/layers|Tiers]]

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|Top-Down Hierarchy]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Transaction Script]]

[[wiki/concepts/source/extension-metapatterns/proxy|User Interface]]

[[wiki/concepts/source/implementation-metapatterns/microkernel|Virtualizer]]

[[wiki/concepts/source/basic-metapatterns/shards|Work Queue]]

[[wiki/concepts/source/basic-metapatterns/pipeline|Workflow System]]

[[wiki/concepts/source/extension-metapatterns/orchestrator|Workflow Owner]] (Orchestrator)

[[wiki/concepts/source/extension-metapatterns/orchestrator|Wrapper Facade]] (Orchestrator)

[[wiki/concepts/source/extension-metapatterns/proxy|Write-Behind Cache]]

[[wiki/concepts/source/extension-metapatterns/proxy|Write-Through Cache]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/basic-metapatterns.md ===== -->

---
title: "Basic metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Basic metapatterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Basic%20metapatterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Basic metapatterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Basic metapatterns.md`.

Basic [[wiki/concepts/source/introduction/metapatterns|metapatterns]] are both common stand-alone architectures and building blocks for more complex systems. They include the single-component *Monolithic Architecture* and the results of its division along each of the [[wiki/concepts/source/introduction/metapatterns|coordinate axes]], namely *abstractness*, *subdomain*, and *sharding*:

### [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]]


![A diagram of Monolith, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Monolith.png)


A [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] is a single-component system, the simplest possible architecture. It is easy to write but hard to evolve and maintain.

*<ins>Includes</ins>*: Reactor, Proactor, and Half-Sync/Half-Async.

### [[wiki/concepts/source/basic-metapatterns/shards|Shards]]


![A diagram of Shards, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Shards.png)


[[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] are multiple instances of a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]]. They are scalable but usually require an external component for coordination.

*<ins>Includes</ins>*: Shards and Amazon Cells, Replicas, Pool of Stateless Instances, and Create on Demand.

### [[wiki/concepts/source/basic-metapatterns/layers|Layers]]


![A diagram of Layered Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Layers.png)


[[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] contain one component per level of abstraction. The layers may vary in technologies and qualities and scale individually.

*<ins>Includes</ins>*: Layers and Tiers.

### [[wiki/concepts/source/basic-metapatterns/services|Services]]


![A diagram of Services, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Services.png)


[[wiki/concepts/source/basic-metapatterns/services|*Services*]] organize a system into subdomains, often resulting in parts of comparable size which can be assigned to dedicated teams. However, a system of *Services* is hard to synchronize or debug.

*<ins>Includes</ins>*: Service-Based Architecture, Modular Monolith (Modulith), Microservices, Device Drivers, and Actors.

### [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]]


![A diagram of Pipeline, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Pipeline.png)


A [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] is a kind of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] with unidirectional flow. Each service implements a single step of data processing. The system is flexible but may grow out of control.

*<ins>Includes</ins>*: Pipes and Filters, Choreographed Event-Driven Architecture, and Data Mesh.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/layers.md ===== -->

---
title: "Layers"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Layers.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Layers
source_license_note: "See namespace README; preserve attribution and source links."
---

# Layers

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Layers.md`.


![A diagram for Layered Architecture, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Layers.png)


*Yet another layer of indirection.* Separate business logic from implementation details.

<ins>Known as:</ins> Layers \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\], Layered Architecture \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]], [[wiki/concepts/source/appendices/books-referenced|LDDD]]\], Multitier Architecture, and N-tier Architecture \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\].

<ins>Structure:</ins> A component per level of abstractness.

<ins>Type:</ins> System topology, implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Rapid start for development | Quickly deteriorates as the project grows |
| Easy debugging | Hard to develop with more than a few teams |
| Good performance | Does not solve force conflicts between subdomains |
| Development teams may specialize | Does not support aggressive optimizations |
| Business logic is encapsulated |  |
| Allows for the resolution of conflicting forces, including the use of specialized technologies |  |
| Deployment to dedicated hardware |  |
| Layers with no business logic are reusable |  |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] and \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] discuss layered software in depth; \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] promotes the layered style; most of the architectures in Herberto Graça’s [Software Architecture Chronicles](https://herbertograca.com/2017/07/03/the-software-architecture-chronicles/) are layered. The Wiki has a reasonably [good article](https://en.wikipedia.org/wiki/Multitier_architecture).

*Layering* a system creates interfaces between its levels of abstractness (high-level [use cases](#application-use-cases-or-integration), lower-level [domain logic](#domain-business-rules-or-model), and infrastructure) while also retaining monolithic cohesiveness within each of the levels. That allows both for easy debugging inside each individual layer (no need to jump into another programming language or re-attach the debugger to a remote server) and enough flexibility to have a dedicated development team, tools, deployment, and scaling policies for each layer. Though layered code is slightly better than that of [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], thanks to the separation of concerns, one of the upper (business logic) layers may nonetheless grow too large for efficient development.

Splitting a system into layers tends to resolve conflicts of forces between its abstract and highly optimized parts: the top-level business logic changes rapidly and does not require much optimization (as its methods are called infrequently), thus it can be written in a high-level programming language. In contrast, infrastructure, which is called thousands of times per second, has stable workflows and interfaces but must be thoroughly optimized and extremely well tested.

Many patterns have one or more of their layers split into subdomains, resulting in a layer of *services*. That causes no penalties as long as the services are completely independent (when the original layer had zero coupling between its subdomains), which happens if each of the services deals with a separate subset of requests (as in [*Backends for Frontends*](<Backends for Frontends (BFF)>)) or is choreographed by an upper layer (as in [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]]) which boils down to the same “separate subset of subrequests” under the hood. However, if the services which form a layer need to intercommunicate, you immediately get a whole set of troubles with debugging, sharing data, and performance characteristic of the [[wiki/concepts/source/basic-metapatterns/services|*Services*]] architecture.


![Diagrams of Backends for Frontends and Services with Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Misc/Layers%20of%20Services.png)


> Thanks to its substantial benefits and minor drawbacks, and the many evolutions it supports, *Layers* became the default architecture for starting new projects.

### Performance

The performance of a layered system is shaped by two factors:

- Communication between layers is slower than within a layer. Components of a layer may access each other’s data directly, while accessing another layer involves data transformation (as interfaces tend to operate generic data structures), serialization, and often [IPC](https://en.wikipedia.org/wiki/Inter-process_communication) or networking.
- The frequency and granularity of events or actions increases as we move from the upper more abstract layers to lower-level components that interface an OS or hardware.


> An ideal component should be replaceable and reusable. As soon as a component exposes details of its implementation, such as workflows or data types, in its interface, it becomes incompatible with other possible implementations, and its interface may even see major changes as the related internals of the component evolve. Therefore, well-behaving components tend to have their interfaces written in most generic terms, which requires inputs to be transformed to their internal formats and thus penalizes performance.

There is a number of optimizations to reduce interlayer calls:


![Caching the latest known state of the system in its highest layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layers-caching.png)


*Caching*: an upper layer tends to *model* (cache last known state of) the layers below it. This way it can behave as if it knew the state of the whole system without querying the actual state from the hardware present at the bottom of the system’s stack of layers. Such an approach is universal for [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control software*]]. For example, a network monitoring suite shows you the last known state of all the components it observes without actually querying them – it is subscribed to various notifications and remembers what and when each device has previously reported.


![Aggregation of events from hardware by the lowest layer of a layered system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layers-aggregation.png)


*Aggregation*: a lower layer collects multiple events before notifying the layer above it to avoid being overly chatty. An example is an [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things) field gateway that collects data from all the sensors in the building and sends it in a single report to the server. Or consider a data transfer over a network where a low-level driver collects multiple data packets that come from the hardware and sends an acknowledgement for each of them while waiting for a datagram or file transfer to complete. It notifies its client software only once when all the data has been collected and its integrity confirmed.


![Sending a batch of commands all the way down to the lowest layer of a system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layers-batching.png)


*Batching*: an upper layer forms a queue of commands and sends it as a single job to the layer below it. This takes place in drivers for complex low-level hardware, like printers, or in database access as *stored procedures*. \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] describes variants of this approach as the *Combined Method*, *Enumeration Method*, and *Batch Method* patterns. Programming languages and frameworks may implement *foreach* and *MapReduce* which allow for a single command to operate on multiple pieces of data.


![Moving a part of the business logic from the highest layer to the lowest layer of the system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layers-injection.png)


*Strategy injection*: an upper layer installs an event handler (hook or [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugin*]]) into the lower layer. The goal is for the hook to do basic pre-processing, filtering, aggregation, and decision making to process the majority of events autonomously while escalating to the upper layer in exceptional or important cases. That may help in such time-critical domains as [high-frequency trading](https://en.wikipedia.org/wiki/High-frequency_trading).

Layers can be scaled independently, as [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|exemplified]] by common web applications that comprise a highly scalable and resource-consuming frontend, somewhat scalable backend, and unscalable data layer. Another example is an OS (lower layer) that runs multiple user applications (upper layer).

### Dependencies

Usually an upper layer depends on the *API* (*application programming interface*) of the layer directly below it. That makes sense as the lower the layer is, the more stable it tends to be: a user-facing software gets updated on a daily or weekly basis while hardware drivers may not change for years. As every update of a component may destabilize other components that depend on it, it is much more preferable for a quickly evolving component to depend on others instead of the other way round.

Some domains, including embedded systems and telecom, require their lower layers to be polymorphic as they deal with varied hardware or communication protocols. In that case an upper layer (e.g. OS kernel) defines a *service provider interface* (*SPI*) which is implemented by every variant of the lower layer (e.g. a device driver). That allows for a single implementation of the upper layer to be interoperable with any subclass of the lower layer. Such an approach enables [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]], [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]], and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]].

There may also be an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] layer between your system’s SPI and an external API. It is called *Anticorruption Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], [*Database Abstraction Layer*](https://en.wikipedia.org/wiki/Database_abstraction_layer) / *Database Access Layer* \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] / *Data Mapper* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\], *OS Abstraction Layer*, or *Platform Abstraction Layer / Hardware Abstraction Layer*, depending on what kind of component it adapts.


![Individual layers may depend on other layers' APIs, SPIs, or both. In the last case the layer between the SPI and API is an adapter.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Layers-1.png)


A layer can be *closed* (*strict*) or *open* (*relaxed*). A layer above a closed layer depends only on the closed layer right below it – it does not see through it. Conversely, a layer above an open layer may depend on both the open layer and the layer below it – the open layer is transparent. That helps keep a layer which encapsulates only one or two subdomains small: if such a layer were closed, it would have to copy much of the interface of the layer below it just to pass the incoming requests which it does not know how to handle through to the layer below. The size optimization of open layers has a cost: the team that works on the layer above an open layer needs to learn APIs of both layers below it, which may even differ in their terminologies.


![Dependencies for open and closed layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Layers-2.png)


If you ever need to *scale* (run multiple instances of) a layer, you may notice that a layer which sends requests naturally supports multiple instances, either through the use of communication channels or with the instance address being appended to each request so that its destination layer knows where to send the response. On the other hand, if there are multiple instances of a layer you call into, you need a kind of [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] to dispatch requests among the instances.


![A load balancer helps access multiple instances of a layer directly below it.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Layers-3.png)


### Applicability

*Layers* are <ins>good</ins> for:

- *Small and medium-sized projects.* Separating the business logic from the low-level code should be enough to work comfortably on codebases below 100 000 lines in size.
- *Specialized teams*. You can have a team per layer: some people, who are proficient in optimization, work on the highly loaded infrastructure, while others talk to the customers and write the business logic.
- *Deployment to a specific hardware.* Frontend instances run on client devices, a backend needs much RAM, the data layer demands a large HDD and security. There is no way to unite them into a single generic component.
- *Flexible scaling.* It is common to have hundreds or thousands of frontend instances being served by several backend processes that use a single database.
- *Real-time systems*. Hardware components and network events often need the software to respond within a set time limit. This is achievable by separating the time-critical code from normal priority calculations. See [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]], and [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] for improved solutions.


*Layers* are <ins>bad</ins> for:

- *Large projects.* You are still going to enter *monolithic hell* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] much sooner than your project will reach 1 000 000 lines of code.
- *Low-latency decision making*. If your business logic needs to be applied in real time, you cannot tolerate the extra latency caused by the interlayer communication.


### Relations


![Splitting a layer into services and splitting a service into layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Layers.png)


*Layers*:

- Can be applied to the internals of any component, for example, layering [[wiki/concepts/source/basic-metapatterns/services|*Services*]] results in [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]].
- Can be altered by [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] or extended with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], and/or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] which would become an extra layer.
- Can be implemented by [[wiki/concepts/source/basic-metapatterns/services|*Services*]] yielding layers of services present in [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]], [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>), [*Backends for Frontends*](<Backends for Frontends (BFF)>), and [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].
- May be closely related to [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]].
- A layer often serves as a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], and/or [[wiki/concepts/source/extension-metapatterns/shared-repository|*(Shared) Repository*]], see [below](#variants-of-layer-roles).


## Variants by isolation

There are [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|several grades]] of layer isolation between unstructured [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] and distributed [*Tiers*](#three-tier-architecture). All of them are widely used in practice: each step adds its specific benefits and drawbacks to those of the previous stages until at some point it makes more sense to reject the next deal because its cons are too inconvenient for you.

### Synchronous layers, Layered Monolith

First you separate the high-level logic from low-level implementation details. Then draw interfaces between them. The layers will still call each other directly, but at least the code has been sorted out into some kind of structure, and you can now have two or three dedicated teams, one per layer. The cost is quite low – it is that the newly created interfaces will stand in the way of aggressive performance optimization.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Structured code | Lost opportunities for interlayer optimization |
| Two or three teams |  |

### Asynchronous layers

The next step you may decide to take could be to isolate the layers’ execution threads and data. The layers will communicate only through in-process messages, which are slower than direct calls and harder to debug, but now each layer can run at its own pace – a must for [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|interactive systems]].

| *Benefits* | *Drawbacks* |
| --- | --- |
| Structured code | No opportunities for interlayer optimization |
| Two or three teams | Some troubles with debugging |
| The layers may differ in latency |  |

### A process per layer

Next, you may run each layer in a separate process. You have to devise an efficient means of communication between them, but now the layers may differ in technologies, security, frequency of deployment, and even stability – the crash of one layer does not directly impact any of the others. Moreover, you may scale each layer to make good use of the available CPU cores. However, you will pay through even harder debugging, lower performance, and you will have to take care of error recovery, because if one of the components crashes, the others are likely to remain in an inconsistent state.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Structured code | No opportunities for interlayer optimization |
| Two or three teams | Troublesome debugging |
| The layers may differ in latency | Some performance penalty |
| The layers may differ in technologies | Error recovery must be addressed |
| The layers are deployed independently |  |
| Software security isolation |  |
| Software fault isolation |  |
| Limited scalability |  |

### Distributed Tiers

Finally, you may separate the hardware which the processes run on – going all out for distribution. This allows you to fine-tune the resources available for each layer, run parts of the system close to its clients, and physically isolate the most secure components, with your scalability limited only by your budget. The price is paid in latency and debugging experience.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Structured code | No opportunities for interlayer optimization |
| Two or three teams | Even worse debugging |
| The layers may differ in latency | Definite performance penalty |
| The layers may differ in technologies | Error recovery must be addressed |
| The layers are deployed independently |  |
| Full security isolation |  |
| Full fault isolation |  |
| Full scalability |  |
| Layers vary in hardware setup |  |
| Deployment close to clients |  |

## Variants of layer roles

Though the structure of every software system is unique, there is a common set of roles or functions that need to be covered by its code. It is generally accepted that a piece of code should [*do one thing, and do it well*](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well), which often makes the code written to support the same kind of functionality stick together and end up in a dedicated layer of a system. That also helps your teams specialize and keeps their cognitive load low by limiting the amount of code they deal with, which [allows for high productivity](https://realmensch.org/2018/05/04/we-are-all-10x-developers/).

That clarity of design, which separates technically different pieces, is opposed by a host of more pragmatic [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|*forces*]] that compel you to keep your code together:

- Performance can be easily optimized inside a component, while any communication between components will likely be much slower.
- If many distinct workflows traverse a set of components, those components require large interfaces which take much effort to design, implement, and support. You may end up spending more time maintaining your perfect architecture than writing the business logic which earns money for the company.
- The more components you have, the harder it is to deploy them and keep them consistent, not to mention error recovery. Moreover, as the number of system components increases, the big picture becomes elusive, and soon there is nobody who knows how to change the system if need arises.


Balancing the [[wiki/concepts/source/analytics/cohesers-and-decouplers|cohesers and decouplers]] listed above usually results in coarse-grained system components each of which covers several concerns, with some real-world system compositions shown in the [Examples section](#examples) later in this chapter. However, first we need to see which kinds of roles a system layer may incorporate:


![A stack of layers: client or user, interface, application, domain, generic code, communication, data, and operating system and hardware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Layer%20Roles.png)


### Interface (API or UI)

If a system serves a human user or remote client software, there is a part of it, called an *interface*, that deals with communication and translation between the system’s internal data model and one convenient for its clients.

As an interface represents the system to its clients, it is a kind of [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] by definition \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]. If the client is another software system, the interface is called an *Application Programming Interface* (*API*) and is likely to be implemented by a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] which will receive a message through a well-known protocol, check its correctness and authenticity of the sender, and forward the message’s payload to a layer below it. In most cases it will also send response and notification messages by executing the converse tasks: translation from the system’s internal data format to something more convenient for its clients and sending the resulting message over a network protocol.

When a system interacts with a human, it exposes another kind of interface – [[wiki/concepts/source/extension-metapatterns/proxy|*Human-Machine Interface* (*HMI*) or *User Interface* (*UI*)]]. The basics of its action are similar to the case of software-to-software interaction described above save that humans prefer visual or textual information instead of a highly structured Internet protocol.

Another, less common kind of interface is called *Service Provider Interface* (*SPI*). It is declared by a system that relies on an external component and is implemented by that component’s authors to make it pluggable into the system. *SPI*s are in use by [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] architectures, with *device drivers* being the best known example of pluggable components.

There are also other kinds of *Proxies* which adapt a system to foreign interfaces:

- An [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer* or *Open Host Service*]] translates between two software subsystems to loosen dependencies between them.
- A [[wiki/concepts/source/extension-metapatterns/proxy|*Hardware Abstraction Layer* or *Operating System Abstraction Layer*]] stands between a system and an underlying hardware or OS, respectively, to make the system portable.


![A service wrapped with: a gateway with its API, a user interface, an Anticorruption Layer, a plugin and an Open Host Service with a Published Language.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Interface%20-%20Kinds.png)


A *Proxy* that implements an interface may reside in a dedicated layer (and there may be multiple *Proxies* stacked together, for example, a *Gateway* behind a [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]]) or be merged with a neighboring layer: for example, an [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateway*]] fills the roles of both interface and [*application*](#application-use-cases-or-integration).

An interface layer can contain multiple components (services, modules, or high-level classes) when the system below it supports several kinds of clients: a bank is likely to provide a web interface, a mobile application, and a SWIFT endpoint. See [*Backends for Frontends*](<Backends for Frontends (BFF)>) for a detailed description.


![Diagrams of an API Gateway and Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Interface%20-%20Derived.png)


### Application (use cases or integration)

The *application* determines *what* a system does. If it faces clients, the application runs client commands, called *use cases*, by executing chains of calls to its [*model*](#domain-business-rules-or-model) which knows *how* to do simple actions – the building blocks from which a use case is composed.

For example, to transfer money between accounts, the application asks the model to:

- Verify that the client is the owner of the account to be charged.
- Calculate the bank’s fee for the transfer.
- Subtract the amount to be transferred and the fee from the client’s account.
- Add the fee to the bank’s account.
- Tell the recipient’s bank to add the transferred amount to the target account.


It is also responsible for dealing with any error that may occur in the process. For example, if the target account does not exist or is blocked, the application will need to both refund the client’s account and return a meaningful error message in the client’s preferred language.

Another kind of software, called [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control systems*]], is written to supervise hardware or software entities. In that case there are no client requests or use cases – instead, the system reacts to signals from the components controlled. It is the application layer which is responsible for the system’s behavior: if a smoke sensor detects fire, the application tells an alarm to sound. This role is called *integration* – the system acts as a living organism, all its parts orderly moving in response to a stimulus perceived by its senses.

When an application resides in a dedicated layer, it is called an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]. Like the [*interface*](#interface-api-or-ui) layer, the application layer may also contain multiple components: the bank will likely have distinct applications for its clients and for its managers. The corresponding pattern is also called [*Backends for Frontends*](<Backends for Frontends (BFF)>) (there is little distinction between [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] and *Orchestrators* in that topology).

Some systems lack the application role – they are structured as [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]], so that whatever enters one end of the system passes through all its components and pops out, digested, at the other end. In that case it is the very structure of the system – the connections between its components – that drive its workflow.


![Backends for Frontends between a gateway and a monolithic service; a pipeline with use case logic hardwired into the graph of connections.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Application%20-%20Derived.png)


### Domain (business rules or model)

The *domain* layer (aka *model*) models the real-world system which your software operates or emulates. It contains rules that describe *how* to do anything that your clients may want or *how* the hardware which you control needs to operate.

Back to the banking example, the domain layer can:

- Find if an account is valid and who owns it.
- Calculate a fee.
- Add money to or subtract it from an account.
- Transfer money to another bank.


And it has some tricks up its sleeves to assure that nothing it does about money is ever lost, even if the network is disconnected or the hardware it runs on fails.

In most cases the domain layer is the largest one and it is the one which makes your software valuable for business because it actually *does* whatever your software is about. It is also [the only layer in which OOP classes may correspond to real-world entities](http://tedfelix.com/software/jacobson1992.html).

As the largest layer, the domain is often the first among them to be subdivided:

- The most common way is to partition it into *subdomains* – loosely coupled subsets of your system’s functionality – yielding [[wiki/concepts/source/basic-metapatterns/services|*Services*]] (when other layers are fragmented along the same lines or replicated among the subdomain components) or a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].
- Rare cases allow for [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*hierarchical* decomposition]] where most components blend [*application*](#application-use-cases-or-integration) and domain roles.
- Last but not least, we can use separate models for making changes (executing *commands*) and for analytics (running *queries*), giving rise to [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Command Query Responsibility Segregation* (*CQRS*)]]. This makes sense because a command usually involves many fields of a single record (database row) while a query runs over select rows of all the records – they vary in how they access and treat the data, which is why it is common to have a record wrapped into an OOP class in the command model, while the query model, if it is not omitted completely, provides for direct access to the database.


![Diagrams of Services, Sandwich, Hierarchy, and Command-Query Responsibility Segregation.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Domain%20-%20Derived.png)


### Generic code (libraries and utilities)

*Generic code* is something not directly related to your business but still used by your logic: a graph traversal algorithm, an e-mail server, or even a computer vision framework to identify duplicate user avatars.

In most cases generic code stays together with the [*domain*-level code](#domain-business-rules-or-model) which calls it. However, when the domain layer gets subdivided into services, there emerge [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|multiple options]]:

- If the generic code is not shared, it moves into the service that uses it. See [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- If it needs to be shared, it can be:
  - Extracted into a dedicated service, as in [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>).
  - Replicated as a [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecar*]] attached to every instance of each service that uses it.
  - Copied into the codebases of the services to allow each team to change it independently from other teams – see *Separate Ways* in \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].


![Diagrams of Services, Service-Oriented Architecture, and Microservices with sidecars, with components that carry generic code highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Generic%20Code%20-%20Derived.png)


### Communication (middleware)

If your system is made of multiple components, they need a way to communicate, which may be as simple as in-process method calls or as complex as a [distributed consensus protocol](https://en.wikipedia.org/wiki/Paxos_(computer_science)). The *communication infrastructure*, when used consistently throughout a system, makes a distinct virtual (conjoining separately deployed nodes) system layer, called [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] and often implemented with a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]].


![Multiple instances of a communication library represented as a virtual middleware layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Communication%20-%20Derived.png)


### Data (persistence)

Most systems but the simplest [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] are stateful – they remember something about their users or their environment:

- A backend would usually *persist* useful facts to a *database* which makes a dedicated *persistence layer*.
- A [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|real-time *control system*]] does not have the leisure to access anything remote, therefore its state is embedded in its [*domain* layer](#domain-business-rules-or-model)’s memory.
- Complex distributed frameworks that implement [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] or [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] both keep each service’s data inside the service’s memory for fast access and back all the changes to a persistent data store to support failure recovery.


![Diagrams of a three-tier system, hierarchical control system, and Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Data%20-%20Derived.png)


If the persistence layer becomes a system’s performance bottleneck, as it often does, one of [[wiki/concepts/source/extension-metapatterns/shared-repository|the cures]] is using several specialized data stores, leading to [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].


![A load-balanced service over a database evolves into a monolith with two specialized databases or into a load-balanced stateless service over database replicas with a single leader.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Data%20-%20Evolutions.png)


### Operating system and hardware

All software always runs on *hardware* and usually relies on an *operating system* (*OS*) for file and network access and memory management. Even though many modern backends don’t care about such low-level details and omit them on their diagrams, embedded or systems software communicates with its OS or hardware directly, making the corresponding components indispensable parts of its topology.

Integrating multiple pieces of hardware into an intelligently behaving system is usually what [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control software*]] is written for. Such systems [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|often follow]] the [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Pedestal*]], [[wiki/concepts/source/basic-metapatterns/services|*Actors*]], or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] architectures.


![Diagrams of control systems with the following architectures: monolithic, actors, Pedestal, hierarchical.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Control%20-%20variants.png)


## Examples

The notion of layering seems to be so natural to our minds that most known architectures are layered to an extent. Not surprisingly, there are several approaches to assigning functionality to and naming the layers:

- [*ECB*](#entity-control-boundary-ecb-entity-boundary-control-ebc-boundary-control-entity-bce) distinguishes a client-facing layer, use cases and domain logic.
- [*DDD*](#domain-driven-design-ddd-layers) adds the infrastructure layer.
- [*Tiers*](#three-tier-architecture) are distributed *Layers* that usually include frontend, backend, and database.
- [Layering of an embedded system](#embedded-systems) often matches its supply chain.


### Entity-Control-Boundary (ECB), Entity-Boundary-Control (EBC), Boundary-Control-Entity (BCE)


![The boundary, control and entity layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/ECB.png)


[*Entity-Control-Boundary*](https://en.wikipedia.org/wiki/Entity%E2%80%93control%E2%80%93boundary) (*ECB*) or other combinations of these words (*EBC* and *BCE*) designate a system composed of the following layers:

- *Boundary* – the layer which [interacts with the system’s *clients* or *users*](#interface-api-or-ui). See [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]].
- *Control* – the layer which [contains *use cases*](#application-use-cases-or-integration) – sequences of actions on the system’s internals that should be made to process a client’s request or respond to a user’s action. See [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]].
- *Entity* – the bulk of the system’s business logic and data.


A closer look at an *ECB* system may reveal a finer-grained structure that resembles [*Backends for Frontends*](<Backends for Frontends (BFF)>) or [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) as each layer is composed of modules or objects:


![The boundary, control and entity layers, each subdivided into several services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/ECB%20as%20SOA.png)


### Domain-Driven Design (DDD) Layers


![The four layers of Domain-Driven Design: presentation, application, domain, and infrastructure.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/DDD.png)


*Domain-Driven Design* (*DDD*), as given in \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], is a methodology for enterprise-scale backend development which extends the more generic [*Entity-Control-Boundary*](#entity-control-boundary-ecb-entity-boundary-control-ebc-boundary-control-entity-bce) with a new *Infrastructure* layer responsible for [*communication*](#communication-middleware) and [*persistence*](#data-persistence) roles which don’t exist in most desktop applications. Its layers are called:

- *Presentation* ([[wiki/concepts/source/extension-metapatterns/proxy|*User Interface*]]) – the user-facing component (frontend, UI). It should be highly responsive to the user's input. See [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Separated Presentation*]].
- *Application* ([*Integration*](#application-use-cases-or-integration), *Service*) – the high-level scenarios which build upon the API of the *domain* layer. It should be easy to change and to deploy. See [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]].
- *Domain* ([*Model*](#domain-business-rules-or-model), *Business Rules*) – the bulk of the mid- and low-level business logic. It should usually be well-tested and performant.
- *Infrastructure* (*Utility*, *Data Access*) – the utility components devoid of business logic. Their stability and performance is business-critical but updates to their code are rare.


For example, an online banking system comprises:

- the presentation layer which is its frontend;
- the application layer which implements sequences of steps for payment, card to card transfer, and viewing a client’s history of transactions;
- the domain layer with its classes for various kinds of cards and accounts;
- the infrastructure layer with a database and libraries for encryption and interbank communication.


However, in practice you are much more likely to encounter the derived [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*DDD-style Hexagonal Architecture*]] than the original *DDD Layers*.

### Three-Tier Architecture


![Four instances of the presentation layer accessing two instances of the logic layer accessing a single database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Three-Tier.png)


Here the focus lies with the distribution of the components over heterogeneous hardware (*Tiers*):

- *Presentation* ([[wiki/concepts/source/extension-metapatterns/proxy|*Frontend*]]) tier – a user-facing application which runs on a user’s hardware. It is very scalable and responsive, but insecure.
- *Logic* (*Backend*) tier – the business logic which is deployed on the service provider’s side. Its scalability is limited mostly by the funding committed, security is good, but latency is high.
- *Data* (*Database*) tier – a service provider’s database which runs on a dedicated server. It is not scalable yet is very secure.


In this case the division into layers resolves the conflict between scalability, latency, security, and cost as discussed in detail in the [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|chapter on distribution]].

> *Tiers* don’t map directly to *Layers*. For example, a protocol support library which is used for communication between services belongs to the lowest (infrastructure) layer but to the middle (backend) tier. The discrepancy is rooted in different natures ([views of the *4\+1 model*](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model)) of the patterns in question: *Layers* show the logical composition (codebase) of the system while *Tiers* deal with its physical structure (deployment).

### Embedded systems


![An embedded system with the following pairs of layers: user interface and human-machine interface, software development kit and hardware abstraction layer, firmware and hardware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Embedded.png)


Bare metal and micro-OS systems which run on low-end chips use a different terminology, which is not unified across domains. A generic example involves:

- *Presentation* – a UI engine used by the *HMI*. It may be a third-party library or come as a part of the *SDK*.
- [[wiki/concepts/source/extension-metapatterns/proxy|*Human-Machine Interface*]] (*HMI* aka *MMI*) – the UI and high-level business logic for user scenarios, written by a [value-added reseller](https://en.wikipedia.org/wiki/Value-added_reseller).
- *Software Development Kit* (*SDK*) – the mid-level business logic and device drivers, written by the [original equipment manufacturer](https://en.wikipedia.org/wiki/Original_equipment_manufacturer).
- [[wiki/concepts/source/extension-metapatterns/proxy|*Hardware Abstraction Layer*]] (*HAL*) – the low-level code that hides hardware registers to enable code reuse between hardware platforms.
- *Firmware of Hardware Components* – usually closed-source binary pre-programmed into chips by chipmakers.
- *Hardware* itself.


It is of note that in this approach the layers form strongly coupled pairs. Each pair is implemented by a separate party of the supply chain, which is an extra force that shapes the system into layers.

An example of such a system can be found in an old mobile phone or a digital camera.

## Evolutions

Layers are not without drawbacks which may force a layered system to evolve. A summary of such evolutions is given below while more details can be found in [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]].

### [[wiki/concepts/source/appendices/evolutions-of-layers-that-make-more-layers|Evolutions that make more layers]]

Not all the layered architectures are equally layered. A [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] or database has already stepped into the realm of *Layers* but is far from reaping all its benefits. Such a system may continue its course in a few ways that were previously [[wiki/concepts/source/basic-metapatterns/monolith|discussed for *Monolith*]]:

- Employing a *database* (if you don’t have one yet) lets you rely on a thoroughly optimized state-of-the-art subsystem for data processing and storage.
- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] are similarly reusable generic modules to be added at will.
- Implementing an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] on top of your system may improve programming experience and runtime performance for your clients.


![A diagram of calls in a layered system. A single request from a client is translated by an Orchestrator into multiple calls to lower layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Layers.png)


It is also common to:

- Have the business logic divided into two layers.


![A backend is subdivided into application and domain layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20in%20Two.png)


### [[wiki/concepts/source/appendices/evolutions-of-layers-that-help-large-projects|Evolutions that help large projects]]

The main drawback (and benefit as well) of *Layers* is that much or all of the business logic is kept together in one or two components. That allows for easy debugging and fast development in the initial stages of the project but slows down and complicates work as the project grows in size \[[wiki/concepts/source/appendices/books-referenced|[MP]]\]. The only way for a growing project to survive and continue evolving at a reasonable speed is to subdivide its business logic into several smaller, [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|thus less complex]], components that match subdomains (*bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]). There are several options for such a change, with their applicability depending on the domain:

- In a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] the middle layer with the main business logic is divided into [[wiki/concepts/source/basic-metapatterns/services|*Services*]], leaving the upper [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and lower [[wiki/concepts/source/extension-metapatterns/shared-repository|*database*]] layers intact for future evolutions.


![The domain layer is split into subdomain components, making a Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20Domain%20to%20Services.png)


- Sometimes the business logic can be represented as a set of directed graphs which is known as [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]].


![A backend is subdivided into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Split%20to%20Event-Driven%20Architecture.png)


- If you are lucky, your domain makes a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].


![The lower layers of a system are subdivided, resulting in a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Hierarchy.png)


### [[wiki/concepts/source/appendices/evolutions-of-layers-to-improve-performance|Evolutions that improve performance]]

There are several ways to improve the performance of a layered system. One we have [[wiki/concepts/source/basic-metapatterns/shards|already discussed for *Shards*]]:

- [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] co-locates the data store and business logic and scales both dynamically.


![The database is migrated to a Data Grid, resulting in a scalable Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Space-Based%20Architecture.png)


Others are new:

- Merging several layers improves latency by eliminating the communication overhead.


![The application and domain layers are merged.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20Merge.png)


- [[wiki/concepts/source/basic-metapatterns/shards|Scaling]] some of the layers may improve throughput.


![The application and domain layers are independently sharded.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers_%20Shard.png)


- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] is the name for using multiple specialized data stores.


![The database layer is subdivided into specialized databases, resulting in Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Polyglot%20Persistence.png)


### [[wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility|Evolutions to gain flexibility]]

The last group of evolutions to consider is about making the system more adaptable. We have already discussed the following [[wiki/concepts/source/basic-metapatterns/monolith|evolutions for *Monolith*]]:

- The behavior of the system may be modified with [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] allows for abstracting the business logic from the technologies used in the project.
- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]] allow for customization of the system’s logic on a per client basis.


![Diagrams of Layers with plugins, Layers with scripts, and Hexagonal Architecture with a layered core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers%20-%20Further%202.png)


There is also one new evolution which modifies the upper (*orchestration*) layer:

- The [[wiki/concepts/source/extension-metapatterns/orchestrator|orchestration layer]] may be split into [*Backends for Frontends*](<Backends for Frontends (BFF)>) to match the individual needs of several kinds of clients.


![The application layer is split into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Layers/Layers%20to%20Backends%20for%20Frontends.png)


## Summary

*Layered architecture* separates the high-level logic from the low-level details. It is superior for medium-sized projects as it supports rapid development by two or three teams, is flexible enough to resolve conflicting forces, and provides many options for further evolution, which will come in handy when the project grows in size and complexity.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/monolith.md ===== -->

---
title: "Monolith"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Monolith.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Monolith
source_license_note: "See namespace README; preserve attribution and source links."
---

# Monolith

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Monolith.md`.

Let’s take a look at the simplest possible [[wiki/concepts/source/introduction/metapatterns|metapattern]] – *Monolith* – and see what it can teach us.


![A diagram for Monolith, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Monolith.png)


*Keep it simple, stupid!* If you don’t need a modular design, why bother?

<ins>Known as:</ins> Monolith, Monolithic Architecture.

<ins>Structure:</ins> A monoblock with no strong internal modularity.

<ins>Type:</ins> System topology, the root of the hierarchy of metapatterns.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Rapid start of development | Quickly deteriorates with project growth |
| Easy debugging | Hard to develop with multiple teams |
| Best latency | Does not scale |
| Low resource consumption | Lacks support for conflicting forces |
| The system’s state is self-consistent | Any failure crashes the entire system |

<ins>References:</ins> [Big Ball of Mud](http://www.laputan.org/mud/) for a philosophical discussion, [my article](https://itnext.io/introduction-to-software-architecture-with-actors-part-2-on-handling-messages-940c62cb06dc) and \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] for subtypes of *Monolith*, Martin Fowler’s discussion on [starting development with *Monolith*](https://martinfowler.com/bliki/MonolithFirst.html), \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] for the [definition of *monolithic hell*](https://livebook.manning.com/book/microservices-patterns/chapter-1/25) and a post describing the [first-hand experience of it](https://news.ycombinator.com/item?id=18442941).

We distance ourselves from the [[wiki/concepts/source/analytics/ambiguous-patterns|systems architecture’s definition]] of *Monolith* as a single unit of deployment because our main focus lies with the internal structure of systems. Instead, we will use the old definition of a *monolithic* application as a cohesive lump of code which does not contain any discernible components \[[wiki/concepts/source/appendices/books-referenced|[GoF]], [[wiki/concepts/source/appendices/books-referenced|POSA1]]\].

A *Monolith* is non-modular (not divided by interfaces) along all the [[wiki/concepts/source/introduction/metapatterns|structural dimensions]]. Its thorough cohesiveness is both its blessing (single-step debugging, system-wide optimizations, and self-consistent data) and its curse (messy code, no scalability of development and deployment, zero flexibility).

### Performance

On one hand, monolithic applications provide perfect opportunities for performance optimizations as every piece of code is readily accessible from any other. On the other hand, if the application is stateful, access to the state may [limit the performance benefit](https://stackoverflow.com/questions/16571381/degrading-performance-when-increasing-number-of-cores) of using multiple CPU cores. Furthermore, large *Monoliths* may become too messy, too complicated, and too fragile for programmers to identify and implement any non-local optimizations that could drastically improve performance.

> There are many kinds of bottlenecks which limit an application’s performance. As soon as you change your code to use multiple CPU cores you may find that the program’s throughput [is constrained](https://en.wikipedia.org/wiki/Resource_contention) by the speed of your hard drive or network interface. And when you upgrade those two, you may well hit something more subtle, like OS interrupts or [CPU cache coherence](https://www.youtube.com/watch?v=wGSSUSeaLgA).

Overall, tiny *Monoliths* provide the best latency and throughput per CPU core. Larger performance-critical projects may need to partition the code into [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [[wiki/concepts/source/basic-metapatterns/services|*Services*]] so that any manually optimized part remains small enough to be manageable. Higher throughput is attainable through distributing the software over multiple computers: [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] employ several copies of the whole system while a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] may run each step of data processing on a separate server.

### Dependencies

Even though a *Monolith* is a single module, meaning that there are no dependencies among its parts (in fact, everything depends on everything), it still may depend on some external components or services which it uses. Those dependencies tend to cause [*vendor lock-in*](https://en.wikipedia.org/wiki/Vendor_lock-in) or make the software OS- or hardware-dependent. [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] (including [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVP*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]]) decouples a monolithic system from its dependencies by isolating the latter behind [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]].

### Applicability

*Monolith* is <ins>good</ins> for cases which are harmed by the introduction of modularity:

- *Tiny projects.* The project is relatively small (below 10 000 lines) and the requirements will never change (like when you need to implement an application for running a specific mathematical calculation or a library supporting a well-established communication protocol).
- *Ultra optimization.* You already have a working and thoroughly optimized system, but you still need that extra 5% performance improvement achievable through merging all the components together.
- *Low latency.* If you need ultra low latency for the entire application, any asynchronous communication between its modules is not a viable option. Example: [high-frequency trading](https://en.wikipedia.org/wiki/High-frequency_trading).
- *Prototyping.* You are writing a prototype in a domain which you are not familiar with, and gathering requirements in the process. Chances for a correct initial identification of weakly coupled subdomains (to become [[wiki/concepts/source/basic-metapatterns/services|modules or services]]) are [quite low](https://martinfowler.com/bliki/MonolithFirst.html) and it is worse to have wrong module boundaries than to use no modules at all. [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|At the later stages]] of the project, when you will know the domain much better and your users will have approved the initial implementation, you will be able to split the system into components in a much better way, if and when that will be needed. Nevertheless, you may already know enough to apply [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] which keep the business logic monolithic while isolating it from the periphery and third-party libraries.
- *Quick and dirty.* You are out of time and money and need to show your customers something right now. There is no time to think, no money to perfect the code, and no day after tomorrow.


*Monolith* <ins>should be avoided</ins> when we need modules:

- *Incompatible forces.* There are [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|conflicting *forces*]] for different subsets of functionality. They require splitting the system into (usually asynchronous) components each of which is specifically designed to satisfy its own subset of forces. Your main tool is the careful selection of technologies and architectures on a per component basis which may allow the project to satisfy all the non-functional requirements even if the task looks impossible during the initial analysis.
- *Long-running projects.* The project is going to evolve over time and you believe you can predict the general direction of the future changes. Modularity brings flexibility which you will need for sure.
- *Larger codebases.* The project grows above average size (100 000 lines of code). If you don’t split it into smaller components it will descend into a [monolithic hell](https://livebook.manning.com/book/microservices-patterns/chapter-1/25) with development and debugging slowing down year after year till it reaches [terminal stage](https://news.ycombinator.com/item?id=18442941). Slow development is a waste of money, both in salary and in time to market.
- *Multiple teams.* You have multiple teams to work on the project. Inter-team communication is hard and error-prone whereas merging several teams together is known to greatly reduce the programmers’ productivity (which peaks with teams of 5 or less members). Explicit interfaces between components will formalize interdependencies between the teams, lowering communication overhead.
- *Fault tolerance.* Your domain requires fault tolerance which is next to impossible for large monolithic applications.
- *Resource-limited.* Your project is too resource-hungry for commodity hardware. Even if you buy the best server for its needs right now, it is going to crave more tomorrow (or on the next Black Friday).
- *Distributed setup.* Your project needs to run on multiple hardware devices. One of common examples is a [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|web service]] containing frontend and backend.


### Relations


![Intermediary architectures between Monolith and distributed Shards, Layers, and Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Monolith.png)


*Monolith*:

- Can be extended with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], or turned into a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] or [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].
- Yields [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], [[wiki/concepts/source/basic-metapatterns/services|*Services*]], or [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] if divided along the [[wiki/concepts/source/introduction/metapatterns|*abstractness*, *subdomain*, or *sharding*]] dimensions, respectively. All the known architectures are combinations of those three metapatterns.
- Is the bird’s-eye view of any architecture.


## Variants by the internal structure

*Monoliths* are the atoms to create more complex architectures from, the opaque building blocks, each of which satisfies a consistent set of [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|forces]]. Any individual component of a more complex architecture either is monolithic or encapsulates another architectural pattern, decomposable into *Monoliths*, and any architecture looks monolithic to its clients.


![A Sandwich Architecture looks like a monolith when the details of its internal structure are omitted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/MonolithAsUnzoomed.png)


There is a misunderstanding because *software architecture* inspects the internals of *applications* at the level of *modules* or even classes while *systems architecture* deals with *distributed systems* and operates *deployment units* which tend to incorporate multiple modules or even applications. Each branch of the architecture [[wiki/concepts/source/analytics/ambiguous-patterns|calls]] its atomic unit a *Monolith*, leading to the term sticking both to a *module that cannot be subdivided*, as in \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] and \[[wiki/concepts/source/extension-metapatterns/shared-repository|[POSA1]]\], and to a *(sub)system which must be deployed as a whole*, as per present-day literature.

As we aspire to build a unified classification for both distributed and local systems, we must treat both kinds of components in the same way, whether they are [[wiki/concepts/source/basic-metapatterns/services|distributed services]], [[wiki/concepts/source/basic-metapatterns/services|co-located *Actors*]], or [[wiki/concepts/source/basic-metapatterns/services|in-process modules]]. Thus, for the scope of the current book, we will follow the definition of *Monolith* from \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]: “Tight coupling leads to *monolithic* systems, where you can't change or remove a class without understanding and changing many other classes”. Still, we need to account for a couple of misnomers from systems architecture.

### True Monolith, Big Ball of Mud


![A square that represents a non-modular monolith.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/True%20Monolith.png)


A true *Monolith* features [no clear internal structure](http://laputan.org/mud/). If it has any components, they are so tightly coupled that the entire thing behaves as a single cohesive module. This is the subject of the current chapter.

### (inexact) Lambda Monolith, Monolambda, [[wiki/concepts/source/basic-metapatterns/shards|Lambdalith]]


![Instances of a stateless component between a load balancer and a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Lambdalith.png)


A [*Monolambda*](https://jesseduffield.com/Notes-On-Lambda/) or [*Lambdalith*](https://theburningmonk.com/2025/03/the-pros-and-cons-of-lambdalith/) is a dynamic [[wiki/concepts/source/basic-metapatterns/shards|*Pool* of stateless instances]] of a system. Though each instance may contain [[wiki/concepts/source/basic-metapatterns/layers|*layers*]] or [[wiki/concepts/source/basic-metapatterns/services|*subdomain modules*]], the whole is often called a *Monolith* [[wiki/concepts/source/analytics/ambiguous-patterns|because it is deployed as a single unit]].

### (misapplied) [[wiki/concepts/source/basic-metapatterns/layers|Layered Monolith]]


![Application, domain, and infrastructure layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Layered%20Monolith.png)


When they say [[wiki/concepts/source/basic-metapatterns/layers|*Layered Monolith*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], that refers to a non-distributed application with a layered structure, which is a proper [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] architecture and will be discussed in the corresponding chapter. It is called a *Monolith* for the [[wiki/concepts/source/analytics/ambiguous-patterns|sole reason that it is not distributed]]. Nevertheless, *Layers* resemble *Monolith* in many aspects, including easy debugging and the risk of outgrowing the comfort zone of developers.

### (misapplied) [[wiki/concepts/source/basic-metapatterns/services|Modular Monolith]] (Modulith)


![A diagram of subdomain services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Modular%20Monolith.png)


A [[wiki/concepts/source/basic-metapatterns/services|*Modular Monolith*]] (*Modulith*) \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] is a single-process application subdivided into modules that correspond to subdomains. If the modules communicate via in-process messaging, the architecture is nearly identical to coarse-grained [[wiki/concepts/source/basic-metapatterns/services|*Actors*]], thus it is a *Monolith* only in name. *Modulith* [is a kind of](https://en.wikipedia.org/wiki/Duck_typing) [[wiki/concepts/source/basic-metapatterns/services|*Services*]] – it supports development by multiple teams and its asynchronous variant is hard to debug. The relation to *Monolith* is mostly limited to the inability to scale individual parts of the system.

### (misapplied) [Distributed Monolith](<Service-Oriented Architecture (SOA)#distributed-monolith>)


![A distributed monolith as three layers of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Distributed%20Monolith.png)


A [*Distributed Monolith*](<Service-Oriented Architecture (SOA)#distributed-monolith>) \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] is a highly distributed system (usually [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) or [[wiki/concepts/source/basic-metapatterns/services|*Services*]]) where all the components still need to be deployed together because of their interdependencies. It is said to have the drawbacks of both *Monolith* (low fault tolerance and coupled release cycles) and *Services* (poor debuggability, high latency, and operational complexity).

### (inexact) [[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]


![Hexagonal Architecture with adapters between its core and each component the core interacts with.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Hexagonal%20Monolith.png)


[[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] extend a (sub)system with external components. These architectures can be applied to a *Monolith* without drastically changing its properties – it still remains relatively easy to write and debug but hard to support when it has grown large. Therefore, we will not currently discuss these modifications, mainly because each of them has a dedicated chapter.

## Examples

Let’s take a look inside a *Monolith*.

Any software module reacts to incoming events or data and produces outgoing events or data. But there are a few basic ways to implement that cycle:


![Control flow diagrams for Reactor, Proactor, and Half-Sync/Half-Async.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Subtypes%20of%20Monolith.png)


- *Reactor* runs each request in a separate thread:
  - A [single-threaded version](#single-threaded-reactor-one-thread-one-task) is used to serialize access to a hardware device.
  - A [multi-threaded *Reactor*](#multi-threaded-reactor-a-thread-per-task) is the simplest backend implementation.
- [*Proactor*](#proactor-one-thread-many-tasks) relies on short event handlers to run multiple requests in a single thread.
- [*Half-Sync/Half-Async*](#inexact-half-synchalf-async-coroutines-or-fibers) implements coroutines by changing call stacks of a thread.
- [*(Re)Actor-with-Extractors*](#inexact-reactor-with-extractors-phased-processing) passes the whole system through alternating planning and execution phases to run lock-free.


### Single-threaded Reactor (one thread, one task)


![A single thread that blocks on calls to an operating system executes a request and then another request which has to wait in a queue.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Reactor%20-%20Single%20Thread.png)


In a [*Reactor*](https://www.dre.vanderbilt.edu/~schmidt/PDF/reactor-siemens.pdf) \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] a single thread waits for an incoming event, request, or data packet, processes it with blocking calls to the underlying OS, hardware, and external dependencies, and returns the result, rinse and repeat.

That makes sense when the module wraps a hardware component which cannot do several actions at once, for example, a communication bus or a HDD firmware capable of a single read or write at any given moment.

### Multi-threaded Reactor (a thread per task)


![Two threads, each runs a single request and blocks on accessing an operating system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Reactor%20-%20Multiple%20Threads.png)


A [*Reactor*](https://www.dre.vanderbilt.edu/~schmidt/PDF/reactor-siemens.pdf) \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] may employ multiple threads by having a [[wiki/concepts/source/basic-metapatterns/shards|*pool*]] of them waiting for a request or data to arrive. The incoming event activates one of the waiting threads, which thereby becomes dedicated to processing it, makes several blocking calls and, finally, sends back a response. When the request processing is complete, the thread returns to the pool of idle threads to wait for the next event to process.

This is the default [simple & stupid](https://en.wikipedia.org/wiki/KISS_principle) implementation of backend services. Its pitfalls include contention for shared resources, deadlocks, and high memory consumption by OS-level threads.

### Proactor (one thread, many tasks)


![A single thread handles messages that belong to several use cases in an interleaved manner.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Proactor.png)


In [*Proactor*](https://hillside.net/plop/plop97/Proceedings/pyarali.proactor.pdf) \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] a single thread processes all of the incoming events, both from the module’s clients and from the hardware or dependencies which it manages. When an event is received, the thread goes through a short piece of corresponding business logic (*event handler*) which usually does one or more non-blocking actions, such as sending messages to other components, writing to registers of the managed hardware, or initiating an async I/O. As soon as the event handler returns, the thread becomes ready to process further events. As the thread never blocks, it is resource-efficient (does not hold anything for a noticeable amount of time) and can serve many interleaved tasks.

This approach is good for real-time systems where thread synchronization is largely forbidden because of the associated delays and for reactive [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control]] applications which mostly adapt to the environment instead of running pre-programmed scenarios. The drawback is very poor structure of the code and nightmarish debuggability as any complex behavior is broken into a swarm of separate event handlers.

### (inexact) Half-Sync/Half-Async (coroutines or fibers)


![A system subdivided into two layers: the upper one with a coroutine per request and the lower one with a generic event handling thread.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Half-Sync%20Half-Async.png)


[*Half-Sync/Half-Async*](https://www.dre.vanderbilt.edu/~schmidt/PDF/PLoP-95.pdf) \[[wiki/concepts/source/appendices/books-referenced|[POSA2]]\] originally described the interaction between user space and kernel threads in operating systems which is not much different from what happens under the hood in coroutines or fibers. A single thread (or a thread pool with one thread per CPU core) handles all the incoming events and switches its call stack in the process.

Every incoming request is allocated a call stack which stores the processing state (local variables and methods called) of the request. When it needs to access an external component, the [runtime system](https://en.wikipedia.org/wiki/Runtime_system) saves the request’s stack, makes a non-blocking call, and the executing thread returns to its original stack to wait for any new event to handle while the request processing stack remains frozen until the action it has initiated completes asynchronously, raising an event. Then the runtime, upon receiving the event, switches the execution thread back to the stored request’s stack and continues processing the request until it completes and its stack is deleted.

This makes programming and debugging feel as easy as they are with [*Reactor*](#single-threaded-reactor-one-thread-one-task) (imperative style) while partially retaining the low resource consumption and high performance of [*Proactor*](#proactor-one-thread-many-tasks) (reactive paradigm). Coroutines and fibers are used in highly efficient [game engines](https://www.gdcvault.com/play/1022186/Parallelizing-the-Naughty-Dog-Engine) and [databases](https://docs.seastar.io/master/tutorial.html#coroutines). Though *Half-Sync/Half-Async* has two layers (is not truly monolithic), I believe it belongs next to *Reactor* and *Proactor* which make up its upper and lower halves, respectively.

### The state of the art

These patterns are not widely recognized and programmers tend to mix them together, for better or for worse. One is likely to encounter a heavily multithreaded [big ball of mud](https://www.laputan.org/mud/) where some threads serve user requests while others are dedicated to periodic service routines.

Moreover, people [[wiki/concepts/source/analytics/ambiguous-patterns|often call]] any event-driven service a *Reactor*, causing confusion among those who distinguish between the three patterns.

### (inexact) (Re)Actor-with-Extractors (phased processing)


![In the extraction phase components call each other and add actions to their queues. In the reaction phase they execute the actions from their queues but don't interact. The phases alternate.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Reactor%20with%20Extractors.png)


As a bonus, let’s review an [unconventional execution model](http://ithare.com/multi-coring-and-non-blocking-instead-of-multi-threading-with-a-script/3/) that fits game development and other kinds of simulations with many interacting objects.

We have a long-running system where each simulated object with a complex behavior depends on the objects around it. Common wisdom proposes two ways to implement it:

- [*Actors*](https://doc.akka.io/libraries/akka-core/current/typed/guide/actors-intro.html) (asynchronous messaging, reactive programming) – each [[wiki/concepts/source/basic-metapatterns/services|*actor*]] (simulated object) runs single-threaded and wakes up only to process incoming messages. While processing a message, an actor may change its state and/or send messages to other actors. The entire actor’s data is private and there are no synchronous calls between the actors. The good thing is that actors are very efficient in highly parallel tasks as there are no locks in their code. The bad thing is that actors have no way to synchronize their states: you can only request another actor to tell you about its state, and its response may become outdated even before you receive it. Also, any complex logic that involves multiple actors is fragmented into many event handlers.
- The opposite approach is to have the simulated objects access each other synchronously. This allows for complex logic that depends on states of several objects yet gets in trouble with changing the objects’ states from multiple threads: you need to protect them with those inefficient locks and you get those dreadful deadlocks as the outcome.


Here we see two bad options to choose from. However, it is the simulated nature of the system that saves the day: we can *stop the world to get off*. The objects’ querying each other and their changing their states neither needs to happen at the same time nor obey the same rules!

The simulation runs in steps. Each step consists of two phases:

- *Query phase* (*extraction*) is when the object states are immutable, thus the objects can communicate synchronously with no need for locks. In this phase each object collects information from its surroundings (other objects), plans its actions and posts them as commands to its own message queue. I suppose that objects may also post events to each other’s queues in this phase.
- *Command phase* (*reaction*) is when each object executes its planned (queued) actions that change its state, but it cannot access other objects.


Each phase lasts until every object in the system completes its tasks scheduled for that particular phase. The phase toggle is supervised by a [[wiki/concepts/source/extension-metapatterns/proxy|*Scheduler*]] which runs the objects on all the available CPU cores. The entire process resembles the [game of Mafia](https://en.wikipedia.org/wiki/Mafia_(party_game)) with public daily conversations and covert nightly actions.

*(Re)Actor-with-Extractors* is the perfect example of earning the benefits of two architectural styles without paying their penalties. It utilizes both the lockless parallelism of *Actors*-style [*shared-nothing*](https://en.wikipedia.org/wiki/Shared-nothing_architecture) and the simplicity of synchronous access in [*shared-memory*](https://en.wikipedia.org/wiki/Shared-memory_architecture) by alternating between those two modes through applying the [*CQRS principle*](https://en.wikipedia.org/wiki/Command_Query_Responsibility_Segregation) to the time dimension.

## Evolutions

Every architecture has drawbacks and tends to evolve in a variety of ways to address them as soon as they start causing trouble. Below is a brief summary of common evolutions of *Monolith* with more information available in [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]].

### [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-lead-to-shards|Evolutions to Shards]]

One of the main drawbacks of the *Monolithic Architecture* is its lack of scalability – a single running instance of your system may not be enough to serve all the clients no matter how many resources you add in. If that is the case, you should consider [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] – *multiple instances* of a *Monolith*. There are following options:

- Self-managed [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] – each instance owns a part of the system’s data and may communicate with all the other instances (forming a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]).


![Several instances of a monolith are run as intercommunicating shards, each of which holds a subset of the system's data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Mesh%20of%20Shards.png)


- *Shards* with a [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] – each instance owns a part of the system’s data and relies on an external component to choose a shard for a client.


![Multiple instances of a monolith, each a subset of the system's data, are run behind a sharding proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Isolated%20Shards%20with%20Load%20Balancer.png)


- A [[wiki/concepts/source/basic-metapatterns/shards|*Pool*]] of stateless instances with a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] and a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] – any instance can process any request, but the shared database or file system limits the throughput.


![A monolith is transformed into stateless instances which run behind a load balancer and access a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Stateless%20Shards%20with%20Shared%20DB.png)


- A [[wiki/concepts/source/basic-metapatterns/shards|*Stateful Instance*]] per client with an external persistent storage – each instance owns the data related to its client and runs in a virtual environment (i.e. web browser or an [[wiki/concepts/source/implementation-metapatterns/microkernel|*Actor Framework*]]).


![Each user is allocated a temporary instance of a subsystem which loads their data at the start of the session and persists any changes to the database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Instance%20per%20Client.png)


### [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers|Evolutions to Layers]]

Another drawback of *Monolith* is its… er… monolithism. The entire application exposes a single set of qualities and all its parts (if they ever emerge) are deployed together. However, life awards flexibility: parts of a system may benefit from being written in varying languages and styles and deployed with different frequency and amount of testing, sometimes to specific hardware or end users’ devices. They may need to [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|vary in security and scalability]] as well. Enter [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] – a subdivision by the *level of abstractness*:

- Most *Monoliths* can be divided into 3 or 4 layers of different abstractness.


![A monolith is split into application, domain and database layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Layers.png)


- It is common to see the database separated from the main application.


![The data of a monolithic system is moved to a database, leaving the business logic stateless.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Database.png)


- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] (e.g. [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Cache*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]]) are common additions to the system.


![A part of generic functionality of a monolith is moved to a proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Proxy.png)


- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] adds a layer of indirection to make the system’s external API more user-friendly.


![An orchestrator is added to a monolithic system, allowing for higher-level client requests.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20add%20Orchestrator.png)


### [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-make-services|Evolutions to Services]]

The final major drawback of *Monolith* is the cohesiveness of its code. The rapid start of development with *Monolith* begets a major obstacle as the project grows: every developer needs to know the entire codebase to be productive while changes made by individual developers overlap and may break each other. Such distress is usually solved by dividing the project into modules along *subdomain boundaries* (which usually match [*bounded contexts*](https://martinfowler.com/bliki/BoundedContext.html)). However, that requires much work, and good boundaries and APIs are hard to design, wherefore many organizations prefer a slower iterative transition.

- A *Monolith* can be split into [[wiki/concepts/source/basic-metapatterns/services|*Services*]] right away.


![A monolith is subdivided into services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Services.png)


- A feature may be added or a weakly coupled part of the Monolith separated into a new service.


![A service is split from a monolith.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20Split%20Service.png)


- Some domains allow for sequential data processing best described by [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]].


![A Monolith is transformed into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Pipeline.png)


### [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins|Evolutions with Plugins]]

The last group of evolutions does not really change the monolithic nature of the application. Instead, its goal is to improve the customizability of the *Monolith*:

- Vanilla [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] is the most direct approach which relies on replaceable bits of logic.


![Plugins customize the monolith's behavior.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Plugins.png)


- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] is a subtype of *Plugins* which is all about isolating the main code from any third-party components which it uses.


![The database, external libraries, and a protocol support component are separated from the business logic and isolated with adapters.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Hexagonal.png)


- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]] is a kind of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] – yet another subtype of *Plugins* – which gives users of the system full control over its behavior.


![The high-level logic is rewritten as scripts which are run by an interpreter.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Monolith/Monolith%20to%20Interpreter.png)


## Summary

A *Monolith* is an unstructured application. It is the best architecture for rapid prototyping by a small team and it usually grants the best performance to costs ratio. However, it does not scale, lacks any flexibility and becomes unmanageable as the amount of code grows.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/pipeline.md ===== -->

---
title: "Pipeline"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Pipeline.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Pipeline
source_license_note: "See namespace README; preserve attribution and source links."
---

# Pipeline

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Pipeline.md`.


![A diagram for Pipeline, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Pipeline.png)


*Never return.* Push your data through a chain of processors.

<ins>Known as:</ins> Pipeline \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\].

<ins>Structure:</ins> A component per step of data processing.

<ins>Type:</ins> System topology, implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| It is very easy to add or replace components | Becomes too complex when the number of scenarios grows |
| Multiple development teams and technologies | Poor latency |
| Good scalability | Significant communication overhead |
| The components can be reused | Error handling may be non-trivial |
| The components can be tested in isolation |  |

<ins>References:</ins> *Pipes and Filters* are defined in \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] and are the foundation for part 3 (Derived Data) of \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]. \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] has an overview of all kinds of *Pipelines* in general while \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] has a chapter on *Event-Driven Architecture*. \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] is dedicated to *Event-Driven Architecture*. The \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] chapter on *Data Mesh* was written by the pattern’s author. \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] is a whole book about distributed *Pipelines*.

*Pipeline* is a variation of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] with no user sessions \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\], a unidirectional data flow, and often a single message type per communication channel (which thus becomes a *data stream*). As processed data does not return to the module that requested processing, there is no common concept of request ownership or high-level ([[wiki/concepts/source/basic-metapatterns/layers|*integration*, *application*]]) business logic, which is instead defined by the graph of connections between the system’s components. On the one hand, as all the services involved are equal and know nothing about each other (their interfaces are often limited to a single entry point), it is very easy to reshape the overall algorithm. On the other hand, the system lacks the abstractness dimension, thus any new use case builds a separate pipeline, threatening to turn the architecture into a mess of thousands of intricately interrelated pieces when the number of scenarios grows. Moreover, error handling requires dedicated pipelines that roll back changes to the system’s state which had been committed by the earlier steps of a failed use case.

### Performance

Because any task for a pipeline is likely to involve all (or most of, if branched) its steps, there is no way to optimize away communication. Therefore, latency tends to be high. However, as pipeline components are often stateless, multiple instances of individual services or entire pipelines can run in parallel, making *Pipeline* a highly scalable architecture.

Another point to observe is that a local pipeline naturally spreads the load among the available CPU cores (by using one thread per component) without any explicit locks or thread synchronization.

### Dependencies

There are three ways to build communication in a pipeline, each with different dependencies:

- *Commands* make each service depend on the services it sends messages to. It is easy to add a new input to such a pipeline.
- With *publish/subscribe* each service depends on the services it subscribes to. That case favors downstream branching with multiple consumers.
- Services may share a *message schema*, in which case all of them depend on it, not on each other. That allows for reshuffling the services.


![Commands cause downstream dependencies. Notifications cause upstream dependencies. If a shared message schema is used, every component depends on the shared message.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Pipeline.png)


See the [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreography* chapter]] for a more detailed discussion.

### Applicability

*Pipeline* is <ins>good</ins> for:

- *Experimental algorithms.* This architecture allows for the data processing steps both to be tested in isolation and connected into complex systems without changing their code.
- *Easy scaling.* Pipelines tend to evenly saturate all the available CPU cores without any need for custom schedulers. Stateless services can run distributed, thus the *Pipeline*’s scalability is limited only by its data channels.
- *Tailoring projects*. Many pipeline components are abstract enough to be easily reused, greatly reducing the cost of serial development of customized projects once the company builds a collection of common reusable services.


*Pipeline* <ins>does not work</ins> for:

- *High number of use cases.* The number of components and their interactions is going to be roughly proportional to the number of supported use cases and will easily overwhelm any developer or architect if new scenarios continue to be added over time.
- *Complex use cases*. Any conditional logic written as two or three lines of code with [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] is likely to need a separate pipeline and dedicated services with [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]]. Errors and corner cases are remarkably difficult to handle \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\].
- *Low latency*. Every step of a data packet along its journey between services takes time, not in the least because of data serialization. Moreover, the next service in the chain may still be busy processing previous data packets or its activation involves the OS scheduler.


### Relations

*Pipeline*:

- Is a kind of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] with unidirectional communication which often processes a single kind of data records.
- Is [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|involved]] in [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]], [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence* with derived databases]], and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]].
- Can be extended with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].


## Variants by scheduling

A pipeline may be either always active or run once in a while:

### Stream processing, Nearline system

*Stream processing* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] is when the pipeline components (*jobs, processors, filters, services* – whatever you prefer to call them) are actively waiting for input and process each incoming item immediately. This results in *near-real-time* (*nearline*) latency \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] but the pipeline will then always use resources, even when there is nothing for it to process.

### Batch processing, Offline system

*Batch processing* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]], [[wiki/concepts/source/appendices/books-referenced|DDS]]\] happens when a batch of input items is first collected into storage, and then the pipeline is run (often on a schedule) to process it. Such a mode of action is called *offline* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] as the processing results are delayed. However, the company saves on resources because the pipeline is only active for brief periods of time.

## Examples

*Pipelines* can be local or distributed, linear or branched (usually trees, but cycles may happen in practice), they may utilize a feedback engine to keep the throughput of all their components uniform by slowing down faster steps or scaling out slower ones. In some systems *pipes* (channels) or *filters* (services) persist data. *Pipes* may store the processed data in files or databases to enable error recovery and [*event sourcing*](https://microservices.io/patterns/data/event-sourcing.html). Filters may need to read or write to a database, which is often [[wiki/concepts/source/extension-metapatterns/shared-repository|*shared*]], if the data processing relies on the system’s state. Moreover, transferring data through a pipe may be implemented as anything ranging from a method call on the next filter to a pub/sub framework to polling a database or file system.

Such a variety of options enables the use of pipelines in a wide range of domains. Notwithstanding, there are a few mainstream types of *Pipeline* architectures:

- [*Pipes and Filters*](#pipes-and-filters-workflow-system) for local processing of data streams.
- Distributed and usually branched [*Choreographed Event-Driven Architecture*](#choreographed-broker-topology-event-driven-architecture-eda-event-collaboration).
- [*Data Mesh*](#data-mesh) which builds a reporting pipeline for analytical data.
- Extremely elastic [*Pipelined Nanoservices*](#function-as-a-service-faas-nanoservices-pipelined).


### Pipes and Filters, Workflow System


![A pipeline chaining: source, three filters, and sink.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Pipes%20and%20Filters.png)


*Pipes and Filters* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|EIP]]\] usually name a linear local system which obtains data with its *source*, passes the data through a chain of *filters*, connected by *pipes*, and outputs it via a *sink*. The entire *pipeline* may run as a single process to avoid the overhead of data serialization. It may range from a Unix shell script which passes file contents through a series of utilities to a hardware pipeline for image processing in a video [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|camera]]. The filters tend to be single-purpose (handling only one type of payload) and nearly stateless. In some cases a filter may use dedicated hardware (e.g. for encryption or audio/video processing). The entire pipeline often operates a single data format ([[wiki/concepts/source/extension-metapatterns/shared-repository|*Stamp Coupling*]]).

Though most commonly a filter waits for data to appear in its input pipe, processes it, and pushes the result to its output pipe, which allows for multiple filters to run in parallel, some implementations may let the source push the data through the entire pipeline all the way through to the sink. In that case either each filter calls the next filter in the line directly or the sink pulls the data by making direct upstream calls itself \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\]. The last two approaches remove the need for pipes yet are limited to using a single CPU core.

*Workflow* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]], [[wiki/concepts/source/appendices/books-referenced|DDS]]\] is a more modern name for similar stepwise processing which often stores intermediate results in a file or database and may run distributed. However, the same word generally describes the sequence of high-level steps in a use case \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\], and is another name for [[wiki/concepts/source/basic-metapatterns/layers|*application* or *integration* logic]], therefore we will avoid  using “workflow” as a synonym for “pipeline”.

Examples: Unix shell pipes, processing of video streams, many types of hardware.

### Choreographed (Broker Topology) Event-Driven Architecture (EDA), Event Collaboration


![Event-Driven Architecture as a branched pipeline built from a group of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Event-Driven%20Architecture.png)


*Event-Driven Architecture* (*EDA*) means that the system is built of services which use events to communicate in a non-blocking way. The idea is similar to the [actor model](https://en.wikipedia.org/wiki/Actor_model) of telecom and embedded programming. Thus, *EDA* itself does not define anything about the structure of the system (except that it is not [[wiki/concepts/source/basic-metapatterns/monolith|*monolithic*]]).

In practice, there are [two kinds](https://theburningmonk.com/2020/08/choreography-vs-orchestration-in-the-land-of-serverless/) of *Event-Driven Architectures*:

- [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreographed*]] */ Broker Topology* / [*Event Collaboration*](https://martinfowler.com/eaaDev/EventCollaboration.html) \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] – the events are notifications (usually via publish/subscribe) and the services form tree-like structures, matching our definition of *Pipeline*.
- [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*Orchestrated*]] */ Mediator Topology* / [*Request-Response Collaboration*](https://martinfowler.com/eaaDev/RequestResponseCollaboration.html) – the events are request/confirmation pairs and usually there is a single entity that drives a use case by sending requests and receiving confirmations. Such a system corresponds to our [[wiki/concepts/source/basic-metapatterns/services|*Services*]] metapattern with the supervisor being an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], discussed in a dedicated chapter.


An ordinary *Choreographed Event-Driven Architecture* \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]], [[wiki/concepts/source/appendices/books-referenced|DDS]]\] is built as a set of subdomain services (similar to those of the parent [[wiki/concepts/source/basic-metapatterns/services|*Services*]] metapattern). Each of the services subscribes to notifications from other services which it uses as action / data inputs and produces notifications which other services may rely on. For example, an email service may subscribe to error notifications from other services in the system to let the users know about issues that occur while processing their orders. It will also subscribe to the user data service’s add / edit / delete notifications to keep its user contact database updated.

This example shows several differences from a typical *Pipes and Filters* implementation:

- The system supports multiple use cases (e.g. user registration and order processing).
- A service has several entry points (the email service involves an order error handler and user created handler).
- A notification which a service produces may have many subscribers or no subscribers (nobody needs to act on our sending an email to a user).


Those points translate to difference in structure: while *Pipes and Filters* is usually a linear chain of components, *EDA* entails multiple branched (and sometimes looped) event flow graphs over a single set of subdomain services.

Pipelined *Event-Driven Architecture* (often boosted with [event sourcing](https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing)) works well for highly loaded systems of moderate size, but larger projects are likely to grow prohibitively complex graphs of event flows and service dependencies. This architecture’s scalability is limited by the services’ databases and the pub/sub framework employed.

*Event-Driven Architecture* may involve a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] as a user-facing event source and sink and a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for an application-wise pub/sub engine. [[wiki/concepts/source/extension-metapatterns/orchestrator|*Front Controller*]] or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Stamp Coupling*]] are used if it is important to know the state of requests that are being processed by the pipeline.

Examples: high performance web services.

### Data Mesh


![Data Mesh builds an extra graph of services that stream and process analytical data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Data%20Mesh.png)


First and foremost, [*Data Mesh*](https://martinfowler.com/articles/data-mesh-principles.html) \[[wiki/concepts/source/appendices/books-referenced|[LDDD]], [[wiki/concepts/source/appendices/books-referenced|SAHP]]\] is not a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]], but rather a *Pipeline*. This architecture applies [*CQRS*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) on the system level: it separates the interfaces and channels through which the services change their state (matching *commands* of *CQRS* or [*OLTP*](https://en.wikipedia.org/wiki/Online_transaction_processing)) and the ones used to retrieve their data (similar to *queries* or [*OLAP*](https://en.wikipedia.org/wiki/Online_analytical_processing)). That results in two overlapping subsystems, *operational* and *analytical*, that share most of their nodes.

The *operational system* is an ordinary [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] or [*Event-Driven Architecture*](#choreographed-broker-topology-event-driven-architecture-eda-event-collaboration).

The *analytical system* contains *Data Product Quanta* (*DPQ*) – services that provide convenient access (streaming, replaying, and possibly querying) to parts of the system’s data. The *DPQs* are assembled into a graph akin to *Event-Driven Architecture*. There are three kinds of *DPQs* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\]:

- A *source-aligned (native) DPQ* (*sDPQ*) is coupled to an operational service and streams (or provides queries into) its data. It is likely to be implemented as a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Reporting Database*]].
- An *aggregate DPQ* (*aDPQ*) merges and transforms inputs from several sources (*sDPQs* or other *aDPQs*). It is similar to a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]].
- A *fit-for-purpose (custom-made) DPQ* (*fDPQ*) is an end-user (leaf application) of the *Data Mesh*’s data. It may collect a dataset for machine learning or let a business analyst do their research. *fDPQs* tend to be short-lived one-off components.


There is a pragmatic option to allow an operational service to resort to the analytical system’s *DPQs* to query other services’ data instead of messaging them directly or implementing a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS View*]] and subscribing it to events that flow in the operational system.

### Function as a Service (FaaS), [[wiki/concepts/source/extension-metapatterns/sandwich|Nanoservices]] (pipelined)


![Many Nanoservices access a shared database to implement CRUD functionality.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Nanoservices.png)


A [[wiki/concepts/source/basic-metapatterns/services|*nanoservice*]] is literally a [function as a service](https://en.wikipedia.org/wiki/Function_as_a_service) (*FaaS*) \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] – a stateless (thus perfectly scalable) component whose API comprises a single input method. *Nanoservices* run in proprietary cloud [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] over a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] and are [chained into pipelines](https://increment.com/software-architecture/the-rise-of-nanoservices/) dedicated to specific use cases. The code complexity stays low, but as the project grows, the integration will quickly turn into a nightmare of hundreds or thousands of interconnected nanoservices.

*Nanoservices* are good for rapid development of small elastic (dynamically scalable) applications. The supported load is limited by the *Shared Database*, and the project evolvability is limited by the complexity of scenarios. As any use case is going to involve many asynchronous steps, latency is not a strong side of *Nanoservices*.

## [[wiki/concepts/source/appendices/evolutions-of-a-pipeline|Evolutions]]

*Pipeline* [[wiki/concepts/source/basic-metapatterns/services|inherits its set of evolutions from *Services*]]. Filters can be added, split in two, merged, or replaced. Many systems employ a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] (a pub/sub or pipeline framework), a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] (which may be a database or a file system), or [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]].

There are a couple of [[wiki/concepts/source/appendices/evolutions-of-a-pipeline|pipeline-specific evolutions]], with more details provided in [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]]:

- The first service of the *Pipeline* can be promoted to a [[wiki/concepts/source/extension-metapatterns/orchestrator|*Front Controller*]] which tracks the status updates for every request it handles.


![The first service of a pipeline subscribes to notifications from other services and thus becomes a Front Controller.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Pipeline%20promote%20Front%20Controller.png)


- Adding an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] turns a *Pipeline* into normal [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. As the high-level business logic moves into the orchestration layer, the domain-level filters don’t need to interact directly, therefore the inter-filter communication channels disappear and the system becomes identical to *Orchestrated Services*.


![Adding an orchestrator transforms a pipeline into Orchestrated Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Pipeline%20use%20Orchestrator.png)


## Summary

A *Pipeline* represents a data processing algorithm as a sequence of steps. It not only subdivides the system’s code into smaller components but is also very flexible: its parts are easy to add, remove, or replace. Several use cases can be built over the same set of services. Scalability is good. Event replay helps with debugging. However, this architecture lacks support for complex scenarios and error handling which limits it to smaller domains with a few use cases.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/services.md ===== -->

---
title: "Services"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Services.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Services
source_license_note: "See namespace README; preserve attribution and source links."
---

# Services

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Services.md`.


![A diagram for Services, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Services.png)


*Divide and conquer.* Scale development through decoupling subdomains.

<ins>Known as:</ins> Services, Domain Services \[[wiki/concepts/source/appendices/books-referenced|[FSA]] and [[wiki/concepts/source/appendices/books-referenced|SAHP]], [[wiki/concepts/source/analytics/ambiguous-patterns|but not]] [[wiki/concepts/source/appendices/books-referenced|DDD]]\], Modules \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].

<ins>Structure:</ins> A component per subdomain.

<ins>Type:</ins> System topology.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Supports large codebases | Global use cases are hard to debug |
| Multiple development teams and technologies | Poor latency in global use cases |
| Forces may vary by subdomain | No good way to share state between services |
|  | The domain structure should never change |
|  | Operational complexity |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] has a chapter on *Service-Based Architecture*; \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] is dedicated to *Microservices*.

Splitting a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] by *subdomain* allows for mostly independent properties, development, and deployment of the resulting components (distributed *services* or colocated *modules*). However, for the system to benefit from the division, its subdomains must be loosely coupled and, ideally, of comparable size. In that case the partitioning can reduce complexity of the project’s code by cutting accidental dependencies between the subdomains. Moreover, if one of the resulting services grows unmanageably large, it can often be further partitioned by sub-subdomains to form a [*Cell*](#cell-wso2-definition-service-of-services-domain-uber-definition-cluster). This flexibility is paid for through the complexity and performance of use cases which involve multiple subdomains. Another issue to remember is that boundaries between services are [nearly impossible](https://martinfowler.com/bliki/MonolithFirst.html) to move at later project stages as the services grow to vary in technologies and implementation styles, thus separation into services assumes perfect practical knowledge of the domain and relatively stable requirements.

> [Research](https://www.qsm.com/team-size-can-be-key-successful-software-project) shows that when more than five programmers work on the same subject, their performance degrades. Therefore, if we want our employees to be efficient, they should be grouped into small teams and each team should be given ownership of a dedicated component.

### Performance

Interservice communication is relatively slow and resource-consuming, therefore it should be kept to a minimum.


![Performance of Services is the best when the request is limited to a single service and the worst when the state of several services needs to be synchronized.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Services.png)


The perfect case is when a single service has enough authority to answer a client’s request or process an event. That case should not be that rare as a service often covers a whole subdomain while subdomains are expected to be loosely coupled (by definition).

Worse is when an event starts a chain reaction throughout the system, likely looping back a response to the original service or changing the target state of another controlled subsystem.

In the slowest scenario a service needs to synchronize its state with multiple other services, usually via *locks* and *distributed transactions*.

Multiple [[wiki/concepts/source/basic-metapatterns/shards|instances]] of an individual service may be deployed to improve throughput of the system. However, that will likely need a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] or [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] to distribute interservice requests among the instances and a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] to store and synchronize any non-shardable (accessed by several instances) state.

### Dependencies

When we see a service to *request* help from other services and then receive the results (in a *confirmation* message), that service [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrates*]] the services it uses. Services often orchestrate each other because the subdomain a service is dedicated to is not independent of other subdomains.


![With request/confirm a service depends on whatever it uses.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Services-1.png)


Another way for services to communicate is [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]] – when a service sends a *command* or publishes a *notification* and does not expect any response. This is characteristic of [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] which are covered in the next chapter. Right now we should note that orchestration and choreography may be intermixed, in which case a service depends on all the services it uses or subscribes to.


![With pub/sub a service depends on its notification sources.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Services-2.png)


If the system relies on notifications (services publish *domain events*), it is possible to avoid interservice *queries* (pairs of a *read* request and confirmation with the data retrieved) by aggregating data from notifications in a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS* (or *materialized*) *View*]], which can reside [in memory](https://martinfowler.com/bliki/MemoryImage.html) or in a database. Views can be planted inside every service that needs data owned by other services or can be gathered into a dedicated [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]]. Though the main goal of *CQRS Views* is to resolve distributed joins from databases of multiple services, they also help [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|remove dependencies]] in the code of services and optimize out interservice queries, simplifying APIs and improving performance. Further examples will be discussed in the chapter on [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].


![A CQRS view breaks dependencies between services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Services-3.png)


In general, a large service should wrap its dependencies with an [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]], following the ideas of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]. The layer consists of [*Adapters*](https://refactoring.guru/design-patterns/adapter) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] between the internal domain model of the service and the APIs of the components it uses. The *Adapters* isolate the business logic from the external environment, granting that no change in the interface of an external service or library may ever take much work to support on the side of the team that writes its own business logic as all the ensuing updates are limited to a small adapter.


![Adapters isolate a service from its dependencies.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Services-4.png)


### Applicability

*Services* are <ins>good</ins> for:

- *Large projects.* With multiple services developed independently, a project may grow well above 1 000 000 lines of code and still be comfortable to work on as every team needs to know only the medium-sized component it owns.
- *Specialized teams.* Each service would often be written and supported by a dedicated team that invests its time in learning its subdomain. This way no one needs to have a detailed knowledge of the full set of requirements, which is next to impossible in large domains.
- *Varied forces*. In systems and embedded programming, components of wildly varying behaviors need to be managed. Each of them is controlled by a dedicated service (called *driver*) which adapts to the specifics of the managed subsystem.
- *Flexible scaling.* Some services may be under more load than others. It makes sense to deploy multiple instances of heavily loaded services.


*Services* <ins>should be avoided</ins> in:

- *Cohesive domains.* If everything strongly depends on everything, any attempt to cut the knot with interfaces is going to [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|make things worse]] unless the project is already dying because of its huge codebase, in which case you have little to lose.
- *Unfamiliar domains*. If you don’t understand the intricacies of the system you are going to build, you may [misalign the interfaces](https://martinfowler.com/bliki/MonolithFirst.html) and, by the time that the mistakes come to light, the architecture will be too hard to change \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\]. The coupled *Services* you get may actually be worse than a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]].
- *Quick start*. It takes effort to design good interfaces and contracts for *Services* and managing multiple deployment units is not free of trouble. Debugging will also be an issue.
- *Low latency*. If the system as a whole needs to react to events in real time, complex services should be avoided. Nevertheless, an individual service can provide low latency for local use cases (when a single service has enough authority to react to the incoming event), wherefore [simple non-blocking actors](#asynchronous-modules-modular-monolith-modulith-embedded-actors) are widely used in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control software]].


### Relations


![Splitting an Orchestrator into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Services.png)


- Division by subdomain can be applied to [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] to form [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] (partial subdivision) or [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) (layers of services); to [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], or [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] to make [*Backends for Frontends*](<Backends for Frontends (BFF)>); to a [[wiki/concepts/source/extension-metapatterns/shared-repository|(shared) database]] resulting in [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].
- Services can be extended with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].
- Each service can be implemented by [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] (making a [[wiki/concepts/source/fragmented-metapatterns/layered-services|*layered service*]]), [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], or a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]].


## Variants by isolation

Division by subdomain is so commonplace that no universal terminology has emerged over the years. Below is my summary, in no way complete, of several ways such systems can vary. Each section lists the well-known architectures it applies to.

First and foremost, there are multiple stages between a cohesive [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] and distributed *Services*. You should be careful to stop these incremental changes as soon as the benefits of the next step (color-coded below) don’t outweigh its drawbacks for your project.

> I review here only the most common options while a few more esoteric architectures are found in [Volodymyr Pavlyshyn’s overview](https://volodymyrpavlyshyn.medium.com/monoliths-microlith-moduliths-self-contained-systems-a-system-of-systems-nano-services-cf3e9e1869c0).

### Synchronous modules: Modular Monolith (Modulith)

The first step to take when designing a large project is the division of its codebase into loosely coupled modules that match subdomains (*bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]). If successful, that parallelizes development to a team per module while the entire application still runs in a single process, thus it stays easy to debug, the modules can share data, and any crash kills the whole system (meaning that you don’t need to take care of partial failures). You pay by establishing boundaries which will not be easy to move in the future.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Multi-team development | Subdomain boundaries are settled |

### Asynchronous modules: Modular Monolith (Modulith), Embedded [Actors](#actors)

The next stage is separating the modules’ execution threads and data. Each module becomes a kind of [*actor*](https://en.wikipedia.org/wiki/Actor_model) that communicates with other components through messaging. Now your modules don’t block each other’s execution and you can [replay events](http://ithare.com/chapter-vc-modular-architecture-client-side-on-debugging-distributed-systems-deterministic-logic-and-finite-state-machines/) at the cost of nightmarish debugging and no clean way to share data between or synchronize the state of the components.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Multi-team development | Subdomain boundaries are settled |
| Event replay | No good way to share data or synchronize state |
| Some independence of module qualities | Hard to debug |

### Multiple processes

There is also the option of running system components as separate binaries which lets them vary in technologies, allows for granular updates, and addresses stability (a web browser does not stop when one of its tabs crashes). But it adds a whole new dimension of painful error recovery that includes partially executed scenarios. Moreover, if the technologies of the components diverge, it is impossible to move code between them.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Multi-team development | Subdomain boundaries are frozen |
| Event replay | No good way to share data or synchronize state |
| Independence of component qualities and technologies | Hard to debug |
| Single-component updates | Needs error recovery routines |
| Software fault isolation | Data inconsistencies after partial crashes |
| Limited granular scalability |  |

### Distributed runtime: Backend [Actors](#actors)

Modern distributed [runtimes](https://en.wikipedia.org/wiki/Runtime_system) create virtual namespaces that can be deployed on a single machine or over a network. They may redistribute running components among servers in a way to minimize network communication and may offer distributed debugging. With [*Actors*](https://en.wikipedia.org/wiki/Actor_model), if one of them crashes, that generates a message to another actor which may decide on how to handle the error. The convenience of using a runtime has the dark side of vendor lock-in.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Multi-team development | Subdomain boundaries are frozen |
| Event replay | No good way to share data or synchronize state |
| Independence of component qualities ~and technologies~ | Hard to debug |
| Single-component updates | Needs error recovery routines |
| Full fault isolation | ~Data inconsistencies after partial crashes~ |
| Full dynamic granular scalability | Vendor lock-in |
|  | Moderate communication overhead |
|  | Moderate performance overhead caused by the framework |

### Distributed services: Service-Based Architecture, Space-Based Architecture, Microservices

Fully autonomous services run on dedicated servers or virtual machines. This way you employ resources of multiple servers, but the communication between them is both unstable (requests may be lost, reordered or duplicated) and slow and debugging tends to be very hard. [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based ([[wiki/concepts/source/implementation-metapatterns/mesh|*Microservices*]] and [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based*]]) architectures provide dynamic scaling under load.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Multi-team development | Subdomain boundaries are frozen |
| Event replay | No ~good~ way to share data or synchronize state |
| Independence of component qualities and technologies | Very hard to debug |
| Single-component updates | Needs error recovery routines |
| Full fault isolation | Data inconsistencies after partial crashes |
| Full (dynamic for *Mesh*) granular scalability | High communication overhead |

## Variants by communication

Services also differ in the way they communicate which influences some of their properties:

### Direct method calls

When components run inside the same process and share execution threads, one component can call another. That is blazingly fast and efficient, but you should take care to protect the module’s state from simultaneous access by multiple threads (and yes, [*deadlocks*](https://en.wikipedia.org/wiki/Deadlock_(computer_science)) do happen in practice). Moreover, it is hard to know what the module you call is going to call in its turn, while you are waiting on it – thus no matter how much you optimize your code, its performance depends on that of other components, often in subtle ways.

### RPCs and commands (request/confirm pairs)

If a service [calls another service](https://en.wikipedia.org/wiki/Remote_procedure_call) or requests it to act and return results (this is how method calls are implemented in distributed systems) it has to store the state of the scenario it is executing for the duration of the call (until the confirmation message is received). That uses resources: the stored state is kept in RAM and the interruption and resumption of the execution wastes CPU cycles on context switch and on the resulting cache misses. Blocked [[wiki/concepts/source/basic-metapatterns/monolith|threads]] are especially heavy while [[wiki/concepts/source/basic-metapatterns/monolith|coroutines or fibers]] are more lightweight but are still not free.

Another trouble with distributed systems comes from error recovery: if your component did not receive a timely response, you don’t know if your request was (or is being, or will be) executed by its target – and you need to be really careful about possible data corruption if you retry it and it is executed twice \[[wiki/concepts/source/appendices/books-referenced|[MP]]\].

> If a request is duplicated (as a slow network, overloaded service, or lost confirmation may cause a retry), it is important to make sure that the second (or parallel) execution of the request does not change the system’s data. This is achieved either by using [*idempotent*](https://en.wikipedia.org/wiki/Idempotence#Computer_science_examples) logic (which is based on assignment instead of increasing or decreasing values in place), or by writing the id of the last processed message to the database (and checking that the incoming message’s id is greater than the one found in the database) \[[wiki/concepts/source/appendices/books-referenced|[MP]]\].

On the bright side, [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] is human- and debugger-friendly as it keeps consecutive actions close together in the code. Therefore, synchronous interaction is still the default mode of communication in many projects.

### Notifications (pub/sub) and shared data

A service may do its part, then publish a notification or [[wiki/concepts/source/foundations-of-software-architecture/shared-data|write results to a shared data store]] for other services to process, and finally forget about the task as it has completed its role. [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreography*]] is resource-efficient, but you need to find and read multiple pieces of code which are spread out over several services to understand or debug the whole use case.

### (inexact) No communication

Finally, some kinds of services, namely [*device drivers*](#inexact-device-drivers-pedestal) and [*Nanoservices*](#inexact-nanoservices-api-layer), never communicate with each other. Strictly speaking, such services don’t make a system – instead, they are isolated *Monoliths* which are managed by a higher-level component (OS kernel for drivers, client or a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] for *Nanoservices*).

Nevertheless, it is a fun fact that if the services don’t intercommunicate, the main drawbacks of the *Services* architecture disappear:

- There is no slow and error-prone interservice communication (they never communicate!).
- It’s not hard to debug multi-service use cases (there are no such scenarios!).
- The services don’t corrupt data on crash (there are no distributed transactions).


## Variants by size

Last but not least, the simplest classification of subdomain-separated components is by their size:

### Whole subdomain: [[wiki/concepts/source/extension-metapatterns/sandwich|(Sub-)Domain Services, Macroservices]]

Each *Domain Service* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] (*Macroservice*) of [*Service-Based Architecture*](#service-based-architecture-sba-macroservices) implements a whole subdomain. It is the product of the full-time work of a dedicated team. A project is unlikely to have more than a dozen of such services (in part because the number of top-level subdomains in any domain is usually limited).

### Part of a subdomain: [Microservices](#microservices)

*Microservices* enthusiasts estimate the optimal size of a component of their architecture to be below a month of development by a single team. That allows for a complete rewrite instead of refactoring in case the requirements change. When a team completes one microservice it can start working on another, probably related, one while still maintaining its previous work. A system of *Microservices* is likely to contain from tens to few hundreds of them.  Some projects will cluster these into [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]].

### Class-like: [Actors](#actors)

An [*actor*](https://volodymyrpavlyshyn.medium.com/actors-actor-systems-as-massively-distributed-scalability-architecture-5e40f5ea9e86) is an object with a message-based interface. They are used correspondingly. Though the size of an actor may vary, as does the size of an OOP class, it is still very likely to be written by a single programmer.

### Single function: FaaS, Nanoservices

A [*nanoservice*](https://medium.com/@ido.vapner/unlocking-the-power-of-nano-services-a-new-era-in-microservices-architecture-22647ea36f22) is a single function ([FaaS](https://en.wikipedia.org/wiki/Function_as_a_service) \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\]) usually deployed to a *serverless* provider. Nanoservices are used as API method handlers or as building blocks for [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]].

## Variants by internal structure

A service is not necessarily monolithic inside. Because a service is encapsulated from its users by its interface, it can have any kind of internal structure. The most common cases, which can be intermixed together, are:


![A monolithic service, layered service, hexagonal services, scaled service, and a Cell interconnected into a single system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Subtypes%20of%20Services.png)


### [[wiki/concepts/source/basic-metapatterns/monolith|Monolithic]] service


![A diagram of a monolithic component.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service%20-%20Monolithic.png)


A *monolithic service* is a service with no definite internal structure, probably small enough to allow for complete rewrite instead of refactoring – the ideal of proponents of [*Microservices*](#microservices). It is [simple & stupid](https://en.wikipedia.org/wiki/KISS_principle) to implement but relies on external sources of persistent data. For example, *device drivers* and [*actors*](#actors) usually get their (persisted) configuration during initialization. A monolithic backend service may receive all the data it needs in incoming requests, via a query to another service, or by reading it from a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]].

### [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal]] service


![A core connected to: a protocol adapter, a Database Abstraction Layer with a database behind it, and an adapter with a library behind it.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service%20-%20Hexagonal.png)


A *hexagonal service* has its external dependencies isolated behind vendor-agnostic interfaces.

This is a real-world application of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] which both ensures that the business logic does not depend on specific technologies and protects from vendor lock-in. It is highly recommended for long-lived projects.

### [[wiki/concepts/source/basic-metapatterns/shards|Scaled]] service


![Stateless instances between a load balancer and a database; stateful shards behind a sharding proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service%20-%20Scaled.png)


With *scaled services* there are multiple [[wiki/concepts/source/basic-metapatterns/shards|*instances*]] of a service. In most cases they [[wiki/concepts/source/extension-metapatterns/shared-repository|*share a database*]] (though sometimes the database may be [[wiki/concepts/source/basic-metapatterns/shards|*sharded*]] or [[wiki/concepts/source/basic-metapatterns/shards|*replicated*]] together with the service that uses it) and get their requests through a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer* or *Sharding Proxy*]], making [[wiki/concepts/source/extension-metapatterns/sandwich|a kind of *Sandwich*]].

### [[wiki/concepts/source/basic-metapatterns/layers|Layered]] service


![The integration, core and database layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service%20-%20Layered.png)


A *layered service* is [[wiki/concepts/source/fragmented-metapatterns/layered-services|divided into *layers*]]. This approach is very common both with backend *(micro-)services*, where at least the database is separated from the business logic, and with *device drivers* in system programming, where hardware-specific low-level interrupt handlers and register access are separated from the main logic and high-level OS interface.

Layering provides all of the benefits of the [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] pattern, including support for [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|conflicting forces]], which may manifest, for example, as the ability to deploy the database to a dedicated server for a backend or as a very low latency in the hardware-facing layer of a device driver.

Another benefit comes from the existence of the upper integration layer which may [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrate interactions with other services]], isolating the lower layers from external dependencies.

### [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Cell]] (WSO2 definition) (service of services), Domain (Uber definition), Cluster


![Three subservices behind a Cell gateway. Two of them share a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service%20-%20Cell.png)


When a service is split into a set of subservices, it makes [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|a kind of *Hexagonal Architecture*]] called [*Cell*](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) (WSO2 name), [*Domain*](https://www.uber.com/blog/microservice-architecture/) (Uber name), or *Cluster* \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\]. All the incoming communication passes through a [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]] which encapsulates the *Cell* from its environment. Outgoing communication may involve the *Cell Gateway* or dedicated [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] (which constitute an *Anticorruption Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]) A *Cell* may deploy its own [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] and/or [[wiki/concepts/source/extension-metapatterns/shared-repository|*share a database*]] among its components.

[[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] ([according to WSO2](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md), as opposed to [Amazon's alias](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/what-is-a-cell-based-architecture.html) for [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]]) appears when there is a need to recursively split a service, either because it grew too large or because it makes sense to use several incompatible technologies for its parts. It may also be applied to group services if there are too many of them in the system.

[*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) (DOMA) is a more complex [*SOA*](<Service-Oriented Architecture (SOA)>)-style layered system of *Cells*.

## Examples

*Services* are ubiquitous among advanced architectures which either build around a layer of services that contains the bulk of the business logic (see [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]) or use small services as an extension of the main monolithic component ([[wiki/concepts/source/implementation-metapatterns/plugins|*PlugIns*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]). [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]], [*Backends for Frontends*](<Backends for Frontends (BFF)>) and [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) go all out partitioning the system into interconnected layers of services. [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] and [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] often require the services to implement or use a polymorphic interface to simplify the components that manage them.

Examples of *Services* include:

- [*Service-Based Architecture*](#service-based-architecture-sba-macroservices) with subdomain-sized services which may share a database.
- Highly scalable, and usually smaller, [*Microservices*](#microservices).
- [*Actors*](#actors) that are like classes with asynchronous interfaces.
- [*Nanoservices*](#inexact-nanoservices-api-layer) – stand-alone functions deployed to a cloud.
- [*Device Drivers*](#inexact-device-drivers-pedestal) that interface hardware components inside an operating system.


### [[wiki/concepts/source/extension-metapatterns/sandwich|Service-Based Architecture]] (SBA), [Macroservices](#whole-subdomain-sub-domain-services-macroservices)


![Three interconnected services, two of which share a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Service-Based%20Architecture.png)


Being the simplest use of *Services* where each subdomain gets a dedicated component, a *Service-Based Architecture* (*SBA*) \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] (aka *Macroservices*) tends to consist of a few coarse-grained services, some of which may [[wiki/concepts/source/extension-metapatterns/shared-repository|*share a database*]] and thus have little direct communication. An [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] is often present as well, making the *SBA* into a kind of [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].

### Microservices


![Multiple instances of several services connected to their sidecars which are connected to a shared mesh engine. Instances of each service access its single database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Microservices.png)


*Microservices* \[[wiki/concepts/source/appendices/books-referenced|[MP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] are usually smaller than components in *Service-Based Architecture* and feature multiple services per subdomain with strict decoupling: they never use a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] and are scaled and deployed independently (and often dynamically). Even [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] and distributed transactions ([[wiki/concepts/source/extension-metapatterns/orchestrator|*Sagas*]]) are considered to be a smell of bad design.

*Microservices* fit loosely coupled domains with parts which [vary drastically](https://medium.com/swlh/stop-this-microservices-madness-8e4e0695805b) in both forces and technologies. Any attempt to use them for an unfamiliar domain is [calling for trouble](https://martinfowler.com/bliki/MonolithFirst.html). Some authors insist that the “micro-” means that a microservice should not be larger in scope than a couple of weeks of work for a programming team. That allows rewriting one from scratch instead of refactoring. Others assert that too high a granularity makes everything [overcomplicated](https://dwmkerr.com/the-death-of-microservice-madness-in-2018/). Such a diversity of opinions may mean that the applicability and the very definition of *Microservices* varies from domain to domain.

This architecture usually relies on a [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]] for [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] where common functionality, like logging, is implemented in co-located [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]]. A layer of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] (called *Integration Microservices*) [may be present](https://github.com/wso2/reference-architecture/blob/master/api-driven-microservice-architecture.md), resulting in [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] or [*Backends for Frontends*](<Backends for Frontends (BFF)>).

*Dynamically scaled* [[wiki/concepts/source/basic-metapatterns/shards|*Pools*]] of service instances are common thanks to the elasticity of hosting in a cloud. Extreme elasticity requires [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]], which puts a [[wiki/concepts/source/extension-metapatterns/shared-repository|distributed in-memory data store]] node within each *Sidecar*.

> Some authors [distinguish](https://medium.com/@ali.gelenler/architectural-styles-vs-architectural-patterns-7fab51713470) between *architectural patterns* and *architecture styles* (*architectures*) \[[wiki/concepts/source/appendices/books-referenced|[FSA]], [[wiki/concepts/source/appendices/books-referenced|MP]]\]. The difference is similar to that between libraries and frameworks: you use a library or pattern (e.g. division of a component into [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [*Services*](#)) when you think that it will help your needs, but you build your entire system according to the rules of a framework or style (such as *Microservices* or [*Enterprise SOA*](<Service-Oriented Architecture (SOA)#enterprise-soa>)). This book does not accent that difference – instead, it boils down styles to combinations of patterns.

### [[wiki/concepts/source/implementation-metapatterns/mesh|Actors]]


![Actors running over an actor framework.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Actors.png)


An [*actor*](https://volodymyrpavlyshyn.medium.com/actors-actor-systems-as-massively-distributed-scalability-architecture-5e40f5ea9e86) is an entity with private data and a public message queue. They are like objects with the difference that actors communicate only by sending each other asynchronous messages. The fact that a single execution thread may serve thousands of actors makes actor systems an extremely lightweight approach to asynchronous programming. As an actor is usually single-threaded, there is no place for *mutexes* and *deadlocks* in the code and it is possible to [replay events](https://martinfowler.com/eaaDev/EventSourcing.html). Non-blocking [[wiki/concepts/source/basic-metapatterns/monolith|*Proactors*]] are often found in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|real-time systems]].

> A [*deadlock*](https://en.wikipedia.org/wiki/Deadlock_(computer_science)) happens when several threads in a system wait for each other to release unique resources they have each taken. As no thread involved in the *deadlock* can continue its operation, the system cannot complete its task. A single-threaded actor cannot *deadlock* because it does not contain multiple threads in the first place.

*Actors* have long been used in telephony (which is a domain where real-time communication meets complex logic and low resources) and with the invention of distributed runtime environments (e.g. Erlang/OTP or Akka) they expanded to messengers and banking which need to interconnect millions of users while providing personalized experience and history for everyone. Every user gets an actor that represents them in the system by communicating both with other actors (forming a kind of [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]) and with the user’s client application(s).

If we apply a bit of generalization, we can deduce that any server or backend service is an actor because its data cannot be accessed from outside and asynchronous IP packets are its only means of communication. Services of [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]] closely match this definition.

### (inexact) [[wiki/concepts/source/basic-metapatterns/pipeline|Nanoservices]] (API layer)


![Nanoservices dedicated to Get and Post methods between a client and a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Nanoservices%20-%20API%20Layer.png)


Though *Nanoservices* are defined by their size (a single function), not system topology, I want to mention a specific application from Diego Zanon’s book *Building Serverless Web Applications*. That example is interesting because it comprises a single layer of isolated functions (each providing one API method) which may share functionality by including code from a common repository. As nanoservices of this kind never interact directly ([[wiki/concepts/source/foundations-of-software-architecture/shared-data|they rely]] on a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] instead) the common drawbacks of *Services* (poor debugging and high latency) don’t apply to them.

### (inexact) [[wiki/concepts/source/extension-metapatterns/proxy|Device Drivers]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Pedestal]]


![Applications call a System Call Interface which dispatches their requests to device drivers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Drivers.png)


An operating system must run efficiently with an unpredictable combination of hardware components, any of which can come from different manufacturers. It is impossible to know all the combinations beforehand. Thus it builds a [*Pedestal*](https://alistair.cockburn.us/hexagonal-architecture) by employing one service (called [[wiki/concepts/source/extension-metapatterns/proxy|*driver*]]) per hardware device. A driver *adapts* a manufacturer- and model-specific hardware interface to the generic interface of the OS *kernel*, allowing for the kernel to operate the hardware it controls without the detailed knowledge of the model. Internally, a driver is usually [[wiki/concepts/source/basic-metapatterns/layers|*layered*]]:

- The lowest layer, called the [[wiki/concepts/source/extension-metapatterns/proxy|*Hardware Abstraction Layer*]] (*HAL*), provides a model-independent interface for a whole family of devices from a manufacturer.
- The next layer of a driver is likely to contain manufacturer-specific algorithms for efficient use of the hardware.
- The third layer, if present, is probably busy with high-level tasks which are common for all devices of the given type and may be implemented by the kernel programmers.


The whole system of kernel, drivers, and user applications comprises the [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] architecture which bridges resource consumers and resource providers. As the drivers don’t need to coordinate themselves (this is done by the kernel), they don’t really make a system of *Services* and thus don’t have the corresponding drawbacks.

## Evolutions

*Services* are subject to a wide array of evolutions, just like the other basic metapatterns. These are summarized below and detailed in [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]].

### [[wiki/concepts/source/appendices/evolutions-of-services-that-restructure-services|Evolutions that restructure services]]

*Services* work well when each service matches a subdomain and is developed by a single team. If those premises change, you’ll need to restructure the services:

- A new feature request may emerge outside of any of the existing subdomains, creating a new service, or a service may grow too large to be developed by a single team, calling for division.


![A service is split in half.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Split.png)


- Two services may become so strongly coupled that they fare better if merged together, or the entire system may need to be glued back into a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] if the domain knowledge changes or if interservice communication strongly degrades performance.


![Two services are merged.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Merge.png)


- Alternatively, coupled services may be clustered into co-deployed [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]] to reduce operational complexity.


![Services are grouped into Cells, reducing their interdependencies.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services_%20Cluster.png)


### [[wiki/concepts/source/appendices/evolutions-of-services-that-add-layers|Evolutions that add layers]]

The most common modifications of a system of *Services* involve supplementary system-wide layers which compensate for the inability of the services to [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|share]] anything among themselves:

- A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] tracks all the deployed service instances. It mediates the [[wiki/concepts/source/basic-metapatterns/layers|communication]] between them and may manage their scaling and failure recovery.


![The communication aspect of services can be covered by a dedicated middleware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20add%20Middleware.png)


- [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] of a [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]] make a virtual layer of [[wiki/concepts/source/basic-metapatterns/layers|shared libraries]] for the [*Microservices*](#microservices) it hosts.


![Scaled services reside on a shared layer of sidecars which is placed on top of a shared mesh engine. All instances of each service access the service's database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Multifunctional%20-%20Service%20Mesh.png)


- A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] simplifies the initial phases of development and interservice communication and enables the use of *Services* in [[wiki/concepts/source/foundations-of-software-architecture/shared-data|data-centric domains]].


![The data of individual services is merged into a shared repository.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20to%20Shared%20Database.png)


- [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] stand between the system and its clients and take care of shared aspects that otherwise would need to be implemented by every service.


![Generic aspects of services move to a shared proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20add%20Proxy.png)


- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] is the single place where the high-level logic of all [[wiki/concepts/source/basic-metapatterns/layers|use cases]] resides.


![The application logic is extracted from individual services into a shared orchestrator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20use%20Orchestrator.png)


- Transforming *Services* into a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] greatly simplifies their integration.


![The application and data parts of services are separated from the domain logic and merged into system-wide layers, resulting in a Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Services/Services%20to%20Sandwich.png)


### Evolutions of individual services

Each service starts as either a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or as [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and may undergo the corresponding evolutions:

- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] help to reuse third-party components (e.g. a database), organize the code, support conflicting forces, and the upper layer of the service may [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrate other services]].
- [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] subdivide the code into smaller components and allow for the deployment of  multiple teams.
- A service may use a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] or a load balancing [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to scale. Its [[wiki/concepts/source/basic-metapatterns/shards|*instances*]] usually rely on a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] for persistence.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] or [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]] may be used inside a service to improve the performance of its data layer.
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] or a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] help reconstruct the state of other services from *event sourcing*.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] isolates the business logic of the service from external dependencies.
- Occasionally, [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] or [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]] are used to customize the behavior of a service.


## Summary

*Services* deal with large projects by dividing them into subdomain-aligned components of smaller sizes which can be handled by dedicated teams. These may vary in technologies and qualities. However, services have a hard time cooperating in anything, from sharing data to debugging, and come with an innate performance penalty. There are several options halfway between [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] and distributed *Services* that have milder benefits and drawbacks.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/basic-metapatterns/shards.md ===== -->

---
title: "Shards"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Basic metapatterns/Shards.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Basic%20metapatterns/Shards
source_license_note: "See namespace README; preserve attribution and source links."
---

# Shards

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Basic metapatterns/Shards.md`.


![A diagram for Shards, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Shards.png)


*Attack of the clones.* Solve scalability in the most straightforward manner.

<ins>Known as:</ins> Shards, Instances, Replicas \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\].

<ins>Structure:</ins> A set of functionally identical subsystems with little or no intercommunication.

<ins>Type:</ins> Implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Good scalability | It’s hard to synchronize the whole system’s state |
| Good performance | There is operational effort to deploy or update multiple components |
| Improved latency and/or fault tolerance |  |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[POSA3]]\] is dedicated to pooling and resource management; \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] reviews *Shards*, *Replicas*, and *Stateless Instances*; \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] covers sharding and synchronization of *Replicas* in depth; Amazon promotes full-system sharding, calling it [*Cell-Based Architecture*](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/what-is-a-cell-based-architecture.html).

*Shards* are multiple and, in most cases, independent instances of a component or subsystem which the pattern is applied to. They provide scalability, often redundancy, and sometimes locality, at the cost of slicing or duplicating the component’s state (writable data), which obviously does not affect inherently stateless components. Most of this pattern’s specific evolutions look for a way to coordinate shards at the logic or data level.

> There is a sibling metapattern, namely [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]], in which instances of a component closely communicate among themselves. The difference between the patterns lies in the strength of interactions: while each *shard* exists primarily to serve its clients, a *Mesh node*’s priority is preserving the *Mesh* itself from falling prey to entropy, making the *Mesh* into a reliable distributed (virtual) layer. Some systems, such as distributed databases, hold the middle ground – their shards or nodes both intercommunicate intensely and execute a variety of client requests.

### Performance

A *shard* retains the performance of the original subsystem (a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] in the simplest case) as long as it runs independently. Any task that involves intershard communication has its performance degraded by data serialization and network latency. And as soon as multiple shards need to synchronize their states you find yourself on the horns of a dilemma: accept the possibility of  data inconsistency caused by  [write conflicts](https://en.wikipedia.org/wiki/Write%E2%80%93write_conflict) or else kill performance with distributed transactions \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\].


![Performance of Shards is the best when the request is limited to a single shard and the worst when the state of several shards needs to be synchronized.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Shards.png)


A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] (or its derivation, the [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]]) is a common solution to let multiple shards access the same dataset. However, it does not solve the performance vs consistency conflict (which is rooted in the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem)) but only encapsulates its complexity inside a ready-made third-party component, making your life easier.

### Dependencies

You may need to make sure that all the shards are instances of the same version of your software or at least that their interfaces and contracts are backward- and [forward-compatible](https://en.wikipedia.org/wiki/Forward_compatibility).

### Applicability

A *sharded* system features properties of the pattern it replicates (a single-component [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], local [[wiki/concepts/source/basic-metapatterns/layers|*layered*]] application or distributed [[wiki/concepts/source/basic-metapatterns/services|*Services*]]). Its peculiarities that originate with the *Shards’* scalability, are listed below.

*Shards* are <ins>good</ins> for:

- *High or variable load.* You need to scale your service up (and sometimes down). With *Shards* you are not limited to a single server’s CPU and memory.
- *Survival of hardware failures.* A bad HDD or failing RAM does not affect your business if there is another running instance of your application. Still, make sure that your [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] and Internet connection are replicated as well.
- *Improving worst case latency*. If your service suffers from latency spikes, you can run a few replicas of it in parallel, broadcasting every user request to all of them, and returning the fastest response. Adding a single replica turns your p90 into [p99](https://dzone.com/articles/mastering-latency-with-p90-p99-and-mean-response-t).
- *Improving locality.* A world-wide business optimizes latency and costs by deploying an instance of its software to a local data center in every region of interest. Web and mobile applications that run on client devices are prominent examples of sharding hidden in plain sight.
- [*Canary Release*](https://martinfowler.com/bliki/CanaryRelease.html). It is possible to deploy an instance of your application featuring new code along with the old, stable instances. That tests the update in production.


*Shards’* <ins>weak point</ins> is:

- *Shared data.* If multiple instances of your application need to modify the same dataset, that means that none of them properly owns the data, thus you have to rely on an external component (a *data layer*, implying [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] or another kind of [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]).


### Relations


![Scaling a single service or the entire system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Shards.png)


*Shards*:

- Applies to a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or any kind of subsystem.
- Can be extended with [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]].
- Is the foundation for [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]].


## Variants by isolation

There are intermediate steps between a single-threaded component and distributed *Shards* which gradually augment the pros and cons of having multiple instances of a subsystem:

### Multithreading

The first and very common advance towards scaling a component is running multiple execution threads. That attempts to utilize all the available CPU cores or memory bandwidth but [requires](http://ithare.com/multi-threading-at-business-logic-level-is-considered-harmful/) protecting the data from simultaneous access from several threads, which in turn may cause deadlocks.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Limited scalability | More complex data access |

### Multiple processes

The next stage is running several (usually single-threaded) instances of the component on the same system. If one of them crashes, others survive. However, sharing data among them and debugging multi-instance scenarios becomes non-trivial.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Limited scalability | Non-trivial shared data access |
| Software fault isolation | Troublesome multi-instance debugging |

### Distributed instances

Finally, instances of the subsystem may be distributed over a network to achieve nearly unlimited scalability and fault tolerance by [sacrificing](https://en.wikipedia.org/wiki/CAP_theorem) the consistency of the whole system’s state.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Full scalability | No shared data access |
| Full fault isolation | Hard multi-instance debugging |
|  | No good way to synchronize states of the instances |

## Examples

Sharding can often be transparently applied to individual components of [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|data processing]] systems. That does not hold for [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control systems]] which make centralized decisions based on the modeled system’s state, which must be accessible as a whole, thus the main business logic that owns the model (last known state of the system) cannot be sharded.

Many kinds of *Shards* require an external coordinating component ([[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]]) to assign tasks to the individual instances. In some cases the coordinator may be implicit, e.g. an OS socket or scheduler. In others it may be replicated and co-located with each client (as an [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]]).

Shards usually don’t communicate with each other directly. The common exception is [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] which includes distributed databases and [[wiki/concepts/source/implementation-metapatterns/mesh|*actor*]] systems that explicitly rely on communication between the instances.

There are several subtypes of sharding that differ in the way they handle state:

- [*Shards* or *Partitions*](#persistent-slice-sharding-shards-partitions-multitenancy-cells-amazon-definition) are long-lived service instances which own unique subsets of the system’s data.
- [*Replicas*](#persistent-copy-replica) are also long-lived but all of them hold copies of the same dataset.
- [*Stateless Instances*](#stateless-pool-instances-replicated-load-balanced-services-work-queue-lambdas) reset their state after handling a request.
- [*Actors*](#temporary-state-create-on-demand-actors) are stateful but exist only for the duration of a client’s session.


### Persistent slice: Sharding, Shards, Partitions, Multitenancy, Cells (Amazon definition)


![A sharding proxy connects a new client to a shard that contains data for the first letter of the client's name.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Shards%20-%20Sharding.png)


*Shards* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] own non-overlapping slices of the system’s state. For example, a sharded phonebook (or DNS) would use one shard for all contacts with initial “A”, another shard for contacts with initial “B”, and so on (in reality they use hashes \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]). A large wiki or forum may run several servers, each storing a subset of the articles. This is proper [*sharding*](https://learn.microsoft.com/en-us/azure/architecture/patterns/sharding), which is also called *partitioning* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] in the world of databases.

> Names are not evenly distributed across the letters of the alphabet. Many names start with A but few start with Q. If we use the first letter of a user’s name to assign them to a shard, the shard that serves users whose names start with A will be much more loaded than the one responsible for the letter Q. Therefore, real-world systems rely on *hashing* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] – calculation of a *checksum* of the user’s name which yields a seemingly random number. Then we divide the checksum by the total number of shards we have and use the remainder as the id of the shard that has the user’s data. For example, CRC16(“Bender”) = 52722. If we have 10 shards, Bender goes to (52722 % 10 = 2) the 3rd one.

Another use of *Shards* is when a service provider allocates a whole shard to each of its clients to grant them data isolation, stable performance, and security. This approach is contrasted against a cheaper option of [*Multitenancy*](https://en.wikipedia.org/wiki/Multitenancy) where several client organizations (tenants) share a shard. In that case different shards may be customized to vary in functionality, available resources, and [SLA](https://en.wikipedia.org/wiki/Service-level_agreement) to provide better service to higher-paying tenants.

*Cells*, according to the [Amazon terminology](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/what-is-a-cell-based-architecture.html), are copies of a whole system deployed to several data centers, each serving local users. The locality improves latency and saves on Internet traffic while having multiple instances of the system up and running provides availability. The downside of this approach is its complexity and the amount of global traffic needed to keep the *Cells* in sync.

It usually takes a stand-alone [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] – a kind of *Load Balancer* – to route a client’s requests to the shard that owns its data. However, there are other options \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]:

- The *Sharding Proxy* may be deployed to each client as a client-side [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador*]] to avoid the extra network hop. This approach requires a means for keeping the *Ambassadors* up-to-date with your system’s code.
- You can publish your *sharding function* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] and the number of shards in your public API to let your clients choose which shard to access without your help. That may work for internal clients implemented by your own or a neighbor team.
- Finally, each shard may be able to forward client requests to any other shard – making each shard into a kind of *Sharding Proxy* and an entry point into the resulting [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]. If your client accesses a wrong shard, the request is still served, though a little slower, through being forwarded between the shards \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\].


*Sharding* solves scaling of an application both in regard to the number of its clients and to the size of its data. However, it works well only if each client’s data is independent from other clients. Moreover, if one of the shards crashes, the information it owns becomes unavailable unless [*replication*](#persistent-copy-replica) (see below) has been set up as well.

### Persistent copy: Replica


![A load balancer connects a new client to a free replica which propagates the changes made by the client to other replicas.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Shards%20-%20Replica.png)


*Replicas* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] are identical copies of a stateful (sub)system. Replication improves the system’s throughput (as each replica serves client requests) and its stability (as a fault in one replica does not affect others which may quickly take up the failed replica’s clients). Replicas may also be used to improve tail latency through [*Request Hedging*](https://grpc.io/docs/guides/request-hedging/): each request is sent to several replicas in parallel and the first response received is returned to the client. Mission-critical hardware [runs as three copies](https://en.wikipedia.org/wiki/Triple_modular_redundancy) and relies on majority voting for computation results.

The hard part comes from the need to keep the replicas’ data in sync. The ordinary way is to let the replicas talk to each other on each data update. If the communication is synchronous that may greatly slow down the processing of requests, yet if it is asynchronous the system suffers data conflicts when multiple clients change the same value simultaneously. Synchronization code is quite complex, thus you will likely use a ready-made [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] framework instead of writing one of your own.

Another option found in the field is keeping the replicas only loosely identical. That happens when isolated cache servers make a [[wiki/concepts/source/extension-metapatterns/proxy|*Caching Layer*]]. As clients tend to send similar requests, the data inside each *cache* is more or less the same by the law of large numbers.

And if your traffic is read-heavy, you may turn to [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] by segregating your replicas into the roles of a fully-functional *leader* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] and [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|derived, read-only *followers*]]. The followers serve only the read requests while the leader processes the write requests which make it update its data and broadcast the changes to all its followers. And if the leader dies, one of its followers is elected to become a new leader. As a refinement of this idea, the code of the service itself may be separated into write (*command*) and read (*query*) services (see [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Command Query Responsibility Segregation*]] aka *CQRS*).

Finally, you can mix sharding and replication to make sure that the data of each shard is replicated, either in whole among identical components \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] or piecemeal all over the system \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]. That achieves fault tolerance for volumes of data too large to store unsharded.

### Stateless: Pool, Instances, [[wiki/concepts/source/extension-metapatterns/sandwich|Replicated Load-Balanced Services]], Work Queue, Lambdas


![A load balancer connects a new client to a free instance of a stateless backend that accesses a database shared among all the backend instances.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Shards%20-%20Pool.png)


A predefined number (*pool* \[[wiki/concepts/source/appendices/books-referenced|[POSA3]]\]) of instances (*workers*) is created during the initialization of the system (sometimes called a *Work Queue* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\]). When the system receives a task, a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] assigns it to one of the idle instances, called *Replicated Load-Balanced Services* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\], from the pool. As soon as the instance finishes processing its task it returns to the pool and its state is reset. A well-known example of this pattern is [FastCGI](https://en.wikipedia.org/wiki/FastCGI).

This approach allows for rapid allocation of a worker to any incoming task, but it uses a lot of resources even when there are no requests to serve, yet the system may still be overwhelmed at peak load. Moreover, a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] (database or file storage) is usually involved for the sake of persistence, further limiting the pattern’s scalability.

Many cloud services implement *dynamic* pools, the number of instances ([*lambdas*](https://jesseduffield.com/Notes-On-Lambda/)) growing and shrinking according to the overall load: if all the current instances are busy serving user requests, new instances are created and added to the pool. If some of the instances are idle for a while, they are destroyed. Dynamic pooling is often implemented through [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]], as in [[wiki/concepts/source/implementation-metapatterns/mesh|*Microservices*]] or [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]].

### Temporary state: Create on Demand, [[wiki/concepts/source/basic-metapatterns/services|Actors]]


![A new stateful instance is created when a new client connects to the system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Shards%20-%20Create%20on%20Demand.png)


An instance is created for supporting an incoming client session and is destroyed when the session is closed. Upon creation it is initialized with all the client-related data which makes the instance able to interact with its client without much help from the backend. Examples include web applications that run in users’ browsers and user-dedicated [[wiki/concepts/source/basic-metapatterns/services|*actors*]] in backends of instant messengers.

This approach provides responsiveness, perfect elasticity, and flexibility of deployment at the cost of slower session establishment and it usually relies on an external shared layer for persistence: instances of a frontend are initialized from and send their updates to a backend which itself uses a database.

## Evolutions

There are two kinds of evolutions for *Shards*: those intrinsic to the component sharded and those specific to the *Shards* pattern. All of them are summarized below while [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]] provides more details on the second kind.

### Evolutions of a sharded monolith

When *Shards* are applied to a single component, which is a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], the resulting (sub)system follows most of the [[wiki/concepts/source/basic-metapatterns/monolith|evolutions of *Monolith*]]:

- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] allow for the parts of the system to [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|differ]] in *qualities*, technologies, and [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|deployment]]. Various third-party components can be integrated and the code becomes better structured.
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] help to distribute the work among multiple teams and may decrease the project’s complexity if the division results in loosely coupled components.
- [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and its subtypes, namely [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] and [[wiki/concepts/source/implementation-metapatterns/microkernel|*Scripts*]], make the system more adaptable.


![Diagrams of scaled Layers, Services with a middleware, Pipeline, Plugins, Hexagonal Architecture, and Scripts.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20-%20General.png)


There is a benefit of such transformations which is important in the context of *Shards*: in many cases the resulting components can be scaled independently, arranging for a better resource utilization by the system when compared to scaling a *Monolith*. However, scaling individual services usually requires a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] or [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to distribute requests among the scaled instances.

### [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|Evolutions that share data]]

The issue peculiar to *Shards* is that of coordinating deployed instances, especially if their data becomes coupled. The most direct solution is to let every instance access the shared data:

- If the whole dataset needs to be shared, it can be split into a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] layer.


![The data of shards moves to a shared database. The shards become stateless and are deployed behind a load balancer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20to%20Shared%20DB.png)


- If data collisions are tolerated, [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] promises low latency and dynamic scalability.


![The data of the shards moves to a Data Grid, resulting in a Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20to%20Space-Based%20Architecture.png)


- If a part of the system’s data becomes coupled, only that part can be moved to a *Shared Repository*, making each instance manage [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|two stores of data: private and shared]].


![A coupled subset of the system's data is stored in a shared repository, while the bulk of the data is sharded.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Shared%20DB.png)


- Another possible option is to split a [[wiki/concepts/source/basic-metapatterns/services|service]] that owns the coupled data and is always deployed as a single instance. The remaining parts of the system become coupled to that service, not to each other.


![Coupled business logic and data is separated from shards into a shared singletone service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20split%20Shared%20Service.png)


### [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-logic|Evolutions that share logic]]

Other cases are better solved by extracting the logic that couples the shards:

- Splitting a [[wiki/concepts/source/basic-metapatterns/services|service]] (as discussed above) yields a component that represents both shared data and shared logic.
- Adding a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] lets the shards communicate with each other without maintaining direct connections. It also may do housekeeping: error recovery, replication, and scaling.


![A middleware manages shards and lets them communicate to each other.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Middleware.png)


- A [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] hides the shards from the system’s clients.


![A sharding proxy relieves clients from the need to find the appropriate shard.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20add%20Load%20Balancer.png)


- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] calls multiple shards to serve a user request. That relieves the shards of the need to coordinate their states and actions by themselves.


![The high-level logic of shards moves to a shared orchestrator which integrates the data stored within and processed by individual shards.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/Shards/Shards%20use%20Orchestrator.png)


## Summary

*Shards* are multiple instances of a component or subsystem which is thus made scalable and more fault tolerant. *Sharding* does not change the nature of the component it applies to and it usually relies on a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] or [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to manage the instances it spawns. Its main weakness appears when the *shards* need to intercommunicate, often to the end of synchronizing their data.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/extension-metapatterns.md ===== -->

---
title: "Extension metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Extension metapatterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Extension%20metapatterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Extension metapatterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Extension metapatterns.md`.

These patterns extend [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], or even a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] with a layer that provides an aspect or two of the system’s behavior and often glues other components together.

### [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]


![A diagram of Services with a middleware, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Middleware.png)


A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] is a layer which provides communication with instances of the system’s components and it may also manage those instances. This way each instance is relieved of the need to track the other instances which it accesses.

*<ins>Includes</ins>*: (Message) Broker and Deployment Manager; Message Bus, Event Mediator, Enterprise Service Bus, and Service Mesh.

### [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]


![A diagram of Services with a shared repository, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Shared%20Repository.png)


A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] stores the system’s data, maintains its integrity through transactions, and may support subscriptions to changes in subsets of the data. That lets other system components concentrate on implementing the business logic.

*<ins>Includes</ins>*: Shared Database, Blackboard, Data Grid of Space-Based Architecture, Shared Memory, and Shared File System.

### [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]


![A diagram of Services with a proxy, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Proxy.png)


A [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] mediates between a system and its clients, transparently taking care of some generic functionality.

*<ins>Includes</ins>*: Full Proxy and Half-Proxy; Sidecar and Ambassador; Firewall, Response Cache, Load Balancer, Reverse Proxy and various Adapters, e.g. Anticorruption Layer, Open Host Service, many Abstraction Layers, Repository, and even User Interface.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]


![A diagram of Services with an orchestrator, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Orchestrator.png)


An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] implements use cases as sequences of calls to the underlying components which are usually left unaware of each other’s existence.

*<ins>Includes</ins>*: Workflow Owner, Application Layer, Facade, Mediator; API Composer, Scatter-Gather, MapReduce, Process Manager, Saga Execution Component, and Integration (Micro-)Service.

### [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]]


![A diagram of Sandwich Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Sandwich.png)


[[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] subdivides the largest and loosely coupled [[wiki/concepts/source/basic-metapatterns/layers|*domain* layer]] into modules or services while the other layers remain monolithic.

*<ins>Includes</ins>*: Service-Based Architecture, Space-Based Architecture, Blackboard Architecture, Nanoservices, and Command Query Responsibility Segregation (CQRS).


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/middleware.md ===== -->

---
title: "Middleware"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Middleware.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Middleware
source_license_note: "See namespace README; preserve attribution and source links."
---

# Middleware

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Middleware.md`.


![A diagram for Services with a middleware, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Middleware.png)


*The line between disorder and order lies in logistics.* Use a shared transport.

<ins>Known as:</ins> (Distributed) Middleware.

<ins>Structure:</ins> A low-level layer that provides connectivity.

<ins>Type:</ins> Extension component.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Separates connectivity concerns from the services that use it | May become a single point of failure |
| Transparent scaling of components | May increase latency |
| Available off the shelf | A generic *Middleware* may not fit specific communication needs |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] has a lot of content on the implementation of messaging *Middleware*. \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] features a chapter on *Middleware*. However, those books are old. \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] is about Kafka, but it goes too far advertising it as a [*Shared Event Store*](#persistent-event-log-shared-event-store). There is also a [Wikipedia article](https://en.wikipedia.org/wiki/Middleware_(distributed_applications)).

Extracting transport into a separate layer relieves the components that implement business logic of the need to know the addresses and statuses of each other’s instances. An industrial-grade, third-party *Middleware* is likely to be more stable and provide better error recovery than anything an average company can afford to implement on its own.

A *Middleware* may function as:

- A *Message Broker* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|EIP]], [[wiki/concepts/source/appendices/books-referenced|MP]]\] which provides a unified means of communication and implements some cross-cutting concerns like the persisting or logging of messages.
- A *Deployment Manager* \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] which collects telemetry and manages service instances for error recovery and dynamic scaling.


As *Middleware* is ubiquitous and does not affect business logic, it is usually omitted from structural diagrams.

### Performance

A *Middleware* may negatively affect performance when compared to direct communication between services. Old implementations (star topology) relied on a *Broker* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|EIP]]\] that used to add an extra network hop for each message and limited scalability. Newer [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based variants avoid those drawbacks but are very complex and may have consistency issues (according to the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem)).

A more subtle drawback is that transports which a *Middleware* supports or uses by default may be suboptimal for some of the interactions in your system, causing programmers to hack around the limitations or build higher-level protocols on top of your *Middleware*. Both cases can be ameliorated by adding means for direct communication between the services to bypass the *Middleware* or by using multiple specialized kinds of *Middleware*. However, that adds to the complexity of the system – the very issue the *Middleware* promised to help with.

### Dependencies

Each service depends both on the *Middleware* and on the API of every service it communicates with.


![Each service depends on the middleware and on every service which it uses.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Middleware.png)


You may decide to use an [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]] over your *Middleware* just in case you may need to change its vendor in the future. That will trade performance for flexibility.

### Applicability

*Middleware* <ins>helps</ins>:

- *Multi-component systems.* When a service has several instances deployed which need to be accessed, its clients must know the addresses of (or have channels to) its instances and use an algorithm for instance selection. As the number of services grows, so does the amount of information about the instances of other services that each service needs to track. Even worse, services sometimes crash or are being redeployed, requiring complicated algorithms that queue messages to deliver them in order once the recipient service returns to life. It makes all the sense in the world to use a dedicated component to take care of all of that.
- *Dynamic scaling.* It is good to have a single, even if virtual, component that manages routes for interservice messaging to account for newly deployed (or destroyed) service instances.
- [*Blue-green deployment*](https://martinfowler.com/bliki/BlueGreenDeployment.html)*,* [*canary release*](https://martinfowler.com/bliki/CanaryRelease.html)*, or* [*dark launching*](https://martinfowler.com/bliki/DarkLaunching.html) *(traffic mirroring)*. It is easier to switch, whether fully or in part, to a new version of a service when the communication is centralized.
- *System stability.* Most implementations of *Middleware* guarantee message delivery with unstable networks and failing components. Many persist messages to be able to recover from failures of the *Middleware* itself.


*Middleware* <ins>hurts</ins>:

- *Critical real-time paths.* An extra layer of message processing is bad for latency. Such messages may need to bypass the *Middleware*, likely via pre-established message channels.


### Relations


![Middleware for Services, Shards, and Service-Oriented Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Middleware.png)


*Middleware*:

- Extends [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) or, in rare cases, [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] or [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].
- Can participate in a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Bus of Buses*]] ([[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]]) or be merged with other *extension metapatterns*.
- Is closely related to [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]. A persistent *Middleware* employs a *Shared Repository*.
- Is usually implemented by a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] or [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] (which is often based on a *Mesh*).


## Variants by functionality

There are several dimensions of freedom with a *Middleware*, some of them may be configurable:

### By addressing (channels, [[wiki/concepts/source/implementation-metapatterns/mesh|actors]], pub/sub, gossip)

Systems vary in the way their components address each other:

- *Channels* (one to one) – components which need to communicate establish a message channel between them. Once created, the channel accepts messages or a data stream on its input end and transparently delivers them to its output end. Examples: sockets, Unix pipes, and private chats.
- *Actors* (many to one) – each component has a public mailbox. Any other component that knows its address or name may push a message into it. Examples: e-mail.
- *Publish/subscribe* (one to many) – a component can publish events to topics. Other components subscribe to those topics and one or all of the subscribers receive copies of a published event. Examples: IP multicast and subscriptions for e-mail notifications.
- [*Gossip*](https://highscalability.com/gossip-protocol-explained/) (many to many) – an instance of a component periodically synchronizes its version of the system's state with random other instances, which further spread the updates. As time passes, more and more participants become aware of the changes in the system, leading to eventual consistency of the [[wiki/concepts/source/basic-metapatterns/shards|*replicas*]] of the system's state.


### By flow (notifications, request/confirm, RPC)

Control flow may take one or more of the following approaches:

- *Notifications* – a component sends a message about an event that occurred and does not really care about the further consequences or wait for a response.
- *Request/confirm* – a component sends a message which requests that another component does something and sends back the result. The sender may execute other tasks meanwhile. A request usually includes a unique id that will be added to the confirmation for the *Middleware* to know which of the requests in progress the confirmation belongs to.
- *Remote procedure call* (RPC) is usually built on top of a request/confirm protocol. The difference is that the sender blocks on the *Middleware* while waiting for the confirmation, thus to the application code the whole process of sending the request and waiting for the confirmation looks like a single method call.


### By delivery guarantee

If the transport (network) or the destination fails, a message may not be processed, or may be processed twice because of retries. A *Middleware* may [promise to deliver messages](https://blog.bytebytego.com/p/at-most-once-at-least-once-exactly):

- *Exactly once*. This is the slowest case which is [implemented through distributed transactions](https://docs.confluent.io/kafka/design/delivery-semantics.html). If the network, *Middleware* itself, or the message handler fails, there is no side effect, and the whole process of delivering and executing the message is repeated. The *exactly once* contract is used for financial systems and accounting where money should never disappear or duplicate during a transfer.
- *At least once*. On failure the message is redelivered, but the previous message could have already been processed (if only the confirmation was lost), thus there is a chance for a message to be processed twice. If the message is *idempotent* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\], meaning that it sets a value (x = 42) instead of incrementing or decrementing it (x = x \+ 2), then we can more or less safely process it multiple times (x = 42; x = 42; x = 42;) and use the relatively fast *at least once* guarantee.
- *At most once*. If anything fails, the message is lost and never retried. This is the fastest of the three guarantees, suitable for such monitoring applications as weather sensors – it is not too bad if a single temperature measurement disappears when you receive hundreds of them every day.
- *At will* (no guarantee). As with the bare [UDP transport](https://en.wikipedia.org/wiki/User_Datagram_Protocol#Reliability_and_congestion_control), a message may disappear, become duplicated, or arrive out of order. That fits real-time streaming protocols (video or audio calls) where it is acceptable to skip a frame while a frame coming too late is of no use at all. Each frame contains its sequence number, and it is up to the application to reorder and deduplicate the frames it receives.


### By persistence

A *Middleware* with a delivery guarantee needs to store messages whose delivery has not yet been confirmed. They may be:

- Written to a data store of the *broker*.
- Persisted in a distributed data store in brokerless ([[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]) systems.
- Replicated over an in-memory *Mesh* storage (like [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]]).


If the messages are stored indefinitely, the *Middleware* [becomes](#persistent-event-log-shared-event-store) a *Persistent* [*Event Log*](https://medium.com/sundaytech/event-sourcing-audit-logs-and-event-logs-deb8f3c54663) or even a *Shared* [*Event Store*](https://cloudnative.ly/event-driven-architectures-edas-vs-event-sourcing-c8582578e87) with the schemas of the stored events coupling the involved services \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] just like the database schema does in [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].

### By structure ([[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]], [[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]], Broker)


![In middleware each service is co-located with a generic component which may either be a node of a mesh or forward the service's requests to a centralized broker as a proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Middleware%20-%20Structure.png)


A *Middleware* may be:

- Implemented by an underlying operating or virtualization system (see [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]]).
- Run as a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] of identical modules co-deployed with the distributed components in their [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]].
- Rely on a single *broker* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|EIP]]\] for coordination.


The last configuration is simpler but features a single point of failure unless multiple instances of the broker are deployed and kept synchronized.

## Examples

There are several patterns which extend *Middleware* with other functions:

- A [*Persistent Event Log*](#persistent-event-log-shared-event-store) allows for replaying past events.
- A [*Service Mesh*](#service-mesh) adds a *Sidecar* with shared libraries to every service instance it hosts.
- A [*Message Bus*](#message-bus) uses *Adapters* to support a variety of protocols.
- An [*Event Mediator*](#event-mediator) orchestrates request processing for the services it connects.
- An [*Enterprise Service Bus*](#enterprise-service-bus-esb) both supports multiple protocols and orchestrates request processing.


### [[wiki/concepts/source/extension-metapatterns/shared-repository|Persistent Event Log, Shared Event Store]]


![Both persistent event log and shared event store merge the functionality of middleware and shared repository.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Middleware%20-%20Shared%20Event%20Store.png)


When a *Middleware* persists messages, it takes on the function (and drawbacks) of a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]. A *Persistent Event Log* allows to replay events incoming to a given service (to help a debug session or fix data corrupted by a bug) while a *Shared Event Store* also captures changes of the internal states of the services \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\], thus [replacing their private databases](https://cloudnative.ly/event-driven-architectures-edas-vs-event-sourcing-c8582578e87). However, with either approach, changing an event field impacts all the services that use the event and may involve rewriting the entire event log (the system’s history) \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\].

### [[wiki/concepts/source/implementation-metapatterns/mesh|Service Mesh]]


![Multiple instances of several services connected to their sidecars which are connected to a shared mesh engine. Instances of each service access its single database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Microservices.png)


*Service Mesh* \[[wiki/concepts/source/appendices/books-referenced|[FSA]], [[wiki/concepts/source/appendices/books-referenced|MP]]\] is a smart [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based *Middleware* that manages service instances and employs at least one co-located [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] (called [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecar*]]) per service instance deployed. The *Sidecars* may provide protocol translation and cover cross-cutting concerns such as encryption or logging. They make a good place for shared libraries.

The internals of [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] are discussed in the [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh* chapter]].

### Message Bus


![A message bus has an adapter per service to allow each service to use its own protocol.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Message%20Bus.png)


A *Message Bus* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] employs one or more [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] per service to let the services intercommunicate even if they differ in protocols. That helps to integrate legacy services without major changes to their code but it degrades the overall performance as up to two protocol translations per message are involved.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Event Mediator]]


![An event mediator calls event processors one by one.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Event%20Mediator.png)


*Event Mediator* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], which pervades both [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*s]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Nanoservices*]], combines a *Middleware* (used for the delivery of messages) and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] (that coordinates high-level use cases). A message arrives to a service and is responded to without any explicit support on the service’s side – it appears *out of thin Middleware* which implements the entire integration logic.

Slightly more details on the *Event Mediator* are [[wiki/concepts/source/extension-metapatterns/orchestrator|provided in the *Orchestrator* chapter]].

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Enterprise Service Bus]] (ESB)


![An Enterprise Service Bus is between the fragmented task and entity layers of Service-Oriented Architecture. It mediates all calls and messages between the system components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Enterprise%20Service%20Bus.png)


[*Enterprise Service Bus*](https://www.confluent.io/learn/enterprise-service-bus/) (*ESB*) \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] is a mixture of *Message Bus* and *Event Mediator*. A *ESB* blends a *Middleware* and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and adds an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] per service as a topping. It emerged to connect components that originated in incompatible networks of organizations that had been acquired by a corporation.

See the [chapter about *Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)#enterprise-soa>).

## [[wiki/concepts/source/appendices/evolutions-of-a-middleware|Evolutions]]

A *Middleware* is unlikely to be removed (though it may be replaced) once it is built into a system. There are [[wiki/concepts/source/appendices/evolutions-of-a-middleware|few evolutions for *Middleware*]] because it is usually a third-party product and thus unlikely to be modified in-house:

- If the *Middleware* in use does not fit the preferred mode of communication between some of your services, there is the option to deploy a second, specialized *Middleware*.


![A specialized middleware added to a system that already has a generic middleware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Middleware%20add%20Middleware.png)


- If several existing systems need to be merged, that is accomplished by adding yet another layer of *Middleware*, resulting in a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Bottom-up Hierarchy*]] *(Bus of Buses)*.


![A low-level middleware interconnects several higher-level middlewares.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Middleware%20to%20Bus%20of%20Buses.png)


## Summary

A *Middleware* is a ready-to-use component that provides a system of services with means of communication, scalability, and error recovery. It is very common in distributed backends.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/orchestrator.md ===== -->

---
title: "Orchestrator"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Orchestrator.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Orchestrator
source_license_note: "See namespace README; preserve attribution and source links."
---

# Orchestrator

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Orchestrator.md`.


![A diagram for Services with an orchestrator, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Orchestrator.png)


*One ring to rule them all.* Make a component to integrate other components.

<ins>Known as:</ins> Orchestrator \[[wiki/concepts/source/appendices/books-referenced|[MP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\], Orchestrated Services, Service Layer \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\], [[wiki/concepts/source/basic-metapatterns/layers|Application Layer]] \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], Wrapper Facade \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\], Multi-Worker \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\], Control, Workflow Owner \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] of [[wiki/concepts/source/basic-metapatterns/services|Microservices]], and Processing Grid \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] of [[wiki/concepts/source/extension-metapatterns/sandwich|Space-Based Architecture]].

<ins>Structure:</ins> A layer of high-level business logic built on top of lower-level services.

<ins>Type:</ins> Extension component.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Separates integration concerns from the services – decouples the services’ APIs | May increase latency for global use cases |
| Global use cases can be changed and deployed independently from the services | Qualities of the services become coupled to an extent |
| Decouples the services from the system’s clients | API design is an extra step before implementation |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] discusses orchestration in its chapters on *Event-Driven Architecture*, *Service-Oriented Architecture*, and *Microservices*. \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] describes orchestration-based *Sagas* and its Order Service acts as an *Application Service* without explicitly naming the pattern. \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] defines several variants of *Facade*.

An *Orchestrator*, named after the person that assigns musical parts in an orchestra, takes care of global use cases (those involving multiple services) thus allowing each service to specialize in its own subdomain and, ideally, forget about the existence of all the other services. This way the entire system’s high-level logic (which is subject to frequent changes) is kept (and deployed) together, isolated from usually more complex subdomain-specific services. Dedicating a [[wiki/concepts/source/basic-metapatterns/layers|layer]] to global scenarios makes them relatively easy to implement and debug, while the corresponding development team that communicates with clients shelters the other narrowly-focused teams from disruptions. The cost of employing an *Orchestrator* is both degraded performance when compared to basic [[wiki/concepts/source/basic-metapatterns/services|*Services*]] that rely on [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]], [[wiki/concepts/source/appendices/books-referenced|MP]]\] and some coupling of the properties of the orchestrated services as the *Orchestrator* usually treats every service in the same way.

An *Orchestrator* fulfills two closely related roles:

- As a [*Mediator*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]], [[wiki/concepts/source/appendices/books-referenced|SAHP]]\] it keeps the states of the underlying components consistent by propagating changes that originate in one component to the rest of the system. This role is prominent in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control* software]], pervading automotive, aerospace, and IoT industries. The *Mediator* role also emerges as [*Saga*](#orchestrated-saga-saga-orchestrator-saga-execution-component-transaction-script-coordinator).
- As a [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] it builds high-level scenarios out of smaller steps provided by the services or modules it controls. This role is obvious for [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*processing* systems]] where clients communicate with the *Facade*, but it is also featured in *control* software, because sometimes a simple event may trigger a complex multi-component scenario managed by the system’s *Orchestrator*.


![Control flows in a facade and mediator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Misc/Orchestrator.png)


[[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|Data *processing*]] systems, such as backends, may deploy multiple [[wiki/concepts/source/basic-metapatterns/shards|instances]] of stateless *Orchestrators* to improve stability and performance. In contrast, an *Orchestrator* in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control* software]] incorporates a high-level view of the system’s state thus it cannot be easily replicated (as any replicated state must be kept synchronized, introducing delay or inconsistency in decision-making).

### Performance

When compared to [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]], [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] usually worsens latency as it involves extra steps of communication between the *Orchestrator* and orchestrated components. However, the effects should be estimated on case by case basis, as there are exceptions in at least the following cases:

- An *Orchestrator* may cache the state of the orchestrated system, gaining the ability to immediately respond to read requests with no need to query the underlying components. This is very common with [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control* systems]].
- An *Orchestrator* may persist a write request, respond to the client, and then start the actual processing (similar to the [[wiki/concepts/source/foundations-of-software-architecture/choreography|*early response* optimization]] in choreography). Persistence grants that the request will eventually be completed as it can be restarted.
- An *Orchestrator* may run multiple subrequests in parallel, reducing latency compared to a chain of choreographed events.
- In a highly loaded or latency-critical system, orchestrated services may establish direct data streams that bypass the *Orchestrator*. A classic example is [VoIP](https://en.wikipedia.org/wiki/Voice_over_IP) where the call establishment logic (SIP) goes through an orchestrating server while the voice or video (RTP) streams directly between the clients.


![Caching, early response, parallel execution, and direct communication between services as optimization techniques for Orchestrated Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Orchestrator.png)


I don’t see how orchestration can affect throughput as in most cases the *Orchestrator* can be scaled. However, scaling weakens consistency (or requires centralized locking, with a chance for a locked use case to hang if the *Orchestrator* instance which has locked it crashes) as then no instance of the *Orchestrator* has exclusive control over the system’s state.

### Dependencies

An *Orchestrator* may depend on the *APIs* of the services it orchestrates or define *SPIs* for them to implement, with the first mode being natural for its [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] aspect and the second one for the [*Mediator*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]:


![A facade depends on every service. Contrariwise, every service depends on a mediator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Orchestrator.png)


If an *Orchestrator* is added to integrate existing components, it will use their APIs.

In large projects, where each service gets a separate team, the APIs need to be negotiated beforehand, and will likely be owned by the orchestrated services.

Smaller (single-team) systems tend to be developed top-down, with the *Orchestrator* being the first component to implement, thus it defines the interfaces it uses.

Likewise, [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control systems]] tend to reverse the dependencies, with their services depending on the orchestrator’s SPI to provide for polymorphism between the low-level components. See the [[wiki/concepts/source/foundations-of-software-architecture/orchestration|chapter on *orchestration*]] for [[wiki/concepts/source/foundations-of-software-architecture/orchestration|more details]].

### Applicability

*Orchestrators* <ins>shine</ins> with:

- *Large projects.* The partition of business logic into a high-level [[wiki/concepts/source/basic-metapatterns/layers|*application*]] (*Orchestrator*) and the multiple [[wiki/concepts/source/basic-metapatterns/services|subdomain *Services*]] it relies on provides perfect code decoupling and team specialization.
- *Specialized teams.* As an improvement over [[wiki/concepts/source/basic-metapatterns/services|*Services*]], the teams which develop deep knowledge of subdomains will delegate communication with customers to the application team.
- *Complex and unstable requirements*. The *integration* layer (*Orchestrator*) should be high-level and simple enough to be easily extended or modified to cover most of the customer requests or marketing experiments without much help from the domain teams.


*Orchestrators* <ins>fail</ins> in:

- *Huge projects.* At least one aspect of complexity is going to hurt. Either the number of the subdomain services and the size of their APIs will make it impossible for an *Orchestrator* programmer to find the correct methods to call, or the *Orchestrator* itself will become unmanageable due to the sheer number and length of its use cases. This can be addressed by dividing the *Orchestrator* into a layer of services (resulting in [*Backends for Frontends*](<Backends for Frontends (BFF)>) or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]]) or multiple layers (often yielding a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]]). It is also possible to go for the [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) as that has more fine-grained components.
- *Small projects*. The implementation overhead of defining and stabilizing service APIs and the performance penalty of the extra network hop may outweigh the extra flexibility of having the *Orchestrator* as a separate system component.
- *Low latency*. Any system-wide use case will make multiple calls between the application (*Orchestrator*) and services, with each interaction adding to the latency.


### Relations


![Orchestrator for a monolith, layers, shards and services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Orchestrator.png)


*Orchestrator*:

- Extends [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or, rarely, [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], or [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] (forming *Layers*).
- Can be merged with a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] into an [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateway*]], with a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] into an [[wiki/concepts/source/extension-metapatterns/middleware|*Event Mediator*]], or with a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] and [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] into an [[wiki/concepts/source/extension-metapatterns/middleware|*Enterprise Service Bus*]].
- Is a special case (single service) of [*Backends for Frontends*](<Backends for Frontends (BFF)>), [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) or (2-layer) [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]].
- Is a part of [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].
- Can be implemented by a [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


## Variants by transparency

It seems that an *Orchestrator*, just like a [[wiki/concepts/source/basic-metapatterns/layers|*layer*]], which it is, [[wiki/concepts/source/basic-metapatterns/layers|can be]] *open* (*relaxed*) or *closed* (*strict*):

### Closed or strict


![An orchestrator mediates every request from every client.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Closed.png)


A *strict* or *closed Orchestrator* isolates the orchestrated services from their users – all the requests go through the *Orchestrator*, and the services don’t need to intercommunicate.

### Open or relaxed


![An orchestrator mediates a multi-step client request while it is transparent to simpler requests.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Open.png)


An *open Orchestrator* implements a subset of system-wide scenarios that require strict data consistency while less demanding requests go from the clients directly to the underlying services, which rely on [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]] or [[wiki/concepts/source/foundations-of-software-architecture/shared-data|*shared data*]] for communication. Such a system sacrifices the clarity of design to avoid some of the drawbacks of both *choreography* and *orchestration*:

- The orchestrator development team, which may be overloaded or slow to respond, is not involved in implementing the majority of use cases.
- Most of the use cases avoid the performance penalty caused by the orchestration.
- Failure of the *Orchestrator* does not disable the entire system.
- The relaxed *Orchestrator* still allows for synchronized changes of data in multiple services, which is rather hard to achieve with choreography.


## Variants by structure (can be combined)

The orchestration ([[wiki/concepts/source/basic-metapatterns/layers|application]] \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] / [integration](https://github.com/wso2/reference-architecture/blob/master/event-driven-api-architecture.md) / [composite](https://github.com/wso2/reference-architecture/blob/master/event-driven-api-architecture.md)) layer has several structural (implementation) options:

### [[wiki/concepts/source/basic-metapatterns/monolith|Monolithic]]


![An orchestrator communicates with several services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Monolythic.png)


A single *Orchestrator* is deployed. This option fits ordinary medium-sized projects but fails for anything more demanding as the *Orchestrator* limits throughput, becomes a single point of failure, and may grow too complex for comfortable development.

### [[wiki/concepts/source/basic-metapatterns/shards|Scaled]]


![Multiple instances of a stateless orchestrator are behind a load balancer and they persist their actions into a dedicated shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Scaled.png)


High availability requires multiple [[wiki/concepts/source/basic-metapatterns/shards|instances]] of a stateless *Orchestrator* to be deployed. A *Mediator* ([*Saga*](#orchestrated-saga-saga-orchestrator-saga-execution-component-transaction-script-coordinator), writing *Orchestrator*) may store the current transaction’s state in a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] to assure that if it crashes there is always another instance ready to take up its job.

High load systems also require multiple instances of *Orchestrators* because a single instance is not enough to handle the incoming traffic.

> Not all data is made equal. For example, an online store has different requirements for reliability of its buyers’ cart contents and the payments. If the current buyers’ carts become empty when the store’s server crashes, that makes only a minor annoyance (unless it happens repeatedly). However, any financial data loss or a corrupted money transfer is a real trouble. Therefore, an online store may implement its cart with a simple in-memory *Orchestrator*, but should be very careful about the payments workflow, every step of which must be persisted to a reliable database.

### [[wiki/concepts/source/basic-metapatterns/layers|Layered]]


![A simple orchestrator calls services or a complex orchestrator, which also calls the same services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Layered.png)


\[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] describes an option of a layered [*Event Mediator*](#event-mediator). A client’s request comes to the topmost layer of the *Orchestrator* which uses the simplest (and least flexible) framework. If the request is found to be complex, it is forwarded to the second layer which is based on a more powerful technology. And if it fails or requires a human decision then it is forwarded again to the even more complex custom-tailored orchestration layer.

That allows the developers to gain the benefits of a high-level declarative language in a vast majority of scenarios while falling back to hand-written code for a few complicated cases. This choice is not free as the programmers need to learn multiple technologies, interlayer debugging is anything but easy, and performance is likely to be worse than that of a monolithic *Orchestrator*.

A similar example is using an [*API Composer*](#api-composer-remote-facade-gateway-aggregation-composed-message-processor-scatter-gather-mapreduce) for the top layer, followed by a [*Process Manager*](#process-manager-orchestrator) and a [*Saga Engine*](#orchestrated-saga-saga-orchestrator-saga-execution-component-transaction-script-coordinator).

### A service per client type ([Backends for Frontends](<Backends for Frontends (BFF)>))


![Each client communicates with its own orchestrator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20BFF.png)


If your clients strongly differ in workflows (e.g. [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) and [OLTP](https://en.wikipedia.org/wiki/Online_transaction_processing), or user and admin interfaces), implementing dedicated *Orchestrators* is an option to consider. That both makes each client-specific *Orchestrator* smaller and more cohesive than the unified implementation would be and gives more independence to the teams responsible for different kinds of clients.

This pattern is known as [*Backends for Frontends*](<Backends for Frontends (BFF)>) and has a chapter of its own.

### A service per subdomain ([[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]])


![A top-level orchestrator communicates with lower-level Orchestrators each of which manages a group of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20Hierarchy.png)


In a large system a single *Orchestrator* is very likely to become overgrown and turn into a development bottleneck (see [*Enterprise Service Bus*](#enterprise-service-bus-esb)). Building a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*hierarchy*]] of *Orchestrators* may help \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], but that requires the domain itself to be hierarchical.

The top-level component may even be a [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]] if no use cases cross subdomain borders or if the sub-orchestrators employ [[wiki/concepts/source/foundations-of-software-architecture/choreography|choreography]], resulting in a flat [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]]. Otherwise it is a tree-like [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Orchestrator of Orchestrators*]].

### A service per use case ([SOA](<Service-Oriented Architecture (SOA)>)-style)


![There are several orchestrators which use the same set of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Orchestrator%20-%20SOA.png)


\[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] advises for single-purpose *Orchestrators* in [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]: each *Orchestrator* manages one use case. This enables fine-grained scalability but will quickly lead to integration hell as new scenarios keep getting added to the system. Overall, such a use of *Orchestrators* resembles the [*task layer*](<Service-Oriented Architecture (SOA)#enterprise-soa>) of [*SOA*](<Service-Oriented Architecture (SOA)>).

## Examples

An *Orchestrator* may function in one of the following ways:

- An [*API Composer*](#api-composer-remote-facade-gateway-aggregation-composed-message-processor-scatter-gather-mapreduce) distributes parts of a client request to multiple services for parallel execution.
- A [*Process Manager*](#process-manager-orchestrator) splits a request into consecutive steps and oversees their execution.
- A [*Saga*](#orchestrated-saga-saga-orchestrator-saga-execution-component-transaction-script-coordinator) applies a change to multiple services in an “all or nothing” manner.
- An [*Integration Service*](#integration-micro-service-application-service) is a full-featured service which utilizes other services while providing for its users.
- [*Front Controller*](#inexact-front-controller) describes the first service in a *Pipeline* if it receives notifications from other services to know the ongoing status of every request.


There are also several patterns that have other functions in addition to orchestration:

- An [*API Gateway*](#api-gateway) blends an *API Composer* (orchestrating request) and a *Gateway* (dealing with protocols and logging).
- An [*Event Mediator*](#event-mediator) is a *Process Manager* with *Middleware* capabilities.
- An [*Enterprise Service Bus*](#enterprise-service-bus-esb) is an orchestrating *Message Bus* (multi-protocol *Middleware*).


### API Composer, Remote Facade, Gateway Aggregation, Composed Message Processor, Scatter-Gather, MapReduce


![An API Composer calls services in parallel. A Scatter/Gather or MapReduce calls shards in parallel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/API%20Composer.png)


*API Composer* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] is a kind of [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] which decreases the system’s latency by translating a high-level incoming message into a set of lower-level internal messages, sending them to the corresponding [[wiki/concepts/source/basic-metapatterns/services|services]] in parallel, waiting for results, and collecting the latter into a response to the original message. Such a logic may often be defined declaratively in a third-party tool without writing any low-level code. *Remote Facade* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] is a similar pattern which makes synchronous calls to the underlying components – its goal is implementing a coarse-grained protocol for the system’s clients, so that a client may achieve whatever it needs through a single request. [*Gateway Aggregation*](https://learn.microsoft.com/en-us/azure/architecture/patterns/gateway-aggregation) is a generalization of these patterns.

*Composed Message Processor* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] disassembles *API Composer* into smaller components: it uses a *Splitter* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] to subdivide the request into smaller parts, a *Router* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] to send each part to its recipient, and an *Aggregator* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] to collect the responses into a single message. Unlike *API Composer*, it can also address [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]]. A [*Scatter-Gather*](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/scatter-gather.html) \[[wiki/concepts/source/appendices/books-referenced|[EIP]], [[wiki/concepts/source/appendices/books-referenced|DDS]]\] broadcasts a copy of the incoming message to each recipient, thus it lacks a *Splitter* (though \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] seems to ignore this difference). [*MapReduce*](https://en.wikipedia.org/wiki/MapReduce) \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] is similar to *Scatter-Gather* except that it summarizes the results received in order to yield a single value instead of concatenating them.

If an *API Composer* needs to conduct sequential actions (e.g. first get user id by user name, then get user data by user id), it becomes a [*Process Manager*](#process-manager-orchestrator) which may require some coding.

An *API Composer* is usually deployed as a part of an [*API Gateway*](#api-gateway).

Example: Microsoft has an [article](https://learn.microsoft.com/en-us/azure/architecture/patterns/gateway-aggregation) on aggregation.

### Process Manager, Orchestrator


![The orchestrator calls several services one by one.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Process%20Manager.png)


*Process Manager* \[[wiki/concepts/source/appendices/books-referenced|[EIP]], [[wiki/concepts/source/appendices/books-referenced|LDDD]]\] (referred to simply as *Orchestrator* in \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\]) is a kind of *Facade* that translates high-level tasks into sequences of lower-level steps. This subtype of *Orchestrator* receives a client request, stores its state, runs pre-programmed request processing steps, and returns a response. Each of the steps of a *Process Manager* is similar to a whole task of an *API Composer* in that it generates a set of parallel requests to internal services, waits for the results, and stores them for the future use in the following steps or final response. The scenarios it runs may branch on conditions.

A *Process Manager* may be implemented in a general-purpose programming language, a declarative description for a third-party tool, or a mixture thereof.

A *Process Manager* is usually a part of an [*API Gateway*](#api-gateway), [*Event Mediator*](#event-mediator) or [*Enterprise Service Bus*](#enterprise-service-bus-esb).

Example: \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] provides several examples.

### (Orchestrated) Saga, Saga Orchestrator, [[wiki/concepts/source/implementation-metapatterns/microkernel|Saga Execution Component]], Transaction Script, Coordinator


![An atomically consistent saga rolls back changes after a failed write. An eventually consistent saga retries the failed write till it succeeds.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Saga.png)


*(Orchestrated* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\]*) Saga* \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\], *Saga Orchestrator* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] or [*Saga Execution Component*](https://www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf) is a subtype of *Process Manager* which is specialized in *distributed transactions*. Its name comes from epic stories woven from multiple episodes.

- An *Atomically Consistent Saga* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] (which is the default meaning of the term) comprises a pre-programmed sequence of \{“do”, “undo”\} action pairs. When it is run, it iterates through the “do” sequence till it either completes (meaning that the transaction succeeded) or fails. A failed *Atomically Consistent Saga* begins iterating through its “undo” sequence to roll back the changes that were already made.
- In contrast, an *Eventually Consistent Saga* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] always retries its writes till all of them succeed.


A *Saga* is often programmed declaratively in a third-party [[wiki/concepts/source/implementation-metapatterns/microkernel|*Saga Framework*]] which can be integrated into any service that needs to run a *distributed transaction*. However, it is quite likely that such a service itself is an [*Integration Service*](#integration-micro-service-application-service) as it seems to [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrate]] other services.

A *Saga* plays the roles of both *Facade* by translating a single transaction request into a series of calls to the services’ APIs and *Mediator* by keeping the states of the services consistent (the transaction succeeds or fails as a whole). Sometimes a *Saga* may include requests to external services (which are not parts of the system you are developing).

A *Transaction Script* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]], [[wiki/concepts/source/appendices/books-referenced|LDDD]]\] is a procedure that executes a transaction, possibly over multiple data stores \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\]. Unlike a *Saga*, it is synchronous, written in a general programming language, and does not require a dedicated framework to run. It operates the data store(s) directly while a *Saga* usually sends commands to services. A *Transaction Script* may return data to its caller.

*Coordinator* \[[wiki/concepts/source/appendices/books-referenced|[POSA3]]\] is a generalized pattern for a component which manages multiple tasks (e.g. software updates of multiple components) to achieve “all or nothing” results (if any update fails, other components are rolled back).

Example: \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] investigates many kinds of *Sagas* while \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] has a shorter description.

### Integration (Micro-)Service, Application Service


![An integration service is a full-featured service that stands between the client and the remaining services of the system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Integration%20Service.png)


An [*Integration Service*](https://github.com/wso2/reference-architecture/blob/master/event-driven-api-architecture.md) is a full-scale service (often with a dedicated database) that runs high-level scenarios while delegating the bulk of the work to several other services (remarkably, delegating to a single component forms [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]]). Though an *Integration Service* usually features both functions of *Orchestrator*, in a [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control* system]] its *Mediator* role is more prominent while in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*processing* software]] it is going to behave more like the *Facade*. A system with an *Integration Service* often resembles a shallow [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].

Example: Order Service in \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] seems to fit the description.

### (inexact) [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Front Controller]]


![A Front Controller is the first service of a pipeline which receives status notifications from every other service and responds to the client's get status query.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Front%20Controller.png)


*Front Controller* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]] [[wiki/concepts/source/analytics/ambiguous-patterns|but not]] [[wiki/concepts/source/appendices/books-referenced|PEAA]]\] is the name for the first (client-facing) service of a [[wiki/concepts/source/basic-metapatterns/pipeline|*pipeline*]] in [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]] when that service collects information about the status of each request it has processed and forwarded down the *pipeline.* The status is received by listening for notifications from the downstream services and is readily available for the *Front Controller*’s clients, which makes *Front Controller* resemble [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]) and [*Application Service*](#integration-micro-service-application-service).

### [[wiki/concepts/source/extension-metapatterns/proxy|API Gateway]]


![An API Gateway both translates from the client's to the system's protocol and calls services in parallel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/API%20Gateway.png)


An *API Gateway* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] is a component that not only processes client requests (and encapsulates an implementation of a client protocol(s)) as a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] (a kind of [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]]) but also splits every client request into multiple requests to internal services as an [*API Composer*](#api-composer-remote-facade-gateway-aggregation-composed-message-processor-scatter-gather-mapreduce) or [*Process Manager*](#process-manager-orchestrator) (which are *Orchestrators*). It is a common pattern for backend solutions as it does everything necessary to isolate the stable core of the system’s implementation from its fickle clients. Usually a third-party framework implements and colocates both its aspects, namely *Proxy* and *Orchestrator*, thus simplifying deployment and improving latency.

Example: a thorough article from [Microsoft](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway).

### [[wiki/concepts/source/extension-metapatterns/middleware|Event Mediator]]


![An event mediator calls event processors one by one.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Event%20Mediator.png)


*Event Mediator* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] is an *orchestrating* [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]. It not only receives requests from clients and turns each request into a multistep use case (as a [*Process Manager*](#process-manager-orchestrator)) but it also manages the deployed instances of services and acts as a medium which calls them. Moreover, unlike an ordinary *Middleware*, it seems to be aware of all of the kinds of messages in the system and which service each message must be forwarded to, resulting in overwhelming complexity concentrated in a single component which does not even follow the principle of separation of concerns. \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] recommends [building a stack of *Event Mediators*](#layered) from several vendors, further complicating this architecture.

Example: Mediator Topology in the chapter of \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] on Event-Driven Architecture.

### [[wiki/concepts/source/extension-metapatterns/middleware|Enterprise Service Bus]] (ESB)


![An Enterprise Service Bus is between the fragmented task and entity layers of Service-Oriented Architecture. It mediates all calls and messages between the system components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Enterprise%20Service%20Bus.png)


[*Enterprise Service Bus*](https://www.confluent.io/learn/enterprise-service-bus/) (*ESB*) \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] is an overgrown [*Event Mediator*](#event-mediator) that incorporates lots of [*cross-cutting concerns*](https://en.wikipedia.org/wiki/Cross-cutting_concern), including protocol translation for which it utilizes at least one [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] per service (just as a [[wiki/concepts/source/extension-metapatterns/middleware|*Message Bus*]] does). The combination of a central role in organizations and its complexity was among the main reasons for the demise of [*Enterprise Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)#enterprise-soa>).

Example: Orchestration-Driven Service-Oriented Architecture in \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], [how it is born](http://memeagora.blogspot.com/2009/01/tactics-vs-strategy-soa-tarpit-of.html) and [how it dies](http://memeagora.blogspot.com/2009/03/triumph-of-hope-over-reason-soa-tarpit.html) by Neal Ford.

## [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|Evolutions]]

Employing an *Orchestrator* has two pitfalls:

- The system becomes slower because too much communication is involved.
- A single *Orchestrator* may grow too large and rigid.


There is [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|one way to counter the first point and more than one to solve the second]]:

- Subdivide the *Orchestrator* by the system’s subdomains, forming [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]] and minimizing network communication.


![An orchestrator is subdivided into subdomain components which become the application layers of respective services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Layered%20Services.png)


- Subdivide the *Orchestrator* by the type of client, forming [*Backends for Frontends*](<Backends for Frontends (BFF)>).


![An orchestrator is subdivided into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Backends%20for%20Frontends.png)


- Add another [[wiki/concepts/source/basic-metapatterns/layers|*layer*]] of orchestration.


![An orchestrator is subdivided into a pair of simple and complex orchestrators.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20add%20Orchestrator.png)


- Build a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]].


![An orchestrator is subdivided into a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Orchestrator%20to%20Hierarchy.png)


## Summary

 An *Orchestrator* distills the high-level logic of your system and keeps it together in a layer which integrates other components. However, the separation of business logic into two layers results in much communication which impairs performance.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/proxy.md ===== -->

---
title: "Proxy"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Proxy.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Proxy
source_license_note: "See namespace README; preserve attribution and source links."
---

# Proxy

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Proxy.md`.


![A diagram for Services with a proxy, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Proxy.png)


*Should I build the wall?* A layer of indirection between your system and its clients.

<ins>Known as:</ins> [Proxy](https://refactoring.guru/design-patterns/proxy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\].

<ins>Structure:</ins> A layer that pre-processes and/or routes user requests.

<ins>Type:</ins> Extension component.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Separates cross-cutting concerns from the services | A single point of failure |
| Decouples the system from its clients | Most proxies degrade latency |
| Low attack surface |  |
| Several kinds of Proxies are available off the shelf |  |

<ins>References:</ins> Half of \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] is about the use of *Proxies*. See also: \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] on *Proxy*; [Chris Richardson](https://microservices.io/patterns/apigateway.html) and [Microsoft](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway) on *API Gateway*; [Martin Fowler](https://martinfowler.com/articles/gateway-pattern.html) on *Gateway*, *Facade*, and *API Gateway*.

A *Proxy* stands between a (sub)system’s implementation and its users. It receives a request from a client, does some pre-processing, then forwards the request to a lower-level component. In other words, a *Proxy* encapsulates selected aspects of the system’s communication with its clients by serving as yet another layer of indirection. It may also decouple the system’s internals from changes in the public protocol. The [main functions](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway) of a *Proxy* include:

- *Isolation* – the *Proxy* hides the internals of the system behind it from the clients. This both improves security because access to other system components is supervised and permits changes to the system’s components or structure as nothing external knows what’s behind the *Proxy*.
- *Translation* – the *Proxy* may convert between the system’s internal protocol and its published interfaces. [*User Interface*](#user-interface-presentation-layer-separated-presentation-command-line-interface-cli-graphical-user-interface-gui-frontend-human-machine-interface-hmi-man-machine-interface-mmi-operator-interface) is a translating *Proxy* taken to extremes: it represents the system’s internal data and commands as human-readable information.
- *Routing* – the *Proxy* tracks addresses of deployed instances of the system’s components and is able to forward a client’s request to the [[wiki/concepts/source/basic-metapatterns/shards|*shard*]] or [[wiki/concepts/source/basic-metapatterns/services|*service*]] which can handle it. Clients need to know only the public address of the *Proxy*. A *Proxy* may also respond on its own if the request is invalid or there is a matching response in the *Proxy*’s cache.
- *Offloading* – a *Proxy* may implement generic aspects ([*cross-cutting concerns*](https://en.wikipedia.org/wiki/Cross-cutting_concern)) of the system’s public interface, such as authentication, authorisation, encryption, or request logging which would otherwise need to be implemented by the underlying system components. That allows for the services to concentrate on what you write them for – the business logic.


### Performance

Most kinds of proxies trade latency (the extra network hop) for some other quality:

- A [*Firewall*](#firewall-api-rate-limiter-api-throttling) slows down processing of good requests but *protects* the system from attacks.
- Both a [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler) and a [*Dispatcher*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway) allow for the use of multiple servers (with identical or specialized components, respectively) to improve the system’s *throughput* but they still increase its minimal latency.
- An [*Adapter*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver) adds *compatibility* but its latency cost is higher than with other *Proxies* as it not only forwards the original message but also changes its payload – an activity which involves data processing and serialization.


A [*Cache*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache) is a bit weird in that respect. It improves latency and throughput for repeated requests but degrades latency for unique ones. Furthermore, it is often colocated with some other kind of *Proxy* to avoid the extra network hop between the *Proxies*, which makes caching almost free in terms of latency.

### Dependencies

*Proxies* widely vary in their functionality and level of intrusiveness. The most generic proxies, like *Firewalls*, may not know anything about the system or its clients. A *Response Cache* or *Adapter* must parse incoming messages, thus it depends on the communication protocol and message format. A *Load Balancer* or *Dispatcher* is aware of both the protocol and system composition.

In fact, because *Proxies* tend to be configurable (on startup or through their APIs), there is no need to modify the code of a *Proxy* each time something changes in the underlying system.

### Applicability

*Proxy* <ins>helps</ins> with:

- *Multi-component systems.* Having multiple types and/or instances of services means that a client needs to know the components’ addresses to access them. A *Proxy* encapsulates that knowledge and may also provide other common functionality as an extra benefit.
- *Dynamic scaling or sharding.* The *Proxy* both knows the system’s structure (the address of each instance of a service) and delivers user requests, thus it is the place to implement *sharding* (when a service instance is [[wiki/concepts/source/basic-metapatterns/shards|dedicated to a subset of users]]) or *load balancing* (when any service instance can [[wiki/concepts/source/basic-metapatterns/shards|serve any user]]) and even manage the size of the *Pool* of service instances.
- *Multiple client protocols*. When the *Proxy* is the endpoint for the system’s users it may translate multiple external (user-facing) protocols into a unified internal representation. See also [*Backends for Frontends*](<Backends for Frontends (BFF)>).
- *System security.* Though a *Proxy* does not make a system more secure, it takes away the burden of security considerations from the services which implement the business logic, improving the separation of concerns and making the system components more simple and stupid. An off-the-shelf *Proxy* may be less vulnerable compared to in-house services (but don’t disregard [security through obscurity](https://en.wikipedia.org/wiki/Security_through_obscurity)!).


*Proxy* <ins>hurts</ins>:

- *Critical real-time paths.* It adds an extra hop in request processing, increasing latency for thoroughly optimized use cases. Such requests may need to bypass *Proxies*.


### Relations


![A proxy for a monolith, shards, layers, and services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Proxy.png)


*Proxy*:

- Extends [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] (forming *Layers*), [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], or [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Can be extended with another *Proxy* or merged with an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] into an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]].
- Can be a part of a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].
- At least one *Proxy* per [[wiki/concepts/source/basic-metapatterns/services|*service*]] is employed by [[wiki/concepts/source/extension-metapatterns/middleware|*Message Bus*]], [[wiki/concepts/source/extension-metapatterns/middleware|*Enterprise Service Bus*]], [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]], and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]].
- Is a special case (when there is a single kind of client) of [*Backends for Frontends*](<Backends for Frontends (BFF)>).


## Variants by transparency

A *Proxy* [may either fully isolate the system which it represents or merely help establish connections](https://community.f5.com/kb/technicalarticles/what-is-a-proxy/282718) between clients and servers. This resembles [[wiki/concepts/source/basic-metapatterns/layers|closed and open layers]] because a *Proxy* is a [[wiki/concepts/source/basic-metapatterns/layers|layer]] between a system and its clients.

### Full Proxy


![A full proxy mediates all messages between a client and a server.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Full%20Proxy.png)


A *Full Proxy* processes every message between the system and its clients. It completely isolates the system and may meddle with the protocols but it is resource-heavy and adds to latency. [*Adapters*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver) and [*Response Caches*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache) are always *Full Proxies*.

### Half-Proxy


![A half-proxy intercepts only the session establishment request and is transparent to the following in-session communication between the client and server.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Half%20Proxy.png)


A *Half-Proxy* intercepts, analyzes, and routes the session establishment request from a client but then goes out of the loop. It may still forward the subsequent messages without looking into their content or it may even help connect the client and server directly, which is known as [*direct server return*](https://www.haproxy.com/glossary/what-is-direct-server-return-dsr) *(DSR)*. This approach is faster and much less resource-hungry but is also less secure and less flexible than that of *Full Proxy*. A [*Firewall*](#firewall-api-rate-limiter-api-throttling), [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), or [*Reverse Proxy*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway) may act as a *Half-Proxy*. IP telephony servers often use *DSR*: the server helps call parties find each other and then establish direct media communication.

## Variants by placement

As a *Proxy* stands between a (sub)system and its client(s), we can imagine a few ways to deploy it and then generalize our observation to other kinds of system components:

### Separate deployment: Standalone


![A standalone proxy is placed between a client and a layer of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Proxy%20placement%20-%20Standalone.png)


We can deploy a *Proxy* as a separate system component. This has the downside of an extra network hop (higher latency) in the way of every client request to the system and back but that is unavoidable in the following cases:

- The *Proxy* uses a lot of system resources, thus it cannot be colocated with another component. This mostly affects [*Firewall*](#firewall-api-rate-limiter-api-throttling) and [*Cache*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache).
- The *Proxy* is stateful and deals with multiple services, which is true for a [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), [*Reverse Proxy*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway), or [*API Gateway*](#api-gateway).


### On the system side: Sidecar


![A sidecar is co-located with the services and translates from the client's protocol to the service's API.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Proxy%20placement%20-%20Sidecar.png)


We can often co-locate a *Proxy* with our system when the latter is not distributed. That avoids the extra network delay, traffic, and operational complexity and does not add any new hardware which can fail at the most untimely moments. Such a placement is called *Sidecar* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] (after the motorcycle add-on) and it is mostly applicable to [*Adapters*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver).

It should be noted that *Sidecar* – co-locating a generic component and business logic – is more of a DevOps approach than an architectural pattern, thus we can see it used in a variety of ways \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\]:

- As a *Proxy* between a component and its clients.
- As an extra [[wiki/concepts/source/basic-metapatterns/services|*service*]] that provides observability or configures the main service.
- As a [[wiki/concepts/source/basic-metapatterns/layers|*layer*]] containing general-purpose utilities.
- As an *Adapter* for [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].


![A proxy between a service and its client; one between a service and a middleware; an extension aside of a service; a utility layer below a service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Sidecars.png)


[[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] (the [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]) makes heavy use of *Sidecars* for co-locating any kind of generic code with every instance of a *Microservice*.

### On the client side: Ambassador


![An ambassador runs on the client side and translates the client's protocol into the one in use with the service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Proxy%20placement%20-%20Ambassador.png)


Finally, a *Proxy* may be co-located with a component’s clients, making it an *Ambassador*  \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\], which is good for:

- Low-latency systems with [[wiki/concepts/source/basic-metapatterns/shards|stateful *shards*]] – each client should access the shard that has their data, which only the *Proxy* knows how to choose.
- [*Adapters*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver) that help client applications use an optimized or secure protocol.


Notably, a [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugin*]] may act as an *Ambassador* for its origin subsystem. It makes local decisions in some scenarios while others cause it to communicate with the service it represents. See [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugin*]].


![An ambassador plugin is a part of one service hosted inside another service. When called, it may consult its origin service or make independent decisions.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Ambassador%20Plugin.png)


## Examples

*Proxies* are ubiquitous in backend systems as using one or several of them frees the underlying code from the need to provide boilerplate non-business-logic functionality. It is common to have several kinds of *Proxies* deployed sequentially (e.g. [*API Gateways*](#api-gateway) behind [*Load Balancers*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler) behind a [*Firewall*](#firewall-api-rate-limiter-api-throttling)) with many of them [[wiki/concepts/source/basic-metapatterns/shards|*pooled*]] to improve performance and stability. It is also possible to employ multiple kinds of *Proxies*, each serving its own kind of client, in parallel, resulting in [*Backends for Frontends*](<Backends for Frontends (BFF)>).

As *Proxies* are used for many purposes, there are a variety of their specializations and names. Below is a very rough categorization, complicated by the fact that real-world *Proxies* often implement several categories at once:

> For example, NGINX claims to be: an HTTP web server, [*Reverse Proxy*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway), content [*Cache*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache), [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), TCP/UDP *Proxy* server, and mail *Proxy* server – all at once.

- A [*Firewall*](#firewall-api-rate-limiter-api-throttling) defends a system from attacks.
- A [*Response Cache*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache) reuses a system’s responses to reduce load on the system.
- A [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler) evenly distributes requests over several instances of a service.
- A [*Reverse Proxy*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway) dispatches requests that come through a single entry point to several internal services.
- An [*Adapter*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver) translates between a pair of protocols or interfaces.
- An [*API Gateway*](#api-gateway) parses a client protocol, interprets compound requests, and forwards the subrequests to multiple internal services.
- A [*User Interface*](#user-interface-presentation-layer-separated-presentation-command-line-interface-cli-graphical-user-interface-gui-frontend-human-machine-interface-hmi-man-machine-interface-mmi-operator-interface) represents a system in a way convenient for human interaction.


### Firewall, (API) Rate Limiter, API Throttling


![A firewall lets a request from a good client pass through while requests from a malicious client are blocked.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Firewall.png)


The *Firewall* is a component for white- and black-listing network traffic, mostly to protect against attacks. It is possible to use both generic hardware *Firewalls* on the external perimeter for brute force (D)DoS protection and more complex access rules at a second layer of software *Firewalls* to protect critical data and services from unauthorized access.

[*Rate Limiting*](https://testfully.io/blog/api-rate-limit/) makes sure that no single client uses too much of the system’s resources – it sets a limit on how many requests from a single source the system can process over a unit of time. Any requests over the limit are rejected.

*Throttling* differs from *Rate Limiting* in that over-the-limit requests are queued for later processing, effectively slowing down communication by overly active clients.

### Response Cache, Read-Through Cache, Write-Through Cache, Write-Behind Cache, Cache, Caching Layer, [[wiki/concepts/source/extension-metapatterns/shared-repository|Distributed Cache, Replicated Cache]]


![A cache proxies requests and remembers responses to shortcircuit the processing of future requests.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Cache.png)


If a system often receives identical requests, it is possible to remember its responses to most frequent of them and return the cached response without fully re-processing the request. The real thing is more complicated because users tend to change the data which the system stores, necessitating a variety of *cache refresh policies*. A *Response Cache* may be co-located with a [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler) or it may be \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] [[wiki/concepts/source/basic-metapatterns/shards|*sharded*]] (each *Cache* processes a unique subset of requests) and/or [[wiki/concepts/source/basic-metapatterns/shards|*replicated*]] (all the *Caches* are similar) and thus require a *Load Balancer* of its own.

This kind of component is called *Response Cache* because it stores the system’s responses to requests of its users or just *Cache* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] because it is the most common kind of a *Cache* in systems architecture.

If the cached subsystem is a database, we can discern between read and write requests:

- [*Read-Through Cache*](https://www.enjoyalgorithms.com/blog/read-through-caching-strategy) is when the *Cache* is updated on a miss for a read request but is transparent to or invalidated by write requests.
- [*Write-Through Cache*](https://www.enjoyalgorithms.com/blog/write-through-caching-strategy) is when the *Cache* is updated by write requests that pass through it.
- [*Write-Behind*](https://www.enjoyalgorithms.com/blog/write-behind-caching-pattern) is when the *Cache* aggregates multiple write requests to later send them to the database as a batch, saving bandwidth and possibly merging multiple updates of the same key.


It is possible to combine multiple servers into a virtual *Caching Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\]:

- In the simplest case, which does not require any additional instrumentation aside from a [*Load Balancer*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), the instances of the *Caches* are independent and may return stale results.
- In a *Distributed Cache*, driven by a [*Sharding Proxy*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), every server ([[wiki/concepts/source/basic-metapatterns/shards|*shard*]]) holds a subset of the cached data, thus allowing for caching datasets which don’t fit in a single computer’s memory.
- In a *Replicated Cache* the datasets of all the servers are identical and synchronized on any modification. This scales the cache’s throughput but requires a kind of synchronization engine, e.g. a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]].


### Load Balancer, Sharding Proxy, Cell Router, Messaging Grid, Scheduler


![A load balancer forwards a client's request to any idle instance of a stateless service. A sharding proxy forwards a client's request to the shard that contains the client's data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Load%20Balancer.png)


Here we have a hardware or software component which distributes user traffic among multiple [[wiki/concepts/source/basic-metapatterns/shards|instances]] of a service:

- A *Sharding Proxy* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] selects a [[wiki/concepts/source/basic-metapatterns/shards|*shard*]] based on specific data which is present in a request (OSI level 7 request routing) for a system where each shard owns a part of the system’s state, therefore only one (or a few for [[wiki/concepts/source/basic-metapatterns/shards|*replicated*]] *shards*) of the shards has the data required to process the client’s request.
- A [*Load Balancer*](https://en.wikipedia.org/wiki/Load_balancing_(computing)) \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] for a [[wiki/concepts/source/basic-metapatterns/shards|*Pool of stateless instances*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]], or a *Messaging Grid* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] of [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] evenly distributes the incoming traffic over identical request processors ([OSI level](https://en.wikipedia.org/wiki/OSI_model) 4 load balancing) to protect any instance of the underlying system from overload. In some cases it needs to be session-aware (process OSI level 7) to assure that all the requests from a client are forwarded to the same instance of the service \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\].
- It may forward read requests to [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Read-Only Replicas*]] of the data while write requests are sent to the *leader* database ([*CQRS*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs)-like behavior).
- A [*Cell Router*](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/cell-routing.html) chooses a data center which is the closest to the user’s location.


*Load Balancers* are very common in high-load backends. High-availability systems deploy multiple instances of a *Load Balancer* in parallel to remain functional if one of the *Load Balancers* fails. CPU-intensive applications (e.g. 3D games) often post asynchronous tasks for execution by *Thread Pools* under the supervision of a *Scheduler*. A similar pattern is found in OS kernels and *fiber* or *actor* frameworks where a limited set of CPU-affined threads is scheduled to run a much larger number of tasks.

### Dispatcher, Reverse Proxy, Ingress Controller, Edge Service, Microgateway


![A dispatcher exposes an interface which merges the interfaces of the services below the dispatcher.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Dispatcher.png)


A [*Reverse Proxy*, *Ingress Controller*](https://traefik.io/blog/reverse-proxy-vs-ingress-controller-vs-api-gateway/), [*Edge Service*](https://medium.com/knerd/api-infrastructure-at-knewton-whats-in-an-edge-service-51a3777aeb41), or [*Microgateway*](https://github.com/wso2/reference-architecture/blob/master/event-driven-api-architecture.md) is a router that stands between the Internet and the organization’s internal network. It allows clients to use a public address for the system without knowing how and where their requests are processed. It parses user requests and forwards them to an internal server based on the requests’ bodies. A *Reverse Proxy* can be extended with a [*firewall*](#firewall-api-rate-limiter-api-throttling), *SSL termination*, [*load balancing*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler), and [*caching*](#response-cache-read-through-cache-write-through-cache-write-behind-cache-cache-caching-layer-distributed-cache-replicated-cache) functionality. Examples include Nginx.

*Dispatcher* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] is a similar component for a single-process application. It serves a complex command line interface by receiving and preprocessing user commands only to forward each command to a module which knows how to handle it. The modules may register their commands with the *Dispatcher* at startup or there may be a static dispatch table in the code.

You could have noticed that *Dispatcher* or *Reverse Proxy* is quite similar to [*Load Balancer* or *Sharding Proxy*](#load-balancer-sharding-proxy-cell-router-messaging-grid-scheduler) – they differ mostly in what kind of system lies below them: [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]].

### Adapter, [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Anticorruption Layer, Abstraction Layer]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Open Host Service]], Gateway, Message Translator, API Service, Cell Gateway, (inexact) Backend for Frontend, Database Access Layer, Data Mapper, Repository, [[wiki/concepts/source/basic-metapatterns/services|Driver]]


![An adapter between a client and a service provider translates between their protocols.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Adapter.png)


An [*Adapter*](https://refactoring.guru/design-patterns/adapter) \[[wiki/concepts/source/appendices/books-referenced|[GoF]], [[wiki/concepts/source/appendices/books-referenced|DDS]]\] is a mostly stateless *Proxy* that translates between an internal and public protocol and API formats. It may often be co-located with a [*Reverse Proxy*](#dispatcher-reverse-proxy-ingress-controller-edge-service-microgateway). When it adapts messages, it is called a *Message Translator* \[[wiki/concepts/source/appendices/books-referenced|[EIP]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\].

*Adapters* are often found between two system components (in [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]) or between a component and [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] (in [[wiki/concepts/source/extension-metapatterns/middleware|*Enterprise Service Bus*]] and [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]]).

In \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], when one component (*consumer*) depends on another (*supplier*), there may be an *Adapter* in between to [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|decouple them]]. It is called *Anticorruption Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] (as it protects its host from changes in its dependencies) when owned by the *consumer*’s team or *Open Host Service* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] (for its readiness to serve any clients) if the *supplier* adds it to grant one or more stable interfaces (*Published Languages* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]).

A *Gateway* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] or an [*API Service*](https://backendless.com/what-is-api-as-a-service/) often implies an *Adapter* with extra functionality, like *Reverse Proxy*, authorization, and authentication. [*Cell Gateway*](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) is a *Gateway* for a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]].

When a *Gateway* translates a single public API method into several calls towards internal services, it becomes an [*API Gateway*](#api-gateway) \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] which is an aggregate of *Proxy* (protocol translation) and [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] (integration of the lower-level services).

An *Adapter* between an end-user client (web interface, mobile application, etc.) and the system’s API is often called [*Backend for Frontend*](<Backends for Frontends (BFF)>). It decouples the UI from the backend-owned system’s API, giving the teams behind both components the freedom to work more independently as changes in one component no longer directly affect the other.

Adapters between software and hardware components are called (*device*) *Drivers*.

There is also a whole bunch of *Abstraction Layers* that aim to protect the business logic from its environment, the idea which [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|is perfected]] by [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]:

- [*Hardware Abstraction Layer*](https://en.wikipedia.org/wiki/Hardware_abstraction) (*HAL*) hides details of hardware to make the code which controls it portable.
- [*Operating System Abstraction Layer*](https://en.wikipedia.org/wiki/Operating_system_abstraction_layer) (*OSAL*) or *Platform Abstraction Layer* (*PAL*) abstracts the OS to make the application cross-platform.
- [*Database Abstraction Layer*](https://en.wikipedia.org/wiki/Database_abstraction_layer) (*DBAL* or *DAL*), *Database Access Layer* \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] or *Data Mapper* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] attempts to help building database-agnostic applications by making all the databases look the same.
- [*Repository*](https://martinfowler.com/eaaCatalog/repository.html) \[[wiki/concepts/source/appendices/books-referenced|[PEAA]], [[wiki/concepts/source/appendices/books-referenced|DDD]]\] provides methods to access a record stored in a database as if it were an object in the application’s memory.


> An *Adapter* creates a [layer of indirection](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering) between your code and a library or service which it uses. If the external component’s interface changes, or you need to substitute a component with an incompatible implementation from another vendor, and your code accesses the component directly, you will have to make many changes throughout your code. However, if there is an *Adapter* in-between, your code depends only on the interface of the *Adapter*. And when the external component changes or is replaced, only the relatively small *Adapter*’s implementation needs to change while your main code is blessed with ignorance of what lies beyond the *Adapter*’s borders.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|API Gateway]]


![An API Gateway both translates from the client's to the system's protocol and calls services in parallel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/API%20Gateway.png)


*API Gateway* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] is a fusion of [*Gateway*](#adapter-anticorruption-layer-abstraction-layer-open-host-service-gateway-message-translator-api-service-cell-gateway-inexact-backend-for-frontend-database-access-layer-data-mapper-repository-driver) (*Proxy*) and [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Composer*]] ([[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]). The *Gateway* aspect encapsulates the external (public) protocol while the *API Compose*r translates the system’s high-level public API methods into multiple (usually parallel) calls to the APIs of internal components, collects the results, and conjoins them into a response.

*API Gateway* is [[wiki/concepts/source/extension-metapatterns/orchestrator|discussed in more detail]] under *Orchestrator*.

### User Interface, Presentation Layer, [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Separated Presentation]], Command Line Interface (CLI), Graphical User Interface (GUI), Frontend, Human-Machine Interface (HMI), Man-Machine Interface (MMI), Operator Interface


![A user interface stands between a human and software. It receives mouse input and produces output on a display.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/User%20Interface.png)


An *Adapter* between a human and a computer system is called a [[wiki/concepts/source/basic-metapatterns/layers|*User Interface*]] (*UI*) or *Presentation Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. Though a *UI* mainly translates user actions into commands to the underlying system and presents the results which the system returns and other information supposedly important to the user, it may also include [[wiki/concepts/source/basic-metapatterns/layers|*integration logic*]] (use cases) which are occasionally tightly coupled to the visual behavior. *UI* comes in several flavors:

- *Command Line Interface* (*CLI*) is text-based and sequential – it executes one command at a time. It’s the simplest kind of *UI*.
- *Graphical User Interface* (*GUI*) is built around graphical representation of information and controls. It may rely on the windowing system of the underlying OS, a third-party framework, or build something unique, which takes place in games.
- *Frontend* is an [*Ambassador*](#on-the-client-side-ambassador) executed by a client’s browser on the system’s behalf.
- [*Human-Machine Interface*](https://en.wikipedia.org/wiki/User_interface#Terminology) (*HMI*) or *Man-Machine Interface* (*MMI*) is usually used for human interaction with an embedded system. Sometimes this term may include both input / output hardware (e.g. mouse and display, or touch screen) and software that operates it.
- [*Operator Interface*](https://en.wikipedia.org/wiki/User_interface#Terminology) is an *HMI* that grants its user access to a system of several embedded devices.


[*Separated Presentation*](https://martinfowler.com/eaaDev/SeparatedPresentation.html) is, basically, another name for *User Interface* except that this pattern focuses on dispensability of any implementation of a *UI*: the same system can be driven by a *CLI*, *GUI*, or *Frontend* without noticing any difference. Many variants of *Separated Presentation* are known as [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVP*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]] families of patterns discussed under [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]].

## [[wiki/concepts/source/appendices/evolutions-of-a-proxy|Evolutions]]

It usually makes little sense to get rid of a *Proxy* once it has been integrated into a system. The only real drawback to using a *Proxy* is a slight increase in latency for user requests which may be mitigated through the creation of [bypass channels](#half-proxy) between the clients and a service which needs low latency. The other drawback of the pattern, the *Proxy* being a single point of failure, is countered by deploying multiple instances of the *Proxy*.

As *Proxies* are usually third-party products, there is not much that [[wiki/concepts/source/appendices/evolutions-of-a-proxy|we can change about them]]:

- We can add another kind of a *Proxy* on top of an existing one.


![A proxy is added on top of an existing proxy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Proxy%20add%20Proxy.png)


- We can use a stack of *Proxies* per client, making [*Backends for Frontends*](<Backends for Frontends (BFF)>).


![A proxy is subdivided into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Proxy%20to%20Backends%20for%20Frontends.png)


## Summary

 A *Proxy* represents your system to its clients and takes care of some aspects of the communication. It is common to see multiple *Proxies* deployed sequentially as they are often stackable.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/sandwich.md ===== -->

---
title: "Sandwich"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Sandwich.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Sandwich
source_license_note: "See namespace README; preserve attribution and source links."
---

# Sandwich

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Sandwich.md`.


![A diagram for Sandwich Architecture, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Sandwich.png)


*Follow the line of least resistance.* Divide where it is loosely coupled.

<ins>Structure:</ins> A layer of domain-level services between shared integration and data layers.

<ins>Type:</ins> System topology, implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Supports medium to large codebases | Aggressive optimization is impossible |
| Multiple specialized development teams | Low fault tolerance |
| There are many ways to evolve the system |  |

<ins>References:</ins> None I know of.

A *Sandwich* is a (sub)system midway between [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. It emerges when a *layered* component outgrows its architecture and its middle ([[wiki/concepts/source/basic-metapatterns/layers|*domain*]]) layer – which tends to be both the largest and least cohesive – is divided into subdomains while the [[wiki/concepts/source/basic-metapatterns/layers|*application*]] and [[wiki/concepts/source/basic-metapatterns/layers|*data*]] layers remain intact. Another, less common, origin is a (sub)system of [[wiki/concepts/source/basic-metapatterns/services|*(Micro)Services*]] which becomes so tightly coupled that it needs to be partially merged.

A *Sandwich*, named after the shape of its diagram, includes the following components:

- A shared [[wiki/concepts/source/introduction/system-topologies|*managing layer*]] which receives client requests and dispatches them to the underlying *domain-level services*. Though this layer may either implement [[wiki/concepts/source/basic-metapatterns/layers|*use cases*]] as an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], forward each client action to a matching service as a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], or do both as an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]], it remains the component that ties the entire system together.
- [[wiki/concepts/source/basic-metapatterns/layers|*Domain-level*]] [[wiki/concepts/source/basic-metapatterns/services|*services*]] (if distributed) or [[wiki/concepts/source/basic-metapatterns/services|*modules*]] (otherwise) that implement the bulk of the system’s business logic and thus contain most of the system’s code.
- A shared [[wiki/concepts/source/basic-metapatterns/layers|*data layer*]] which the upper layer’s services operate on. It may be a persistent database or an in-memory application state.


*Sandwiches* often occur naturally without being recognized as a distinct architecture. In fact, I had to make up a name for this [[wiki/concepts/source/introduction/system-topologies|system topology]].

### Performance

As [[wiki/concepts/source/basic-metapatterns/layers|*domain*-level]] services rarely interact among themselves, the performance of a *Sandwich* is similar to that of [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] with the same kind of deployment (components of a *Sandwich* may or may not be colocated).


![Control and data flow is identical in Sandwich and Layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Sandwich.png)


### Dependencies

The *Sandwich*’s [[wiki/concepts/source/basic-metapatterns/layers|*integration* layer]] depends on every service inside the *Sandwich*. The services themselves depend on the [[wiki/concepts/source/basic-metapatterns/layers|*data* layer]].


![The integration layer depends on every service. Every service depends on the data layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Sandwich.png)


Having two shared layers provides three options for invoking the [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] components:

- The most common approach is [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] by the integration layer.
- [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|Data-centric]] domains may rely on [[wiki/concepts/source/foundations-of-software-architecture/shared-data|*data change notifications*]].
- [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreography*]] via publish/subscribe is rare because it is inferior to the other two options:
  - It is not enough to decouple the subdomain services which are already bound together by the shared data layer.
  - *Publish/subscribe* requires additional libraries and setup, while the data store, which often supports notifications, is already in place.
  - Furthermore, *orchestration* allows for much better control over use case logic and error handling than *choreography*.


### Applicability

*Sandwich* <ins>fits</ins>:

- *Medium-sized projects with complex domain logic.* The subdivision of the *domain* layer keeps the code complexity under control and supports development by multiple teams with little increase of operational burden.
- *Rapid development of ordinary systems.* If you don’t face any challenging forces, you should keep your architecture [simple and stupid](https://en.wikipedia.org/wiki/KISS_principle) but still flexible – which is the pragmatic *Sandwich*. You will be able to evolve it in the future if needed.
- *Data-centric domains.* This architecture allows all the services to work on the same dataset, each reading and writing the parts that are involved in its business logic.


*Sandwich* <ins>does not help</ins>:

- *Projects with a large number of use cases.* As the [[wiki/concepts/source/basic-metapatterns/layers|*integration* layer]] remains monolithic, it still can grow out of control, requiring the system to transform into [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]].
- *Huge systems.* Both the [[wiki/concepts/source/basic-metapatterns/layers|*integration*]] and [[wiki/concepts/source/basic-metapatterns/layers|*data*]] layers are cumbersome in that case.
- *Demanding forces.* The *Sandwich* architecture is a jack of all trades, master of none. In general, it is an average backend, and is neither highly elastic, flexible, nor low latency.


### Relations


![Transitions between Layers, a Sandwich, a Service-Based Architecture, and Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Sandwich.png)


*Sandwich*:

- Is a system in transition between [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Is [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] with a middle layer split into services or [[wiki/concepts/source/basic-metapatterns/services|*Services*]] sandwiched between layers.
- May implement a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or *service*.
- Often provides the internals of a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]].
- Includes a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and/or [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]].


> A [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] encapsulates several services so that they can be treated as a single entity with the goal of reducing the number of top-level system components. Typically, interdependent and closely communicating services are clustered into a single *Cell*, predisposing the *Cell*’s internals for further merging to reduce the communication overhead and the amount of boilerplate code. Such a scenario often results in a *Sandwich* trapped inside a *Cell*.

## Examples

Though most real-world *Sandwiches* stay beneath the radar as non-standard architectures, there are two well-documented and highly specialized occurrences of this topology in [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|data-centric]] domains and a few less stringent generic cases:

- [*Blackboard System*](#blackboard-system) describes how specialized algorithms cooperate to try solving a non-deterministic problem.
- [*Space-Based Architecture*](#space-based-architecture) runs multiple instances of services co-located with a distributed in-memory data store.
- [*Service-Based Architecture*](#service-based-architecture) comprises large services that often share a database.
- [*Nanoservices*](#nanoservices) is a system of functions deployed to a cloud.
- [*Command Query Responsibility Segregation*](#command-query-responsibility-segregation-cqrs) uses different models for read-write and read-only scenarios.
- [*Replicated Load-Balanced Services*](#inexact-replicated-load-balanced-services-lambdas) are identical instances of a stateless service that access a shared database.


### [[wiki/concepts/source/extension-metapatterns/shared-repository|Blackboard]] System


![A Blackboard System includes a control which orchestrates knowledge sources which access a blackboard with shared data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Blackboard.png)


Some domains are [complex and ill-structured](http://i.stanford.edu/pub/cstr/reports/cs/tr/86/1123/CS-TR-86-1123.pdf): there is only a vague understanding of how the inputs relate to outputs, therefore you cannot write a single algorithm to solve it. If you are lucky to have a huge labeled dataset, you can attempt training a neural network. If there are not so many examples, you are in trouble.

[*Blackboard Systems*](https://en.wikipedia.org/wiki/Blackboard_system) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] were invented half a century ago to tackle non-deterministic problems: speech or image recognition, X-ray crystallography of proteins, or even tracking enemy submarines or stealth aircraft. In these cases inputs are noisy and scarce and outputs can vary indefinitely, therefore one must go through trial and error proposing, refining, and comparing many possible solutions to arrive at something plausible.

The system consists of:

- A [[wiki/concepts/source/extension-metapatterns/shared-repository|*blackboard*]] – a [[wiki/concepts/source/extension-metapatterns/shared-repository|*shared data store*]] that contains all the current knowledge about the problem, namely inputs and hypotheses. It is subdivided into abstraction levels which range from the original inputs through multiple intermediate representations to the output data structure. Each level usually contains multiple solution attempts.
- *Knowledge sources* – independent, specialized components that process data from a lower level to create a higher-level hypothesis. For example, in voice recognition, a knowledge source may read a sound wave and write a letter which that wave encodes. Another knowledge source may read letters and output English words, while another one tries to find French words. And the final one collects words into sentences.
- A [[wiki/concepts/source/extension-metapatterns/orchestrator|*control*]] – a [[wiki/concepts/source/extension-metapatterns/proxy|*scheduler*]] that assigns processor time to knowledge sources. It balances the quality and speed of the solution attempts based on the current progress and remaining time.


This architecture makes best use of every system layer:

- The *control* is required to prune the exponential growth of possible solutions because there are not enough system resources to check all of them.
- The independent *knowledge sources* are easy to add or remove, allowing the developers to try various algorithms without touching other components.
- The *blackboard* enables the cooperation of knowledge sources, each of which is limited to a small part of the overall solution.


### [[wiki/concepts/source/implementation-metapatterns/mesh|Space-Based Architecture]]


![Space-Based Architecture comprises the following layers: a messaging grid, a processing grid, scaled processing units, a data grid, a deployment manager, and a persistent database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Multifunctional%20-%20Space-Based%20Architecture.png)


*Space-Based Architecture* \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] is an extremely elastic alternative to [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] which works well for [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|data-centric]] domains. Each *processing unit* – a [[wiki/concepts/source/basic-metapatterns/layers|domain-level]] service – is co-located with an in-memory replica of the entire system’s data, which makes both data access and creation of new instances of *processing units* blazingly fast. As is common for *Sandwiches*, *processing units* can be [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrated*]] by the [[wiki/concepts/source/extension-metapatterns/orchestrator|*processing grid*]] or they can [[wiki/concepts/source/foundations-of-software-architecture/shared-data|*subscribe to changes*]] in the shared [[wiki/concepts/source/extension-metapatterns/shared-repository|*data grid*]], this architecture being flexible enough to allow for choosing a [[wiki/concepts/source/foundations-of-software-architecture/arranging-communication|communication paradigm]] on per request basis.

Aside from *processing units*, which contain the main business logic, *Space-Based Architecture* involves:

- A *messaging grid* which is a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] (combination of [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]], [[wiki/concepts/source/extension-metapatterns/proxy|*Dispatcher*]], and [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]]) that receives, preprocesses, and persists client requests. Simple requests are forwarded to the least loaded *processing unit* while anything complicated goes to the *processing grid*.
- A [[wiki/concepts/source/extension-metapatterns/orchestrator|*processing grid*]] is an optional [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] which manages multi-step workflows for complicated requests that involve branching and error handling.
- A [[wiki/concepts/source/extension-metapatterns/shared-repository|*data grid*]] is a distributed in-memory data store. It is built of caching [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] nodes which are co-located with instances of *processing units*, making the data store access extremely fast. However, the speed and scalability is paid for with stability – any data in memory is prone to disappearing. Therefore the *data grid* backs up all the changes to a slower *persistent database*.
- A [[wiki/concepts/source/extension-metapatterns/middleware|*deployment manager*]] is a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] that creates and destroys instances of *processing units* (which are paired to the nodes of the *data grid*), just like [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]] does for [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] (which are paired to [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]]). However, in contrast to *Service Mesh*, it does not provide a messaging infrastructure because *processing units* communicate by sharing data via the *data grid*, not by sending messages.


As *Space-Based Architecture* runs every component in a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]], it avoids the fault tolerance and database performance drawbacks inherent to *Sandwich*, trading them for possibility of write conflicts when multiple clients cause changes to the same piece of data simultaneously.

### [[wiki/concepts/source/basic-metapatterns/services|Service-Based Architecture]]


![A Sandwich-like topology with user interface, a layer of domain services, and a shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Service-Based%20Architecture.png)


*Service-Based Architecture* \[[wiki/concepts/source/appendices/books-referenced|[FSA]] [[wiki/concepts/source/analytics/ambiguous-patterns|but not]] [[wiki/concepts/source/appendices/books-referenced|DEDS]]\] is the most pragmatic and loosely defined of topologies based on *Services* (hence the name). In a basic *Service-Based Architecture* the [[wiki/concepts/source/basic-metapatterns/services|*subdomain services*]] are integrated by a [[wiki/concepts/source/extension-metapatterns/proxy|*User Interface*]] layer, usually a *Frontend*, and there is a single [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]]. However, as there are no written rules for *Service-Based Architecture*, multiple databases or finer-grained *GUI*s may be used for programmers’ convenience, disintegrating the *Sandwich* topology for the sake of less coupled [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Service*s]].


![A Sandwich-like topology with shared user interface and database is gradually transformed into layered services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Service-Based%20to%20Layered%20Services.png)


### [[wiki/concepts/source/basic-metapatterns/services|Nanoservices]]


![Nanoservices form a Sandwich-shaped architecture. The upper layer is an API Gateway for an orchestrated system or a gateway for pipelined Nanoservices. The lower layer is a shared datastore.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Nanoservices.png)


*Nanoservices* is another loosely defined architecture built of single-purpose *functions* ([FaaS](https://en.wikipedia.org/wiki/Function_as_a_service)) individually deployed to the cloud. It is highly elastic and relies on a cloud provider for operational support, saving costs for small businesses.

As a single *nanoservice* is too small to implement a use case, there must be an [[wiki/concepts/source/basic-metapatterns/layers|*integration layer*]] that receives client or user requests, runs several *nasoservices* to execute it, and returns a response. The integration layer may be a [[wiki/concepts/source/extension-metapatterns/proxy|*Frontend*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]], an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Event Mediator*]] for [[wiki/concepts/source/basic-metapatterns/services|*orchestrated Nanoservices*]], or an ordinary [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] that initiates a [[wiki/concepts/source/basic-metapatterns/pipeline|*pipelined*]] scenario and receives its response from a [[wiki/concepts/source/basic-metapatterns/pipeline|*choreographed* system]].

As each *nanoservice* is stateless, for the system to be stateful there must be a *data store*. And as each *nanoservice* can do only one thing (either read, write, or search), the *data store* must be [[wiki/concepts/source/extension-metapatterns/shared-repository|*shared*]] to be of any use.

Please note how a fine-grained decomposition of business logic necessarily results in a *Sandwich* architecture.

### [[wiki/concepts/source/fragmented-metapatterns/layered-services|Command Query Responsibility Segregation]] (CQRS)


![A large read and smaller write models between a user interface and database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/CQRS.png)


[*Command Query Responsibility Segregation*](https://martinfowler.com/bliki/CQRS.html) (*CQRS*) is a principle which calls for separation of components that process *commands* (requests that change the system’s data) and *queries* (requests that analyze the data). The subdivision necessarily happens at the [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] (*model*) level, resulting in separate [*Write Model*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) ([*Command Model*](https://martinfowler.com/bliki/CQRS.html)) and [*Read Model*](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) ([*Query Model*](https://martinfowler.com/bliki/CQRS.html), [*Thin Read Layer*](https://cqrs.wordpress.com/wp-content/uploads/2010/11/cqrs_documents.pdf)). In the simplest case the [[wiki/concepts/source/basic-metapatterns/layers|*data* layer]] is kept monolithic, as shown in the diagram above.

*CQRS* helps decouple the logic-heavy object-oriented code which maintains data consistency and business constraints during editing data records from the search and aggregation code that needs direct database access to run complex SQL queries. If that is not enough, it is possible to trade complexity for performance by employing specialized databases: [*OLTP*](https://en.wikipedia.org/wiki/Online_transaction_processing) for use with the *Write Model* and [*OLAP*](https://en.wikipedia.org/wiki/Online_analytical_processing) for the *Read Model*, as described in the [[wiki/concepts/source/fragmented-metapatterns/layered-services|corresponding section of the *Layered Services* chapter]]:


![The single database of a Sandwich-like CQRS with a shared database is subdivided into OLTP and OLAP databases, forming Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/CQRS%20to%20Layered%20Services.png)


### (inexact) [[wiki/concepts/source/basic-metapatterns/shards|Replicated Load-Balanced Services]], Lambdas


![A load balancer connects a new client to a free instance of a stateless backend that accesses a database shared among all the backend instances.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/1/Shards%20-%20Pool.png)


Replicating a system’s [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] [[wiki/concepts/source/basic-metapatterns/layers|*tier*]] along the [[wiki/concepts/source/introduction/metapatterns|*sharding* axis]] also results in a *Sandwich*-like [[wiki/concepts/source/introduction/system-topologies|topology]], albeit with altered properties: while the original *Sandwich*’s subdivision of the codebase along the [[wiki/concepts/source/introduction/metapatterns|*subdomain* axis]] allows for multiteam development and easy integration of new functionality, replication along the *sharding* axis only makes it simple to add or remove instances of the middle tier as the system load changes.

*Replicated Load-Balanced Services* \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\] is the general name for running multiple instances of a stateless service that [[wiki/concepts/source/extension-metapatterns/shared-repository|*share a database*]] and run under a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]]. [*Lambdas*](https://jesseduffield.com/Notes-On-Lambda/) is a synonym for a similar setup from cloud computing providers (see also [*Nanoservices*](#nanoservices)).

## Evolutions

The components of a *Sandwich* provide plenty of ways to alter the system, with unique evolutions detailed in [[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Appendix E]]:

### [[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Primary evolutions]]

[[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Some evolutions]] involve the system’s [[wiki/concepts/source/basic-metapatterns/layers|domain logic]] or its topology:

- The *domain-level services* are independent enough to be easily added or removed.


![One of the domain-level services is removed and another one is added.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20add%20remove%20Service.png)


- In most cases they share technologies, allowing for splitting or merging of the services.


![One domain-level service is split in half while two other services are merged together.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20split%20merge%20Services.png)


- If the services are found to be strongly coupled, they can be merged into a monolithic layer, likely to be subdivided in a better way later on.


![The entire domain layer is merged, resulting in Layers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20to%20Layers.png)


- Alternatively, the subdomains can be further decoupled.


![The integration and data layers are divided into subdomains, producing Three-Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Sandwich%20to%20Layered%20Services.png)


### [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|Evolutions of the data layer]]

If the [[wiki/concepts/source/basic-metapatterns/layers|*data* layer]] becomes a performance bottleneck, it can be [[wiki/concepts/source/extension-metapatterns/shared-repository|split as a *Shared Repository*]]:

- [[wiki/concepts/source/basic-metapatterns/shards|*Shard*]] the database if its records are mutually independent or [[wiki/concepts/source/basic-metapatterns/shards|*replicate*]] it if it is the read traffic which overloads the system.
- Apply [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] if elasticity is more important than consistency.
- Divide the data into databases, private to the domain-level services, thus transforming the system into [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated*]] [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Deploy specialized data stores ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).


### [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|Evolutions of the application layer]]

If the [[wiki/concepts/source/basic-metapatterns/layers|*integration* layer]] contains use cases and becomes cumbersome, it should be subdivided following the [[wiki/concepts/source/extension-metapatterns/orchestrator|evolutions of *Orchestrator*]]:

- Into [[wiki/concepts/source/basic-metapatterns/services|*Services*]] if the use cases cluster around subdomains.
- Into [*Backends for Frontends*](<Backends for Frontends (BFF)>) if the system serves several kinds of clients.
- Into [[wiki/concepts/source/extension-metapatterns/orchestrator|*Layers*]] if some use cases are simple while others are complicated.
- Into a [[wiki/concepts/source/extension-metapatterns/orchestrator|*Hierarchy*]] if the use cases include both generic and specialized logic.


## Summary

*Sandwich* is a pragmatic architecture midway between [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. It combines simplicity and flexibility, avoiding unnecessary effort for the present while retaining many paths to evolve in the future.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/extension-metapatterns/shared-repository.md ===== -->

---
title: "Shared Repository"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Extension metapatterns/Shared Repository.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Extension%20metapatterns/Shared%20Repository
source_license_note: "See namespace README; preserve attribution and source links."
---

# Shared Repository

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Extension metapatterns/Shared Repository.md`.


![A diagram for Services with a shared repository, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Shared%20Repository.png)


*Knowledge itself is power.* Sharing data is simple (& stupid).

<ins>Known as:</ins> Shared Repository \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\].

<ins>Structure:</ins> A layer of data shared among higher-level components.

<ins>Type:</ins> Extension for [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]].

| *Benefits* | *Drawbacks* |
| --- | --- |
| Supports domains with coupled data | A single point of failure |
| Implements data access and synchronization (consistency) concerns | All the services depend on the schema of the shared data |
| Helps saving on hardware, licenses, traffic, and administration | A single data store technology may not fit the needs of all the services equally well |
| Quick start for a project | Limits scalability |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] is all about databases; \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] has chapters on *Service-Based Architecture* and *Space-Based Architecture*; \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] deals with *Shared Event Store.*

A *Shared Repository* builds communication in the system around its data, which is natural for [[wiki/concepts/source/foundations-of-software-architecture/shared-data|data-centric domains]] and multiple [[wiki/concepts/source/basic-metapatterns/shards|instances of stateless services]] and may often simplify the development of a system of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] which need to exchange data. It covers the following concerns:

- Storage of the entire domain data.
- Keeping the data self-consistent by providing atomic transactions for use by the application code.
- Communication between the services (if the repository supports notifications on data change).
- Data aggregation and analytics (if the database engine supports complex queries).


The drawbacks are extensive coupling (it’s hard to alter a thing which is used in many places throughout the entire system) and limited scalability (even distributed databases struggle against distributed locks and the need to keep their nodes’ data in sync).

### Performance

A shared database with consistency guarantees ([ACID](https://en.wikipedia.org/wiki/ACID)) is likely to lower the total resource consumption compared to one database per service (as the services don’t need to implement and keep updated [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS views*]] of other services’ data) but it increases latency and it may become the system’s performance bottleneck. Moreover, by using a shared database services lose the ability to choose the database technologies which best fit their tasks and data.

Another danger lies with locking records inside the database. Different services may use different order of tables in transactions, hitting deadlocks in the database engine which show up as transaction timeouts.

Non-transactional distributed data stores may be very fast when colocated with the services (see [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]]) but the resource consumption becomes very high because of the associated data duplication (as every instance of each service gets a copy of the entire dataset) and simultaneous writes may corrupt the data (cause inconsistencies or merge conflicts).

### Dependencies

Normally, every service depends on the repository. If the repository does not provide notifications on changes to the data, the services may need to communicate directly, in which case they will also depend on each other through [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]] or *mutual* [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]].


![If the shared repository supports notifications, services depend only on the repository. Otherwise each service also depends on its event sources.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/SharedRepository-1.png)


Any dependencies on the repository technology and the data schema are dangerous for long-running projects as both of them may need to change sooner or later. Decoupling the code from the data storage is done with [yet another layer of indirection](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering) which is called a [[wiki/concepts/source/extension-metapatterns/proxy|*Database Abstraction Layer*]] (*DAL*), a *Database Access Layer* \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\], or a *Data Mapper* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\]. The DAL, which translates between the data schema and database’s API on one side and the business logic’s SPI on the other side, may reside inside each service or wrap the database:


![Each service may have a private Database Abstraction Layer, or there may be one shared Database Abstraction Layer colocated with the shared repository.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/SharedRepository-2.png)


Still, the DAL does not remove shared dependencies and only adds some flexibility. It seems that there is a peculiar kind of coupling through shared components: if one of the services needs to change the database schema or technology to better suit its needs, it is unable to do so because other components rely on (and exploit) the old schema and technology. Even deploying a second database, private to the service, is often not an option, as there is no convenient way to keep the databases in sync.

### Applicability

*Shared Repository* is <ins>good</ins> for:

- *Data-centric domains.* If most of your domain’s data is used in every subdomain, keeping any part of it private to a single service will be a pain in the system design. Examples include a [[wiki/concepts/source/foundations-of-software-architecture/shared-data|ticket reservation system]] and even the minesweeper game.
- *A scalable service.* When you run several [[wiki/concepts/source/basic-metapatterns/shards|instances]] of a service, like in [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]], the instances are likely to be identical and stateless, with the service’s data pushed out to a database shared among the instances.
- *Huge datasets*. Sometimes you may need to deal with a lot of data. It is unwise (meaning expensive) to stream and replicate it between your services just for the sake of ensuring their isolation. Share it instead. If the data does not fit in an ordinary database, some kind of [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] (which [was invented to this end](https://en.wikipedia.org/wiki/Space-based_architecture#History)) may become your friend.
- *Quick simple projects.* Don’t over-engineer if the project won’t live long enough to benefit from its flexibility. You may also save a buck or two on the storage.


*Shared Repository* is <ins>bad</ins> for:

- *Quickly evolving, complex projects.* As everything changes, you just cannot devise a stable schema, while every change of the database schema breaks all the services.
- *Varied forces and algorithms*. Different services may require different kinds of data stores to work efficiently.
- *Big data with random writes*. Your data does not fit on a single server. If you want to avoid write conflicts, you must keep all the database nodes synchronized, which kills performance. If you let them all broadcast their changes asynchronously, you get collisions. You may want to first decouple and [[wiki/concepts/source/basic-metapatterns/shards|*shard*]] the data as much as possible, and then turn your attention to esoteric data stores, specialized caches, and even tailor-made [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to get out of the trouble.


### Relations


![A shared repository for Services, Shards, and Service-Oriented Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Shared%20Repository.png)


*Shared Repository*:

- Extends [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>), [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], or occasionally [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].
- Is a part of a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]], [[wiki/concepts/source/extension-metapatterns/middleware|persistent *Middleware*]], or [[wiki/concepts/source/basic-metapatterns/pipeline|*Nanoservices*]].
- Is [closely related](https://itnext.io/a-practical-guide-to-modular-monoliths-with-net-59da23c01137) to [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].
- May be implemented by a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]].


## Examples

*Shared Repository* is a sibling of [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]. While a *Middleware* assists direct communication between services (*shared-nothing* messaging), a *Shared Repository* grants them indirect communication through access to an external state (similar to *shared memory*) which usually stores all the data for the domain.

A *Shared Repository* may provide a generic interface (e.g. SQL) or a custom API (with a domain-aware [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] / [*ORM*](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping) for the database). The *repository* itself can be anything ranging from a trivial OS file system or a memory block accessible from all the components to an ordinary database to a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based, distributed [*tuple space*](https://en.wikipedia.org/wiki/Tuple_space):

- A [*Shared Database*](#shared-database-integration-database-data-domain-database-of-service-based-architecture), [*Shared File System*](#shared-file-system), and [*Shared Memory*](#shared-memory) are just what you think they are.
- A [*Blackboard*](#blackboard) provides a shared solution space for several algorithms to cooperate on a task.
- A [*Data Grid*](#data-grid-of-space-based-architecture-sba-replicated-cache-distributed-cache) is a distributed in-memory data store that replicates data among many instances of multiple services.
- A [*Persistent Event Log*](#persistent-event-log-shared-event-store) stores every message sent between services for a possible future use.
- [*Stamp Coupling*](#inexact-stamp-coupling) is an approach for collecting data spread over the components of a *Pipeline*.


### Shared Database, Integration Database, Data Domain, Database of [[wiki/concepts/source/extension-metapatterns/sandwich|Service-Based Architecture]]


![Several services access a shared database and optionally communicate with each other directly.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Shared%20Database.png)


*Shared Database* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\], [*Integration Database*](https://martinfowler.com/bliki/IntegrationDatabase.html)*,* or *Data Domain* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] is a single database available to several [[wiki/concepts/source/basic-metapatterns/services|services]]. The services may subscribe to data change triggers in the database itself or notify each other directly about domain events. The latter is often the case with [[wiki/concepts/source/basic-metapatterns/services|*Service-Based Architecture*]] which consists of large services dedicated to subdomains.

### Shared File System


![An algorithm processes a batch of input files and writes output files. Its output becomes an input for another algorithm. The algorithms make a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Shared%20files.png)


As a file system is a kind of shared dictionary, writing and reading files can be used to transfer data between applications. A [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|data processing]] [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] which stores intermediate results in files benefits from the ability to restart its calculation from the last successful step because files are persistent \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\].

### Shared Memory


![Areas of shared memory (ring buffers) between two processes make a pair of event channels.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Shared%20memory.png)


Several actors (processes, modules, device drivers) communicate through one or more mutually accessible data structures (arrays, trees, or dictionaries). Accessing a shared object may require some kind of synchronization (e.g. taking a *mutex*) or employ [*atomic variables*](https://codescoddler.medium.com/concurrency-made-simple-the-role-of-atomic-variables-8327b9b35023). Notwithstanding that communication via *shared memory* is the archenemy of ([*shared-nothing*](https://www.scylladb.com/glossary/shared-nothing-architecture/)) messaging it is actually used to implement messaging: high-load multi-process systems (web browsers and high-frequency trading) rely on shared memory *mailboxes* for messaging between their [[wiki/concepts/source/basic-metapatterns/services|constituent processes]].

### [[wiki/concepts/source/extension-metapatterns/sandwich|Blackboard]]


![A Blackboard System includes a control which orchestrates knowledge sources which access a blackboard with shared data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Blackboard.png)


[*Blackboard*](https://hillside.net/plop/plop97/Proceedings/lalanda.pdf) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] was used for non-deterministic calculations where several algorithms were concurring and collaborating to gradually build a solution from incomplete inputs. The *control* ([[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) component schedules the work of several *knowledge sources* ([[wiki/concepts/source/basic-metapatterns/services|*Services*]]) which encapsulate algorithms for processing the data stored in the *blackboard* (*Shared Repository*) named after the well-known collaborative tool used for a brainstorming session. This approach has mostly been superseded by convolutional neural networks.

Examples: several use cases are [mentioned on Wikipedia](https://en.wikipedia.org/wiki/Blackboard_system).

### Data Grid of [[wiki/concepts/source/extension-metapatterns/sandwich|Space-Based Architecture]] (SBA), [[wiki/concepts/source/extension-metapatterns/proxy|Replicated Cache, Distributed Cache]]


![A layer of scaled processing units each connected to a node of an in-memory database over a data replication engine which communicates with a persistent database through readers and writers.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Data%20Grid.png)


The [*Space-Based Architecture*](https://en.wikipedia.org/wiki/Space-based_architecture) (*SBA*) \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] is a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]] (a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] with at least one [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] per service instance) which also implements an in-memory [*tuple space*](https://en.wikipedia.org/wiki/Tuple_space) (shared dictionary). Although it does not provide a full-featured database interface it has very good performance, elasticity, and fault tolerance, while some implementations allow for dealing with datasets which are much larger than anything digestible by ordinary databases. Its drawbacks include write collisions and high operating costs (huge traffic for data replication and lots of RAM to store the [[wiki/concepts/source/basic-metapatterns/shards|replicas]]).

The main components of the architecture are:

- *Processing Units* – the [[wiki/concepts/source/basic-metapatterns/services|*Services*]] with the business logic. There may be one class of *Processing Units*, making *SBA* look like [[wiki/concepts/source/basic-metapatterns/shards|*Replicated Load-Balanced Services*]], or multiple classes, in which case the architecture becomes similar to [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] with a *Shared Database*.
- *Data Grid* (*Replicated Cache* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\]) – a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]]-based in-memory data store. Each node of the *Data Grid* is co-located with a single instance of a *Processing Unit*, providing the latter with very fast access to the data. Changes to the data are replicated across the grid by its virtual *Data Replication Engine* which is usually implemented by every node of the grid.
- *Persistent Database* – an external database which the *Data Grid* replicates (caches). Its schema is encapsulated in the *Readers* and *Writers*.
- *Data Readers* – components that read any data not found in the *Data Grid* from the *Persistent Database*. Most setups employ *Readers* upon starting the system to upload the entire contents of the database into the memory of the nodes.
- *Data Writers* – components that replicate the changes done in the *Data Grid* to the persistent storage to assure that no updates are lost if the system is shut down. There can be a pair of *Reader* and *Writer* per class of *Processing Units* (subdomain) or a global pair that processes all read and write requests.


*SBA* provides nearly perfect scalability (high read and write throughput as all the data is [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|cached]]) and elasticity (new instances of *Processing Units* are created and initialized very quickly as they copy their data from already running units with no need to access the *Persistent Database*). Though for smaller datasets the entire database is [[wiki/concepts/source/basic-metapatterns/shards|replicated]] to every node of the grid (the *Replicated Cache* mode), *Space-Based Architecture* also allows for processing datasets that don’t fit into the memory of a single node by assigning each node a [[wiki/concepts/source/basic-metapatterns/shards|*shard*]] of the dataset (the *Distributed Cache* mode).

The drawbacks of this architecture include:

- Structural and operational complexity.
- Very basic dictionary-like interface of the *tuple space* (no joins or other complex operations).
- High traffic for data replication among the nodes.
- Data collisions if multiple clients change the same piece of data simultaneously.


### [[wiki/concepts/source/extension-metapatterns/middleware|Persistent Event Log, Shared Event Store]]


![A service posts a message to a shared event log which both persists the message to a shared event store and forwards the message to other services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Shared%20Database%20-%20Event%20Log.png)


A data store for events (an *event log* for interservice events or an *event store* for internal state changes) [[wiki/concepts/source/foundations-of-software-architecture/shared-data|can be used]] as a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]: an event producer writes its events to a topic in the repository while the event consumers get notified as soon as a new record appears.

### (inexact) Stamp Coupling


![A message collects pieces of data while passing through a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/2/Stamp%20Coupling.png)


*Stamp Coupling* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] happens when a single data structure passes through an entire [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], with separate fields of the data structure matching individual processing steps.

A [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] system with no shared databases does not provide any way to aggregate the data spread over its multiple services. If we need to collect everything known about a user or purchase, we pass a query message through the system, and every service appends to it whatever it knows of the subject, just as administrative offices used to rubber stamp the paper documents which passed through them. The unified message becomes a kind of virtual (temporary) *Shared Repository* which the services (*Content Enrichers* according to \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\]) write to. This also manifests in the dependencies: all the services [[wiki/concepts/source/foundations-of-software-architecture/choreography|depend on the format of the query message]] as they would on the schema of a *Shared Repository*, instead of depending on one of their neighbors, as is usual with *Pipelines*.

## [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|Evolutions]]

Once a database appears, it is unlikely to go away. I see the [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|following evolutions]] to improve performance of the data layer:

- [[wiki/concepts/source/basic-metapatterns/shards|Shard]] the database.


![The shared database is sharded so that each database instance holds a subset of data,](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database_%20Shard.png)


- Use [[wiki/concepts/source/implementation-metapatterns/mesh|*Space-Based Architecture*]] for dynamic scalability.


![The shared database is migrated to a Data Grid, resulting in Space-Based Architecture](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Space-Based%20Architecture.png)


- Divide the data into private databases.


![The shared database is split into databases dedicated to subdomains, resulting in Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Services.png)


- Deploy specialized data stores ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).


![The shared database is migrated to specialized databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/2/Shared%20Database%20to%20Polyglot%20Persistence.png)


## Summary

A *Shared Repository* encapsulates a system’s data, allowing for [[wiki/concepts/source/foundations-of-software-architecture/shared-data|data-centric]] development and kickstarting [[wiki/concepts/source/basic-metapatterns/services|*Service-Based*]] architectures through simplifying interservice interactions. Its downsides are a frozen data schema and limited performance.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/arranging-communication.md ===== -->

---
title: "Arranging communication"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Arranging communication.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Arranging%20communication
source_license_note: "See namespace README; preserve attribution and source links."
---

# Arranging communication

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Arranging communication.md`.

As a project grows, it tends to become subdivided into services, modules, or whatever you call the [[wiki/concepts/source/basic-metapatterns/services|components that match its subdomains]] (or *bounded contexts*, if you prefer the \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] convention). Still, there remain system-wide use cases that require collaboration from many or all of the system’s parts – otherwise the components don’t even form a single system. Let’s see how they can be integrated.


![A monolithic system is subdivided into several services but it is an open question how the resulting components should be integrated.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Monolith%20to%20Services.png)


As integration is not unique to distributed systems – it is present even in smaller programs that need to make data, functions, and classes work together – we’ll take a look at programming and architectural paradigms next.

## Contents:

- [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|Programming and architectural paradigms]]
- [[wiki/concepts/source/foundations-of-software-architecture/orchestration|Orchestration]]
- [[wiki/concepts/source/foundations-of-software-architecture/choreography|Choreography]]
- [[wiki/concepts/source/foundations-of-software-architecture/shared-data|Shared data]]
- [[wiki/concepts/source/foundations-of-software-architecture/comparison-of-communication-styles|Comparison of communication styles]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/choreography.md ===== -->

---
title: "Choreography"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Choreography.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Choreography
source_license_note: "See namespace README; preserve attribution and source links."
---

# Choreography

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Choreography.md`.

Another integration option, named *choreography* after seemingly spontaneous interactions between dancers, is to build a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] to pass every client’s request through a chain of components:


![After a monolith is subdivided into services, the services are assembled into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Services%20to%20Pipeline.png)


In that case there is no owner for *workflows* – each request is just a data packet which is transformed multiple times as it passes through the *Pipeline*. Debugging is mostly limited to reading logs as there is no dedicated component to connect a debugger to for single-step execution of a use case. Nor is there a single piece of code to define each of the system-wide scenarios – their logic emerges from the graph of event channels between services and from message types that each involved event handler sends. Maintaining the consistency of the services’ states is the responsibility of the services themselves as there is none to supervise them.

On the bright side, there is no communication overhead caused by response messages as there are no responses – the processing cost is one message per service, half of the cost for an orchestrated architecture. Still, messages in choreographed systems tend to be longer than those used with [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestration]] as each message needs to carry the entire request’s state – there is no [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] to own the state and distribute parts of the request’s payload among involved services.


![A request collects data from every service in a pipeline as it passes those services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Pipeline%20Enricher.png)


Latency may also be suboptimal as parallelizing execution of a request is easier said than done because in a purely choreographed system there is no place (called *Aggregator* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\]) to collect multiple related messages, which also means that there is no associated cost in resources (RAM and CPU time) for storing their payloads. Please note that an *Aggregator*, when added, starts orchestrating the system – it stands between the client and services and meddles with the traffic and logic. It spends resources to store the received messages for aggregation, and the messages start forming request/confirm pairs – which are characteristic of orchestration.


![An Orchestrator can run subrequests in parallel which is impossible for a sequential pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Pipeline%20Not%20Parallel.png)


Still another trouble with choreography comes from its weakness in error processing. When a service in the middle of a request processing pipeline encounters an error, it cannot generate the normal output which would have been sent further downstream. One option is to fill in a null (or error) value but in that case each receiver of the message should remember to check for null and know how to deal with the error. Another way is adding a dedicated error channel for each service to push failed requests into, but that complicates the high-level system’s architecture. Moreover, a failure in the middle of processing a request may cause the services to end up with inconsistent data if no special attention (i.e. a new kind of request to compensate the original one) is paid to roll back the partial change.

Please note that all of the above is comfortably handled by an *Orchestrator*. Essentially, the exception handling, which an *Orchestrator* covers within its code, in a choreographed system escalates to the system’s architecture level.


![Rollback of changes done by services arranged into a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Pipeline%20Error.png)


## Early response

The ordinary mode of action for a pipeline – sending the final results of processing to the client – requires either for the tail of the pipeline to send data to its head or for existence of a stateful intermediate component – [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] – to receive the client’s request, forward it to the head of the pipeline, wait on the pipeline’s tail for the result of processing, and return it to the client. That is necessary because a client would usually open a single connection which is impossible to share between multiple services, namely the (receiving) head and (sending) tail of the pipeline.


![The component that receives a client request should send back the response. It can be a dedicated Gateway or the first service of a looped pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Pipeline%20Gateway.png)


The gateway, if used, may parallelize processing of [scatter-gather](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/scatter-gather.html) requests by turning into an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] which is a kind of *Orchestrator*. Which means that the system changes its paradigm from choreography to orchestration.


![An API Gateway runs subrequests in parallel while a pipeline runs them consecutively by passing a message through a chain of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Gateway%20to%20API%20Gateway.png)


It is possible to avoid both adding a *Gateway* and having the cyclic dependency if clients don’t immediately need the final results of processing their requests. In such a case the service which receives the original request does its (first) step of processing, sends the response to the client, and then notifies services down the pipeline. Though such a use case seems to be unlikely, it happens in real life, for example, with pizza delivery. As soon as a buyer fills in their contact details and pays for the food, the order can be confirmed and forwarded to the kitchen. When it is ready it’s forwarded to the delivery, and finally the physical goods appear at the buyer’s door.


![The first service of a pipeline responds to the client immediately while forwarding the client's request to other services, which will eventually produce the result.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Pipeline%20Early%20Response.png)


*Early response* allows for choreography to shine in its purest form: with extensibility, high performance, but also high latency. A similar approach may be used in [[wiki/concepts/source/basic-metapatterns/services|*Service-Based Architecture*]] (aka *Macroservices*) [for communication between the services](https://learn.microsoft.com/en-us/azure/architecture/patterns/choreography) (*bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]) if they only need to notify each other of events without waiting for responses.

## Dependencies

A pipeline may be built with downstream or upstream dependencies or with a shared schema.

If services communicate through commands, each service depends on all the direct destinations of its commands as it must know each of the APIs which it uses. This mode of communication is mostly used with [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] that power embedded, telecom, messengers, and some banking systems. Downstream dependencies make it easy to add input chains (upstream services that deal with new hardware or external clients) although changing anything at the output end of the pipeline is going to break the input parts that send messages to the component changed.


![Adding an upstream component in a command-based pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Downstream%20Dependencies.png)


Upstream dependencies come from the [publish/subscribe](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) model ([*Event Collaboration*](https://martinfowler.com/eaaDev/EventCollaboration.html)) where each service broadcasts notifications to any interested subscriber about what it has done. This way of building systems engines [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]] which is used in high-load backends. Extending or truncating an already implemented request processing tree is as easy as adding or removing subscribers to existing events but the creation of a new event source will require changes in the downstream components. The easy addition of downstream branches supports new customer experiences and analytical features which businesses are hungry for.


![Downstream services are easily added to a pub/sub pipeline, turning it into a tree.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Upstream%20Dependencies.png)


The final option is for the entire pipeline to use a uniform message format ([[wiki/concepts/source/extension-metapatterns/shared-repository|*Stamp Coupling*]]) which often contains one dedicated field per service involved. This way a service depends only on the message header (with the list of the fields and a record id) and the format of the single field it reads (stores data) or writes (retrieves data as a *Content Enricher* \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\]). That works well with system-wide queries but binds all the services to the schema of the message in a way similar to accessing a shared database (to be discussed [[wiki/concepts/source/foundations-of-software-architecture/shared-data|below]]). Such an architecture decouples the services to the extent that any of them can be freely added or removed, together with the message field(s) it fills or reads.


![Each component depends on the message header and the message field(s) it accesses.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Shared%20Message%20Format.png)


![A service in a pipeline with a shared message format can be replaced with another service if the message fields which it uses are also replaced.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Add%20Remove%20with%20Shared%20Message.png)


A peculiar feature of choreography is the ability to cut and cross-link pipelines with compatible interfaces by changing a single service (or even system configuration if you build it with communication channels). That gives it a lot of flexibility – as long as you can comprehend all the dependencies (and channels) in the system, which becomes non-trivial as it grows.


![Cross-linking independent pipelines by establishing new data or event streams.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Cross-link%20Pipeline.png)


## Multi-choreography

It is very common for a service to participate in multiple pipelines, especially if it owns a database – as there should be a use case which fills in the data and at least one other scenario which reads from that database. Each pipeline makes the service depend on one or more of the interfaces it communicates with, which often belong to multiple services, thus increasing the coupling between system components and impairing future structural changes.


![A set of services participates in multiple pipelines.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Multi-choreography.png)


## Summary

Overall, choreography seems to be a lightweight approach that prioritizes throughput over latency and is suitable for highly-loaded scenarios of limited complexity. However, a choreographed system will likely become unintelligible if it is made to support more than a few use cases.

There is a decent [overview from Microsoft](https://learn.microsoft.com/en-us/azure/architecture/patterns/choreography).


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/comparison-of-communication-styles.md ===== -->

---
title: "Comparison of communication styles"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Comparison of communication styles.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Comparison%20of%20communication%20styles
source_license_note: "See namespace README; preserve attribution and source links."
---

# Comparison of communication styles

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Comparison of communication styles.md`.

We have briefly discussed three approaches to communication: orchestration, choreography, and shared data. Let’s recall when it makes the most sense to use each of them.

- [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*Orchestration*]] is built around [[wiki/concepts/source/basic-metapatterns/layers|use cases]]. They are easy to program and add, no matter how complex they become. Thus, if your (sub)domain is coupled, or your understanding of it is still evolving, this is the way to go, as you will be able to change the high-level logic in any imaginable way because you express it as convenient imperative code.
- [[wiki/concepts/source/foundations-of-software-architecture/shared-data|*Shared data*]] is all about… er… domain data. If you really (believe that you) know your domain, and it deals with coupled data – this is your chance. You may even add in an *Orchestrator* if there are use cases that involve multiple subdomains. The business logic is going to be easy to extend while changes to the data schema are sure to cause havoc.
- [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreography*]] pays off for weakly coupled domains with a few simple use cases. It has good performance and flexibility, but lacks the expressive power of orchestration and becomes very messy as the number of tasks and components grows. It works best with independent teams and delayed processing – when users are not waiting for the final results of their actions.


There is advice [from Microsoft](https://learn.microsoft.com/en-us/azure/architecture/patterns/choreography) and \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] which makes perfect sense: use choreography for communication between *bounded contexts* (subdomains) \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] but revert to orchestration (or maybe shared data) inside each context. Indeed, subdomains are likely to be loosely coupled while most user requests don’t traverse subdomain boundaries – which kindles hope that their interactions are few and not time-critical. If we follow the advice, we get [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] ([WSO2 definition](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md)), which collects the best of two worlds: orchestration and/or shared data for strongly coupled parts and choreography between them.


![A diagram of the Cell-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Cell-Based%20Architecture.png)


By the way, you could have noticed a few odd cases:

- An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] in a [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control system]] does not run scenarios and its mode of action resembles choreography.
- A choreographed system may use a [[wiki/concepts/source/extension-metapatterns/shared-repository|shared message format]], which makes it resemble a system with shared data, even though no shared database is present.
- A shared database may be used to [[wiki/concepts/source/extension-metapatterns/shared-repository|implement messaging]] for an orchestrated or choreographed system, effectively becoming a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].


That likely means that our distinction between the modes of communication is a bit artificial and there exists a yet unknown deeper model to look for.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution.md ===== -->

---
title: "Forces, asynchronicity, and distribution"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Forces, asynchronicity, and distribution.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Forces%2C%20asynchronicity%2C%20and%20distribution
source_license_note: "See namespace README; preserve attribution and source links."
---

# Forces, asynchronicity, and distribution

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Forces, asynchronicity, and distribution.md`.

Many systems rely on asynchronous communication between their components or are distributed over a network. Why is dividing a system into modules or classes then not enough in real life?

## Requirements and forces

Any software is built to meet a set of (explicit or implicit) *requirements*. As a bare minimum, you as a programmer must have at least a vague vision of how your software is expected to operate. At the most, business analysts bring you volumes of incomprehensible documentation they wrote for the sole purpose of forcing you to practice *Domain-Driven Design* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\].

Some requirements are *functional*, others are *non-functional*.

*Functional requirements* describe what the system must do: a night vision device must be able to represent heat radiation as a video stream; a multiplayer game must create a shared virtual world for users to interact with over a network; a tool for formatting floppies … er, formats floppies.

[*Non-functional requirements*](https://en.wikipedia.org/wiki/Non-functional_requirement) (*NFR*s) define the expected qualities of the system and are known to drive architectural decisions \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA5]]\]. They may be formulated or implied: “our game should be fast enough and stable enough”. “A medical application should be extremely well-tested”. “An online shop should provide an easy way to add new goods”.

Notice all those “fast enough”, “stable enough”, “well”, and “easy” terms on the wishlist – those are *soft* requirements, open to subjective interpretation and compromises. There are also *hard* NFRs, either as an [SLA](https://en.wikipedia.org/wiki/Service-level_agreement) with numbers: “your service should be available 99.999% of the time” or as (presumably) verifiable statements: “no user should ever see the personal data of another user”.

*Forces* – the drivers of architectural decisions – include both non-functional requirements and the business reality: it makes little sense to start a year-long development project if competitors are expected to have their products ready in three months, and you cannot plan for five teams if your budget is limited to two.

Let’s take an example.

A night vision surveillance camera may spend seconds compressing its video stream to limit the required network bandwidth – this kind of system sacrifices low latency in favor of low traffic. The device will need a fast CPU (probably a DSP) and lots of RAM to store multiple frames for efficient compression.

A night vision camera of a drone should have moderately low latency as the drone (and likely its operator) uses the video stream for navigation. Thus it should send out every frame immediately, except that it may still spend some time compressing the frame to JPEG to achieve a balance between latency and bandwidth. Pushing for extremely low latency of the camera does not help much because the whole system is limited by the delay of the radio communication and the human operator in the loop.

Night vision goggles or helmets are [stringent on latency](https://ntrs.nasa.gov/api/citations/20050192646/downloads/20050192646.pdf) to the extent which no ordinary digital system satisfies, thus [expensive analog devices](https://gloomgroup.com/blogs/night-vision-info/night-vision-digital-vs-analog) have to be used.

Here we see how forces – namely, latency, bandwidth, and cost – impact all the stuff all the way down to hardware. The same happens with multiplayer games: while a chess client is a simple web page, a fighting tournament or a first-person shooter is very likely to need a client-installed application that processes much of the game logic locally while relying on a highly customized network protocol to decrease communication latency.

Another example is the choice of programming language: you can quickly write your system in Java or Python sacrificing its performance or you can spend much more time with C or C\+\+ and manual optimization to achieve top performance at the cost of development speed. And your choice also depends on which programmers are readily available: if there are C\+\+ programmers waiting on the bench while those with Java skills would need to be hired, that may well shift your decision towards writing the project in C\+\+ because that will give you a flying start.

## Conflicting forces

We see that forces influence architecture. That becomes way more interesting when a system is shaped by conflicting forces – the ones that, though opposing each other, still need to be met by the architecture.

Remember how old Windows used to freeze on formatting a floppy or when it encountered one with a bad cluster? Let’s see how such things could have happened (though [the real cause was a bit different](https://sudonull.com/post/124038-Why-did-Windows-95-freeze-when-formatting-a-floppy-disk), it also came from the modules’ sharing a context).


![Synchronous communication freezes the system UI and format windows while a driver formats a floppy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Floppy-Sync.png)


The system implements the function it was made for – it formats floppies. However, while the low-level module is busy interacting with the hardware, all the modules above it have no chance to run because they have called the driver and are waiting for it to return. The modules are there, with the code separated into bounded contexts (the UI does not need to care about sectors and FATs) but all of them share non-functional qualities – latency in this case. Either the UI is responsive or the floppy driver runs a long-running action. We need the UI and the driver to execute independently.

## Asynchronous communication

If the components cannot communicate directly (call each other and wait for the results returned) how should they interact? Through an intermediary where one of them leaves a message for another. Such an intermediary may be a message queue, a pub/sub channel, or even a data record in [[wiki/concepts/source/extension-metapatterns/shared-repository|shared memory]]. The sender posts its message and continues its routine tasks. The receiver checks for incoming messages whenever it has a free time slot. Behold multithreading in action!


![Asynchronous communication unblocks the system UI and format windows while a driver formats a floppy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Floppy-Async.png)


## Distribution

Once modules run independently, we can separate them into processes and even distribute the processes over multiple computers. That is required to address fault tolerance and high availability and solve conflicts around scaling or locality.

Consider a web site. Most of them follow [*Three-Tier Architecture*](https://en.wikipedia.org/wiki/Multitier_architecture#Three-tier_architecture):

- A *frontend* runs in users’ browsers.
- A *backend* runs on the business owner’s servers.
- A *database* usually runs on a single powerful server.


This common division makes quite a lot of sense:


![Frontend, backend, and database layers differ in their scalability, security, and operational costs.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/3-Tier.png)


Websites are accessed by many users simultaneously. Any business owner wants to pay less for his servers, thus as much work as possible is offloaded to the users’ web browsers which provide unlimited resources for free (from the business owner’s viewpoint). Here we have a nearly perfect scalability – the business owner pays only for the traffic.

Other parts of the software are business-critical and should be protected from hacking. Such ones are kept on private servers or in a cloud. This means that the business owner pays for the servers but still may scale their application by flooding it with money.

The deepest layer – the database – is nontrivial to scale. Distributed databases are expensive, consume a lot of traffic, and still scale only to a limited extent. It often makes more sense to buy or rent top-tier hardware for a single database server than to switch over to a distributed database.

This is a good example of how the physical distribution of a system solves the scalability, security, and cost conflict by choosing the best possible combination of forces for each module. Whatever is not secure scales for free. Whatever does not scale gets assigned expensive hardware. Whatever remains is in between.

Another example comes from IoT – a fire alarm system. They tend to use 3 tiers as well:

- *Sensors* (smoke or fire detectors) and *actuators* (fire suppression, sirens, etc.).
- A *field gateway* – a kind of router the sensors and actuators are directly connected to.
- A *control panel* – some place where operators drink their coffee.


Sensors and actuators are cheap and energy-efficient but too dumb to act on their own –  they do not react to events unless explicitly commanded to do so. The control panel is where all the magic happens, but it may be unreachable if the network is damaged or the wireless communication is jammed. Field gateways stand in between: they collect information from the sensors, aggregate it to save on traffic, communicate with the control panel, and even activate actuators if the control panel is unreachable. In this case a part of the business logic is installed into the dedicated devices which are located within the controlled building.

Here reliability conflicts with accuracy: a human operator makes an accurate estimate of the threat and chooses an appropriate action, but it is not granted that we can always reach the operator. Thus to be reliable we add an inaccurate but trustworthy fallback reaction.


![Normal and autonomous operation of a field gateway of a fire alarm system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Field%20Gateway.png)


A similar pattern can be found with robotics, drones or even computer hardware (e.g. a HDD): dedicated peripheral controllers supervise their managed devices in real time while a more powerful but less interactive central processor drives the system as a whole.

## The goods and the price

Let’s review what we found out.

Modules make it easier to reason about the system, enable development by multiple teams in parallel, and resolve some conflicts between forces. For example, development speed against performance or release frequency against stability are solved by choosing a programming language and release management style on a per module basis.

The cost is the loss of some options for performance optimization between modules and the extra cognitive load while debugging a module you are not familiar with.

Asynchronous communication is a step forward from modules that solves more conflicts between forces. It addresses latency and multitasking.

We pay for that with context switches and the need to copy and serialize data transferred in messages, making communication between participating modules slower. Debugging asynchronous communication becomes non-trivial as one cannot single-step in the debugger from the message sender into the message handler.

Distribution builds upon asynchronous communication (as networks are asynchronous) and decouples participant components in such qualities as scalability, security and locality. It separates release cycles of the services involved and makes it possible for the system to recover from failures of some of its components.

The price? Even slower and more complicated communication in the now distributed system (networks are quite laggy and unreliable) and extremely inconvenient debugging as you need to connect to multiple components over the network.

We see that the more isolated our components become, the more their qualities are decoupled and the more flexible the resulting system grows. But this very same decoupling devastates the system’s performance and makes debugging into a nightmare.

Any moral? There is one, even a few.

- [Do not overisolate](https://martinfowler.com/bliki/MonolithFirst.html). Go asynchronous or distributed only if you are *force*d to. Especially if you are actively evolving your system. Especially in an unfamiliar domain.
- Cohesive logic belongs together. If you split it among asynchronous or distributed components, it may become very hard to debug.
- Components that communicate a lot should reside together. Distributing them may kill performance and even break the consistency of the data.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/foundations-of-software-architecture.md ===== -->

---
title: "Foundations of software architecture"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Foundations of software architecture.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Foundations%20of%20software%20architecture
source_license_note: "See namespace README; preserve attribution and source links."
---

# Foundations of software architecture

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Foundations of software architecture.md`.

This part defines some ideas which are used throughout the book:

- [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|Complexity]] and its relation to modules, coupling and cohesion.
- [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|Forces]] (including non-functional requirements), their conflicts, and how those are resolved through asynchronous communication and distribution of system components.
- Different [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|kinds of software systems]]: [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control]], [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|interactive]], [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|streaming]], and [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|computational]].
- [[wiki/concepts/source/foundations-of-software-architecture/arranging-communication|Communication paradigms]]: [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestration]], [[wiki/concepts/source/foundations-of-software-architecture/choreography|choreography]] and [[wiki/concepts/source/foundations-of-software-architecture/shared-data|shared data]].


Please feel free to skip (through) it as you probably know most of them quite well.

## Contents:

- [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|Modules and complexity]]
- [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|Forces, asynchronicity, and distribution]]
- [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|Four kinds of software]]
- [[wiki/concepts/source/foundations-of-software-architecture/arranging-communication|Arranging communication]]
  - [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|Programming and architectural paradigms]]
  - [[wiki/concepts/source/foundations-of-software-architecture/orchestration|Orchestration]]
  - [[wiki/concepts/source/foundations-of-software-architecture/choreography|Choreography]]
  - [[wiki/concepts/source/foundations-of-software-architecture/shared-data|Shared data]]
  - [[wiki/concepts/source/foundations-of-software-architecture/comparison-of-communication-styles|Comparison of communication styles]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software.md ===== -->

---
title: "Four kinds of software"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Four kinds of software.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Four%20kinds%20of%20software
source_license_note: "See namespace README; preserve attribution and source links."
---

# Four kinds of software

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Four kinds of software.md`.

Software products vary in their goals which, surprisingly, determine their structure and operation. The main features of software make a fuzzy continuous space rather than a strict set of well-defined classification options. Let’s examine two of its dimensions:

### Source of inputs

Some systems receive their inputs from users via text commands or UI controls, often mediated by a network protocol. Such inputs are highly meaningful, structured and compact – processing a single user command often invokes a larger part of the program’s functionality.

Another kind of system deals with binary data or signals that come from hardware. Those input sources have low informational payload – a digitized movie is orders of magnitude larger than a book written in a human language and still omits many details of the original text. Raw inputs often require context (the program’s state) to understand their meaning: the same sequence of bits may be treated as a part of a video, audio, executable file or archive – and the correct interpretation is known only from the command your program is running and the name and header of the file it is processing.

### Latency constraints

Programs that control hardware or interface with users need to respond to their inputs in real time. Milliseconds of delay result in any kind of bad stuff that ranges from negative reviews and lost business opportunities to lost human lives (which are the same from the business PoV). That kind of software can never block its execution or run long calculations and has to keep all the data involved in memory.

Other programs are not that time-constrained – they run a single task for a long time, accessing many files or consulting remote services in the process. They may use more powerful decision-making algorithms and all the data in the world – but they are slower to respond.

Those dimensions make four corner cases that vary in architectural styles:


![Diagrams of control, interactive, streaming, and computational systems.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/4%20Kinds.png)


## Control (real-time, hardware input)


![A control system receives an event from a hardware component, processes it with a hardware driver, passes the result to a mediator, which calls another driver, which activates another hardware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Control%20-%20main.png)


A *control* application supervises several hardware or software interfaces with the goal of keeping a certain system-wide *invariant*:

- A fly-by-wire program receives readings from the airplane’s sensors and adjusts its [actuators](https://en.wikipedia.org/wiki/Actuator) to keep the vehicle on its course, which is the invariant.
- When a telephony gateway receives an outgoing call request from one of the devices that it manages, it checks the dialed number, initiates an incoming call to a matching interface, and connects a voice channel between the devices as soon as the destination accepts the call. The invariant is that calls live in pairs: if a call comes in, it is to be rejected or a derived call should go out of the device.
- A [[wiki/concepts/source/implementation-metapatterns/microkernel|*Container Orchestrator*]] checks the health of the services it manages and restarts any one which is slow to respond to its keep-alive request, making sure that all the services are online.


As a control software must react quickly, it has no time to read from storage or obtain from other components the data it needs to make decisions. Thus it has to build and maintain in its memory a *model* of the system it controls:

- An autopilot knows the last measured plane's coordinates, speed, angles and states of all its actuators.
- A telephony application models both the phones and accounts it supervises and the calls present in the system.
- A container manager remembers the state of every service it oversees, the time of the last health check and user request statistics (number of requests and processing time).


When a program receives information from a component it controls, it updates its in-memory model with the new data and checks if the target invariant still holds:

- A plane should remain on its course, otherwise its [angles](https://en.wikipedia.org/wiki/Aircraft_principal_axes) or thrust must be adjusted.
- If there is a new incoming call, a VoIP gateway must create a corresponding outgoing call.
- If a service is known to have not responded for a while, it must be killed and restarted.


After the compensating action is initiated, the model is updated accordingly, and the software resumes processing events. After a while it should receive events that confirm that the invariant was restored:

- The new sensor readings will show that the plane is back on its course.
- The outgoing call will have been accepted and the gateway will connect the voice path between the call parties.
- The container will have been restarted successfully and will be serving user requests.


The flow of changes through the system is **M**-shaped: it starts as a low-level event, gets interpreted by a hardware driver or protocol stack, and goes up to an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], which updates its model and decides if there should be any reaction, which would then go all the way down to the same or another low-level interface.

### Variants

At the architectural level, control systems are [event-driven](https://en.wikipedia.org/wiki/Event-driven_programming) – their components communicate by messages. There are several architectures I am aware of:

- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] is the simplest and fastest implementation, usually tiny enough to run everything in a single [super loop](https://blog.mbedded.ninja/programming/design-patterns/how-to-write-super-loops-in-firmware/).
- Plain ([[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]]) [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] fit systems of trivial logic but massive scale, like messenger backends. Each actor models the component (remote device or user) it interacts with, and there is no global model except for a registry of actors.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Pedestal*]] is a better solution for complicated ([[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|*cohesive*]]) systems that need centralized management. In it, the [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] (called *Control* or [*Mediator*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]) contains the whole system’s model and integration logic. Each hardware component is encapsulated with a [[wiki/concepts/source/extension-metapatterns/proxy|*driver*]] which hides its specifics from the business logic that resides in the hardware-agnostic, thus reusable and portable, *Orchestrator*.
- A [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchical Orchestrator*]] can manage even more complex systems. The *Orchestrator* may run synchronously with polymorphic specialized components or asynchronously. In the last case each sub-orchestrator reacts independently based on its own model but also sends a notification to the high-level component which builds a global strategy and configures the smaller models of sub-orchestrators.


![Diagrams of control systems with the following architectures: monolithic, actors, Pedestal, hierarchical.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Control%20-%20variants.png)


### Patterns

The following patterns are prominent in control software:

- [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] – partitioning the domain into self-consistent asynchronous entities allows fine control over the order of execution of system activities, provided that we run a [preemptive scheduler](https://micrium.atlassian.net/wiki/spaces/osiiidoc/pages/131347/Preemptive+Scheduling) (from [POSIX real-time threads](https://man7.org/linux/man-pages/man7/sched.7.html) or [RTOS](https://en.wikipedia.org/wiki/Real-time_operating_system)) – we can assign top priority to reading data from communication interfaces (which would quickly overflow if the data is not retrieved), make reacting to events a bit less urgent, and still have leftovers of our CPU time for such long-running tasks as file access or strategic planning.
- [[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]] – almost every component is single-threaded, reactive, and non-blocking, which makes the system very responsive. The downside is being unable to represent a multi-step scenario as a single function, which is usually unimportant as no predefined scenario ever survives event-driven reality unshattered. Following a planned path leads directly to your grave. Proceed stepwise, checking for dangers every millisecond, being ready to jump away from any approaching trouble.
- [*Mediator*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] (a kind of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) – when you rely on information from and manage several devices or interfaces, you need a single entity that knows what is going on, makes informed decisions and dispatches commands to be executed. It integrates all the lower-level components into a coherent system. It is a *Mediator*.
- [[wiki/concepts/source/basic-metapatterns/services|*Pedestal*]] (a kind of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]) – hardware components quickly become obsolete, and if you want your software to survive for a decade, you must be able to change them at will. And if you want to run, test, and debug your code on your desktop, you often need to [stub](https://martinfowler.com/articles/mocksArentStubs.html) or [mock the hardware](https://stackoverflow.com/questions/38745542/unit-testing-application-interface-to-hardware-to-mock-or-not). Therefore wrap each hardware component with a dedicated [[wiki/concepts/source/extension-metapatterns/proxy|*driver*]] that provides a generic interface to the upper layers of the system. This way you will be able to emulate or replace the hardware together with its driver because a driver conceals peculiarities and even the existence of the hardware it adapts.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] – if you manage a variety of interfaces that have the same role (telephony protocols, account providers, or payment systems) you want to make them polymorphic towards your main application logic, which is simpler if it does not need to address tens or hundreds of special cases. In other domains, like [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things), you may need to start reacting immediately with little precision and correct your actions after you have spent more time on better planning, which is achieved through a hierarchy of feedback loops.


> Very complex hardware with tens or hundreds of components is usually managed by an [[wiki/concepts/source/implementation-metapatterns/microkernel|*Operating System*]] (a kind of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] architecture) with multiple control applications that have specific roles and govern distinct subsystems. An [extensively documented](https://www.autosar.org/fileadmin/standards/R22-11/CP/AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf) real-world example is [[wiki/concepts/source/implementation-metapatterns/microkernel|*AUTOSAR*]] which is too vast a topic to discuss here.

### Implementation

Even though we may (or may not) see [*State*](https://refactoring.guru/design-patterns/state) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] (aka *Objects for States* \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\]) close to hardware or protocol interfaces, the higher-level logic tends to be coded as a decision tree (with explicit conditions or polymorphic [*Strategies*](https://refactoring.guru/design-patterns/strategy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]) because it depends on multiple parameters which would make [too many combinations](https://en.wikipedia.org/wiki/Combinatorial_explosion#Computing) to write down as state classes.

System components ([[wiki/concepts/source/basic-metapatterns/services|*actors*]]) have private in-memory data and communicate only by messages. They are usually single-threaded and non-blocking ([[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]]) – this way, the only locks in the system are those protecting the actors’ message queues and the global memory manager, which don’t contain anything complicated to block on for a noticeable time. And as nothing ever blocks, the whole system is extremely responsive.

Messages may be dispatched through multilevel index arrays or [*Visitors*](https://refactoring.guru/design-patterns/visitor) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]. [[wiki/concepts/source/foundations-of-software-architecture/shared-data|Message queues]] may be shared (a queue per thread priority) or private (a queue per component). With shared queues the destination of a message must either be resolvable from its type (when there is a single instance of every kind of system component) or stored in the message’s header.

## Interactive (soft real-time, user input)


![An interactive system workflow with an event coming from the presentation layer to the model and back.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Interactive%20-%20main.png)


An *interactive* software deals with users who expect it to provide immediate feedback to their actions. Examples include:

- Desktop and mobile applications, from text editors to browsers.
- Simple games, like chess or tetris.
- UI of embedded devices, such as clocks or air conditioning systems.


The [[wiki/concepts/source/basic-metapatterns/layers|user interface layer]] ([[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Separated Presentation*]]) receives input (mouse, keyboard / keypad, or touchscreen events), interprets it as a user action based on the current application’s *state* (pressing enter in a text editor may break a line of text in two, begin a new line, or even activate a menu item), forwards the action to the lower levels of the software and displays any feedback received, producing a **U**-shaped flow.

### Variants

Interactive systems vary in a couple of ways:

- The presentation layer may wait for the business logic to execute the user’s action, blocking further user input and screen updates (air conditioner controller), or it may asynchronously pass the command to the lower layer and continue processing new user input and showing progress of the already running tasks (many games) while the main program is busy with the command.


![With blocking interaction between the presentation and model layers the user interface is frozen for the duration of processing. With non-blocking it is mostly active.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Interactive%20-%20variants%201.png)


- There may be dedicated modules for processing user input and output ([[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC* family]] of patterns) or both may pass through the same stack of components ([[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVP* family]]). The asymmetric approach deals with raw controller input, which is what most games need, while the bidirectional flow operates UI widgets provided by the host OS or GUI framework.


![Model-View-Controller features separate components for input and output. In Model-View-Presenter both layers above its model participate in both input and output.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Interactive%20-%20variants%202.png)


### Patterns

You will likely encounter:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Separated Presentation*]] – the business logic is unaware of the implementation of the UI layer, though this may not be the case with some games that rely on *game development frameworks*. This pattern is usually implemented by:
  - [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Presenter*]] (MVP) – two input layers, namely: a *view* which receives input and shows output and a *presenter* which translates between the business logic, called *model*, and the view.
  - [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-ViewModel*]] (MVVM) also has two layers, but the intermediate *ViewModel* [binds](https://en.wikipedia.org/wiki/Data_binding) to the view and bears its state.
  - [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller*]] (MVC) separates the input (*controller*) from the output (*view*).
- [*State*](https://refactoring.guru/design-patterns/state) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\], subclassed by \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] into *Objects for States*, *Methods for States*, and *Collections for States*, is prominent in games, though it may not always be implemented explicitly.
- [*Flyweight*](https://refactoring.guru/design-patterns/flyweight), [*Command*](https://refactoring.guru/design-patterns/command), [*Observer*](https://refactoring.guru/design-patterns/observer) and many other \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] patterns originated with desktop software and [may often appear](https://gameprogrammingpatterns.com/contents.html) in games.


### Implementation

The presentation layer may be called into by the desktop environment or it may run in a dedicated thread, for example, to play animations.

The business logic is likely to rely on its own threads, at least for long-running actions.

The presentation would usually receive (subscribe to) updates from the business logic.

## Streaming (continuous, raw data input)


![A streaming system is a pipeline of data processing steps.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Streaming%20-%20main.png)


A *streaming* system processes a long sequence of similar events or data packets, usually by transforming individual items in a predetermined way:

- Each party in an audio call or video conference deals with incoming and outgoing media streams. For example, incoming audio stream processing involves: saving audio packets to a [jitter buffer](https://bloggeek.me/webrtcglossary/jitter-buffer/) to restore their order, [compensation for lost packets](https://en.wikipedia.org/wiki/Packet_loss_concealment), decoding, equalization, and playback. Outgoing audio passes through the following steps: [echo suppression or cancelation](https://en.wikipedia.org/wiki/Echo_suppression_and_cancellation), noise reduction, equalization, encoding, adding network headers, and sending packets to the network.
- An image recognition system applies a [long sequence of transformations](https://keras.io/examples/vision/image_classification_from_scratch/#build-a-model) to every input image.
- Hardware often works with streams. For example, a [CPU instruction pipeline](https://en.wikipedia.org/wiki/Instruction_pipelining) comprises at least: instruction fetching, instruction decoding and register fetching, execution, memory access, and register writeback. High-end processors may involve up to 20 stages.
- Many UNIX command-line tools process streams of lines of text, allowing for complex text processing to be done by chaining pre-existing utilities \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\].


Streaming usually passes data through a chain of transformations ([[wiki/concepts/source/basic-metapatterns/pipeline|*pipeline*]]) which differ in functionality but stay at about the same level of abstractness – there are no managers or hierarchy. Such a **–**-shaped structure allows for each specialized component to process its own chunk of the stream in parallel to the other system components, which increases the system’s throughput but suffers from moderate to high latency.

### Variants

As [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] can exploit multiple CPU cores and specialized hardware, they are found everywhere from lowest-level firmware to large-scale distributed systems. \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] classifies them into:

- [[wiki/concepts/source/basic-metapatterns/pipeline|*Stream processing*]], where the pipeline is always alive waiting for more input to come.
- [[wiki/concepts/source/basic-metapatterns/pipeline|*Batch processing*]], where the pipeline runs till it finishes processing an input file.


### Patterns

- [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipes and Filters*]] is *the* stream processing pattern that describes pipelines: the system is built of *filters* (individual data processing steps) connected through *pipes* (data channels).


- [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]] (EDA) and [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]] are tree-like pipelines that process streams of domain events or data, respectively.


\[[wiki/concepts/source/appendices/books-referenced|[EIP]]\] is full of patterns for the distributed processing of event streams.

### Implementation

Every component is likely to run in its own thread or process and be unaware of other components – it only knows where to pull its input from and push its output into. One common challenge is to [slow down](https://medium.com/@beeindian04/back-pressure-in-data-pipeline-bdc25c6c1d79) a too fast data producer or scale data consumers when too much intermediate data accumulates in the channel between them.

## Computational (single run, user input)


![A computational system makes multiple calls to the underlying OS during a single run.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Computational%20-%20main.png)


Finally, there is a large group of applications created to process long-running commands:

- A scientific calculation runs for days or weeks to provide insight into the physical reality or validate a new theory.
- A compiler creates a platform-specific binary by processing text files with the program’s code.
- An interpreter runs scripted actions on its user’s behalf.


In each case the application starts with parsing (interpreting) its input, proceeds to execute it in a stepwise (and likely looped) manner, and finishes by outputting results of the run, making a **W**-shaped flow.

### Variants

Some computational systems are single-use with a hard-coded task (calculation of Pi) while others can execute a variety of user scenarios (script interpreters).

### Patterns

Long-running programs with user input are probably the most common, ancient, and well-studied kind of software, which also inspired many design patterns. Those of special significance are:

- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Interpreter*]] that supports very complex user commands.
- [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Process Manager*]] (kinds of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) that executes a user command as a sequence of calls to lower-level components.


### Implementation

There can be some kind of *parser* (complex for SQL or very simple for command-line parameters) that transforms user input into a [syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) or a set of flags, respectively. Then there is a kind of *main loop* which iteratively executes actions, pre-defined or encoded in the parsed tree, until an *exit condition* is met or the entire input has been processed.

Any calls to external components (OS or libraries) are likely to be blocking as the computation does not need to react quickly to any additional input – actually, it does not read any input or change its behavior for the entire duration of its run.

Parts of computations may be offloaded to [SIMD](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data) or [GPU](https://en.wikipedia.org/wiki/Graphics_processing_unit) / [TPU](https://en.wikipedia.org/wiki/Tensor_Processing_Unit) because that greatly speeds up number crunching which is often characteristic of long-running calculations.

## Mixed cases

Most real-life software is too complex to fit the classification outlined above. It tends to merge the paradigms either by mixing them to find a middle ground or by implementing two or three of them at once. Let’s inspect a few random examples to see how that works:

### Camera


![Internal components of a camera with interactive, control, and streaming communication highlighted.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Camera.png)


A digital camera incorporates subsystems of different kinds:

- There is an interactive [[wiki/concepts/source/basic-metapatterns/layers|user interface]] that receives commands for other components and displays either the video stream from the matrix or the camera’s settings menu.
- A control layer provides feedback loops to keep the camera focused on a selected object and preserve the overall brightness level and color balance when shooting in automatic mode.
- An image processing pipeline applies noise reduction, rescaling, and color correction, then either passes the resulting frames to the UI to show them on the screen or proceeds with compressing the frame and storing it as a file.


### 3D action game


![A game framework receives data from hardware and sends an event to the business logic which updates multiple game objects. Finally, the framework sends updates to the hardware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/3D%20action.png)


Games with 3D graphics often bypass the host OS’ [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and access the underlying hardware drivers to achieve fine control and improved performance. Such applications, though pretending to be interactive software driven by user input, strongly resemble control systems by polling hardware with fixed frequency (the game’s frame rate).

### SQL database


![Internals of a database with the following groups of components: session, parser, task, metadata manager, and tables.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/4Kinds/Database.png)


SQL databases support several kinds of user commands:

- [*Data definition*](https://en.wikipedia.org/wiki/Data_definition_language) and [*data control*](https://en.wikipedia.org/wiki/Data_control_language) *languages* (*DDL* / *DCL*) manage the database’s metadata: table definitions and user permissions, respectively.
- [*Data manipulation*](https://en.wikipedia.org/wiki/Data_manipulation_language) and [*data query*](https://en.wikipedia.org/wiki/Data_query_language) *languages* (*DML* / *DQL*) write to and read from the tables.
- [*Procedural language*](https://neon.tech/postgresql/postgresql-plpgsql/introduction-to-postgresql-stored-procedures) (*PL*) programs user-defined functions (*stored procedures*).


Each kind of command is processed in a unique way:

- When the parser recognizes a DDL or DCL request, it calls a corresponding method that reads or modifies the metadata. If a table is to be altered, the action will either lock the table for the duration of operation or require a complicated workaround to allow other sessions to access the table while it is being restructured.
- DML or DQL input is compiled into a tree of elementary operations (reads, conditions, joins, etc.) which is then passed to the *query optimizer* to be rearranged into a linear sequence of operations that accounts for table sizes and index types. The execution of the resulting *pipeline* depends on its type:
  - As a *query* (DQL) does not change anything, it merely [reserves a virtual *snapshot*](https://en.wikipedia.org/wiki/Multiversion_concurrency_control) of the current state of the tables, runs the compiled pipeline on the snapshot (probably taking quite a while), streams the output to the client and, finally, releases the snapshot.
  - *Commands* (*DML*) modify data, thus they involve a few extra steps. A snapshot is allocated as well, however, now it is writable, storing all the changes to the database the command’s pipeline makes. Every change is also written to a [*Write-Ahead Log*](https://en.wikipedia.org/wiki/Write-ahead_logging) (*WAL*) [*buffer*](https://stackoverflow.com/questions/39879754/wal-buffers-fills-before-the-transaction-commits). When the pipeline or a wrapping transaction completes, the database engine ensures that the data changed in the snapshot is still unchanged in the main database. In case of a conflict the snapshot and WAL buffer are dropped, a new snapshot is allocated on top of the conflicting changes in the main storage, and the command is re-applied. As soon as there are no conflicts, the WAL buffer is flushed to the *WAL file*, which is the single source of truth for the database’s crash recovery. After that the changes from the snapshot are integrated into the main data storage, marking any updated data structures as *dirty*. The snapshot and WAL buffer are released, the command returns the number of rows it changed to the user, and another background thread lazily flushes the dirty data to the file system or network storage.


*Snapshotting* ([MVCC](https://en.wikipedia.org/wiki/Multiversion_concurrency_control)) allows long-running queries ([OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing)) to return consistent data (without reporting any concurrent changes from commands) and commands ([OLTP](https://en.wikipedia.org/wiki/Online_transaction_processing)) to commit with [no need to lock](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) database records.

- PL requests are identified by keywords and forwarded to a PL-dedicated parser which checks their syntax, compiles the user-defined functions into some kind of pseudocode and stores them for further use by queries or commands.


Here we have:

- Dynamically created *streaming pipelines* that represent DQL and DML requests.
- Heavy reliance on parsers and compilers, like in *computational* software.
- A long-running main application that deals with multiple user requests that often need to be executed quickly, like in *interactive* applications.


\[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] is dedicated to the implementation of databases, which are indeed way more complex and varied than what I outlined above.

## Summary

We can discern four kinds of systems that differ in their goals, architecture, and code:

- *Control* – supervises hardware and must react with extremely low latency. It never blocks and relies on an in-memory model of the system it manages.
- *Interactive* – deals with users and should handle their actions while providing feedback in near real time. Its user-facing layer tends to be separated from the main logic.
- *Streaming* – processes boring sequences of blocks of data. Such systems are usually assembled from single-purpose components.
- *Computational* – performs a long-running calculation. It parses user input to prepare its task, then goes deep into the engine for its execution and, finally, pops up the result.


Complex real-world software usually involves two or three of these approaches.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity.md ===== -->

---
title: "Modules and complexity"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Modules and complexity.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Modules%20and%20complexity
source_license_note: "See namespace README; preserve attribution and source links."
---

# Modules and complexity

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Modules and complexity.md`.

> This chapter is loosely based on [A Philosophy of Software Design](https://blog.pragmaticengineer.com/a-philosophy-of-software-design-review/) by John Ousterhout and [my article](https://medium.com/itnext/introduction-to-software-architecture-with-actors-part-1-89de6000e0d3).

Any software system which we encounter is very likely to be too complex to comprehend all at once – the human mind is incapable of discerning a large number of entities and their relations \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. It tends to simplify reality by building abstractions: as soon as we define the many shiny pieces of metal, glass and rubber as a ‘car’ we can identify ‘highways’, ‘parking spaces’ and ‘passengers’ – we live in a world of the abstractions which we create. In the same way the software we write is built of services, processes, files, classes, procedures – modules that conceal the swarm of bits and pieces which we are powerless against. Let’s reflect on that.

## Concepts and complexity

Any system is comprised of *concepts* – notions defined in terms of other concepts. For example, if you are implementing a phonebook, you deal with *first* and *last names*, *numbers*, *sorting*, and *search*, which one must always keep in mind for any phonebook-related development task – just because requirements for the phonebook are described in terms of those concepts and their relations.

In code high-level concepts are embodied as services, modules, or directories while lower-level concepts match to individual classes, API methods, or source files.

Concepts are important because it is their quantity (or the number of the corresponding classes and methods) that defines the *complexity* of a system – the cognitive load which developers of the system face. If the programmers grasp the behavior of a component they work on in detail they tend to [become extremely productive](https://www.quora.com/What-are-some-habits-of-10x-programmers) and are often able to find [simple solutions for seemingly complex tasks](https://realmensch.org/2017/08/25/the-parable-of-the-two-programmers/). Otherwise the development is slow and requires extensive testing because the programmers are [unsure of how their changes affect the system’s behavior](https://news.ycombinator.com/item?id=18442941).


![Complexity represented as the number of interconnected nodes.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-1.png)

Figure 1: Complexity correlates with the number of entities.


## Modules, encapsulation and bounded context

Let’s return to our example. As you implement the phonebook you find out that sorting and search are way more complex than you originally thought. Once you prepare to enter the international market you are in [deep trouble](https://en.wikipedia.org/wiki/Alphabetical_order#Language-specific_conventions). Some telephony providers send 7-digit numbers, others use 10 digits, still others – 13 digits (with either “\+” or “0” for the first character). German has “ß” which is identical to “ss” while Japanese uses two alphabets simultaneously. Once you start reading standards, implementing all the weird behavior and responding to user complaints you feel that your phonebook implementation is drowning in the unrelated logic of foreign alphabets’ special cases. You need *encapsulation*.

Enter *modules*. A module wraps several concepts, effectively hiding them from external users, and exposes a simplified view of its contents \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. Introducing modules splits a complex system into several, usually less complex, parts.


![A module hides a cluster of the original nodes but creates new interface nodes which add to the complexity of the modules that use them.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-2.png)

Figure 2: Dividing a system into modules, bounded contexts highlighted.


This diagram has several important points to note:

- Modules create new concepts for their *public APIs*.
- The API entry points add to the complexity of *both* the owner module and its clients.
- The total number of concepts in the system has increased (from 18 to 22) but the highest complexity in the system has dropped (from 18 to 15).


Here we see how introducing modularity applies the [divide and conquer](https://en.wikipedia.org/wiki/Divide-and-conquer_algorithm) approach to lessen the cognitive load of working on any part of a system at the cost of a small increase in the total amount of work to be done.

In our phonebook example, the peculiarities (including case sensitivity) of the locale-aware string comparison and alphabetical sorting of contact names would be better kept behind a simple string comparison interface in order to relieve the programmer of the phonebook engine of the complexity of supporting multiple languages.

Modules represent *bounded contexts* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] – areas of the knowledge about a system that operate distinct sets of terms. In the case of phonebook the *collation* and *case sensitivity* do not matter for the phonebook engine – they are defined only in the context of language support. On the other hand, *matching a contact by number* is not defined in the language support module – that term exists only in the phonebook engine. It is the complexity of the current bounded context that a programmer struggles with.

Apart from dividing the problem into simpler subproblems, modules open the path to a few extra benefits:

- *Code reuse*. A well-written module that implements something generic may be used in multiple projects.
- *Division of labor*. Once a system is split into modules and each module is assigned one or more programmers, development is efficiently parallelized.
- *High-level concepts*. Some cases allow for merging several concepts of the original problem into higher-level aggregates, further reducing the complexity:


![Some of the interface nodes are grouped to lower the complexity.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-3.png)

Figure 3: Merged two API concepts in the green module.


For example, the original definition of a phonebook contained *first name* and *last name*. Once we separate the language support into a dedicated module, we may find out that various locales differ in the way they represent contacts: some (USA) use ‘first name \+ last name’ while others (Japan) need ‘last name \+ first name’. If we want to abstract ourselves from that detail, we should use a new concept of *full name* which conjoins first and last names in a locale-specific way. Such a change actually simplifies some of the phonebook’s representation logic and code as it replaces two concepts with one.

## Coupling and cohesion

We need to learn a couple of new concepts in order to use modules efficiently:

*Coupling* is a measure of the number (density) of connections between modules relative to the modules’ sizes.

*Cohesion* is a measure of the number (density) of connections inside a module relative to the module’s size.

The rule of thumb is to aim for *low coupling and high cohesion*, meaning that each module should encapsulate a cluster of related (intensely interacting) concepts \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. This is how we have split the system in figures 2 and 3. Now let’s see what happens if we violate the rules:


![Subdividing a complex module with many internal connections results in two complex modules because many new interface nodes are created.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-4.png)

Figure 4: The upper modules are tightly coupled.


Splitting a cohesive module (a cluster of concepts that interact with each other) yields two strongly coupled modules. That’s what we wanted, except that each of the new modules is nearly as complex as the original one. Meaning, that we now face two hard tasks instead of one. Also, the system’s performance may be poor because communication between modules is rarely optimal, and we’ve got too much of that.


![Merging loosely coupled modules only marginally reduces the overall number of nodes in the system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-5.png)

Figure 5: The lower module has low cohesion.


What happens if we put several clusters of concepts into the same module? Nothing too evil if the clusters are small – the module acquires a higher complexity than each of its constituents, but lower overall than their sum. In practice, multiple unrelated functions are often gathered in a ‘utils’ or ‘tools’ file or directory to alleviate *operational complexity*.

## Development and operational complexity

What we discussed above is *structural* or *development complexity* – the number of concepts and rules inside a bounded context. However, we also need to understand operations and components of the system as a whole, leading to *operational* or *integration complexity*:

- Does this new requirement fit into an existing module or does it call for writing a dedicated one?
- Which libraries with known security vulnerabilities do we use?
- Is there any way to cut our cloud services cost?
- 1% of requests time out. Would you please investigate that?
- My team needs to implement this and that. Do we have something fit for reuse?
- What the \*\*\*\* is [that global variable](https://news.ycombinator.com/item?id=18442941) about?
- Do we really need this code in production?
- I need to change the behavior of that shared component a little bit. Any objections?


When there are hundreds or thousands of modules deployed nobody knows the answers. That’s similar to the case of one needing to do something in Linux: hundreds of tools are pre-installed and thousands more are available as packages, but the only real way forward is first searching the web for your needs, then trying two or three recipes from the results to see which one fits your setup. Unfortunately, Google does not index your company’s code.

## Composition of modules

A module may encapsulate not only individual concepts, but even other modules. That is not surprising as an OOP class is a kind of module – it also has public methods and private members. Hiding a module inside another one removes it from the global scope, decreasing the operational complexity of the system – now it is not the system’s architect but the maintainer of the outer module who cares about the inner module. On one hand, that builds a manageable hierarchy in both the organization and the code. On the other hand, code reuse and many optimizations become nearly impossible as internal modules are hardly known organization-wide:


![When a module is hidden inside another module, there is no clear way to expose it to external clients.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-6.png)

Figure 6: Composition of modules prevents reuse.


If the functionality of our internal module is needed by our clients, we have two bad options to choose from:

## Forwarding and duplication


![The interface of the internal module is duplicated in the interface of the wrapping module.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-7.png)

Figure 7: Forwarding the API of an internal module.


We can add the API of a module which we encapsulate to our public API and forward its calls to the internal module. However, that increases the complexity and lowers the cohesion of our own module – now each client of our module is also exposed to the details of the methods of the module which we have encapsulated whether they are used or not.


![The internal module itself is duplicated outside of the module which wraps it.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Modules-8.png)

Figure 8: Duplicating an internal module.


Another bad option is to let the clients that need a module which we encapsulate duplicate it and own the copies as their own submodules. This relieves us of any shared responsibility, lets us modify and misuse our internals in any way we like, but violates [a couple](https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)) [of rules](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) of common sense.

Both approaches, namely keeping all the modules in the global scope and encapsulating utility modules through composition, found their place in history \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\]. [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) was based on the idea of reuse but fell prey to the complexity of its [[wiki/concepts/source/extension-metapatterns/orchestrator|*Enterprise Service Bus*]] which had to account for all the interactions (API methods) in the system. In response, the [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] approach turned the tide in the opposite direction: its proponents disallowed sharing any resources or code between services to enforce their decoupling.

## Summary

*Complexity* is the number of *concepts* and their relations which one must remember to work efficiently. A *module* hides some of the concepts from its users but creates new concepts (its *interface*). *Coupling* is the measure of dependencies between the modules, while *cohesion* is the same for the concepts inside a module. We prefer *low coupling and high cohesion* to group related things together.

Having too many modules causes trouble for the system’s maintainers. A module may contain other modules. When a client wants to use a submodule, the wrapping module may extend its interface to forward client’s requests to the submodule or the client may deploy a copy of the submodule for its own use. Both approaches gave rise to prominent architectures.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/orchestration.md ===== -->

---
title: "Orchestration"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Orchestration.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Orchestration
source_license_note: "See namespace README; preserve attribution and source links."
---

# Orchestration

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Orchestration.md`.

The most straightforward way to integrate services is to add a coordinating layer, called [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] after the person that assigns parts in an orchestra, on top of them:


![After a monolith is subdivided into services, an orchestrator is added to communicate with the client and with each service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Services%20to%20Orchestrator.png)


The good thing is that your *Orchestrator* has explicit code for every use case it covers and every running scenario gets an associated thread, coroutine, or object so that you are able to attach to the *Orchestrator* and debug any use case step by step. Nor do you have to worry about keeping the state of the services consistent as they are passive with all the changes in the system being driven by the *Orchestrator*.

Orchestration is the default approach for single-process (desktop) applications where it is faster to call into an orchestrated module and return than to send it a message. However, in distributed systems orchestration doubles the communication overhead (when compared to [[wiki/concepts/source/foundations-of-software-architecture/choreography|choreography]] or [[wiki/concepts/source/foundations-of-software-architecture/shared-data|shared data]]) as every method call into an orchestrated service uses two messages: request and confirmation.

## Roles

In a backend which serves client requests an *Orchestrator* takes the role of [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] – a module that provides and implements a high-level interface for a multicomponent system. It sends requests to the underlying services and waits for their confirmations – the mode of action that can be wrapped in an [*RPC*](https://en.wikipedia.org/wiki/Remote_procedure_call) (*remote procedure call*). The state of each scenario that the facade runs resides in the associated thread’s or coroutine’s call stack (for [[wiki/concepts/source/basic-metapatterns/monolith|*Reactor*]] or [[wiki/concepts/source/basic-metapatterns/monolith|*Half-Sync/Half-Async*]] implementations, respectively) or in a dedicated object (for [[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]]).


![A facade uses request/confirm pairs of messages to communicate with the services which it orchestrates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Facade.png)


A *Facade* also supports querying the services in parallel and collecting the data returned into a single message through the *Splitter* and *Aggregator* patterns of \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\]. That reduces latency (and resource consumption as the whole task is completed faster) for [scatter-gather](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/scatter-gather.html) requests when compared to sequential execution.


![A facade initiates communication with every service that it orchestrates simultaneously in a fan-out manner.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Facade%20-%20Parallel.png)


Embedded and systems programming – the areas that deal with automating [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control*]] of hardware or distributed software – employ *Orchestrators* as [*Mediators*](https://refactoring.guru/design-patterns/mediator) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\]  – components that keep the state of the whole system (and, by implication, any hardware it may manage) consistent by enacting a system-wide reaction to any observable change in any of the system’s constituents. A mediator operates in non-blocking, fire-and-forget mode which is more characteristic of choreography, to be discussed [[wiki/concepts/source/foundations-of-software-architecture/choreography|below]]. This also means that you will not be able to debug a use case as a thread – because [there are no predefined scenarios in control software](https://medium.com/itnext/control-and-processing-software-9011fee8bc66)!


![A mediator receives an input from one component, processes it, and initiates actions in other components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mediator.png)


Such a difference may be rooted in the direction of the control and information flow: in a backend it comes as a complex, high-level request while a control system reacts to a flood of low-level events.

## Dependencies

By default an *Orchestrator* depends on each service which it manages – that means that a change in a service’s interface or contract – caused by fixing a bug, adding a feature, or optimizing performance – requires corresponding changes in the *Orchestrator*. That is acceptable as the *Orchestrator*’s client-facing, high-level logic tends to evolve much faster than the business rules of the lower layer of services, therefore the team behind the *Orchestrator*, unrestricted by other components depending on it, will likely release way more often than any other team. However, as the number of the managed services and the lengths of their APIs increase, so does the amount of information that the *Orchestrator*’s team must remember and the influx of changes which they must integrate in their code. For a large project the workload of supporting the *orchestration layer* may paralyze its development – that was a major reason behind the decline of [*Enterprise SOA*](<Service-Oriented Architecture (SOA)#enterprise-soa>) where [[wiki/concepts/source/extension-metapatterns/orchestrator|*ESB*]] used to orchestrate all the interactions in the system, including those between domain-level services and components of the utility layer.


![An orchestrator depends on every service which it uses.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Orchestrator%20-%20Dependencies.png)


Another option, which appears in [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and develops in [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], stems from [*dependency inversion*](https://en.wikipedia.org/wiki/Dependency_inversion_principle): the *Orchestrator* defines an [*SPI*](https://en.wikipedia.org/wiki/Service_provider_interface) (*service provider interface*) for every service. That makes each service depend on the *Orchestrator* so that a single *Orchestrator*’s team does not need to follow updates of the multiple services’ APIs – instead it initiates the changes at its own pace. However, with that approach the design of an SPI requires coordination from the teams on both sides of it and the once settled interface becomes hard to change. The most famous example of modules that implement SPIs are OS drivers.


![In a Microkernel each managed service depends on a dedicated Service Provider Interface of the microkernel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Microkernel%20-%20Dependencies.png)


Furthermore, some domains develop that idea into a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]]: when services implement related concepts, they may match a single SPI, making the *Orchestrator* simpler (as there is no further need for its developers to remember multiple interfaces). That is the case with telecom or payment gateways and it may also be found with trees of product categories in online marketplaces.


![In a hierarchy each child component depends on the same Service Provider Interface of their parent component.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Hierarchy%20-%20Dependencies.png)


All kinds of orchestration allow for an easy addition of new use cases which may even involve new services as that changes nothing in the existing code. However, removing or restructuring (splitting or merging) previously integrated services requires much work within the orchestrator, except for in a *Hierarchy* where all the services implement the same interface which means that the code in the *Orchestrator* does not depend (much) on any specific child.


![Adding a new use case to an orchestrated system changes only the orchestrator.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Orchestrator%20add%20a%20Use%20Case.png)


## Mutual orchestration

In some systems there are several services that have their own kinds of clients (for example, employees of different departments). Each of the services tries hard to process its clients’ requests on its own but occasionally still needs help from other parts of the system. This creates a paradoxical case where several services orchestrate each other:


![A set of services which call each other while executing requests from their clients.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mutual%20Orchestration%20-%201.png)


As each of the services depends on the APIs of the others, any change to any interface or composition of such a system requires consent and collaboration from every team as it impacts the code of all the services.


![Each service depends on every other service which it calls.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mutual%20Orchestration%20-%202.png)


In real life [[wiki/concepts/source/fragmented-metapatterns/layered-services|services are likely to be layered]], with their upper layers acting as both internal and external *Orchestrators*. Layering isolates interdependencies to the relatively small [[wiki/concepts/source/basic-metapatterns/layers|application-level]] components and resolves, to an extent, the seemingly counterintuitive case of mutual orchestration as now there is an explicit, though fragmented, system-wide orchestration layer.


![In Layered Services only the application layers of the services call each other.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mutual%20Orchestration%20-%203.png)


![In Layered Services only the application layers of the services are interdependent.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mutual%20Orchestration%20-%204.png)


## Summary

Orchestration represents [[wiki/concepts/source/basic-metapatterns/layers|use cases]] as a code, allowing for an orchestrated system to support many complex scenarios. Dealing with errors is as trivial as properly handling exceptions. This approach trades performance for clarity.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms.md ===== -->

---
title: "Programming and architectural paradigms"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Programming and architectural paradigms.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Programming%20and%20architectural%20paradigms
source_license_note: "See namespace README; preserve attribution and source links."
---

# Programming and architectural paradigms

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Programming and architectural paradigms.md`.

Sharing a database is the greatest sin when you architect [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] yet [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] is built around shared data. How do these approaches coexist? Does *Microservice Architecture* make any sense if blatantly violating its principles still results in successful projects?

Another programming paradox holds a clue. There was C. Then there came C\+\+ to kill C. Then we’ve got Rust to kill C\+\+. Now we have C, C\+\+, and Rust, all of them alive and kickin’.

## Technologies are specialized

When a new technology emerges, it must show its superiority over existing mature methods. In most cases that is achieved by specialization. Is a car superior to a donkey? It depends. Probably yes, when there are good roads, plenty of gas, and spare parts. A car is narrowly specialized, thus some areas have successfully adopted cars, while others still rely on donkeys.

The same holds true for programming languages and architectures. C is good when you work close to hardware and need complete control over whatever happens in the system. C\+\+ is great at partitioning business logic, but it lost the simplicity of its predecessor. Rust will likely shine in communication libraries, which are often targeted by hackers, though we have yet to see its wide adoption. Hence the usefulness (and choice) of a tool or programming language depends on the circumstances.

Let’s turn our attention to your average code. It often mixes together:

- *Object-oriented* programming that divides the application into a tree of loosely interacting pieces.
- *Functional* programming, with the output of one function becoming the input to another, [method chaining](https://en.wikipedia.org/wiki/Method_chaining) included.
- *Procedural* programming, where multiple functions access the same set of data, which also happens inside classes whose many methods operate their private data members.


Each [programming paradigm](https://en.wikipedia.org/wiki/Programming_paradigm) fits its own kind of tasks. Moreover, the same three approaches reemerge at the system level:

## Object-oriented (centralized, shared nothing) paradigm – orchestration

Almost every software project is too complex for a programmer to keep all the details of its requirements and implementation in their mind. Notwithstanding, those details must be written down and run as code.

The good old way out of the trouble is called [*divide and conquer*](https://en.wikipedia.org/wiki/Divide-and-conquer_algorithm). The global task is divided into several subtasks, and each subtask is subdivided again and again – till the resulting pieces are either simple enough to solve directly or [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|too messy]] to allow for further subdivision. Essentially, we need to split our domain’s *control*, *logic*, and *data* into a single hierarchy of moderately sized components.

We have heard a lot about keeping *logic and data* together: an object (or [[wiki/concepts/source/basic-metapatterns/services|actor]], or [[wiki/concepts/source/basic-metapatterns/services|module]], or [[wiki/concepts/source/basic-metapatterns/services|service]] – no matter what you call it) must own its data to assure its consistency and hide the complexity of the component’s internals from its users. If the encapsulation of an object's data is violated, the object’s code can neither trust nor ever restructure it. On the other hand, if the data is bound to the logic that deals with it, the entire thing becomes a useful black box which one does not need to look into to operate.

Adding *control* to the blend is more subtle, but no less crucial than the encapsulation discussed above. If an object commands another thing to do something, it must receive the result of the delegated action to know how to proceed with its own task. Returning control after the action is conducted enables separation of high-level supervising (orchestration, integration) logic from low-level algorithms which it drives, adding depth to the structure.


![A diagram of an object-oriented system built through composition.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Object-oriented.png)


The ability to address complex domains by reducing the whole to self-contained pieces makes object-oriented design ubiquitous. This paradigm, when applied to distributed systems, gives birth to [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated Services*]], and [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>).


![Diagrams of: Microservices, Orchestrated Services, and Service-Oriented Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Object-oriented%20-%20Variants.png)


## Functional (decentralized, streaming) paradigm – choreography

Sometimes you don’t need that level of fine-tuning for the behavior of the system you build – it operates as an [assembly line](https://en.wikipedia.org/wiki/Assembly_line) with high throughput and little variance: its logic is made of steps that resemble work stations along a [conveyor belt](https://en.wikipedia.org/wiki/Conveyor_belt) through which identically structured pieces of data flow. In that case there is very little to control: if an item is good, it goes further, otherwise it just falls off the line. Here the *control* resides in the graph of connections*,* the [[wiki/concepts/source/basic-metapatterns/layers|domain *logic*]] is subdivided, while the *data* is copied (or, more rarely, moved) between the components.


![A diagram of a pipeline with components implementing steps of data processing.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Functional.png)


Functional or pipelined design is famous for its simplicity and high performance as the majority of processing steps can be scaled. However, its straightforward application lacks the depth needed for handling complex processes, which would translate into webs of relations between hundreds of functions present at the same level of design. It is also inefficient for choose-your-own-adventure-style ([[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control*]]) systems where too many too short conveyor belts would be required, negating the paradigm’s benefits. And it may not be the right tool for making small changes in large sets of data as you’ll likely need to copy the whole dataset between the constituent functions.

In distributed systems the functional paradigm is disguised as [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]], [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]], and various [[wiki/concepts/source/basic-metapatterns/pipeline|batch or stream]] processing \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]].


![Diagrams of Event-Driven Architecture and Data Mesh.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Functional%20-%20Variants.png)


## Procedural (data-centric) paradigm – shared data

The final approach is integration through data. There are cases where the domain data and business logic differ in structure – you cannot divide your project into objects because each of the many pieces of its logic needs to access several (seemingly unrelated) parts of its data.


![A diagram of a procedural system where logic and data make independent hierarchies.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Data-centric.png)


In the data-centric paradigm *logic* and *data* are orthogonal. There are two ways to deal with the control:

- In procedural programming, like in object-oriented paradigm, *control* is implemented inside the logic, making the logic layer hierarchical ([[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrated*]]), as on the diagram above.
- Another, much less common, option relies on [*Observer*](https://refactoring.guru/design-patterns/observer) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] to provide data change notifications, resulting in decentralized ([[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]]) application logic, as shown below.


![Components of a data-centric system rely on data change notifications.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Data-centric%20-%20Notifications.png)


The data-centric approach works well for moderately-sized projects with a stable data model (like reservation of seats in trains or the game of chess). The best-known distributed data-centric architectures include [[wiki/concepts/source/extension-metapatterns/shared-repository|*Services with a Shared Database*]] and [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]].


![Diagrams for Services with a shared database and Space-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Paradigms%20-%20Data-centric%20-%20Variants.png)


## Composite cases

The three programming paradigms tend to collaborate:

- An ordinary class is object-oriented on the outside but procedural inside: each of its methods can access any of its private data members. Moreover, a class  method may chain function calls, applying the functional paradigm to two or three lines of its code.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] tends to use [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]] (pub/sub) between [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]] and [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]] or communication via a [[wiki/concepts/source/foundations-of-software-architecture/shared-data|*shared database*]] inside them \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\].
- A system of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] (or [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]]) may be integrated through both [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] (or [[wiki/concepts/source/extension-metapatterns/orchestrator|*processing grid*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*data grid*]], respectively), see [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]].


## Reality is more complex

We have reviewed a few cases directly supported by common programming languages. However, there is a wide variety of possible combinations of (at least) the following dimensions, each making a unique programming paradigm:

- Synchronous (method calls) vs asynchronous (messaging), with closely related:
  - Imperative vs reactive.
  - Blocking vs non-blocking.
- Centralized (orchestrated) vs decentralized (choreographed) flow.
- Shared data (tuple space) vs [shared nothing](https://en.wikipedia.org/wiki/Shared-nothing_architecture) (messaging).
- Commands (actors) vs notifications (agents).
- One-to-one (channels) vs many-to-one (mailboxes) vs one-to-many (multicast) vs many-to-many (gossip) communication.


Some of the combinations look impossible or impractical, others are narrowly specialized thus uncommon, while many more are commonplace. Discussing all of them would require insights from people who have used them in practice and would likely take a dedicated book.

## Summary

We have deconstructed the most common programming paradigms into their driving forces and shown how those forces shape distributed architectures:

- An object-oriented system relies on hierarchical decomposition of a complex domain, just like [*SOA*](<Service-Oriented Architecture (SOA)>) and [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated (Micro-)Services*]] do.
- Functional programming streams data through a sequence of transformations, which is the idea behind [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]].
- Procedural style lets any piece of logic access the entire project’s data, resembling [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Services with a Shared Database*]].


Now let’s examine each of these approaches in depth:


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/foundations-of-software-architecture/shared-data.md ===== -->

---
title: "Shared data"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Foundations of software architecture/Arranging communication/Shared data.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Foundations%20of%20software%20architecture/Arranging%20communication/Shared%20data
source_license_note: "See namespace README; preserve attribution and source links."
---

# Shared data

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Foundations of software architecture/Arranging communication/Shared data.md`.

The final approach is integration through shared data ([[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]):


![After a monolith is subdivided into services, a shared database is used to integrate the services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Services%20to%20Shared%20Data.png)


The shared data is a “blackboard” available for each service to read from and write to. It is passive (as controlled by the services) and does not contain any logic except for the data schema, which represents a part of the domain knowledge. That makes communication through shared data the antipode of [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestration]], which also features a shared component, namely an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], which is, however, active (controls services) and contains business logic, not data.

Shared data can be used for storage, messaging, or both:

## Storage

The most common case of shared data is persistent storage (usually a database, sometimes a file system) for a (sub)domain that comprises functionally independent services which operate on a common dataset. For example, a ticket purchase service and a ticket refund service share a database of ticket details. The ticket purchase service reads in the available seats and fills in ticket data for purchases. The ticket refund service should be able to find all tickets bought by a user and delete the user data from seats refunded. The only communication between the purchase and refund services is the shared database of tickets or seats, so that one of them sees the changes made by the other the next time it reads the data.


![Both purchase and refund services see and edit the entire system's data.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Purchase%20and%20Return.png)


With this model the services don’t depend on each other – instead, they depend on the shared (domain) data format and the database technology. Thus, it is easy to add, modify, or remove services but hard to change the shared data structure or the database vendor.


![Each service depends only on the shared database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Shared%20Data%20-%20Dependencies.png)


![Adding a service to a system integrated through shared data does not require changes to other services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Shared%20Data%20add%20a%20Service.png)


Services usually need to coordinate their actions. Commonly, services with a shared database rely on a messaging [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for communication. Users of our ticketing system will want to be notified (through email, SMS or an instant message) when a free seat that they are interested in appears. We’re not going to complicate either of the existing services by integration with instant messengers, so we will create a new notification service, which must track each returned ticket to see if any user wants to buy it. This is easily implemented by the refund service publishing and the notification service subscribing to a ticket refund event, mixing in a bit of choreography into our data-centric backend.


![A diagram of a ticketing service whose components use direct messaging to intercommunicate.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Notification%20to%20Notification.png)


Another case is found with data processing pipelines where an element may periodically read new files from a folder or new records from a database table to avoid implementing notifications. This increases latency and may cause a little CPU load when the system is idle, but is perfectly ok for long-running calculations.


![Stepwise processing of a batch of files.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Shared%20files.png)


Finally, there is the rarely used option of an external [[wiki/concepts/source/extension-metapatterns/proxy|*Scheduler*]] which selects the services which should run based on the data available. This is known as [[wiki/concepts/source/extension-metapatterns/sandwich|*Blackboard System*]], and [[wiki/concepts/source/basic-metapatterns/monolith|something similar]] happens in 3D game engines. The *Scheduler* (which in this case serves as an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) is needed when CPU (or GPU or RAM) resources are much lower than what the services would consume if all of them ran in parallel, thus they must be given priorities, and the priorities change based on the context which is regularly estimated from the latest data.


![Components of the Blackboard Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Blackboard.png)


> There is no clear distinction between [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] and [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], and between [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] and [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]]. Their [[wiki/concepts/source/introduction/system-topologies|topologies]] are identical, and functionality is often intermixed. Indeed, a database can be used for messaging, as we see below, and many communication frameworks store the history of messages; while the [[wiki/concepts/source/introduction/system-topologies|managing layer]] can both provide protocol support and implement use cases, as seen with [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateways*]]. *Scheduler*, which is normally a *Proxy* with a simple [round-robin](https://micrium.atlassian.net/wiki/spaces/osiiidoc/pages/131360/Round-Robin+Scheduling) or [preemption](https://micrium.atlassian.net/wiki/spaces/osiiidoc/pages/131347/Preemptive+Scheduling) algorithm, in *Blackboard* is delegated complex strategic planning, which turns it into an *Orchestrator*.

## Messaging

The other, not as obvious, use case for shared data is messaging, which is implemented by the sender writing to a (shared) queue (or log) while the recipient is waiting to read from it. Queues can be used for any kind of messages: request/confirm pairs, commands, or notifications. Each service may have a dedicated queue (either input for commands mode or output for notifications), a pair of queues (messages from the service’s output are duplicated by an underlying distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to input queues of their destinations), or there may be a queue per communication channel, or a single queue for the entire system (or one global-level queue per message priority) with each message carrying destination id (for commands) or topic (for notifications).


![Diagrams for: a queue per service, separate input and output queues, a queue per channel, and a single system queue.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Queues.png)


The use of shared data for messaging turns our data store into a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]. The dependencies are identical to [[wiki/concepts/source/foundations-of-software-architecture/choreography|those in choreography]] – each service depends on the APIs of its destinations for commands or its sources for notifications.

There should be a means for the recipient of a message to know about its arrival so that it starts processing the input. Usually a messaging *Middleware* implements a receive() method for the service to block on. However, very low latency applications, like [HFT](https://en.wikipedia.org/wiki/High-frequency_trading), may [busy-wait](https://en.wikipedia.org/wiki/Busy_waiting) by repeatedly re-reading the shared memory so that the service starts processing the incoming data immediately on its arrival, bypassing the OS scheduler. This is the fastest means of communication available in software.

## Full-featured

Finally, some (usually distributed) data stores implement data change notifications. That allows for the services to communicate through the data store in near real-time, removing both the need for an additional *Middleware* and interdependencies for the services. Such a system follows the [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] pattern of \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] which was rectified as [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]]. In our example, the available seats notification service subscribes to changes in the seats data in the database – this way it does not need to be aware of the existence of other services at all. We can also move the email notifications logic of the ticket purchase service into a separate component which would track purchases in the database and send a printable version of each newly acquired ticket to the buyer’s email address which can be found in the ticket details in the database.


![A diagram of a ticketing service whose components rely on database notifications.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Notification%20inside%20the%20DB.png)


## Summary

Communication through shared data is best suited for data-centric domains (for example, ticket purchase). It allows for the services to be unaware of each other’s existence, just as they are with orchestration, but the structure of the domain data becomes hard to change as it is referenced all over the code. Shared data may also be used to implement messaging.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/backends-for-frontends-bff.md ===== -->

---
title: "Backends for Frontends (BFF)"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Backends for Frontends (BFF).md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Backends%20for%20Frontends%20%28BFF%29
source_license_note: "See namespace README; preserve attribution and source links."
---

# Backends for Frontends (BFF)

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Backends for Frontends (BFF).md`.


![A diagram for Services with Backends for Frontends, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Backends%20for%20Frontends.png)


*Hire a local guide.* Dedicate a service for every kind of client.

<ins>Known as:</ins> Backends for Frontends (BFF), [Layered Microservice Architecture](https://github.com/wso2/reference-architecture/blob/master/api-driven-microservice-architecture.md).

<ins>Structure:</ins> A layer of integration services over a shared layer of core services.

<ins>Type:</ins> Extension component, derived from [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] and/or [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]].

| *Benefits* | *Drawbacks* |
| --- | --- |
| Clients become independent in their protocols, workflows and, to an extent, qualities | No single place for cross-cutting concerns |
| A specialized team and technology per client may be employed | More work for the DevOps team |
| The multiple *Orchestrators* are smaller and more cohesive than a universal one would be |  |

<ins>References:</ins> The [original article](https://samnewman.io/patterns/architectural/bff/), a [smaller one](https://learn.microsoft.com/en-us/azure/architecture/patterns/backends-for-frontends) from Microsoft, and an [excerpt](https://microservices.io/patterns/apigateway.html) from \[[wiki/concepts/source/appendices/books-referenced|[MP]]\]. Here are the [reference diagrams](https://github.com/wso2/reference-architecture/blob/master/api-driven-microservice-architecture.md) from WSO2 (notice multiple *Microgateway* \+ *Integration Microservice* pairs).

If some aspect(s) of serving our system’s clients strongly vary by client type (e.g. OLAP vs OLTP requests, user vs admin privileges, buyer vs seller vs customer support roles), it makes sense to use a dedicated component (the titular *Backend for Frontend* or *BFF*) per client type to encapsulate that variation. Protocol variations call for multiple [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]], workflow variations – for several [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]], both coming together – for [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateways*]] or *Proxy \+ Orchestrator* pairs. It is even possible to vary the *BFF*’s programming language on a per client basis. The drawback is that once the clients get their dedicated *BFFs* it becomes hard to share a common functionality between them, unless you are willing to add yet another new utility [[wiki/concepts/source/basic-metapatterns/services|*service*]] (that will strongly smell of [*SOA*](<Service-Oriented Architecture (SOA)>)) or a [[wiki/concepts/source/basic-metapatterns/layers|*layer*]] that can be used by each of them.

### Performance

As the multiple *Orchestrators* of *BFF* don’t intercommunicate, the pattern’s performance is identical to that of an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]: it also slows down request processing in the general case but allows for several [[wiki/concepts/source/extension-metapatterns/orchestrator|specific optimizations]], including direct communication channels between the orchestrated [[wiki/concepts/source/basic-metapatterns/services|services]].

### Dependencies

Each *BFF* depends on all the services which it uses (usually every service in the system). The services themselves are likely to be independent, as is common in [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrated* systems]].


![Each Backend for Frontend depends on every service which it calls.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Backends%20for%20Frontends.png)


### Applicability

*Backends for Frontends* are <ins>good</ins> for:

- *Multiple client protocols.* Deploying a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] per protocol hides the variation from the underlying system.
- *Multiple UIs.* When you have one team per UI, each of them may [want to have](https://netflixtechblog.com/embracing-the-differences-inside-the-netflix-api-redesign-15fd8b3dc49d) an API which they feel comfortable with.
- *Drastically different workflows.* Let each client-facing development team own a component and choose the best fitting technologies and practices.


*Backends for Frontends* <ins>should be avoided</ins> when:

- *The clients are mostly similar.* It is hard to share code and functionality between *BFF*s. If the clients have much in common, the shared aspects either find their place in a shared monolithic layer (e.g. multiple client protocols call for multiple [[wiki/concepts/source/extension-metapatterns/proxy|*Gateways*]] but a shared [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]) or are duplicated. *BFF* may not be the best choice – use OOD (conditions, factories, strategies, and inheritance) instead to handle the clients’ differences within a single codebase.


### Relations


![Diagrams of Backends for Frontends over a monolith, layers, shards, and services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/BFF.png)


*Backends for Frontends*:

- Extends [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or rarely [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]].
- Is derived from a client-facing extension pattern: [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]], or [[wiki/concepts/source/extension-metapatterns/orchestrator|*Event Mediator*]].


## Variants

*Backends for Frontends* vary according to the kind of component that gets dedicated to each client:

- A [*Proxy*](#proxies) per client when clients differ in protocols.
- An [*Orchestrator*](#orchestrators) or [*Event Mediator*](#event-mediators) per client for different client roles and use cases.
- A [*Proxy \+ Orchestrator* pair](#proxy--orchestrator-pairs) or an [*API Gateway*](#api-gateways) when clients differ in both protocols and roles.


### [[wiki/concepts/source/extension-metapatterns/proxy|Proxies]]


![Each gateway in the Backends for Frontends layer adapts its client's protocol and calls the services of the domain layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/BFF%20-%20Gateways.png)


Dedicating a [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] per client is useful when the clients differ in the mode of access to the system (protocols / encryption / authorization) but not in workflows.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrators]]


![Each orchestrator in the Backends for Frontends layer calls the services of the domain layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/BFF%20-%20Orchestrators.png)


An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] per client makes sense if the clients use the system in completely unrelated ways, e.g. a shop’s customers have little to share with its administrators.

### [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]] \+ [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]] pairs


![In each pair in the Backends for Frontends layer the gateway adapts its client's protocol while the orchestrator calls the services of the domain layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/BFF%20-%20Gateways%20%2B%20Orchestrators.png)


Clients vary in both access mode (protocol) and workflow. [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] or [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] may be reused if some kinds of clients share only the protocol or [[wiki/concepts/source/basic-metapatterns/layers|*application logic*]].

### [[wiki/concepts/source/extension-metapatterns/orchestrator|API Gateways]]


![Each API Gateway in the Backends for Frontends layer both adapts its client's protocol and orchestrates the services of the domain layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/BFF%20-%20API%20gateways.png)


Clients vary in access mode (protocol) and workflow and there is a third-party [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] framework which seems to fit your requirements off the shelf.

Multiple *API Gateways* match the literal meaning of *Backends for Frontends* – each UI team ([backend, mobile, desktop](https://www.thoughtworks.com/insights/blog/bff-soundcloud); or [end-device-specific](https://netflixtechblog.com/embracing-the-differences-inside-the-netflix-api-redesign-15fd8b3dc49d) teams) gets some code on the backend side to adapt the system’s API and protocols to its needs by building a new, probably higher-level specialized API with a convenient transport.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Event Mediators]]


![Each event mediator in the Backends for Frontends layer orchestrates the services of the domain layer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/BFF%20-%20Event%20mediators.png)


\[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] mentions that multiple [[wiki/concepts/source/extension-metapatterns/orchestrator|*Event Mediators*]] may be deployed in [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]] to split the codebase and improve stability.

## Evolutions

*BFF*-specific evolutions aim at sharing logic between the *BFF*s:

- The *BFF*s can be merged into a single [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] if their functionality becomes mostly identical.
- A shared *orchestration* [[wiki/concepts/source/basic-metapatterns/layers|*layer*]] with common functionality may be added for use by the *BFF*s.
- A layer of *Integration Services* under the *BFF*s simplifies them by providing shared high-level APIs for the resulting [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]].
- [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] (of [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]]) are a way to share libraries among the *BFF*s.


![Backends for Frontends can be merged into an Orchestrator, can share code via sidecars, or put shared functionality into a dedicated orchestration layer or into Cell gateways.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/BFF.png)


## Summary

*Backends for Frontends* assigns a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] and/or an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] per each kind of a system’s client to encapsulate client-specific use cases and protocols. The drawback is that there is no good way for sharing functionality between the *BFF*s.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns.md ===== -->

---
title: "Fragmented metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Fragmented metapatterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Fragmented%20metapatterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Fragmented metapatterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Fragmented metapatterns.md`.

There are several [[wiki/concepts/source/introduction/system-topologies|topologies]] with no system-wide layers. Some of them incorporate two or three orthogonal domains which vary in abstractness to the extent that a service (limited to a subdomain) of one domain acts as a layer for another domain.

### [[wiki/concepts/source/fragmented-metapatterns/layered-services|Layered Services]]


![A diagram of Layered Services, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Layered%20Services.png)


[[wiki/concepts/source/fragmented-metapatterns/layered-services|*Layered Services*]] is an umbrella metapattern which highlights implementation details of [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], or [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]].

*<ins>Includes</ins>*: Orchestrated Three-Layered Services, Choreographed Two-Layered Services, and Command Query Responsibility Segregation (CQRS).

### [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]]


![A diagram of Services with Polyglot Persistence, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Polyglot%20Persistence.png)


[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] is about using multiple data stores which differ in roles or technologies. Each of the upper-level components may have access to any data store. Each data store is a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].

*<ins>Includes</ins>*: specialized data stores, private and shared databases, data file, and Content Delivery Network (CDN); read-only replicas, Reporting Database, CQRS View Database, Memory Image, Query Service, search index, historical data, and Cache-Aside.

### [Backends for Frontends](<Backends for Frontends (BFF)>)


![A diagram of Services with Backends for Frontends, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Backends%20for%20Frontends.png)


[*Backends for Frontends*](<Backends for Frontends (BFF)>) feature a service (*BFF*) for each kind of the system’s client. A *BFF* may be a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], or both. Each *BFF* communicates with all the components below it. The pattern looks like multiple *Proxies* or *Orchestrators* deployed in parallel.

*<ins>Includes</ins>*: Layered Microservice Architecture.

### [Service-Oriented Architecture](<Service-Oriented Architecture (SOA)>)


![A diagram of Service-Oriented Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Service-Oriented%20Architecture.png)


[*SOA*](<Service-Oriented Architecture (SOA)>) comprises three or four layers of services, with each layer making a domain. The upper layer contains [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] which are often client-specific, just like [*BFF*](<Backends for Frontends (BFF)>)*s*. The second layer incorporates business rules and is divided into business subdomains. The lower layer(s) are libraries and utilities, grouped by functionality and technologies. Any component may use (orchestrate) anything below it.

*<ins>Includes</ins>*: distributed monolith, enterprise SOA, and Domain-Oriented Microservice Architecture (DOMA).

### [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]


![A diagram of Hierarchy, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Hierarchy.png)


Some domains allow for [[wiki/concepts/source/fragmented-metapatterns/hierarchy|hierarchical composition]] where the functionality is spread over a tree of components.

*<ins>Includes</ins>*: Orchestrator of Orchestrators, Presentation-Abstraction-Control (PAC) and Hierarchical Model-View-Controller (HMVC), Bus of Buses, and the WSO2 version of Cell-Based (Microservice) Architecture (Services of Services).


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/hierarchy.md ===== -->

---
title: "Hierarchy"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Hierarchy.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Hierarchy
source_license_note: "See namespace README; preserve attribution and source links."
---

# Hierarchy

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Hierarchy.md`.


![A diagram for Hierarchy, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Hierarchy.png)


*Command and conquer.* Build a tree of responsibilities.

<ins>Structure:</ins> A tree of components.

<ins>Type:</ins> System topology or extension component.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Very good in decoupling logic | Global use cases may be hard to debug |
| Supports multiple development teams and technologies | Poor latency for global use cases |
| Components may vary in their qualities | Operational complexity |
| Low-level components are easy to replace | Slow start of the project |
| Limited fault tolerance |  |

<ins>References:</ins> None good I know of.

Though not applicable to every domain, hierarchical decomposition is arguably the best way to distribute responsibilities between components. It limits the connections (thus the number of interfaces and contracts for the team to keep in mind) of each component to its parent and a few children, allowing for the building of complex (and even complicated) systems in a simple way. The hierarchical structure is very flexible as it features [multiple layers of indirection](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering) (and often polymorphism), which makes addition, replacement, or [stubbing/mocking](https://stackoverflow.com/questions/3459287/whats-the-difference-between-a-mock-stub) of leaf components trivial. It is also quite fault-tolerant as individual subtrees operate independently.

This architecture is not ubiquitous because few domains are truly hierarchical. Its high fragmentation results in increased latency and poor debugging experience. Moreover, component interfaces must be designed beforehand and are hard to change.

### Performance

No kind of distributed hierarchy is latency-friendly as many use cases involve several network hops. The fewer layers of the hierarchy are involved in a task, the better its performance.


![Comparison of latency for decision-making at various levels of a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Hierarchy%20-%20speed.png)


Maintaining high throughput usually requires deployment of multiple instances of the root component, which is not possible if it is stateful (as in [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|*control systems*]]) and the state cannot be split into [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]]. The following tricks may help unloading the root:

- *Aggregation* ([[wiki/concepts/source/basic-metapatterns/layers|first met]] in [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]]): a node of a hierarchy collects reports from its children, aggregates them into a single package, and sends the aggregated data up to its parent. This greatly reduces traffic to the root in large [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things) networks.
- *Delegation* (resembles [[wiki/concepts/source/basic-metapatterns/layers|strategy injection and batching]] for [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]]): a node should try to handle all the low-level details of communication with its children without consulting its parent node. For a [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|control system]] that means that its mid-level nodes should implement control loops for the majority of incoming events. For a [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|computational system]] that means that its mid-level nodes should expose coarse-grained interfaces to their parent(s) while translating each API method call into multiple calls to their child nodes.
- *Direct communication channels* ([[wiki/concepts/source/extension-metapatterns/orchestrator|previously described]] for [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]): if the low-level nodes need to exchange data, their communication should not always go through the higher-level nodes. Instead, they may negotiate a direct link (open a socket) that bypasses the root of the hierarchy.


![Aggregation of data in mid-level nodes; autonomous decision-making by mid-level nodes; direct communication between low-level nodes of a hierarchy.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Hierarchy%20-%20optimizations.png)


### Dependencies

A parent node would usually define one (for polymorphic children) or more (otherwise) [*SPIs*](https://en.wikipedia.org/wiki/Service_provider_interface) for its child nodes to implement. The interfaces reside on the parent side because low-level nodes tend to be less stable (new types of them are often added and old ones replaced) therefore we don’t want our main business logic to depend on them.


![In Hierarchy a child component depends on an SPI of its parent component. If the children are polymorphic, their parent has a single SPI.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Hierarchy.png)


### Applicability

*Hierarchy* <ins>fits</ins> with:

- *Large and huge projects.* The natural division by both level of abstractness and subdomain allows for using smaller modules, ideally with intuitive interfaces. The APIs for each team to learn are limited to just a few which their component interacts with directly.
- *Systems of hardware devices.* Real-world [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things) systems may use a hierarchy of controllers to benefit from [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|autonomous decision-making and data aggregation]].
- *Customization*. The tree-like structure provides opportunities for easy customization. A medium-sized hierarchical system may integrate hundreds of leaf types.
- *Survivability*. A distributed hierarchy retains limited functionality even if several of its nodes fail.


*Hierarchy* <ins>fails</ins> with:

- *Cohesive domains.* Horizontal interactions between nodes that belong to the same layer bloat interfaces as they have to pass through parent nodes.
- *Quick start*. Finding (and verifying) a good hierarchical domain model may be hard if at all possible. Debugging an initial implementation will not be easy.
- *Low latency*. System-wide scenarios involve many cross-component interactions which are slow in distributed systems.


### Relations


![Diagrams of Orchestrator of Orchestrators, Middleware of Middlewares, and Services of Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Hierarchy.png)


*Hierarchy*:

- Can be applied to [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]]*,* [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] or [[wiki/concepts/source/basic-metapatterns/services|*Services*]].


## Variants by structure (may vary per node)

*Hierarchy* comes in various shapes as it is more of a design approach than a ready-to-use pattern:

### Polymorphic children

All the child nodes managed by a given parent node expose the same interface and contract. This tends to simplify the implementation of the parent and resembles the inheritance of OOD.

Example: a fire alarm system may treat all of its fire sensors as identical devices, even though the real hardware comes from many manufacturers.

### Functionally distinct children

The managing node is aware of several kinds of children that vary in their APIs and contracts, just like with the composition in OOD.

Example: an intrusion alarm logic may need to discern between cat-affected IR sensors and mostly cat-proof glass break detectors.

## Variants by direction

A *Hierarchy* may have its root [at the top](#top-down-hierarchy-orchestrator-of-orchestrators-presentation-abstraction-control-pac-hierarchical-model-view-controller-hmvc) (client side), [at the bottom](#bottom-up-hierarchy-bus-of-buses-network-of-networks-hierarchical-middleware) (deep infrastructure), or [no root at all](#in-depth-hierarchy-cell-based-microservice-architecture-wso2-version-segmented-microservice-architecture-services-of-services-clusters-of-services) (recursive decomposition):

### Top-Down Hierarchy: [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]] of Orchestrators, Presentation-Abstraction-Control (PAC), Hierarchical [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Model-View-Controller]] (HMVC)


![A single component calls two components in the layer below it, each of which calls two or three lower-level leaf components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Hierarchy%20-%20Top-down.png)


In the most common case *Hierarchy* is applied to business logic to build a layered system which grows from a single generic high-level root into a swarm of specialized low-level pieces. The most obvious applications are protocol parsers, decision trees, [IIoT](https://en.wikipedia.org/wiki/Industrial_internet_of_things) (e.g. a fire alarm system of a building), and [modern automotive](https://semiengineering.com/managing-todays-advanced-vehicle-networks-design-challenges/) networks. A marketplace that allows for customized search and marketing algorithms within each category of its goods may also be powered by a hierarchy of category-specific services.

[*Presentation-Abstraction-Control*](https://en.wikipedia.org/wiki/Presentation%E2%80%93abstraction%E2%80%93control) (*PAC*) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] applies *Top-Down Hierarchy* to a user-facing application, providing each of the resulting [[wiki/concepts/source/basic-metapatterns/layers|*layered*]] nodes with its own widget (*presentation*) on the UI screen (which is the *presentation* of the root node). *Controls* are responsible for inter-node communication and [[wiki/concepts/source/basic-metapatterns/layers|integration logic]], while [[wiki/concepts/source/basic-metapatterns/layers|domain logic]] and data reside in *abstractions*.

[*Hierarchical Model-View-Controller*](https://herbertograca.com/2017/08/17/mvc-and-its-variants/#hierarchical-model-view-controller) (*HMVC*) is similar, but its *views* access *models* directly, like in [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*MVC*]], and every model synchronizes with the global data. This pattern [was used](https://web.archive.org/web/20060319064042/http://www.javaworld.com/javaworld/jw-09-2000/jw-0908-letters.html) in [rich clients](https://en.wikipedia.org/wiki/Rich_client).


![Both Presentation-Abstraction-Control and Hierarchical Model-View-Controller are top-down hierarchies with three-component nodes, which share a database in the second pattern.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/PAC.png)


### Bottom-Up Hierarchy: [[wiki/concepts/source/extension-metapatterns/middleware|Bus]] of Buses, Network of Networks, Hierarchical Middleware


![An integration middleware interconnects the middlewares of two systems.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Hierarchy%20-%20Bottom-up.png)


Other cases require building a common base for intercommunication between several networks which vary in their protocols (and often their hardware). The root of such a *Hierarchy* is a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] generic and powerful enough to cover the needs of all the specialized networks which it interconnects.

Example: [Automotive networks](https://www.mdpi.com/1424-8220/21/23/7917), integration of corporate networks, [the Internet](https://en.wikipedia.org/wiki/Internet_service_provider).

### In-Depth Hierarchy: [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Cell]]-Based (Microservice) Architecture (WSO2 version), Segmented Microservice Architecture, [[wiki/concepts/source/basic-metapatterns/services|Services]] of Services, Clusters of Services


![Cells of different kinds communicate with each other through cell gateways.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Cell-Based%20Architecture.png)


When several [[wiki/concepts/source/basic-metapatterns/services|*services*]] in a system grow large, in some cases it is possible to divide each of them into *subservices*. Each group of the resulting subservices (known as a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]], [*Domain*](https://www.uber.com/blog/microservice-architecture/) or *Cluster* \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\]) usually implements a *bounded context* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. It is hidden behind its own [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]] and may even use its own [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]. Subservices of a *Cell* may [[wiki/concepts/source/extension-metapatterns/shared-repository|*share a database*]] and may be deployed as a single unit. This keeps the system’s integration complexity (the length of its APIs and the number of deployable units) reasonable while still scaling development among many teams or individuals, each owning a service. If each instance of a *Cell* owns a [[wiki/concepts/source/basic-metapatterns/shards|*shard*]] of its database, the system [becomes more stable](https://docs.aws.amazon.com/wellarchitected/latest/reducing-scope-of-impact-with-cell-based-architecture/what-is-a-cell-based-architecture.html) as there is no single point of failure (except for the [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]] called *Cell Router*). Another benefit is that *Cells* can be deployed to regional data centers to improve locality for users of the system. However, that will likely cause data synchronization traffic between the data centers.

The [*Cell-Based Architecture*](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) ([*Segmented Microservice Architecture*](https://github.com/wso2/reference-architecture/blob/master/api-driven-microservice-architecture.md)) may be seen as a combination of an *Orchestrator of Orchestrators* and a *Bus of Buses* where the subservices are leaf nodes of both *hierarchies* while the [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateways*]] of the *Cells* are their internal nodes.

Uber [compacted](https://www.uber.com/blog/microservice-architecture/) 2200 [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] into 70 *Cells* arranged in a [*SOA*](<Service-Oriented Architecture (SOA)>)-style topology called [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>).

## Evolutions

- The upper component of a *Top-Down Hierarchy* can be split into [*Backends for Frontends*](<Backends for Frontends (BFF)>).


![The upper layer of a top-down hierarchy is subdivided into Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Hierarchy%20-%201.png)


## Summary

*Hierarchy* fits a project of any size as it evenly distributes complexity among the system’s many components. However, it is not without drawbacks in performance, debuggability, and operational complexity. Moreover, very few domains allow for seamless application of this architecture.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/layered-services.md ===== -->

---
title: "Layered Services"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Layered Services.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Layered%20Services
source_license_note: "See namespace README; preserve attribution and source links."
---

# Layered Services

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Layered Services.md`.


![A diagram for Layered Services, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Layered%20Services.png)


*Cut the cake.* Divide each service into layers.

<ins>Structure:</ins> Subdomain services divided into layers.

<ins>Type:</ins> Implementation of [[wiki/concepts/source/basic-metapatterns/services|*Services*]], [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], or [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]].

*Layered Services* is an umbrella architecture for common implementations of systems of [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. It does not introduce any special features as the layers are completely encapsulated by the service which they belong to. Still, as the services may communicate at different layers, there are a couple of things to learn by exploring the subject matter.

### Performance

*Layered Services* are similar to [[wiki/concepts/source/basic-metapatterns/services|*Services*]] performance-wise: use cases that involve a single service are the fastest, those that need to synchronize states of multiple services are the slowest.

Remarkable features of *Layered Services* include:

- Independent scaling of the layers inside the services. It is common to have multiple [[wiki/concepts/source/basic-metapatterns/shards|instances]] (with the number varying from service to service and changing dynamically under load) of the layers that contain business logic while the corresponding [[wiki/concepts/source/basic-metapatterns/layers|data layers]] (databases) are limited to a single instance.


![The use of scaled stateless services and load balancers in Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layered%20Services%20-%20sharding.png)


- The option to establish additional communication channels between the lower layers in order to drive [*CQRS*](#command-query-responsibility-segregation-cqrs) databases ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|read/write replicas]] of the same database) or [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] (cached subsets of data from other services) \[[wiki/concepts/source/appendices/books-referenced|[MP]]\].


![Data streams in Three-Layered Services: from data layer to data layer, from domain layer to data layer, and between two domain-level components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Layered%20Services%20-%20channels.png)


## Variants

*Layered Services* vary in the number of [[wiki/concepts/source/basic-metapatterns/layers|layers]] and in the layer through which the [[wiki/concepts/source/basic-metapatterns/services|services]] communicate:

- In [*Orchestrated Three-Layered Services*](#orchestrated-three-layered-services) the application layer of any service may call the same layer in other services.
- In [*Choreographed Two-Layered Services*](#choreographed-two-layered-services) the domain layers of services are assembled into a *Pipeline*.
- [*Command Query Responsibility Segregation*](#command-query-responsibility-segregation-cqrs) streams changes from a transactional to an analytical database.


## Orchestrated Three-Layered Services


![In three-layered services the application layer of every service calls the domain layer of its service and the application layers of other services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Three-Layered%20Services.png)


Likely the most common backend architecture has [[wiki/concepts/source/basic-metapatterns/layers|three layers]]: [[wiki/concepts/source/basic-metapatterns/layers|*application*]], [[wiki/concepts/source/basic-metapatterns/layers|*domain*]], and *infrastructure* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. The application layer [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrates*]] the domain layer.

If such an architecture is divided into [[wiki/concepts/source/basic-metapatterns/services|services]], each of them receives a part of every layer, including application, which means that now there are as many *Orchestrators* as services. Each *Orchestrator* implements the API of its service by integrating (calling or messaging into) the domain layer of its service and the APIs of other services, which makes all the *Orchestrators* interdependent:

### Dependencies

The upper ([[wiki/concepts/source/basic-metapatterns/layers|*application*]]) layer of each service orchestrates both its middle (*domain*) layer and the upper layers of other services, resulting in [[wiki/concepts/source/foundations-of-software-architecture/orchestration|mutual orchestration and interdependencies]].


![In Layered Services only the application layers of the services are interdependent.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Communication/Mutual%20Orchestration%20-%204.png)


The good thing is that the majority of the code belongs to the domain layer which depends only on its service’s database. The bad thing is that changes in the application of one service may affect the application layers of all of the other services.

### Relations

*Three-layered services*:

- Implement [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Are derived from [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Have multiple [[wiki/concepts/source/extension-metapatterns/orchestrator|*Integration (sub)Services*]] ([[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]]).


### Evolutions

*Orchestrated Layered Services* may become coupled, which is resolved either by merging their layers:

- A part of or the whole [[wiki/concepts/source/basic-metapatterns/layers|*application layer*]] can be merged into a shared [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]].
- Some or all the [[wiki/concepts/source/basic-metapatterns/layers|*databases*]] can be united into a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] or shared as [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].
- Both the *application* and *data* layers can be merged into a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]]*.*


![Diagrams for Three-Layered Services with partially merged application layer, partially merged databases and shared databases, and a Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Three-Layered%20Services%20-%201.png)


or by building derived datasets:

- A [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS View*]] inside a service aggregates any events from other services which its host is interested in.
- A dedicated [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] captures the whole system’s state by subscribing to events from all the services.


![Diagrams for Three-Layered Services employing CQRS views and a Query Service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Three-Layered%20Services%20-%202.png)


If a service becomes too large:

- Its middle layer can be split, resulting in a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]].


![The domain layer of a large three-layered service is split into sub-subdomain components, resulting in a Sandwich Cell.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Three-Layered%20Services%20-%203.png)


## Choreographed Two-Layered Services


![The domain-level components of two-layered services participate in multiple pipelines and access their service's databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Two-Layered%20Services.png)


If there is no [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestration*]], there is no role for the [[wiki/concepts/source/basic-metapatterns/layers|*application* layer]]. [[wiki/concepts/source/foundations-of-software-architecture/choreography|*Choreographed*]] systems are made up of services that implement individual steps of request processing. The sequence of actions (*integration logic*) which three-layered systems put in the [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] now moves to the graph of *event channels* between the services. This means that with choreography the high-level part of the business logic (use cases) exists outside of the code for the system’s constituent services.

### Dependencies

Dependencies are identical to those of a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] or [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] [[wiki/concepts/source/basic-metapatterns/services|*Services*]] except that each service also depends on its database.

### Relations

*Two-layered services*:

- Implement [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].
- Are derived from [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].


### Evolutions

If *Choreographed Layered Services* become coupled:

- The *business logic* of two or more services can be merged together, resulting in [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].
- Some databases can be united into a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] or shared as [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].


![Diagrams for Two-Layered Services with partially merged domain layer, partially merged databases, and shared databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Two-Layered%20Services%20-%201.png)


[[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*CQRS Views*]] or a [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Query Service*]] are also an option:


![Diagrams for Two-Layered Services employing CQRS views and a Query Service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Two-Layered%20Services%20-%202.png)


An overgrown service can be:

- Split in two


![The domain layer of a large two-layered service is split in half.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Two-Layered%20Services%20-%203.png)


## [[wiki/concepts/source/extension-metapatterns/sandwich|Command Query Responsibility Segregation]] (CQRS)


![Write requests from a client go to the write backend and OLTP database which feeds OLAP databases. Read requests go to the scaled read backend and the scaled OLAP database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/CQRS.png)


*Command Query Responsibility Segregation* (*CQRS*) \[[wiki/concepts/source/appendices/books-referenced|[MP]], [[wiki/concepts/source/appendices/books-referenced|LDDD]]\] is, essentially, the division of a [[wiki/concepts/source/basic-metapatterns/layers|layered]] application or a service into two (rarely more) [[wiki/concepts/source/basic-metapatterns/services|services]], one of which is responsible for write access (handling *commands*) to the domain data while the other(s) deal with read access (*queries*), thus [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|creating]] a data [[wiki/concepts/source/basic-metapatterns/pipeline|*pipeline*]] (see the diagram below). Such an architecture makes sense when the write and read operations don’t rely on a common vision (*model*) of the domain, for example, writes are individual changes ([*OLTP*](https://en.wikipedia.org/wiki/Online_transaction_processing)) that require cross-checks and validation of input while reads show aggregated data ([*OLAP*](https://en.wikipedia.org/wiki/Online_analytical_processing)) and may take long time to complete (meaning that the [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|*forces*]] for the read and write paths differ). If there is nothing to share in the code, why not separate the implementations?


![In CQRS data streams from the client to the write backend, then to the OLTP database, to the OLAP database, to the read backend and, finally, returns to the client.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/CQRS%20-%20pipeline%20view.png)


This separation brings in the pros and cons of [[wiki/concepts/source/basic-metapatterns/services|*Services*]]: commands and queries may differ in technologies (including schemas or even kinds of the databases) and forces, and even be developed by separate teams, at the expense of [consistency](https://en.wikipedia.org/wiki/Eventual_consistency) (database replication delay) and increasing the system’s complexity. In addition, for read-heavy applications the read database(s) is easy to scale.

*CQRS* has the following variations:

- The database may be shared, commands and queries may use dedicated databases, or the read service may maintain a [*Memory Image*](https://martinfowler.com/bliki/MemoryImage.html) / [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Materialized View*]] fed by events from the write service (as in other kinds of *Layered Services*).
- Data [[wiki/concepts/source/basic-metapatterns/shards|replication]] may be implemented as a [[wiki/concepts/source/basic-metapatterns/pipeline|*pipeline*]] between the databases (based on nightly snapshots or [log-based replication](https://www.dremio.com/wiki/log-based-replication/)) or a [direct event feed](https://martinfowler.com/bliki/EagerReadDerivation.html) from the OLTP code to the OLAP database.


![In CQRS the OLAP databases receive data from the OLTP database or from events originating in the write backend. Alternatively, the read and write backends may share a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/CQRS%20-%20subtypes.png)


It is noteworthy that while ordinary *Layered Services* usually communicate through their upper-level components that drive the use cases, a *CQRS* system is held together by spreading data changes through its lowest layer.

Examples: Martin Fowler has a [short article](https://martinfowler.com/bliki/CQRS.html) and Microsoft a [longer one](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs).

### Dependencies

Each backend depends on its database (its technology and schema). The OLTP to OLAP data replication requires an additional dependency that comes from the way the replication is implemented:


![In CQRS each service depends on its database while the OLAP database depends on the source of its event feed.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/CQRS.png)


### Relations

*CQRS*:

- Implements [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] (a whole *system* or a single [[wiki/concepts/source/basic-metapatterns/services|*service*]]).
- Is derived from both [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].
- Is a development of [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].


### Evolutions

- You will usually need a [[wiki/concepts/source/extension-metapatterns/proxy|*Reverse Proxy*]] or an [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateway*]] to segregate commands from queries.
- If the commands and queries become intermixed, the business logic can be merged together but the databases are left separate, resulting in [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].
- Both read and write backends can be split into [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [[wiki/concepts/source/basic-metapatterns/services|*Services*]] (yielding [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]]).
- Applying [[wiki/concepts/source/extension-metapatterns/shared-repository|*Space-Based Architecture*]] may further improve performance.
- Multiple schemas or even kinds of OLAP databases can be used simultaneously ([[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]]).


![Diagrams of CQRS behind an API Gateway, with a single backend, with multiple OLAP databases, with layered backends, Cells for backends, and Data Grid for a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/CQRS.png)


## Summary

*Layered Services* is an umbrella pattern that conjoins:

- *Three-Layered Services* where each service [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrates*]] other services.
- *Two-Layered Services* that form a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].
- *CQRS* that separates the read and write request processing paths.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/polyglot-persistence.md ===== -->

---
title: "Polyglot Persistence"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Polyglot Persistence.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Polyglot%20Persistence
source_license_note: "See namespace README; preserve attribution and source links."
---

# Polyglot Persistence

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Polyglot Persistence.md`.


![A diagram for Services with Polyglot Persistence, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Polyglot%20Persistence.png)


*Unbind your data.* Use multiple specialized data stores.

<ins>Known as:</ins> Polyglot Persistence.

<ins>Structure:</ins> A layer of data services used by higher-level components.

<ins>Type:</ins> Extension component, derived from [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].

| *Benefits* | *Drawbacks* |
| --- | --- |
| Performance is fine-tuned for various data types and use cases | The peculiarities of each data store need to be learned |
| Less load on each data store | Muсh more work for the DevOps team |
| The data stores may satisfy conflicting forces | More points of failure in the system |
|  | Consistency is hard or slow to achieve |

<ins>References:</ins> The [original](https://martinfowler.com/bliki/PolyglotPersistence.html) and closely related [CQRS](https://martinfowler.com/bliki/CQRS.html) articles from Martin Fowler, chapter 7 of \[[wiki/concepts/source/appendices/books-referenced|[MP]]\], chapter 11 of \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] and much information dispersed all over the Web.

You can choose a dedicated technology for each kind of data or pattern of data access in your system. That improves performance (as each data store engine is optimized for a few use cases), distributes load between the data stores, and may solve conflicts between forces (like when you need both low latency and large storage). However, you may need to hire several experts to get the best use of and to support the multiple data stores, especially if those are full-featured databases. Moreover, having your data spread over multiple data stores makes it the application’s responsibility to keep the data in sync (by implementing some kind of distributed transactions or making sure that the clients don’t get stale data).

> A *database* is a complex service which provides both data storage and such high-level functionality as transactions and analytical queries. A [*data store*](https://en.wikipedia.org/wiki/Data_store) is anything where data can be placed and retrieved: a shared memory, file system, cloud storage, or a database. Though this chapter mostly deals with databases, several patterns which it discusses pertain to non-database storage.

### Performance

*Polyglot Persistence* aims at improving performance through the following means:

- Optimize for [specific data use cases](#specialized-databases). It is impossible for a single database to be good at everything.
- Redirect read traffic to [read-only database *replicas*](#read-only-replicas). The write-enabled *leader* database then processes only the write requests.
- [*Cache* any frequently used data](#database-cache-cache-aside) in a fast in-memory data store to let the majority of client requests be served without hitting the slower persistent storage.
- Build a [*view* of the states of other services](#reporting-database-cqrs-view-database-event-sourced-view-source-aligned-native-data-product-quantum-dpq-of-data-mesh) in the system to avoid querying them.
- Maintain an external [*index*](#external-search-index) or [*Memory Image*](#memory-image-materialized-view) for use with tasks that don’t need the history of changes.
- [Purge old data](#historical-data-data-archiving) to a slower storage.
- Store read-only sequential [data as files](#data-file-content-delivery-network-cdn), often close to the end users who download them.


Beware that the read-write separation introduces a replication lag \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] which is a headache when both data consistency and responsiveness are important for the system’s clients.

### Dependencies

In general, each service depends on all of the data stores which it uses. There may also be an additional dependency between the data stores if they share a dataset (one or more data stores are derived).


![The business logic depends on every database. A derived database depends on its data source.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/PolyglotPersistence.png)


### Applicability

*Polyglot Persistence* <ins>helps</ins>:

- *High load and low latency projects.* [*Specialized Databases*](#specialized-databases) shine when given fitting tasks. [*Caching*](#database-cache-cache-aside) and [*Read-Only Replicas*](#read-only-replicas) take the load off the main database. [*External Search Indices*](#external-search-index) may occasionally save the day as well.
- [*Event sourcing*](https://martinfowler.com/eaaDev/EventSourcing.html) *and* [*event collaboration*](https://martinfowler.com/eaaDev/EventCollaboration.html)*.* A [*Memory Image*](#memory-image-materialized-view) maintains the current state of an event-sourced component. A [*CQRS View*](#reporting-database-cqrs-view-database-event-sourced-view-source-aligned-native-data-product-quantum-dpq-of-data-mesh) aggregates domain events to provide its host service with whatever data from other subdomains it may need to use.
- *Conflicting forces*. An instance of a stateless service inherits many of the qualities of the data store which it accesses for any given request it is processing. When there are several data stores, the qualities (e.g. latency) of a service instance may vary from request to request, depending on which data store is involved.


*Polyglot Persistence* may <ins>harm</ins>:

- *Small projects.* Properly setting up and maintaining multiple databases is not that easy.
- *High availability*. Each data store which your system uses will tend to fail in its own crazy way.
- *User experience*. For systems with read-write database separation the replication lag between the databases will make you [choose](https://medium.com/@Ian_carson/replication-lag-82c736081e32) between reading changes from the *leader* (write database), adding synchronization code to your application to wait for the read database to be updated, and risking returning outdated results to the users.


### Relations


![Polyglot Persistence for Monolith, Layers, Shards, and Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Polyglot%20Persistence.png)


*Polyglot Persistence*:

- Extends [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Is derived from [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] (the persistence layer) or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].
- Variants with derived databases have an aspect of [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] and are closely related to [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]].


## Examples with independent storage

Many cases of *Polyglot Persistence* use multiple data stores just because there is no single technology that matches all the application’s needs. The data stores used are filled with different subsets of the system’s data:

- Each service may have its own private data while [another dataset is shared](#private-and-shared-databases).
- [Specialized databases](#specialized-databases) that differ in storage and analytical technologies may be used.
- Many kinds of data can be [stored as files](#data-file-content-delivery-network-cdn).


### Private and Shared Databases


![A subset of data shared between shards and between services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/PP%20-%20Private%20and%20Shared.png)


If several services or shards become coupled through a subset of the system’s data, that subset can be put into a separate database which is accessible to all the participants. All the other data remains private to the [[wiki/concepts/source/basic-metapatterns/shards|shards]] or [[wiki/concepts/source/basic-metapatterns/services|services]].

### Specialized Databases


![A service which uses both SQL and NoSQL databases.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/PP%20-%20Specialized.png)


Databases [vary in their optimal use cases](https://www.jamesserra.com/archive/2015/07/what-is-polyglot-persistence/). You can employ several different databases to achieve the best performance for each kind of data that you persist.

### Data File, Content Delivery Network (CDN)


![A backend reads page templates while a frontend reads content from a content delivery network.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/PP%20-%20File%20Storage.png)


Some data is happy to stay in files. Web frameworks load web page templates from OS files and store images and videos in a *Content Delivery Network* (*CDN*) which replicates the data all over the world so that each user downloads the content from the nearest server (which is faster and cheaper).

## Examples with derived storage

In other cases there is a single writable data store (called *system of record* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]) which is the main *source of truth* from which the other data stores are derived. The primary reason to use several data stores is to [relieve the main database of read requests](#read-only-replicas) and maybe support some additional qualities: special kinds of queries, aggregation for [*materialized*](#memory-image-materialized-view) and [*CQRS views*](#reporting-database-cqrs-view-database-event-sourced-view-source-aligned-native-data-product-quantum-dpq-of-data-mesh), full text search for [*text indices*](#external-search-index), huge dataset size for [*historical data*](#historical-data-data-archiving), or high performance for an [*in-memory cache*](#database-cache-cache-aside).

The updates to the derived data stores may come from:

- the main database as [*Change Data Capture*](https://www.dremio.com/wiki/change-data-capture/) (*CDC*) \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] (a log of changes),
- the application after it changes the main data store (see caching strategies [below](#database-cache-cache-aside)),
- another service as an *event stream* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]], [[wiki/concepts/source/appendices/books-referenced|MP]]\],
- a dedicated *indexer* that periodically crawls the main data store or web site.


![A derived database is fed data from the main database, from an indexer which scans the main database, from application events, or from events originating with another service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/PP%20-%20Derived%20Storage.png)


### Read-Only [[wiki/concepts/source/basic-metapatterns/shards|Replicas]]


![An instance of a backend writes to a leader database which streams updates to database replicas. Other backend instances read from the replicas.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Read-only%20Replica.png)


Multiple instances of the database are deployed and one of them is the *leader* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] instance which processes all writes to the system’s data. The changes are then replicated to the other instances (via [*Change Data Capture*](https://www.dremio.com/wiki/change-data-capture/) (*CDC*)) which are used for read requests. Distributing workload over multiple instances increases maximum read throughput which the system is capable of, as the database is usually the system’s bottleneck. Having several running [[wiki/concepts/source/basic-metapatterns/shards|*replicas*]] greatly improves reliability and allows for nearly instant recovery of database failures as any replica may quickly be promoted to the leader role to serve write traffic.

### Database [[wiki/concepts/source/extension-metapatterns/proxy|Cache]], Cache-Aside


![A cache hit only reads from the cache; a cache miss reads from the cache, reads from the database, and writes to the cache; a write writes to the database and to the cache.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Cache-Aside.png)


Database queries are resource-heavy while databases scale only to a limited extent. That means that a highly loaded system benefits from bypassing its main database in as many queries as possible, which is usually achieved by storing recent queries and their results in an in-memory data store ([*Cache-Aside*](https://www.enjoyalgorithms.com/blog/cache-aside-caching-strategy)). Each incoming query is first looked for in the fast cache, and if it is found then you are lucky to get the result immediately without having to consult the main database.

Keeping the cache consistent with the main database is the hard part. There are quite a few strategies (some of them treat the [[wiki/concepts/source/extension-metapatterns/proxy|cache as a *Proxy*]] for the database): [write-through](https://www.enjoyalgorithms.com/blog/write-through-caching-strategy), [write-behind](https://www.enjoyalgorithms.com/blog/write-behind-caching-pattern), [write-around](https://www.enjoyalgorithms.com/blog/write-around-caching-pattern) and [refresh-ahead](https://www.enjoyalgorithms.com/blog/refresh-ahead-caching-pattern).

### Memory Image, Materialized View


![At startup a service reads from an event store and writes to a memory image. At runtime it reads from the memory image and updates both the memory image and event store.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Memory%20Image.png)


[*Event sourcing*](https://martinfowler.com/eaaDev/EventSourcing.html) (of [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]] or [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]) is all about changes. A service persists only *changes* to its data instead of its *current* data. As a result, the service needs to aggregate its history into a [*Memory Image*](https://martinfowler.com/bliki/MemoryImage.html) (*Materialized View* \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\]) by loading a snapshot and replaying any further events to rebuild its current state (which other architectural styles store in databases) to start operating.

### Reporting Database, CQRS View Database, Event-Sourced View, Source-Aligned (Native) Data Product Quantum (DPQ) of [[wiki/concepts/source/basic-metapatterns/pipeline|Data Mesh]]


![A service reads from a CQRS view which aggregates updates streamed by another service. An analyst queries a reporting database which aggregates a stream of events from the main database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Reporting%20DB%20and%20CQRS%20View.png)


It is common wisdom that a database is good for either *OLTP* (transactions) or *OLAP* (queries). Here we have two databases: one optimized for commands (write traffic protected with transactions) and another one for complex analytical queries. The databases differ at least in their schemas (the OLAP schema is optimized for queries) and often vary in type (e.g. SQL vs NoSQL).

A [*Reporting Database*](https://martinfowler.com/bliki/ReportingDatabase.html) (or *Source-Aligned (Native) Data Product Quantum* of [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]] \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\]) derives its data from a write-enabled database in the same subsystem (service) while a *CQRS View* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] or *Event-Sourced View* \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\] is fed a stream of events from another service from which it filters the data relevant to its owner. This way a *CQRS View* lets its host service query (its replica of) the data that originally belonged to other services.

### Query Service, [[wiki/concepts/source/extension-metapatterns/orchestrator|Front Controller]], Data Warehouse, Data Lake, Aggregate Data Product Quantum (DPQ) of [[wiki/concepts/source/basic-metapatterns/pipeline|Data Mesh]]


![Several services both stream updates and query data from a shared query service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Query%20Service.png)


A *Query Service* \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] (or *Aggregate Data Product Quantum* of [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]] \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\]) subscribes to events from several full-featured services and aggregates them into its data store, making it a [*CQRS View*](#reporting-database-cqrs-view-database-event-sourced-view-source-aligned-native-data-product-quantum-dpq-of-data-mesh) of several services or even the whole system. If any other service or a data analyst needs to process data which belongs to multiple services, it retrieves it from the *Query Service* which has already joined the data streams and represents the join in a convenient way.

A [[wiki/concepts/source/extension-metapatterns/orchestrator|*Front Controller*]] \[[wiki/concepts/source/appendices/books-referenced|[SAHP]] [[wiki/concepts/source/analytics/ambiguous-patterns|but not]] [[wiki/concepts/source/appendices/books-referenced|PEAA]]\] is a *Query Service* embedded in the first (user-facing) service of a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]]. It collects status updates from the downstream components of the *Pipeline* to track the state of every request being processed by the *Pipeline*.

*Data Warehouse* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] and *Data Lake* \[[wiki/concepts/source/appendices/books-referenced|[SAHP]]\] are *analytical* data stores that connect directly to and import all the data from the *operational* (main) databases of all the system’s services. A *Data Warehouse* transforms the imported data into its own unified schema while a *Data Lake* stores the imported data in its original format(s).

### External Search Index


![An external index receives events from the main datastore. A service queries the external index to find ids of specific records which it later reads from the main database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Search%20Index.png)


Some domains require a kind of search which is not naturally supported by ordinary database engines. Full text search, especially [NLP](https://en.wikipedia.org/wiki/Natural_language_processing)-enabled, is one such case. Geospatial data may be another. If you are comfortable with your main data store(s), you can set up an *External Search Index* by deploying a product dedicated to the special kind of search that you need and feeding it updates from your main data store.

Alternatively, you may just need a way to quickly search through text documents or videos stored in a file system or in a cloud, which requires some kind of index.

### Historical Data, Data Archiving


![A service works with an operational database. An archiver reads from the operational database and writes to an archive. An analyst reads from both the archive and operational database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Historical%20Data.png)


It is common to store the history of sales in a database. However, once a month or two has passed, it is very unlikely that the historical records will ever be edited. And though they are queried on very rare occasions, like audits, they still slow down your database. Some businesses offload any data older than a couple of months to a cheaper [*archive storage*](https://www.datacore.com/glossary/what-is-data-archiving/) which does not allow for changing the data and has limited query capabilities. That helps keep the main datasets small and fast.

## Evolutions

*Polyglot Persistence* with derived storage can often be made subject to *CQRS*:

- The service that uses the read and write databases is [[wiki/concepts/source/fragmented-metapatterns/layered-services|split into separate read and write services]].


![The backend layer that uses OLAP and OLTP databases is subdivided into command and query backends, resulting in full-featured Command-Query Responsibility Segregation.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/Polyglor%20Persistence%20-%201.png)


## Summary

*Polyglot Persistence* employs several specialized data stores to improve performance, often at the cost of eventual data consistency or implementing transactions in the application.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/fragmented-metapatterns/service-oriented-architecture-soa.md ===== -->

---
title: "Service Oriented Architecture (SOA)"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Fragmented metapatterns/Service-Oriented Architecture (SOA).md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Fragmented%20metapatterns/Service-Oriented%20Architecture%20%28SOA%29
source_license_note: "See namespace README; preserve attribution and source links."
---

# Service Oriented Architecture (SOA)

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Fragmented metapatterns/Service-Oriented Architecture (SOA).md`.


![A diagram for Service-Oriented Architecture, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Service-Oriented%20Architecture.png)


*The whole is equal to the sum of the parts.* Distributed [Object-Oriented Design](https://en.wikipedia.org/wiki/Object-oriented_design).

<ins>Known as:</ins> Service-Oriented Architecture (SOA), [Segmented Architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-layered-segmented.md).

<ins>Structure:</ins> Usually three layers of services where each service can access any other service in its own or lower layers.

<ins>Type:</ins> System topology, derived from [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].

| *Benefits* | *Drawbacks* |
| --- | --- |
| Supports huge codebases | Very hard to debug |
| Multiple development teams and technologies | Hard to test as there are many dependencies |
| Forces may vary between the components | Very poor latency |
| Deployment to dedicated hardware | Very high DevOps complexity |
| Fine-grained scaling | The teams are highly interdependent |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] has a chapter on Orchestration-Driven (Enterprise) Service-Oriented Architecture. \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] mentions Distributed Monolith. There is also much (though somewhat conflicting) content over the Web.

*Service-Oriented Architecture* looks like the [application of modular or object-oriented design](https://www.uber.com/en-UA/blog/microservice-architecture/) followed by distribution of the resulting components over a network. The system usually contains three (rarely four) [[wiki/concepts/source/basic-metapatterns/layers|*layers*]] of [[wiki/concepts/source/basic-metapatterns/services|*services*]] where every service has access to all the services below it (and sometimes some within its own layer). The services stay small, but as their number grows it becomes hard for programmers to keep in mind all the API methods and contracts available for use by their component. Another issue originates from the idea of reusable components – multiple applications, written for different clients with varied workflows, require the same service to behave in (subtly) different ways, either causing its API to bloat or else impairing its usability (which means that a new customized duplicate service will likely be added to the system). On top of that, request processing is slow because there is much interservice communication. Teams are interdependent as any use case involves many services, each owned by a dedicated team. Testability is poor because there are too many moving (and being independently updated!) parts. The OOP’s foundational idea of reuse [failed in practice](https://softwareengineering.stackexchange.com/questions/7618/does-oop-fulfill-the-promise-of-code-reuse-what-alternatives-are-there-to-achie), but its child architecture, namely *SOA*, still survives in historical environments.

Even though *SOA* fell from grace and is rarely seen in modern projects, it may soon be resurrected by low-code and no-code frameworks for serverless systems (e.g. [[wiki/concepts/source/basic-metapatterns/services|*Nanoservices*]]) – it has everything ready: code reuse, granular deployment, and elastic scaling.

### Performance

*SOA* is remarkable for its poor latency which results from extensive communication between its distributed components. There is hardly any way to help that as processing a request usually involves many services from all the layers.

Nevertheless, this pattern allows for good throughput as its stateless components can be scaled individually, leaving the system’s scalability to be limited only by its databases, [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] … and funding.

### Dependencies

Each service of each layer depends on everything it uses. As a result, development of a low-level (utility) component may be paralyzed because too many services already use it, thus no changes are welcome. Hence, the team writes a new version of their utility as a new service, which defeats the very idea of component reuse which *SOA* was based on.


![Tasks depend on entities. Entities depend on utilities and libraries. The many dependencies make it hard to change almost any component.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Service-Oriented%20Architecture.png)


### Applicability

*Service-Oriented Architecture* <ins>is useful</ins> in:

- *Huge projects.* Many teams can be employed, each handling a moderate amount of code. Yet, dependencies between the teams and the combined length of the APIs in the system may [stall the development](https://goomics.net/374) anyway.
- *A system of specialized hardware devices.* If there is a lot of different hardware interacting in complex ways, the system may naturally fit the description of *SOA*. Don’t fight this kind of [Conway’s law](https://en.wikipedia.org/wiki/Conway%27s_law).


*Service-Oriented Architecture* <ins>hurts</ins>:

- *Fast-paced projects.* Any feature requires coordination of multiple teams, which is hard to achieve in practice.
- *Latency-sensitive domains*. Over-distribution means too much messaging which causes too high latency.
- *High availability systems*. Components may fail. The failure of a lower-level component is going to stall a large part of the system because every low-level component is used by many higher-level services.
- *Safety-critical systems with frequent updates*. *SOA* is hard to test comprehensively. Either all the components must be certified with a strict standard and an exhaustive test suite or any single component update requires re-testing the entire system.


### Relations

*Service-Oriented Architecture*:

- Is a stack of [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] each of which is divided into [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- Is often extended with an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Enterprise Service Bus*]] (a kind of [[wiki/concepts/source/extension-metapatterns/orchestrator|*orchestrating*]] [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]]) and one or more [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Databases*]].


## Examples

This architecture was hyped at the time when enterprises were expanding by acquiring smaller companies and conjoining their IT systems. The resulting merged systems were still heterogeneous and the development experience unpleasant, which inclined popular opinion towards the then novel notion of [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]. As nearly everybody has turned from merging existing systems to failing to apply *Microservices* in practice, the chance to find a pure greenfield *SOA* project in the wild is quite low. Known examples of this topology include:

- [*Distributed Monolith*](#distributed-monolith) with synchronous interactions.
- [*Enterprise SOA*](#enterprise-soa) that features a notorious *Enterprise Service Bus*.
- [*Domain-Oriented Microservice Architecture*](#domain-oriented-microservice-architecture-doma) built of *Cells*.
- [*Automotive SOA*](#misapplied-automotive-soa) which may actually be a *Microkernel*.
- *SOA*-topology [*Nanoservices*](#nanoservices).


### Distributed Monolith


![There are three segmented layers: tasks, services and infrastructure. Each component of a layer accesses multiple components in layers below it.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Distributed%20Monolith.png)


If a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] gets too complex and resource-hungry, the most simple & stupid way out of the trouble is to deploy each of its component modules to a separate, dedicated hardware. The resulting services still communicate synchronously and are subject to domino effect on failure. Such an architecture may be seen as a (hopefully) intermediate [[wiki/concepts/source/introduction/system-topologies|topology]] in transition to more independent and stable event-driven [[wiki/concepts/source/basic-metapatterns/services|*Services*]] (or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]]).

### Enterprise SOA


![An Enterprise Service Bus interconnects multilayered segmented subsystems each using its own protocol.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/Enterprise%20SOA.png)


Multiple systems of [[wiki/concepts/source/basic-metapatterns/services|*Services*]], each featuring an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] and sometimes a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]], are integrated, resulting in new cross-connections. Much of the orchestration logic is removed from the *API Gateways* and reimplemented in an [[wiki/concepts/source/extension-metapatterns/orchestrator|*orchestrating*]] [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] called [[wiki/concepts/source/extension-metapatterns/orchestrator|*Enterprise Service Bus*]] (*ESB*). This option allows for fast and only moderately intrusive integration (as no changes to the services, which implement the mass of the domain logic, are required), but the single [[wiki/concepts/source/foundations-of-software-architecture/orchestration|orchestrating]] component (*ESB*) often becomes the bottleneck for future development of the system due to its size and complexity. It is likely that if the orchestration were encapsulated in the individual *API Gateways*, the system would be easier to deal with (making what is now [marketed by WSO2](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) as [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]]).

The layers of *SOA* are:

- *Business Process* (*Task*) – the definitions of [[wiki/concepts/source/basic-metapatterns/layers|use cases]] for a single business department, similar to the *API Gateways* layer of [*BFF*](<Backends for Frontends (BFF)>).
- *Services* (*Enterprise*, *Entity*) – the implementation of the [[wiki/concepts/source/basic-metapatterns/layers|business logic of a subdomain]], to be used by the *tasks*.
- *Components* (*Application* & *Infrastructure*, *Utility*) – external libraries and in-house utilities that are designed for shared use by the *services* layer.


### Domain-Oriented Microservice Architecture (DOMA)


![There are five layers: segmented gateways, segmented presentation, segmented product made of cells, segmented business made of cells, and monolithic infrastructure.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/DOMA.png)


A huge business may build a *SOA* of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]] (called *Domains*) instead of plain [[wiki/concepts/source/basic-metapatterns/services|*Services*]]. That greatly simplifies:

- administration (by reducing the number of components at the system level – Uber [packed](https://www.uber.com/blog/microservice-architecture/) 2200 [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] into 70 *Domains*),
- refactoring of individual subsystems (which are isolated behind [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateways*]]),
- development of business logic (as programmers need to learn much fewer interfaces of components they rely on).


Uber’s *DOMA* also [makes heavy use](https://www.uber.com/blog/microservice-architecture/) of [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]] which programmers from a client service team develop for the services which they rely on. That allows for cross-*Domain* customization (injection of business logic from another *Cell*) of a service’s behavior without making slow and possibly failing interservice calls.

### (misapplied) [[wiki/concepts/source/implementation-metapatterns/microkernel|Automotive SOA]]


![User applications run on top of a system-wide Virtual Functional Bus which communicates to various services that run on different chips in the system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/3/SOA%20-%20AUTOSAR.png)


*Automotive* architectures were inspired by *SOA*, but the old [[wiki/concepts/source/implementation-metapatterns/microkernel|*AUTOSAR Classic*]] looks more like [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] (which indeed is similar to a 2-layered *SOA* with an [[wiki/concepts/source/extension-metapatterns/orchestrator|*ESB*]]) while the newer system diagrams resemble a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]]. Therefore, they are addressed in the corresponding chapters.

### Nanoservices

It seems that some proponents of [[wiki/concepts/source/basic-metapatterns/services|*Nanoservices*]] [take them](https://medium.com/@ido.vapner/unlocking-the-power-of-nano-services-a-new-era-in-microservices-architecture-22647ea36f22) for a novel version of *SOA* – with the old good promise of reusable components. However, as that promise was failing miserably ever since the ancient days of OOP, it is of no surprise that [in practice](https://increment.com/software-architecture/the-rise-of-nanoservices/) *Nanoservices* are used instead to build [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] with little to no reuse.

## Evolutions

*SOA* suffers from excessive reuse and fragmentation. To fix that, first and foremost, each service of the *components* ([[wiki/concepts/source/basic-metapatterns/layers|*utility*]]) layer should be duplicated:

- Into every *service* that uses it, giving the developers who write the business logic full control over all the code which they use. Now they have several projects to support on their own (instead of asking other teams to make changes to their components).


![The shared components are replicated into services which use them.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/SOA%20-%201.png)


- Or into [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] if you employ a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]], resulting in much fewer network hops (thus lower latency) in request processing, but retaining the inter-team dependencies.


![The shared components are replicated into sidecars.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/SOA%20-%202.png)


That removes the largest and most obvious part of the fragmentation, making the [[wiki/concepts/source/extension-metapatterns/orchestrator|*ESB*]] (if you use one) [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrate*]] only the *entity* layer.

Afterwards you may deal with the remaining orchestration. The idea is to move the orchestration logic from the *ESB* to an explicit *layer* of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]]:

- Either a monolithic *Orchestrator* over all the services.
- Or [*Backends for Frontends*](<Backends for Frontends (BFF)>) with an *Orchestrator* per client type (department of an enterprise) if each client uses most of the services.
- Or go for [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]] with an *Orchestrator* per subdomain if your clients are subdomain-bound.
- Or a combination of the above.


![Diagrams for Services with an orchestrator, Backends for Frontends, and Cell-Based Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Evolutions/3/SOA%20-%203.png)


Still another step is unbundling the [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], which supports multiple protocols via [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]]:

- If you have a [[wiki/concepts/source/implementation-metapatterns/mesh|*Service Mesh*]], the *Adapters* may be added to [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]].
- Otherwise there is an option of a [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*hierarchical Middleware*]] (*Bus of Buses*) if closely interacting components share protocols.


Still, these evolutions of [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] may not bring any real benefit except for removing the [[wiki/concepts/source/extension-metapatterns/orchestrator|*ESB*]] altogether, which may not be that bad after all when it is not misused.

In any case, many of the evolutions will likely be very expensive, thus it makes sense to conduct some of them gradually via a kind of [strangler fig approach](https://martinfowler.com/bliki/StranglerFigApplication.html). Or let the architecture live and die as it is.

## Summary

*Service-Oriented Architecture* divides each of the *integration*, *domain*, and *utility* layers into shared services. The extensive fragmentation and reuse degrade performance and speed of development. Nevertheless, huge projects are known to survive with this architecture.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/implementation-metapatterns/hexagonal-architecture.md ===== -->

---
title: "Hexagonal Architecture"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Implementation metapatterns/Hexagonal Architecture.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Implementation%20metapatterns/Hexagonal%20Architecture
source_license_note: "See namespace README; preserve attribution and source links."
---

# Hexagonal Architecture

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Implementation metapatterns/Hexagonal Architecture.md`.


![A diagram for Hexagonal Architecture, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Hexagonal%20Architecture.png)


*Trust no one.* Protect your code from external dependencies.

<ins>Known as:</ins> Hexagonal Architecture, or originally as Ports and Adapters.

<ins>Structure:</ins> Monolithic or subdivided business logic extended with a set of (adapter, component) pairs that encapsulate external dependencies.

<ins>Type:</ins> Implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Isolates business logic from external dependencies which thus become expendable | Suboptimal performance |
| The programmers of business logic don’t need to learn any external technologies | The vendor-independent interfaces must be designed before the start of development |
| Facilitates the use of stubs/mocks for testing and development |  |
| Allows for qualities to vary between the external components and the business logic |  |

<ins>References:</ins> [Herberto Graça’s chronicles](https://herbertograca.com/2017/07/03/the-software-architecture-chronicles/) is the main overview of patterns in this chapter. For *Hexagonal Architecture* there is  [the original article](https://alistair.cockburn.us/hexagonal-architecture/) and a brief summary of its layered variant in \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\]. Most of the *Separated Presentation* patterns are featured on Wikipedia and there are collections of them from [Martin Fowler](https://martinfowler.com/eaaDev/uiArchs.html), [Anthony Ferrara](https://blog.ircmaxell.com/2014/11/alternatives-to-mvc.html), and [Derek Greer](https://lostechies.com/derekgreer/2007/08/25/interactive-application-architecture/). *Cells* originate with [WSO2](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) and [Uber](https://www.uber.com/en-UA/blog/microservice-architecture/).

*Hexagonal Architecture* (see the [original article](https://alistair.cockburn.us/hexagonal-architecture/) for the explanation of its name) is a variation of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] that aims for self-sufficiency of a system’s business logic *core*. It hides external components such as libraries, services, or data stores, which the business logic would normally depend upon, behind [[wiki/concepts/source/extension-metapatterns/proxy|*adapters*]] \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] that translate from the external component’s interface to an interface ([*API*](#upper-half-separated-presentation-open-host-service) or [*SPI*](#lower-half-pedestal-abstraction-layer-anticorruption-layer)) defined in terms of the business logic. This indirection not only makes the bulk of the system’s code easy to port, test, and run in isolation, but also allows for replacing external components and for changing the interfaces or even the internal structure of the business logic late in the [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|project’s life cycle]].

Though various kinds of *Hexagonal Architecture* are de facto industry standards, they are not without drawbacks: the [extra layer of indirection](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering) requires careful planning with insights into how the system will evolve and which kinds of external components will need to be integrated or which platforms the system will need to run on. It also adds boilerplate code and prevents aggressive performance optimization that would rely on peculiarities of the currently integrated external component.

### Performance

*Hexagonal Architecture* is a strange beast performance-wise. The generic interfaces between the *core* and *adapters* stand in the way of whole-system optimization and may add a context switch. Still, at the same time, each *adapter* concentrates all the vendor-specific code for its external dependency, which makes the *adapter* a perfect single place for aggressive optimization by an expert or consultant who is proficient with the adapted third-party software but does not have time to learn the details of your business logic. Thus, some opportunities for optimization are lost while others emerge.

Occasionally, the system may benefit from direct communication between the *adapters*. However, that requires several of them to be compatible or polymorphic, in which case your *Hexagonal Architecture* may in fact be a kind of a shallow [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]]. Examples include a service which uses several databases which are kept in sync through [*Change Data Capture*](https://www.dremio.com/wiki/change-data-capture/) (*CDC*) or a telephony gateway that interconnects various kinds of voice devices.


![A data stream between adapters of Hexagonal Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Hexagonal%20Architecture.png)


### Dependencies

Each [[wiki/concepts/source/extension-metapatterns/proxy|*adapter*]] breaks the dependency between the *core* that contains business logic and an adapted component. This makes all the system’s components mutually independent – and easily interchangeable and evolvable – except for the *adapters* themselves, which are small enough to be rewritten as need arises.


![In Hexagonal Architecture each adapter depends on the core and the component or protocol it adapts.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Hexagonal%20Architecture.png)


Still, there is a hidden pitfall of designing a [*leaky abstraction*](https://en.wikipedia.org/wiki/Leaky_abstraction) – an interface that looks generic but whose contract matches that of the component it encapsulates, making it much harder than expected to change the external component’s vendor.

### Applicability

*Hexagonal Architecture* <ins>benefits</ins>:

- *Medium-sized or larger components.* The programmers don’t need to learn details of external technologies and may concentrate on the business logic instead. The code of the *core* becomes smaller as all the details of managing the external components are moved into their *adapters*.
- *Cross-platform development.* The core is naturally cross-platform as it does not depend on any (platform-specific) libraries or frameworks.
- *Long-lived products*. Technologies come and go, your product remains. Always be ready to change the technologies it uses.
- *Unfamiliar domain.* You don’t know how much load you’ll need your database to support. You don’t know if the library which you have selected is stable enough for your needs. Be prepared to replace vendors even after the public release of your product.
- *Automated testing.* [Stubs and mocks](https://stackoverflow.com/questions/3459287/whats-the-difference-between-a-mock-stub) are great for reducing load on test servers. And stubs for the [SPI](#lower-half-pedestal-abstraction-layer-anticorruption-layer)s which you wrote yourself are as easy as a pie.
- *Zero bug tolerance.* SPIs allow for event replay. If your business logic is deterministic, you can [reproduce your user’s bugs in your office](http://ithare.com/chapter-vc-modular-architecture-client-side-on-debugging-distributed-systems-deterministic-logic-and-finite-state-machines/).


*Hexagonal Architecture* <ins>is not good</ins> for:

- *Small components.* If there is little business logic, there is not much to protect, while the overhead of defining [SPI](#lower-half-pedestal-abstraction-layer-anticorruption-layer)s and writing *adapters* for them is high compared to the total development time.
- *Write-and-forget projects.* You don’t want to waste your time on long-term survivability of your code.
- *Quick start*. You need to show the results right now. No time for good architecture.
- *Low latency*. The *adapters* slow down communication. This is somewhat alleviated by creating [direct communication channels](#performance) between the *adapters* to bypass the *core*.


### Relations


![Diagrams of Hexagonal Architecture with a monolithic core, with a layered core, and Cell.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Hexagonal%20Architecture.png)


*Hexagonal Architecture*:

- Is a kind of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].
- May be a shallow [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]].
- Implements [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].
- Extends [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or [[wiki/concepts/source/basic-metapatterns/services|*Services*]] with one or two layers of [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]].
- The [*MVC* family of patterns](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine) is also [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|derived]] from [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].


## Variants by placement of adapters

There is a variation in a distributed or asynchronous *Hexagonal Architecture* regarding the deployment of [[wiki/concepts/source/extension-metapatterns/proxy|*adapters*]], which may reside with the components they adapt or stay adjacent to the *core*:

### Adapters on the external component side


![Adapters co-located with external components translate a single message from the core into multiple calls to the adapted components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Adapters%20with%20Components.png)


If your team owns the component adapted, the *adapter* may be placed next to it. That usually makes sense because a single domain message (designed in the terms of your business logic) tends to unroll into a series of calls to an external component. The fewer messages you send, the faster your system is.

### Adapters on the core side


![Adapters for external services and a shared database are co-located with the core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Adapters%20with%20the%20Core.png)


Sometimes you need to adapt an external service which you don’t control. In that case the only real option is to place its *adapter* together with your *core* logic. For a monolithic *core* ([*Ports and Adapters*](#ports-and-adapters-hexagonal-architecture)) the *adapters* may run in the core’s process as ordinary modules. A distributed *core* ([*Cell*](#cell-cluster-domain)) requires the *adapters* to be stand-alone components, which however can be co-located and co-deployed with the *core* as [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]].

## Variants by encapsulation

In most cases a component or subsystem is involved in two kinds of communication:

- Input/output from clients, users, or network devices which we [[wiki/concepts/source/introduction/metapatterns|draw on the upper side of diagrams]]. These events initiate the application’s use cases thus they are called [*primary* or *driving*](https://alistair.cockburn.us/hexagonal-architecture).
- The activities and calls initiated by the component itself while executing a use case. They usually target the infrastructure or external services, are called [*secondary* or *driven*](https://alistair.cockburn.us/hexagonal-architecture), and are drawn on the lower side.


![The system's core is isolated with adapters for the following communication: data stream, REST, and SSH inputs; database and library access; publish/subscribe output stream.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Driving%20and%20Driven.png)


> Client output *adapters*, such as the *view* in [*MVC*](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine) or *responder* in [*ADR*](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine), are treated as *primary* even though they are called by the business logic. The reason is that such an *adapter* is a part of the client feedback loop which *drives* the system’s behavior.

We can protect a component from its environment by inserting *adapters* into its *primary*, *secondary*, or both communication pathways:

### Upper half: [[wiki/concepts/source/extension-metapatterns/proxy|Separated Presentation]], [[wiki/concepts/source/extension-metapatterns/proxy|Open Host Service]]


![A component provides an API which is called by a GUI adapter for a system's user, a REST adapter for a web application, and a gRPC adapter for a software client.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Driving.png)


Isolation on the input ([*primary*, *driving*](https://alistair.cockburn.us/hexagonal-architecture)) side is achieved by designing an *Application Programming Interface* (*API*) that provides access to your component’s use cases which your software exists to implement and writing *adapters* that translate your *API* into something convenient for every kind of communication used by your clients. For example, you may need a desktop GUI, mobile GUI, CLI, web application (REST), and customer (JSON or gRPC) *adapters* all of which are built on top of your component’s API.

Input side isolation allows for your system to be used in different environments and roles and enables automated testing of its business logic without hard-to-support GUI tests.

> Though it may seem that a system’s business logic cannot depend on its [[wiki/concepts/source/basic-metapatterns/layers|*interface*]] (GUI or web API) because it is the *interface* that calls the business logic, in fact the business logic must prepare the data it returns in the format declared by the interface (for a web protocol) or output the data queried to a widget (for a GUI). Therefore, making the business logic independent requires an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] to translate between the domain terms native to the business logic and the data format used by a web protocol or GUI framework which calls the business logic.

[*Separated Presentation*](https://martinfowler.com/eaaDev/SeparatedPresentation.html) protects business logic (*model*) from a dependency on the [[wiki/concepts/source/extension-metapatterns/proxy|*Presentation Layer*]] \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] (interactions with the system’s user via a window, command line, or web page). There is a [great variety](https://blog.ircmaxell.com/2014/11/alternatives-to-mvc.html) of such patterns, commonly known as *Model-View-Controller* (*MVC*) alternatives, which make three structurally distinct groups:

- Bidirectional flow – the *view* (user-facing component) both receives input and produces output, and there is often an extra *adapter* between it and the main system, resulting in [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]]. These patterns make the [*Model-View-Presenter* (*MVP*) family](#model-view-presenter-mvp-model-view-adapter-mva-model-view-viewmodel-mvvm-model-1-mvc1-document-view).
- Unidirectional flow – the *controller* receives input while the *view* only produces output, [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|forming]] a kind of [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]]. Such patterns are [associated with *Model-View-Controller* (*MVC*)](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine).
- Hierarchical patterns with multiple *models*, [[wiki/concepts/source/fragmented-metapatterns/hierarchy|discussed]] in the [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]] chapter.


*Open Host Service* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] is an enterprise pattern about providing functionality for use by other components (hence the name) through publishing a stable interface, known as a *Published Language* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. As the subject service should be able to change, and as its clients may differ in their needs, requiring multiple *Published Languages*, an *Open Host Service* usually involves an *adapter* for every *Published Language* it provides – just like *Separated Presentation* does for supported *UI*s.

> As is common with patterns, there is a slight difference between what the client-facing side comprises in *Separated Presentation* and *Open Host Service*, with the last pattern including adapters for *Publish-Subscribe* interfaces. Neither of these two patterns provides indirection for input streams of data or events.

### Lower half: [[wiki/concepts/source/basic-metapatterns/services|Pedestal]], [[wiki/concepts/source/extension-metapatterns/proxy|Abstraction Layer, Anticorruption Layer]]


![The core uses adapters to call a database, a library, and an external service.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Driven.png)


In many cases you need to protect your component from its dependencies. If the bulk of your code depends on a certain external service provider or component, you face a major risk, called [*vendor lock-in*](https://en.wikipedia.org/wiki/Vendor_lock-in), of that provider going out of business, being [acquired and killed by a larger company](https://killedbygoogle.com/), or greatly increasing the price of its services. Therefore you better define a *Service Provider Interface* (*SPI*) in terms of your business logic and write an *adapter* between it and the external provider’s *API*. This way you will be able to change the external provider by merely rewriting the *adapter*. It will also be easy to upgrade to new versions of the provider’s API. The set of *adapters* to the services used by a component is called *Anticorruption Layer* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] because it protects the component from any external changes.

There is a similar situation in embedded and systems programming where software faces hardware. A hardware component is normally in production only for a few years before being replaced by a newer, and often incompatible, chip. You have to make sure that your business logic can run on any hardware that provides the functions it needs – therefore you write hardware-specific [[wiki/concepts/source/extension-metapatterns/proxy|*drivers*]] which adapt the target hardware’s interface to the expectations of your business logic. The *drivers* make an [[wiki/concepts/source/extension-metapatterns/proxy|*Hardware Abstraction Layer*]] while the entire architecture is called a [*Pedestal*](#pedestal).

Another common case is platform independence – you may need to run your code under different operating systems or cloud orchestrators, which requires an [[wiki/concepts/source/extension-metapatterns/proxy|*OS Abstraction Layer*]] (*OSAL*) or a [[wiki/concepts/source/extension-metapatterns/proxy|*Platform Abstraction Layer*]] (*PAL*). And you may even use a [[wiki/concepts/source/extension-metapatterns/proxy|*Database Abstraction Layer*]] (*DAL*) to feel more secure.

> Embedded software and operating systems [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|don’t run use cases]] – they react to events which come from hardware. This fact breaks the *Hexagonal Architecture*’s model of [*driving* and *driven* adapters](#variants-by-encapsulation) – any hardware component can *drive* a part of the system’s behavior but none of them initiates use cases.

The extra benefit of the isolation from infrastructure and external services by using [*secondary* or *driven*](https://alistair.cockburn.us/hexagonal-architecture) *adapters* is the ability to run against [*test doubles*](https://martinfowler.com/bliki/TestDouble.html) – local [*stubs* or *mocks*](https://stackoverflow.com/questions/3459287/whats-the-difference-between-a-mock-stub) that replace an external dependency, saving testing time and money. They also allow for implementing business logic before the external services which it will use are chosen, and even replacing a service provider late in the [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|project’s life cycle]].

> *Stubs* and *mocks* are [*test doubles*](https://martinfowler.com/bliki/TestDouble.html) – simplistic replacements for real-world components. They are used to run the business logic in isolation – without the need to deploy any heavyweight libraries or services which the logic may depend upon. A *stub* supports a single usage scenario in a single test case while a *mock* is more generic – its behavior is programmed on a per test basis.

### Full encapsulation: [Ports and Adapters](#ports-and-adapters-hexagonal-architecture)


![A system with its core fully isolated by adapters from both inputs and outputs. The core depends only on its own interfaces.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Hexagonal%20-%20Full%20Isolation.png)


Complete isolation of business logic – when both *driving* and *driven* communication is mediated by *adapters* – not only reaps the benefits of both approaches described above but also simplifies the main codebase because the entire business logic is written in its own terms, called *ubiquitous language* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]. It also lowers the cognitive complexity which its programmers face because they don’t need to learn any external technology, and [allows for event replay to reproduce bugs](http://ithare.com/chapter-vc-modular-architecture-client-side-on-debugging-distributed-systems-deterministic-logic-and-finite-state-machines/) (*any reproducible bug is a dead bug*) if the business logic is deterministic.

The pattern for full isolation of business logic is known as [*Ports and Adapters*](https://herbertograca.com/2017/09/14/ports-adapters-architecture/) which is the original [*Hexagonal Architecture*](https://alistair.cockburn.us/hexagonal-architecture).

## Examples

Several patterns apply the principles of *Hexagonal Architecture* to different extents:

- The patterns of the [*MVP family*](#model-view-presenter-mvp-model-view-adapter-mva-model-view-viewmodel-mvvm-model-1-mvc1-document-view) add one or two layers of indirection between a GUI or web framework and the business logic.
- Those of the [*MVC family*](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine) use separate *adapters* for input and output flows.
- [*Pedestal*](#pedestal) wraps each hardware component with a *driver*.
- [*Ports and Adapters*](#ports-and-adapters-hexagonal-architecture) fully isolate the system’s business logic from any dependencies.
- There are a few [related architectures with layered *cores*](#ddd-style-hexagonal-architecture-onion-architecture-clean-architecture).
- [*Cell*](#cell-cluster-domain) isolates a group of services from the rest of the system.


### Model-View-Presenter (MVP), Model-View-Adapter (MVA), Model-View-ViewModel (MVVM), Model 1 (MVC1), Document-View


![The control flow of Model-View-Presenter is a loop that starts with an OS GUI, is handled by the view, passes to the presenter, then down to the model, and all the way back to the OS.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/MVP.png)


*MVP*-style patterns pass user input and output through one or more [[wiki/concepts/source/extension-metapatterns/proxy|*Presentation Layers*]]. Each pattern includes:

- *View* – the interface exposed to users. In *Hexagonal Architecture*’s terms it is an *adapter* for the OS GUI framework.
- An optional intermediate layer that translates between the *view* and *model*, beneficial for when the internal representation of the domain in the *model* diverges from the way it is presented to users by the *view*. It is this component which differentiates the patterns, both in name and function.
- *Model* – the whole system’s business logic and infrastructure, now independent from the method of presentation (CLI, UI, or web).


*Document-View* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] and [*Model 1*](https://stackoverflow.com/questions/796508/what-is-the-actual-difference-between-mvc-and-mvc-model2) (*MVC1*) skip the intermediate layer and connect the *view* directly to the *model* (*document*). These are the simplest [*Separated Presentation*](https://martinfowler.com/eaaDev/SeparatedPresentation.html) patterns for UI and web applications, respectively.

In a [*Model-View-Presenter*](https://herbertograca.com/2017/08/17/mvc-and-its-variants/#model-view-presenter) (*MVP*), the *presenter* ([*Supervising Controller*](https://martinfowler.com/eaaDev/SupervisingPresenter.html)) receives input from the *view*, interprets it as a call to one of the *model*’s methods, retrieves the call’s results, and shows them in the *view*, which is often completely dumb ([*Passive View*](https://martinfowler.com/eaaDev/PassiveScreen.html)). A complex system may feature multiple *view-presenter* pairs, one per UI screen.

A [*Model-View-Adapter*](https://blog.ircmaxell.com/2014/11/alternatives-to-mvc.html#MVA-Model-View-Adapter) (*MVA*) is quite similar to *MVP*, but it chooses the *adapter* on a per session basis while reusing the *view*. For example, an unauthorized user, a normal user, and an admin would access the *model* through different *adapters* which would show them only the data and actions available under their permissions.

A [*Model-View-ViewModel*](https://herbertograca.com/2017/08/17/mvc-and-its-variants/#model-view-view_model) (*MVVM*) uses a stateful intermediary (*ViewModel* or [*Presentation Model*](https://martinfowler.com/eaaDev/PresentationModel.html)) which resembles a [[wiki/concepts/source/extension-metapatterns/proxy|*Response Cache*]], [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Materialized View*]], [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Reporting Database*]], or the *Read Model* of [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]] – it stores all the data shown in the *view* in a form which is convenient for the *view* to [bind to](https://en.wikipedia.org/wiki/Data_binding). Changes in the *view* are propagated to the *ViewModel* which translates them into requests to the underlying application (the true *model*). Changes in the *model* (both independent and resulting from user actions) are propagated to the *ViewModel* and, eventually, to the *view*.

All those patterns exploit modern OS or GUI frameworks’ widgets which handle and process mouse and keyboard input, thus [removing](https://mvc.givan.se/papers/Twisting_the_Triad.pdf) the need for a separate (input) *controller* (see [below](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine)).


![Diagrams of MVP with a view-presenter pair for each screen, MVA with different adapters for different kinds of users, MVVM with data in ViewModel, and simple Document-View and Model 1.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/MVP%20-%20subtypes.png)


### Model-View-Controller (MVC), Action-Domain-Responder (ADR), Resource-Method-Representation (RMR), Model 2 (MVC2), Game Development Engine


![The control flow in Model-View-Controller starts with mouse events handled by the controller which calls the model which calls the view which updates the display.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/MVC.png)


When your presentation’s input and output are of different natures (raw mouse movement vs 3D graphics in UI, HTTP requests vs HTML pages in websites), it makes sense to separate the [[wiki/concepts/source/extension-metapatterns/proxy|*Presentation Layer*]] into dedicated components for input and output.

*Model-View-Controller* (*MVC*) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] allows for cross-platform development of hand-crafted UI applications (which was necessary before universal UI frameworks emerged) by abstracting the system’s *model* (its main logic and data, the *core* of *Hexagonal Architecture*) from its [[wiki/concepts/source/basic-metapatterns/layers|user interface]] comprised of platform-specific *controller* (input) and *view* (output):

- The *controller* translates raw input into calls to the business-centric model’s API. It may also hide or lock widgets in the *view* when required by the input or if the *model*’s state changes.
- The *model* is the bulk of UI-agnostic code which executes the *controller*’s requests and notifies the *view* and, optionally, *controller* when its data changes.
- Upon receiving a notification, the *view* reads, transforms, and presents to the user the subset of the *model*’s data which it covers.


Each widget on the screen [may have](https://martinfowler.com/eaaDev/uiArchs.html#ModelViewController) its own *model-view* pair. The absence of an intermediate layer between the *view* and *model* makes the *view* heavyweight as it has to translate the *model*'s data format into something presentable to users – the flaw addressed by the 3-layered [*MVP* patterns discussed above](#model-view-presenter-mvp-model-view-adapter-mva-model-view-viewmodel-mvvm-model-1-mvc1-document-view).

Both [*Action-Domain-Responder*](https://github.com/pmjones/adr#action-domain-responder) (*ADR*) and [*Resource-Method-Representation*](https://herbertograca.com/2018/08/31/resource-method-representation/) (*RMR*) are web layer patterns. An *action* (*method*) receives a request, calls into a *domain* (*resource*) to make changes and retrieve data, and brings the results to a *responder* (*representation*) which prepares the return message or web page. *ADR* is technology-agnostic while *RMR* is HTTP-centric.

[*Model 2*](https://stackoverflow.com/questions/796508/what-is-the-actual-difference-between-mvc-and-mvc-model2) (*MVC2*) is a similar pattern from the Java world with integration logic [implemented](https://github.com/pmjones/adr/blob/master/MVC-MODEL-2.md) in the *controller*.

A [*game development engine*](https://slideplayer.com/slide/12426213/) creates a higher-level abstraction over input from mouse / keyboard / joystick and output to sound card and GPU while more powerful engines may also [model physics](https://discussions.unity.com/t/unity3d-architecture/565787) and character interactions. This role is quite similar to what the original *MVC* did, with a couple of differences:

- Games often have to deal with the low-level and very chatty interfaces of hardware components, thus the input and output are at the bottom side of the system diagram.
- The framework itself makes a cohesive layer, becoming a kind of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


Another difference is that while *MVC* provides for changing target platforms by rewriting its minor components (the *view* and *controller*), you are very unlikely to change your game framework – instead, it is the framework itself that makes all the platforms look identical to your code.


![Diagrams of MVC with a dedicated view-controller pair for each widget, ADR and RMR where the action calls the responder, Model 2 with an orchestrating controller, and a game development engine.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/MVC%20-%20subtypes.png)


### [[wiki/concepts/source/basic-metapatterns/services|Pedestal]]


![A Pedestal has a control layer mediating hardware drivers which wrap each hardware component. An operating system adds a kernel between the drivers and an application that uses them.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Pedestal.png)


[*Pedestal*](https://alistair.cockburn.us/hexagonal-architecture) is named after the shape of its diagram and describes a system that operates multiple hardware components. On one hand, *software* takes years to write and stabilize. On the other hand, there are many versions and even vendors for each kind of *hardware* component, and they change over years. Therefore, the bulk of the *software* that contains the system logic (called [[wiki/concepts/source/extension-metapatterns/orchestrator|*control*]]) is decoupled from the *hardware* which it manages through the use of *hardware*-specific [[wiki/concepts/source/extension-metapatterns/proxy|*drivers*]]. As a result, changes in *hardware* require updates only to the matching *drivers*, the business logic remaining intact.

A similar pattern is in use with [[wiki/concepts/source/implementation-metapatterns/microkernel|*OS kernels*]], adjusted for the fact that the business logic now resides in user applications, the *kernel* acting as an [extra layer of indirection](https://en.wikipedia.org/wiki/Fundamental_theorem_of_software_engineering).

### [Ports and Adapters](#full-encapsulation-ports-and-adapters), Hexagonal Architecture


![Adapters of the Hexagonal Architecture translate between the interfaces of its core and those of the adapted external components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Monolithic%20Hexagonal.png)


[*Ports and Adapters*](https://alistair.cockburn.us/hexagonal-architecture/) – the original *Hexagonal Architecture* – provides full isolation for its business logic (*core*) by injecting *adapters* in all its [communication pathways](#variants-by-encapsulation). As a result, the *core* depends only on the interfaces, called *ports* (hence the name of the pattern), which it defines, with the benefits discussed [earlier in this chapter](#full-encapsulation-ports-and-adapters).

Just like [*MVC*](#model-view-controller-mvc-action-domain-responder-adr-resource-method-representation-rmr-model-2-mvc2-game-development-engine) it is based on, *Ports and Adapters* does not care about the contents or structure of its *core* – it is all about isolating the *core* from its environment. The *core* may have [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] or [[wiki/concepts/source/basic-metapatterns/services|*Modules*]], or even [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] inside, but this pattern has nothing to say about them.

### DDD-Style Hexagonal Architecture, Onion Architecture, Clean Architecture


![Control flows for changing an entity in puristic Domain-Driven Design, pragmatic Domain-Driven Design, and Onion Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Layered%20Hexagonal.png)


As *Hexagonal Architecture* built upon the [*Domain-Driven Design*](https://en.wikipedia.org/wiki/Domain-driven_design)’s (*DDD*) idea of isolating business logic with [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] (see the [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer* and *Open Host Service*]] patterns), it was quickly integrated back into DDD \[[wiki/concepts/source/appendices/books-referenced|[LDDD]]\]. However, as *Ports and Adapters* appeared later than the original DDD book, namely \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\], there is no universal agreement on how this architecture should work:

- The cleanest way is for the [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] layer to have nothing to do with the database – with this approach the [[wiki/concepts/source/basic-metapatterns/layers|*application*]] asks the [[wiki/concepts/source/extension-metapatterns/proxy|*repository*]] (the database *adapter*) to create *aggregates* (domain objects), then executes its business actions on the aggregates, and tells the repository to save the changed aggregates back to the database.
- Others say that in practice the logic inside an aggregate may have to read additional information from the database or even depend on the results of persisting parts of the aggregate. Thus it is the aggregate, not the *application*, which should save its changes, and the logic of accessing the database leaks into the domain layer.
- [*Onion Architecture*](https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/) (see the [original article](https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/) for the meaning of the name) – one of early developments of *Hexagonal Architecture* and DDD – always splits the domain layer into a *domain model* and *domain services*. The *domain model* layer contains classes with business data and business logic, which are loaded and saved by the mostly stateless *domain services* layer just above it. And the upper *application services* layer drives use cases by calling into both domain services and the *domain model*.
- There is also [*Clean Architecture*](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) which seems to generalize the approaches above without delving into practical details – thus the way it saves its aggregates remains a mystery.


### Cell, Cluster, Domain


![Several intercommunicating subservices are wrapped with a cell gateway that receives client requests, adapters for outgoing communication, and a plugin.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Cell.png)


A [*Cell*](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) (WSO2 name), *Cluster* \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\], or [*Domain*](https://www.uber.com/en-UA/blog/microservice-architecture/) (Uber’s name) is an encapsulated cluster of [[wiki/concepts/source/basic-metapatterns/services|*services*]] which implements a subdomain and is usually deployed as a single unit. It is modeled after a living cell whose contents are isolated with a membrane. [As a rule of thumb](https://learn.microsoft.com/en-us/azure/architecture/patterns/choreography) \[[wiki/concepts/source/appendices/books-referenced|[DEDS]]\], the communication inside a *Cell* is synchronous, allowing for complex [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrated*]] use cases that involve the tightly coupled *Cell* components. Contrariwise, *Cells* are usually loosely coupled among themselves and the communications between them tend to be asynchronous ([[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreography*]]).

 A *Cell* may naturally emerge when a [[wiki/concepts/source/basic-metapatterns/services|*subdomain service*]] becomes too large for comfortable development, which usually means that at least its [[wiki/concepts/source/basic-metapatterns/layers|*domain* layer]] (already limited to a single subdomain) is to be subdivided into sub-subdomain components. If other layers remain intact, this leads to a [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]], otherwise the result is a subsystem of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].


![Diagrams for: a Cell with a Sandwich, a Cell with services, and a Cell with a pipeline.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Cell%20-%20Basic%20-%20Subtypes.png)


Another way a *Cell* can arise is when architects have overcommitted themselves to [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]], gradually [introducing hundreds of them](https://www.uber.com/en-UA/blog/microservice-architecture/) and turning their project into a [*Microservice Hell*](https://www.reddit.com/r/programming/comments/10xvltx/microservice_hell/). Now they need to group their services to:

- Have a clear high-level picture of what is going on in the system.
- Cut accidental dependencies between their services and the teams behind them.
- Improve latency by co-locating the services that interact intensely.


![A layered system transforms into a Sandwich-based Cell. A group of stand-alone services is aggregated into a cell behind a Cell gateway.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Cell%20-%20Basic%20-%20Evolutions.png)


In the simplest implementation, the *Cell*’s contents are hidden from its clients by a [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]] which acts as an [[wiki/concepts/source/extension-metapatterns/proxy|*Open Host Service*]], allowing for anything inside the *Cell* to be changed at will with no effect on the outside world.

> In practice, there are three kinds of outgoing traffic: responses to incoming client requests, pub/sub notifications, and requests to external services. In a *Cell*, the *responses* are sure to pass through or be generated by the *Cell Gateway*. Indeed, a response usually reuses the request’s transport, therefore if a request arrives at the *Gateway*, the corresponding response should also start there. *Notifications* are harder to pinpoint: on one hand, they are a part of the *Cell*’s API which the *Gateway* takes care of. However, that means that the *Cell*’s internals must be aware of the *Gateway*’s existence to use it for their notifications, thus creating a dependency that violates the [[wiki/concepts/source/basic-metapatterns/layers|normal order for a *layered system*]]. Finally, *outgoing requests* bypass the *Cell Gateway* whose role is limited to the *Cell*’s API.

Better developed *Cells* employ [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] for outgoing requests to build an [[wiki/concepts/source/extension-metapatterns/proxy|*Anticorruption Layer*]] that protects the *Cell*’s contents from changes in its environment. Please note that, unlike in [*Ports and Adapters*](#ports-and-adapters-hexagonal-architecture), there is no *Adapter* for the *Cell*’s database(s) as they are inside the *Cell*’s perimeter.

Another improvement, popularized by Uber’s [*Domains*](https://www.uber.com/en-UA/blog/microservice-architecture/), is the use of [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]] which run pieces of business logic that belong to other *Cells* inside a host *Cell*. That both avoids slow intercell calls and boosts the system’s fault tolerance as each *Cell* can now operate independently.


![Injecting a part of a Cell's business logic into another Cell as an ambassador plugin improves performance by avoiding expensive intercell calls.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Cell%20-%20Full-Featured%20-%20Plugins.png)


> [In Uber](https://www.uber.com/en-UA/blog/microservice-architecture/), the service responsible for a driver’s status accepts *Plugins* from other services, such as safety checks or compliance, which can block the driver from appearing in the system and responding to ride requests.

*Cells* facilitate recursive decomposition by subdomain. They are the building blocks for the following patterns:

- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] which is [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*hierarchical*]] [[wiki/concepts/source/basic-metapatterns/services|*Services*]].
- [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) which is a [*SOA*](<Service-Oriented Architecture (SOA)>) boosted by [[wiki/concepts/source/implementation-metapatterns/plugins|*Ambassador Plugins*]].


## Summary

*Hexagonal Architecture* isolates the component’s business logic from its external dependencies by inserting *adapters* between them. It protects from *vendor lock-in* and allows for late changes of third-party components but requires all the APIs and SPIs to be designed before programming can start and often hinders performance optimizations.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/implementation-metapatterns/implementation-metapatterns.md ===== -->

---
title: "Implementation metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Implementation metapatterns/Implementation metapatterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Implementation%20metapatterns/Implementation%20metapatterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Implementation metapatterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Implementation metapatterns/Implementation metapatterns.md`.

A few architectures focus on implementation of components:

### [[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]]


![A diagram of Plugins Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Plugins.png)


The [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] family of patterns is about separating a system’s main logic from the customizable details of its behavior. That allows for the same codebase to be used for multiple flavors or customers.

*<ins>Includes</ins>*: Plug-In Architecture, Addons, Strategy, Hooks.

### [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]


![A diagram of Hexagonal Architecture, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Hexagonal%20Architecture.png)


[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] is a specialization of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] where every external dependency is isolated behind an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]], making it easy to update or replace third-party components.

*<ins>Includes</ins>*: Ports and Adapters, Onion Architecture, and Clean Architecture; Model-View-Presenter (MVP), Model-View-ViewModel (MVVM), Model-View-Controller (MVC), and Action-Domain-Responder (ADR); Pedestal and Cell (Cluster or Domain).

### [[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]]


![A diagram of Microkernel, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Microkernel.png)


[[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] is another derivation of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]], featuring a rudimentary *core* component which mediates between resource *consumers* (*applications*) and resource *providers*. The *microkernel* is a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] to the *applications* and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] to the *providers*.

*<ins>Includes</ins>*: operating system, software framework, virtualizer, distributed runtime, interpreter, configuration file, Saga Engine, and AUTOSAR Classic Platform.

### [[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]]


![A diagram of Services over a mesh, with explanations.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Contents/Mesh.png)


A [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] consists of intercommunicating shards, each of which may host an application. The shards coalesce into a fault-tolerant distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].

*<ins>Includes</ins>*: peer-to-peer networks, Leaf-Spine Architecture, Actors, Service Mesh, and Space-Based Architecture.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/implementation-metapatterns/mesh.md ===== -->

---
title: "Mesh"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Implementation metapatterns/Mesh.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Implementation%20metapatterns/Mesh
source_license_note: "See namespace README; preserve attribution and source links."
---

# Mesh

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Implementation metapatterns/Mesh.md`.


![A diagram for Services over a mesh, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Mesh.png)


*Hive mind.* Go decentralized.

<ins>Known as:</ins> Mesh, Grid.

<ins>Structure:</ins> A system of interconnected [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] which usually make a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].

<ins>Type:</ins> Implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| No single point of failure | Overhead in administration and security |
| The system is able to self-heal | Performance is likely to suffer |
| Great scalability | The *Mesh* engine is very hard to debug |
| Available off the shelf | Unreliable communication must be accounted for in the code |

<ins>References:</ins> [Wikipedia](https://en.wikipedia.org/wiki/Network_topology#Classification) and \[[wiki/concepts/source/appendices/books-referenced|[DDIA]]\] on topology and protocols. \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] on *Service Mesh* and *Space-Based Architecture*. A [long](https://buoyant.io/service-mesh-manifesto) and [short](https://www.oracle.com/cloud/cloud-native/service-mesh/what-is-a-service-mesh/) article on *Service Mesh*.

If a system is required to survive faults, all of its components must be both [[wiki/concepts/source/basic-metapatterns/shards|*sharded*]] and interconnected, which is the definition of a *Mesh* – a network of interacting instances (*nodes*). In most cases the lower layer of a *shard* implements connectivity while the business logic resides in its upper layer(s). Whilst the connectivity component tends to be identical in every node of a system, the upper components may be identical – forming [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], or different – forming [[wiki/concepts/source/basic-metapatterns/services|*Services*]].

Most *Meshes* support adding and removing parts of their networks dynamically, which allows for scaling up, scaling down, and fault recovery. That is achieved through a flexible network topology, which has the chance of missing or duplicating requests, which may lead to a single action being executed by two instances of a service in parallel or by the same instance twice. Moreover, *Mesh*-mediated communication is likely to be slower than direct one.

### Performance

In most (all?) implementations the user *application* is colocated with a *node* of the *Mesh*, thus communicating through the *Mesh* does not add an extra network hop (which would strongly degrade performance). However, that holds true only when the *Mesh node* knows the destination of the message it should send – when it has already established a communication channel towards it. Finding a new destination may not always be easy and would often require consulting registries, and sometimes waiting for the network topology to stabilize, which may involve timeouts (like the ones you could have experienced with torrents). On the other hand, no other architecture is known to seamlessly support huge networks.

### Dependencies

*Mesh*, being a *sharded Middleware*, inherits dependencies from both of its parent metapatterns:

- As with [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], the services that run over a *Mesh* depend both on the *Mesh’s API* and on each other (or on a shared message format, aka [[wiki/concepts/source/extension-metapatterns/shared-repository|*Stamp Coupling*]], or a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] if they [[wiki/concepts/source/foundations-of-software-architecture/shared-data|use one for communication]]).
- As with [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]], the nodes of the *Mesh* should communicate through a backward- and forward-compatible protocol as there will likely be periods of time when multiple versions of the *Mesh* nodes coexist.


### Applicability

*Mesh* <ins>is perfect</ins> for:

- *Dynamic scaling.* Instances of services may be quickly added or removed.
- *High availability.* A *Mesh* is very hard to disable or kill because it both creates new instances of failed services and finds routes around failed connections.


*Mesh* <ins>fails</ins> in:

- *Low latency domains.* Spreading information through a *Mesh* is slow and sometimes unreliable.
- *Security-critical systems.* A public *Mesh* exposes a high attack surface while the scalability of private deployments is limited by the installed hardware.
- *Quick and dirty programming*. The possible message duplication may cause evil bugs if you ignore the risks.


### Relations

*Mesh*:

- Misuses [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]].
- Uses [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].
- Is the base for running multiple instances of a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/layers|*layers*]], or [[wiki/concepts/source/basic-metapatterns/services|*services*]].
- Implements a distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]], or [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


## Variants

*Meshes* are known to vary:

### By structure

The connections in a *Mesh* can be:

- *Structured* or *pre-defined* – the *Mesh* is pre-designed and hard-wired. This kind of topology provides redundancy but not scalability.
- *Unstructured* or *ad-hoc* – *nodes* can be added or removed at runtime, restructuring the *Mesh*.


### By connectivity

Each *node* is:

- Connected to all other nodes – a *fully connected Mesh*. Such *Meshes* are limited in size because the number of interconnections grows as a square of the number of nodes. Notwithstanding, they offer the best communication speed and delivery guarantees.
- Connected to some other nodes. There are many possible [*topologies*](https://en.wikipedia.org/wiki/Network_topology#Classification) with the choice for any given task better left to experts.


### By the number of mesh layers

The connected *nodes* of a *Mesh* may be:

- Identical (one-layer *Mesh*). A node behaves according to its site in the network.
- Specialized (multi-layer *Mesh*). Some nodes implement *trunk* (route messages and control the topology) while others are *leaves* (run user applications).


## Examples

The diversity of *Meshes* can be seen in the following examples:

- [*Peer-to-Peer Networks*](#peer-to-peer-networks) for sharing files, CPU time, or Internet access.
- [*Leaf-Spine Architecture*](#leaf-spine-architecture-spine-leaf-architecture) found in datacenters.
- [*Actors*](#actors) – class-like software entities that communicate through messaging.
- [*Service Mesh*](#service-mesh) which hosts *Microservices*.
- [*Space-Based Architecture*](#space-based-architecture) which co-locates service instances and nodes of a distributed in-memory data store.


### Peer-to-Peer Networks


![Each application is connected to a node of a mesh. The nodes find each other's addresses in a registry and then communicate directly.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/P2P.png)


[*Peer to Peer*](https://en.wikipedia.org/wiki/Peer-to-peer) (*P2P*) networks are intended for massive resource sharing over unstable connections. The *resource* in question may be data (torrents, blockchain, [P2PTV](https://en.wikipedia.org/wiki/P2PTV)), CPU time ([volunteer computing](https://en.wikipedia.org/wiki/Volunteer_computing), [distributed compilation](https://en.wikipedia.org/wiki/Distcc)), or Internet access ([Tor](https://en.wikipedia.org/wiki/Tor_(network)), [I2P](https://en.wikipedia.org/wiki/I2P)). In most cases it is shared over an *unstructured* (as participants join and leave) *2-layer* (there are dedicated servers that register and coordinate users) network which is [*overlaid*](https://en.wikipedia.org/wiki/Overlay_network) on top of the Internet. All the leaf nodes run identical narrowly specialized software (i.e. either file sharing or blockchain, but not both at once) which provides the clients with access to resources of other nodes, making a kind of distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] or [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].

Examples: torrent, onion routing (Tor), blockchain.

### Leaf-Spine Architecture, Spine-Leaf Architecture


![Each server of a datacenter is connected to a leaf node. Each leaf communicates with every spine node.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Leaf-Spine.png)


This [datacenter network architecture](https://www.geeksforgeeks.org/spine-leaf-architecture/) is a rare example of a *structured fully connected Mesh*. It consists of client-facing (*leaf*) and internal (*spine*) network switches. Each *leaf* is connected to every *spine*, allowing for very high bandwidth (by distributing the traffic over multiple routes) that is almost insensitive to failures of individual hardware as there are always many parallel connections.

### [[wiki/concepts/source/basic-metapatterns/shards|Actors]]


![Each actor reads from its message queue and writes to other actors' message queues.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Actors.png)


A system of *Actors* may be classified as a *fully connected Mesh* with the actors’ message queues being the nodes of the *Mesh*. Any actor can post messages to the queue of any other actor which it knows about, as all the actors share a virtual namespace or physical address space.

### [[wiki/concepts/source/extension-metapatterns/middleware|Service Mesh]]


![A service mesh comprises services each of which is connected to a sidecar connected to a mesh node. The mesh nodes communicate with a monitoring and control infrastructure.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Service%20Mesh.png)


A [*Service Mesh*](https://buoyant.io/service-mesh-manifesto) \[[wiki/concepts/source/appendices/books-referenced|[FSA]], [[wiki/concepts/source/appendices/books-referenced|MP]]\] is a distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for running [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]. It is a 2-layer *Mesh* which contains one or a few management nodes (*control plane*) and many user nodes (*data plane*). Each data plane node colocates:

- A *mesh engine node* that deals with connectivity,
- One or more [[wiki/concepts/source/extension-metapatterns/proxy|*Sidecars*]] ([[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]] where the support of *cross-cutting concerns* – the identical code in use by every service, e.g. logging or encryption – resides),
- A user *application* (*microservice*) that differs from node to node.


The control plane (re-)starts, updates, scales, and collects statistics from the nodes of the data plane.

*Service Mesh* addresses some of the weaknesses of naive [[wiki/concepts/source/basic-metapatterns/services|*Services*]]: it provides tools for centralized management and allows for virtual [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|sharing]] (through creating physical copies) of libraries to be accessed by all the service instances. It also takes care of scaling and load balancing.

Ready-to-use *Service Mesh* frameworks are popular with the [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] architecture.

### [[wiki/concepts/source/extension-metapatterns/sandwich|Space-Based Architecture]]


![Each processing unit is connected to a node of a data grid. The nodes directly exchange data updates and store them into a persistent database via a writer. There is also a reader to initiate nodes.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Space-Based%20Architecture.png)


[*Space-Based Architecture*](https://en.wikipedia.org/wiki/Space-based_architecture) \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\] is a kind of [*Service Mesh*](#service-mesh) with an integrated [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] (a [*tuple space*](https://en.wikipedia.org/wiki/Tuple_space) – shared dictionary – called [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]]) and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] (called *Processing Grid*). The user services are called *Processing Units*. They may be identical (making [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]]) or different (resulting in [[wiki/concepts/source/basic-metapatterns/services|*Services*]]). This architecture is used for:

- Highly scalable systems with relatively small datasets, in which case the entire database contents are replicated in the memory of each node. This works around the throughput and latency limits of an ordinary database.
- Huge datasets, with each node owning a part of the total data. This hacks around the storage capacity and latency limits of a database, which may even be kept out of the loop, leaving the *Mesh* as the only data storage.


There are multiple instances of the same data in *Processing Units*. Any change to the data in one unit must propagate to other units. That can be done in several ways:

- Asynchronously, causing conflicts if the same data is changed elsewhere at the same time.
- Synchronously, waiting for the propagation results and conflict resolution – a kind of distributed transaction which has poor latency.
- The unit takes write ownership of the data before the write. That is not good for latency as well, but it may be a good choice for an evenly distributed load if the *Mesh* engine provides temporary locality of requests, i.e. it forwards requests that touch the same data to the same node.


The choice of the strategy depends on your domain.

The in-memory data in the nodes is usually loaded from a *Persistent Database* on initialization of the system, and any change to the data is replicated asynchronously back to the *Persistent Database*, which serves as a means of fault recovery in the unlikely case the entire *Mesh* goes down.

## Summary

*Mesh* is a layer of intercommunicating instances of an infrastructure component that makes a foundation for running custom services in a distributed environment. This architecture is famous for its scalability and fault tolerance but is too complex to implement in-house, and may incur performance, administration and development overhead.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/implementation-metapatterns/microkernel.md ===== -->

---
title: "Microkernel"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Implementation metapatterns/Microkernel.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Implementation%20metapatterns/Microkernel
source_license_note: "See namespace README; preserve attribution and source links."
---

# Microkernel

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Implementation metapatterns/Microkernel.md`.


![A diagram for Microkernel, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Microkernel.png)


*Communism.* Share resources among consumers.

<ins>Known as:</ins> Microkernel (Architecture) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]] but [[wiki/concepts/source/analytics/ambiguous-patterns|not]] [[wiki/concepts/source/appendices/books-referenced|SAP]] and [[wiki/concepts/source/appendices/books-referenced|FSA]]\].

<ins>Structure:</ins> A layer of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] over a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] over a layer of [[wiki/concepts/source/basic-metapatterns/services|*Services*]].

<ins>Type:</ins> System topology, implementation.

| *Benefits* | *Drawbacks* |
| --- | --- |
| The system’s complexity is evenly distributed among the components | The API and SPIs are very hard to change |
| The resource providers are easy to replace | Performance is suboptimal |
| The components can have independent qualities | Latency is often unpredictable |
| A resource provider can be implemented and tested in isolation |  |
| Each application is sandboxed by the microkernel |  |
| The system is platform-independent |  |

<ins>References:</ins> the Microkernel pattern in \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\].

While vanilla [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] and [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] keep the business logic in their monolithic *core* components, *Microkernel* treats the core as a thin [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] (called *microkernel*) that connects user-facing applications (*external services*) to resource providers (*internal services*). The *resource* in question can be anything ranging from CPU time or RAM to business functions. The external services communicate with the microkernel through its *API* while the internal services implement the microkernel's *service provider interfaces* (*SPIs*) (usually there is one kind of internal service and an SPI per resource type).

On one hand, the pattern is very specific and feels esoteric. On the other – it is indispensable in many domains, with many more real-life occurrences than would be expected. *Microkernel* finds its place where there are a variety of applications that need to use multiple shared resources, with each resource being independent of others and requiring complex management.

### Performance

The *microkernel*, being an extra layer of indirection, degrades performance. The actual extent varies from a few percent for *OSes* and *virtualizers* to an order of magnitude for *scripts*. There is also a more grievous aspect of performance degradation, namely that latency becomes unpredictable as soon as the system runs short of one of the shared resources: memory, disk space, CPU time, or even storage for deleted objects. That is why [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|real-time systems]] rely on extremely minimalistic [real-time OS](https://en.wikipedia.org/wiki/Real-time_operating_system)es or even run on bare metal.

It is common to see system components communicate directly via shared memory or sockets bypassing the *microkernel* to alleviate the performance penalty which it introduces.

### Dependencies

The *applications* depend on the *API* of the *microkernel* while the *providers* depend on its *SPIs*. On one hand, that isolates the applications and providers from each other, letting them develop independently. On the other hand, the microkernel’s API and SPIs should be very stable to support older versions of the components which the microkernel integrates.


![Applications depend on the API of the microkernel. Providers depend on its SPIs.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Microkernel.png)


### Applicability

*Microkernel* is <ins>applicable</ins> in:

- *Systems programming.* You manage system resources and services which will be used by untrusted client applications. Hide the real resources behind a trusted proxy layer. Be ready to change the hardware platform without affecting the existing client code.
- *Frameworks that integrate several subdomains.* The microkernel component coordinates multiple specialized libraries. Its API is a [*Facade*](https://refactoring.guru/design-patterns/facade) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] for the functionality which it organizes.
- *Scripting or* [*DSL*](https://en.wikipedia.org/wiki/Domain-specific_language)*s.* The microkernel is an [*Interpreter*](#interpreter-script-domain-specific-language-dsl) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] which lets your clients’ code manage the underlying system.


*Microkernel* <ins>does not fit</ins>:

- *Coupled domains.* Any degree of coupling between the resource providers complicates the microkernel and its SPIs, and is likely to degrade performance, which, however, may be salvaged by introducing direct communication channels between the providers.


### Relations


![Microkernel as a middleware and as an orchestrator; applications of Microkernel Architecture as Backends for Frontends.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Microkernel.png)


*Microkernel*:

- Is a specialization of [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]].
- Is related to [*Backends for Frontends*](<Backends for Frontends (BFF)>), which is a layer of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]] over a layer of [[wiki/concepts/source/basic-metapatterns/services|*Services*]]; *Microkernel* adds a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] in between.
- Is a kind of 2-layered [*SOA*](<Service-Oriented Architecture (SOA)#enterprise-soa>) with an [[wiki/concepts/source/extension-metapatterns/orchestrator|*ESB*]].
- The *microkernel* layer serves as (implements) a [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for the upper (*external*) [[wiki/concepts/source/basic-metapatterns/services|*Services*]] and often makes an [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] for the lower (*internal*) *Services*.
- May be implemented by a [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]].


## Examples

*Microkernel* can appear in many forms:

- An [*Operating System*](#operating-system) shares hardware resources among many applications.
- A [*Software Framework*](#software-framework-pluggable-component-framework) provides a unified interface to access several libraries.
- A [*Virtualizer*](#virtualizer-hypervisor-container-orchestrator-distributed-runtime) maintains a generic interface to run guest software on any host OS and hardware.
- An [*Interpreter*](#interpreter-script-domain-specific-language-dsl) executes client scripts in a sandbox.
- A [*Configurator*](#configurator-configuration-file) sets up a system in accordance with a configuration file.
- A [*Saga Engine*](#saga-engine) runs distributed transactions.
- An [*AUTOSAR Classic Platform*](#autosar-classic-platform) provides automotive applications with access to any chip on board.


### Operating System


![Each application communicates with its runtime interfacing the shared operating system kernel which communicates with device drivers that adapt hardware components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/OS.png)


The original inspiration for *Microkernel*, namely *operating systems*, provides an almost perfect example of the pattern, even though their kernels are not that “micro-” (unless you are running [MINIX](https://en.wikipedia.org/wiki/Minix_3#Architecture) or [QNX](https://en.wikipedia.org/wiki/QNX#Technology)). [[wiki/concepts/source/basic-metapatterns/services|Device *drivers*]] (*internal services*) encapsulate available hardware resources (see [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Pedestal*]]) and make them accessible to user-space *applications* (*external services*) via an OS *kernel*. *Drivers* for a given kind of subsystem (e.g. network adapter or disk drive) are polymorphic towards the kernel and match the hardware installed.

### Software Framework, Pluggable Component Framework


![A framework is a facade between a user application and several lower-level components.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Framework.png)


In a *Software Framework* or *Pluggable Component Framework* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\] the *microkernel* (*abstract core* \[[wiki/concepts/source/appendices/books-referenced|[DDD]]\]) is a [[wiki/concepts/source/extension-metapatterns/orchestrator|*Facade*]] \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] that integrates a set of libraries and exposes a user-friendly high-level interface. [PAM](https://docs.oracle.com/cd/E23824_01/html/819-2145/pam-01.html) looks like a reasonably good example.

### Virtualizer, Hypervisor, Container Orchestrator, [[wiki/concepts/source/basic-metapatterns/services|Distributed Runtime]]


![A virtualizer stands between user applications and several instances of an operating system each running on a separate computer.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Virtualizer.png)


*Hypervisors* (Xen), PaaS and [FaaS](https://shivangsnewsletter.com/p/why-doesnt-cloudflare-use-containers), *container orchestrators* (Kubernetes) \[[wiki/concepts/source/appendices/books-referenced|[DDS]]\], and distributed *actor frameworks* (Akka, Erlang/Elixir/OTP) use resources of the underlying computer(s) to run guest applications. A hypervisor virtualizes the resources of a single computer while a distributed runtime manages those of multiple servers – in the last case there are several instances of the same kind of an *internal server* which abstracts a host system.

### Interpreter, Script, Domain-Specific Language (DSL)


![Each script runs over its instance of an interprester. All the interpreters share a set of libraries.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Interpreter.png)


User-provided *scripts* are run by an *Interpreter* \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] which also allows them to access a set of installed libraries. The *Interpreter* is a microkernel, and the syntax of the script or [*DSL*](https://en.wikipedia.org/wiki/Domain-specific_language) which it interprets is the microkernel’s API.

### Configurator, Configuration File


![A configurator runs at a system's startup, reads a configuration file, and sets up a system of services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Config%20file.png)


*Configuration files* may be regarded as short-lived [*scripts*](#interpreter-script-domain-specific-language-dsl) that configure the underlying modules at the start of the system. The parser of the configuration file is a transient *microkernel*.

### [[wiki/concepts/source/extension-metapatterns/orchestrator|Saga]] Engine


![A saga engine calls several services while executing multiple short-lived sagas.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Saga%20engine.png)


A [[wiki/concepts/source/extension-metapatterns/orchestrator|*Saga*]] \[[wiki/concepts/source/appendices/books-referenced|[MP]]\] orchestrates distributed transactions. It may be written in a [*DSL*](https://en.wikipedia.org/wiki/Domain-specific_language) which requires a compiler or [interpreter](#interpreter-script-domain-specific-language-dsl), which is a *microkernel*, to execute.

### AUTOSAR Classic Platform


![AUTOSAR Classic defines three segmented layers: applications, runtime environment with a shared Virtual Functional Bus, and basic software with generic and hardware-specific services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/AUTOSAR%20classic.png)


The [notorious](https://www.reddit.com/r/embedded/comments/leq366/comment/gmiq6d0/) [automotive standard](https://www.autosar.org/fileadmin/standards/R20-11/CP/AUTOSAR_EXP_VFB.pdf), though inspired by [*SOA*](<Service-Oriented Architecture (SOA)#misapplied-automotive-soa>), is structured as a distributed / virtualized *Microkernel*. The application layer comprises a network of *software components* spread out over hundreds of chips which are, for some secret reason, called *electronic control units* (*ECU*s). Both communication paths between the software components and much of the system’s code are static (auto-generated at compilation time). A software component may access hardware of its ECU via standard interfaces.

The *microkernel* shows up as *Virtual Functional Bus* (*VFB*) which, as a *distributed* [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]], provides communication between the *applications* by virtualizing multiple *Runtime Environments* (*RTEs*) – the local [system interfaces](https://www.autosar.org/fileadmin/standards/R22-11/CP/AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf).

## Summary

*Microkernel* is a ubiquitous approach to sharing resources among consumers, where both resource providers and consumers may be written by external companies.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/implementation-metapatterns/plugins.md ===== -->

---
title: "Plugins"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Implementation metapatterns/Plugins.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Implementation%20metapatterns/Plugins
source_license_note: "See namespace README; preserve attribution and source links."
---

# Plugins

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Implementation metapatterns/Plugins.md`.


![A diagram for Plugins Architecture, in abstractness-subdomain-sharding coordinates.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Main/Plugins.png)


*Overspecialize, and you breed in weakness.* Customize the system through attachable modules.

<ins>Known as:</ins> Plug-In Architecture \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], [Extension Architecture](https://www.uber.com/en-UA/blog/microservice-architecture/), (misapplied) Microkernel (Architecture) \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\], Plugin \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\], [Strategy](https://refactoring.guru/design-patterns/strategy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\], Reflection \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\], Aspects, Hooks.

<ins>Structure:</ins> A [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or subsystem extended with one or more modules that customize its behavior.

<ins>Type:</ins> Implementation, extension components.

| *Benefits* | *Drawbacks* |
| --- | --- |
| Some aspects are easy to customize | Testability is poor (too many combinations) |
| The customized system is relatively light-weight | Performance is suboptimal |
| Platform-specific optimizations are supported | Designing good SPIs for plugins is hard |
| The custom pieces may be written in a different programming language or DSL |  |

<ins>References:</ins> \[[wiki/concepts/source/appendices/books-referenced|[SAP]]\] and \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] [[wiki/concepts/source/analytics/ambiguous-patterns|mistakenly]] call this pattern *Microkernel* and dedicate chapters to it.

Most systems require some extent of customizability that may range from the basic codec selection by a video player to the screens full of tools and wizards unlocked once you upgrade your subscription plan. This is achieved by keeping the *core* functionality separate from its extensions, which are developed by either your team or external enthusiasts to fine-tune the behavior of the system. The cost of flexibility is paid in complexity of design – the need to predict which aspects should be customizable and which *SPI*s ([*Service Provider Interfaces*](https://en.wikipedia.org/wiki/Service_provider_interface)) are good for both known and still unknown uses by the extensions. If the communication between the core and *plugins* is heavy, performance may suffer.

### Performance

Using plugins usually degrades performance. The effect may be negligible for in-process plugins (such as strategies or codecs) but it becomes noticeable if inter-process communication or networking is involved.

The only case for a plugin to improve performance of a system that I can think of is when a part of the client’s business logic moves to a lower layer of a system or to another service forming an [*Ambassador Plugin*](#ambassador-plugin-logic-extension). That is similar to the [[wiki/concepts/source/basic-metapatterns/layers|strategy injection optimization for *Layers*]]. Real-world examples include:

- The use of *stored procedures* in databases,
- HFT rules and price tables [uploaded](https://www.youtube.com/watch?v=sX2nF1fW7kI) to a network card or FPGA,
- Customization of a supplier [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] for varying needs of its client *Cells* in [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>).


![Business logic injection in Layers and Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Performance/Plugins-injection.png)


### Dependencies

Each *plugin* depends on the *core*’s *API* (for *Addons*) or *SPI* (for *Plugins*) for the functionality it extends. That makes the APIs and SPIs nearly impossible to modify, only to extend, as there tend to be many plugins in the field, some of them out of active development, that rely on any given method of the already published interfaces.


![Each plugin depends on an interface of the core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Dependencies/Plugins.png)


### Applicability

*Plugins* are <ins>good</ins> for:

- *Product lines.* The shared *core* functionality and some *plugins* are reused by many flavors of the product. Per-client customizations are largely built using existing plugins.
- *Frameworks.* A framework is a functional core to be customized by its users. When shipped with a set of plugins it becomes ready-to-use.
- *Platform-specific customizations. Plugins* allow both for native look and feel (e.g. desktop vs mobile vs console) and for the use of platform-specific hardware.


*Plugins* <ins>do not perform well</ins> in:

- *Highly optimized applications.* Any generic code tends to be inefficient. A generic *SPI* that serves a family of plugins is unlikely to be optimized for the use by any one of them.


### Relations


![A monolith with plugins; layers with plugins; a Cell with a plugin.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Plugins.png)


*Plugins*:

- Implement [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]].
- Extend [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]], or [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] with one or two layers of services.


## Variants

*Plugins* are omnipresent if we take [*Strategy*](https://refactoring.guru/design-patterns/strategy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] for a kind of plugin. They vary:

### By the direction of communication

A plugin may:

- Provide input to the core (as UI screens and [CLI](https://en.wikipedia.org/wiki/Command-line_interface) connections do).
- Receive output from the core (e.g. collection of statistics).
- Participate in both input and output (like health check instrumentation).
- Take the role of [[wiki/concepts/source/extension-metapatterns/orchestrator|*Controller*]] (*Orchestrator*) – the plugin processes events from the core and decides on the core’s further behavior.
- Be a data processor – the plugin implements a part of a [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|data processing]] algorithm which is run by the core. This enables platform-specific optimizations, like SIMD or DSP.


### By linkage

Plugins may be *built in* or selected dynamically:

- Every *flavor* (e.g. free, lite, pro, premium) of a product line incorporates a single set of plugins (configuration) built into the application. Web services often use this kind of customization for [[wiki/concepts/source/basic-metapatterns/shards|*Multitenancy*]].
- Other systems choose and initiate their plugins on startup according to their configuration files or licenses.
- Still others support attaching and detaching plugins dynamically at runtime.


### By granularity

Plugins come in different sizes:

- Small functions or classes are built into the core. They seem to implement the [*Strategy*](https://refactoring.guru/design-patterns/strategy) \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] / *Plugins* \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] design patterns.
- [*Aspects*](https://en.wikipedia.org/wiki/Aspect_(computer_programming)), such as logging and memory management, pervade a system and are accessed from many places in its code. *Reflection* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] probably belongs there.
- Modules are plugged in as separate system components. This kind of *Plugins* matches the topic of this book and is further developed by [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] and [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].


### By the number of instances

A plugin may be:

- *Mandatory* (1 instance), like a piece of algorithm used by the core for a calculation.
- *Optional* (0 or 1 instance), like a smart coloring scheme for a text editor.
- *Subscriptional* (0 or more instances), like log output which may go to a console, the system log, a log file, socket, or to all of them simultaneously.


### By execution mode

Plugins may be:

- Linked as a binary code called from within the core.
- Written in a [*domain-specific language*](https://en.wikipedia.org/wiki/Domain-specific_language) (*DSL*) and [[wiki/concepts/source/implementation-metapatterns/microkernel|interpreted]] by the core.
- Remote, available as a stand-alone web service or even hardware component which the core needs to access through a dedicated protocol.


## Examples

*Plugins* can take different roles and places in the system. Though their classification and naming has never been well established, we can discern the following kinds of *plugins*, which are non-exclusive, meaning that a single application may support some or all of them at once:

- A [true *Plugin*](#true-plugin-or-plug-in) provides custom low-level functionality.
- An [*Ambassador Plugin*](#ambassador-plugin-logic-extension) injects a part of a given service’s business logic into another service.
- An [*Extension*](#extension) modifies its target’s workflow (use cases).
- An [*Addin*](#addin-or-add-in) is a deeply integrated optional part of a system’s core logic.
- An [*Addon*](#inexact-addon-or-add-on) is an addition that wraps an application to improve user experience.


### True Plugin (or Plug-in)


![Several low-level plugins are called by a use case running in a system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Plugins.png)


A true *Plugin* is registered with and called by the system’s *core* to provide (as an algorithm) or extend (as a custom step) a specific low-level functionality. It is usually made by a third party.

Customizable software often exposes multiple interfaces for different kinds of *Plugins*, some of which are *optional* (0 or 1 instance) or *subscriptional* (multiple instances) as explained [earlier](#by-the-number-of-instances).

Examples: codecs in a video player, country-specific tax calculation rules in accounting software, or filters in a traffic sniffer.

### [[wiki/concepts/source/extension-metapatterns/proxy|Ambassador]] Plugin, Logic Extension


![An ambassador plugin is a part of one service hosted inside another service. When called, it may consult its origin service or make independent decisions.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Ambassador%20Plugin.png)


A service may accept *Plugins* that [act on behalf of peer services](https://www.uber.com/en-UA/blog/microservice-architecture/) (are are their [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassadors*]]) and are implemented by their teams. That [[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|inverts dependencies]]: whoever wants to affect the behavior of your service uses your SPI to inject their code into your service which apart from that remains self-contained. As a result, whatever used to be a system-wide workflow becomes limited to a single subdomain.

Though an *Ambassador Plugin* (aka Uber’s [*Logic Extension*](https://www.uber.com/en-UA/blog/microservice-architecture/)) may call the service on whose behalf it acts, it is preferable performance-wise for it to make independent decisions without cross-service calls (it works as a smart [[wiki/concepts/source/extension-metapatterns/proxy|*Cache*]] that provides decisions instead of data). For data-driven decisions the *Ambassador* may need to opaquely receive and store data ([*Data Extension*](https://www.uber.com/en-UA/blog/microservice-architecture/)) in its host’s data store.

*Ambassador Plugins* are widely used in Uber’s [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) to decouple its [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]].

### Extension


![An extension is called as a high-level part of a system's use case.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Extension.png)


An *Extension* changes use cases by modifying the application’s business logic, but it is still called by the application’s *core*. An *Extension* may install a group of low-level *Plugins* which add to the system’s low-level functionality whatever tools the *Extension* relies on.

Examples: IDE customization.

### Addin (or Add-in)


![An addin is hosted inside a system and implements a part of its control flow.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Addin.png)


An *Add-in* is deeply integrated with the *core* – the system has been originally designed to provide it thorough access to its internals. It comes from the system’s creators or external teams that commit to the system *core*’s codebase.

Examples: complex extensions for web browsers or static website generators.

### (inexact) Addon (or Add-on)


![An addon is a layer between a system and its client. It translates a single client request into multiple calls to the underlying system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Addon.png)


Though any of the variants of *Plugins* described above may sometimes be called an *addon*, there is a kind of system extension which perfectly matches the meaning of the word.

A true *Addon* is built on top of the system’s *API* (not a dedicated *SPI* as with other kinds of *Plugins*) and calls into the system from outside – it is a kind of an external [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] or even [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] for the system.

Examples: applications that provide [[wiki/concepts/source/extension-metapatterns/proxy|user interface]] for command-line tools such as git.

## Summary

*Plugins* allow for customization of a component’s behavior at the cost of increased complexity, poor testability, and somewhat reduced performance.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/introduction/about-this-book.md ===== -->

---
title: "About this book"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Introduction/About this book.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Introduction/About%20this%20book
source_license_note: "See namespace README; preserve attribution and source links."
---

# About this book

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Introduction/About this book.md`.

When I was learning programming, there was [*Gang of Four*](https://en.wikipedia.org/wiki/Design_Patterns). The book promised to teach software design, and it did to an extent with the case study provided. However, the patterns it described were merely random tools which had little in common. After several years, having reinvented [*Hexagonal Architecture*](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)) along the way, I learned about [*Pattern-Oriented Software Architecture*](https://en.wikipedia.org/wiki/Pattern-Oriented_Software_Architecture). The series had many more intriguing patterns, and promised to provide a *system of patterns* or a *pattern language*, but failed to build an intuitive whole. Then there were specialized books with [*Domain-Driven Design*](https://en.wikipedia.org/wiki/Domain-driven_design) and *Microservices* patterns. There was the [*Software Architecture Patterns*](https://www.oreilly.com/content/software-architecture-patterns/) primer by Mark Richards. Its simplicity felt great, but it had only 5 architectural styles, while his next book, *Fundamentals of Software Architecture*, dived too deeply into practical details and examples to be easily grasped.

Now, having leisure thanks to the war, burnout, unemployment, and depression I have had a chance to collect architectural patterns from multiple sources and build a taxonomy of architectures. My goal was to write the very book I lacked in those early years: a shallow but intuitive overview of all the software and systems architectures as used in practice, their properties and relations. I hope that it will be of some help both to novice programmers as a kind of a primer on the principles of high-level software design and to adept architects by reminding them of the big picture outside of their areas of expertise.

The book is mostly technology-agnostic. It does not answer practical questions like “Which database should I use?” Instead it inclines towards the understanding of “When should I use a shared database?” Any specific technologies ~are easy to google~ can be found ~over the Internet~ somewhere in the Noosphere.

This book started as a rather small project to prove that patterns can be intuitively classified (*These nightmarish creatures* can *be felled! They* can *be beaten!*) but grew into a multifaceted compendium of a hundred or so architectures and architectural patterns. It is grounded in the idea that software and systems architecture evolves naturally, as opposed to being scientifically planned. Thus, the architectures may exhibit [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|fractal features]], just like those in biology – merely because the [[wiki/concepts/source/analytics/cohesers-and-decouplers|set of guidelines and forces]] remains the same for most systems that range from low-end embedded devices to world-wide financial networks. Moreover, in some cases we can see the same patterns applied to hardware design.

The idea of unifying software and systems architecture is heretical. I am well aware of that. Still, the industry is in the early stage of alchemy these days: the same things are sold under multitudes of names, being remarketed or reinvented every decade. If this book manages to provide rules of thumb, similar to those of biology (a bat is a mammal, thus it should run on all four, while ostriches, as birds, must fly to Europe each spring), I will be happy with that. *Science makes progress funeral by funeral*.

The latest version of the book is available for free on [GitHub](https://github.com/denyspoltorak/metapatterns) and [LeanPub](https://leanpub.com/metapatterns), and can be [read online](https://metapatterns.io/). As there is no one who has practiced all the known architectures, it will be full of mistakes. I rely on your goodwill to correct them and improve the text. Critical reviews are warmly welcome: please write an [email](mailto:descri@gmail.com) or contact me [on LinkedIn](https://www.linkedin.com/in/denyspoltorak/).

## Structure of the book

The [[wiki/concepts/source/introduction/metapatterns|first chapter]] explains the main idea which makes this book different from others. The [[wiki/concepts/source/introduction/system-topologies|second chapter]] outlines the scope of the book’s content. The following chapters in the [[wiki/concepts/source/foundations-of-software-architecture/foundations-of-software-architecture|first part]] touch on several general topics that are referenced throughout the book.

The next [[wiki/concepts/source/basic-metapatterns/basic-metapatterns|four parts]] iterate over *metapatterns* (clusters of closely related architectural patterns), starting with the simplest one, namely [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], then heading towards more complex systems that may be derived from *Monolith* by recursively dissecting it with interfaces. Each chapter describes a group of related patterns that share benefits and drawbacks, adds in a few references to books and websites, and summarizes the ways those patterns can be transformed into other architectures. The format of these chapters is described in [[wiki/concepts/source/appendices/format-of-a-metapattern|Appendix F]].

The [[wiki/concepts/source/analytics/analytics|sixth part]] of the book is analytics – the fruits of the pattern classification explored in the earlier parts.

Finally, there are [[wiki/concepts/source/appendices/appendices|appendices]]. [[wiki/concepts/source/appendices/books-referenced|Appendix B]] is the list of the books referenced, [[wiki/concepts/source/appendices/evolutions-of-architectures|Appendix E]] contains detailed evolutions of patterns, and [[wiki/concepts/source/appendices/index-of-patterns|Appendix I]] is the index of the patterns found in the book.

## Diagrams

This book makes heavy use of diagrams to the extent that it can be treated as a kind of visual novel. As it is mostly made of patterns, and *no pattern is an island*, it must not be read sequentially – instead, the reader is advised to use the plentiful cross-links to open whatever (if any) content found to be intriguing and check the corresponding diagram. If it gets your attention, you may read the text below it. If you like the text, you may scroll up or down to see if there are more funny diagrams nearby.

The diagrams are *NoUML* (boxes and arrows) and most of them belong to one of the following kinds:


![A structural, sequence, and dependency diagrams in NoSQL notation as used throughout the Architectural Metapatterns book.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Misc/Diagrams.png)


Components in the diagrams are colored according to the kind of code they contain:

- Use cases ([[wiki/concepts/source/basic-metapatterns/layers|application logic]]) are green.
- Business rules ([[wiki/concepts/source/basic-metapatterns/layers|domain logic]]) are blue.
- Generic code is white.
- The data is gray.


There are also non-code (external) components:

- Users and clients resemble milk chocolate.
- Hardware and the operating system are steel-colored.


Please refer to the [[wiki/concepts/source/introduction/metapatterns|following chapter]] for the system of coordinates used in the diagrams.

## Notation

- Pattern names are given in [[wiki/concepts/source/appendices/index-of-patterns|*Title Case Italics*]] and usually link to the pattern’s definition.
- The first mention of a term or a name of a pattern component is *italicized*.
- *Quotes and puns are in full italics*.
- Book references are \[[wiki/concepts/source/appendices/books-referenced|[BRACKETED]]\] and link to the list of the books in Appendix B.
- > Supplementary explanations are grayed-out.


Many patterns match terms of the common language – indeed, as a pattern is a generalization of human experience, the more widespread a notion, the faster it is turned into a pattern. Such general-use terms, e.g. layers, services or pipeline, are usually not indicated in any way to preserve the overall readability.

## The architectural religions

There are several schools of software architecture:

1.  The believers in [SOLID](https://en.wikipedia.org/wiki/SOLID).
2.  The followers of [nine qualities](https://iso25000.com/index.php/en/iso-25000-standards/iso-25010), [five views](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model) and [as-many-as-one-gets certifications](https://en.wikipedia.org/wiki/Enterprise_architecture_framework#Types_of_enterprise_architecture_framework).
3.  The aspirants to the [nameless](https://en.wikipedia.org/wiki/The_Timeless_Way_of_Building#Summary) way of [patterns](https://en.wikipedia.org/wiki/Software_design_pattern).


In my opinion:

1.  SOLID is a silver bullet that tends to produce a [*DDD*-layered kind of *Hexagonal Architecture*](https://herbertograca.com/2017/09/28/clean-architecture-standing-on-the-shoulders-of-giants/). It lacks the agility of pluralism found with evolutionary ecosystems.
2.  Architectural frameworks are overcomplicated thus hard to understand and inflexible.
3.  Patterns are like a kind of toolbox, the one which a mechanic is often seen carrying around. A skilled craftsman knows best uses of his tools, and can invent new instruments if something is missing in the standard toolset. However, the toolset’s size should be limited for the tools to be familiar to the practitioner and easily carried around.


> There is a similarity between patterns and data structures. Even though you may know hundreds of specialized data structures, most software can be easily built with vectors, lists, and hash tables alone. Something like a [prefix tree](https://en.wikipedia.org/wiki/Trie) or [skip list](https://en.wikipedia.org/wiki/Skip_list) is a rare beast, but under certain circumstances it may save the day. In the same way, business logic can be written without any use of patterns, but the resulting code will likely be hard to maintain, and even its performance may suffer (see [*Spatial Partition*](https://gameprogrammingpatterns.com/spatial-partition.html) and [*Unit of Work*](https://martinfowler.com/eaaCatalog/unitOfWork.html) for patterns that drastically improve performance).

It is likely that those approaches are best used with systems of different sizes: SOLID is aimed at stand-alone application design while the heavy frameworks and certifications suit distributed enterprise architectures. In such a worldview patterns span everything in between the two extremes.

> Patterns of software architecture are abstract just like [Plato’s Ideas or Forms](https://en.wikipedia.org/wiki/Theory_of_forms) in philosophy or classes in object-oriented programming. There is only one instance of each given pattern, which is a general idea or a very high-level blueprint for every implementation of the pattern ever seen in the code.

## What’s wrong with patterns

*Too much information is no information* or, as they say, *what is not remembered never existed*. There are literally thousands of patterns described for software and systems architectures. Nobody knows them all and nobody cares to know them all (if you say you do, you must have already read [the Pattern Languages of Programs archives](https://hillside.net/index.php/past-plop-conferences). Have you? Neither have I). Hundreds of patterns are generated yearly in just the conferences alone, not to mention the books and software engineering websites. Old patterns get [rebranded or forgotten and reinvented](https://datatracker.ietf.org/doc/html/rfc1925). This is especially true for the discrepancy between the pattern names in software architecture and systems architecture. The new [*N-tier*](https://en.wikipedia.org/wiki/Multitier_architecture) is just good old *Layers* under the hood, isn’t it?

This undermines the original ideas which brought in the patterns hype:

1.  *Patterns as a ubiquitous language*. Nowadays similar, if not identical, patterns bear different names, and some of them are too obscure to be ever heard of (see [the PLoP archives](https://hillside.net/index.php/past-plop-conferences)).
2.  *Patterns as a vessel for knowledge transfer*. If an old pattern is reinvented or plagiarized, most of the old knowledge is lost. There is no continuity of experience.
3.  *Pattern language as the ultimate architect’s tool*. As patterns are re-invented, so are pattern languages. At best, we have domain-specific or architecture-limited ([*DDD*](https://en.wikipedia.org/wiki/Domain-driven_design), [*Microservices*](https://microservices.io/patterns/index.html)) systems of patterns. There is no *single unified vision* which pattern enthusiasts of old promised to provide.


Have we been fooled?

## TLDR

Compare [[wiki/concepts/source/extension-metapatterns/proxy|*Firewall*]] and [[wiki/concepts/source/extension-metapatterns/proxy|*Response Cache*]]. Both represent a system to its users and implement generic aspects of the system’s behavior. Both are [[wiki/concepts/source/extension-metapatterns/proxy|*Proxies*]].

Take [[wiki/concepts/source/extension-metapatterns/orchestrator|*Saga Execution Component*]] and [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Composer*]]. Both are high-level services that make a series of calls into an underlying system – they *orchestrate* it. Both are [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrators*]].

It’s that simple and stupid. We can classify architectural patterns.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/introduction/introduction.md ===== -->

---
title: "Introduction"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Introduction/Introduction.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Introduction/Introduction
source_license_note: "See namespace README; preserve attribution and source links."
---

# Introduction

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Introduction/Introduction.md`.

## You’ll find inside

- An atlas of [[wiki/concepts/source/introduction/system-topologies|system topologies]].
- A compendium of [architectural patterns](https://en.wikipedia.org/wiki/Architectural_pattern).
- One of the largest and most cohesive [pattern languages](https://en.wikipedia.org/wiki/Pattern_language).

## Further chapters:

- [[wiki/concepts/source/introduction/about-this-book|About this book]]
- [[wiki/concepts/source/introduction/metapatterns|Metapatterns]]
- [[wiki/concepts/source/introduction/system-topologies|System topologies]]


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/introduction/metapatterns.md ===== -->

---
title: "Metapatterns"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Introduction/Metapatterns.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Introduction/Metapatterns
source_license_note: "See namespace README; preserve attribution and source links."
---

# Metapatterns

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Introduction/Metapatterns.md`.

Is there a way to bring the patterns into order? They are way too many, some obscure, others overly specialized.

We can try. On a subset. And the subset should be:

- *Important* enough to matter for the majority of programmers.
- *Small* enough to fit in one’s memory or in a book.
- *Complete* enough to assure that we don’t miss anything crucial.


Is there such a set? I believe so.

## Architectural patterns

\[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] defines three categories of patterns:

- *Architectural patterns* which deal with the overall structure of a system and functions of its components.
- *Design patterns* which describe relations between objects.
- *Idioms* which provide abstractions on top of a given programming language.


Architectural patterns are important by [definition](https://martinfowler.com/architecture/) (*Architecture is about the important stuff. Whatever that is*). Point 1 (*importance*) – checked.

Any given system has an internal structure. When its developers talk about *architectural style* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]]\] or draw structural diagrams that usually boils down to a composition of two or three well-known architectural patterns. Choosing architectural patterns as the subject of our study lets us feed on a large body of books and articles that describe similar designs over and over again. Moreover, as soon as a system no longer follows the latest fashions, it is widely advertised as a novelty (or its designers are labeled as old-fashioned and shortsighted), thus we may expect to have heard of nearly all of the architectures which are used in practice. Point 3 (*completeness*) – we have more than enough examples to analyze.

To organize a set of patterns we rely on the concept of design space.

## Design space

*Design space* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA5]]\] is a model that allocates a dimension for each choice made while architecting the system. Thus it contains all the possible ways for a system to be designed. The only trouble – it is multidimensional, maybe infinite, and the dimensions will differ from system to system.

There is a workaround – we can use a projection from the design space into a 2- or 3-dimensional space which we are more comfortable with. However, projection causes a loss of information. Counterintuitively, that is good for us – similar architectures that differ in minor details become identical as soon as the dimensions they differ in disappear. If we could only find 2 or 3 most important dimensions that apply equally well to each pattern in the set that we want to research, that is architectural patterns, which cover all the known system designs.

## Structure determines architecture

Systems tend to have an internal structure. Those that don’t are derogatively called [*Big Balls of Mud*](http://www.laputan.org/mud/) for their peculiar properties. Structure is all about components, their roles and interactions. Many architectural styles, for example, [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]], are named after their structures, while others, like [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architecture*]], highlight some of its aspects, hinting that it is the structure which determines principal properties of a system.

I am not the first person to reach such a conclusion. *Metapatterns* – clusters of patterns of similar structure – were [defined](https://softwareresearch.net/fileadmin/user_upload/Documents/publications/conference_proceedings/C010.pdf) shortly after the first collections of design patterns had appeared but they never made a lasting impact on software engineering. I believe that the approach was applied prematurely to analyze the \[[wiki/concepts/source/appendices/books-referenced|[GoF]]\] patterns, which make quite a random and incomplete subset of design patterns, resulting in an overgeneralization. I intend to plot structures of all the architectural patterns I encounter, group patterns of identical structure together into metapatterns, draw relations between the metapatterns, and maybe show how a system’s structure determines its properties. Quite an ambitious plan for a short book, isn’t it?

Our set of architectural patterns is still not known to be complete, is not small and, moreover, the way structural diagrams are drawn differs from source to source – we cannot compare them unless we make up a universal system of coordinates.

## The system of coordinates

Inventing a generic coordinate system to fit any pattern’s representation, from [*Iterator*](https://refactoring.guru/design-patterns/iterator) to [[wiki/concepts/source/basic-metapatterns/monolith|*Half-Sync/Half-Async*]], may be too hard, but we surely can find something for architectural patterns, as all of them share the scope, namely the system as a whole. Which dimensions an implementation of a system would usually be plotted along?

1.  *Abstractness* – there are high-level use cases and low-level details. A single highly abstract operation unrolls into many lower-level ones: Python scripts run on top of a C runtime and assembly drivers; orchestrators call API methods of services, which themselves run SQL queries towards their databases which are full of low-level computations and disk operations.
2.  *Subdomain* – any complex system manages multiple subdomains. An OS needs to deal with a variety of peripheral devices and protocols: a video card driver has very little resemblance to an HDD driver or to the TCP/IP stack. An enterprise has multiple departments, each operating a software that fits its needs.
3.  *Sharding* – if several instances of a module are deployed, and that fact is an integral part of the architecture, we should represent the multiple instances on our structural diagram.


We’ll draw the abstractness axis vertically with higher-level components positioned towards the upper side of the diagram, the subdomain axis horizontally, and sharding diagonally. Here is an (arbitrary) example of such a diagram:


![A diagram of a CQRS system in abstractness-subdomain-sharding coordinates with a detailed legend.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/CQRS%20with%20notes.png)


(A structural diagram for [[wiki/concepts/source/fragmented-metapatterns/layered-services|*CQRS*]], adapted from [Udi Dahan’s article](https://udidahan.com/2009/12/09/clarified-cqrs/), to introduce the notation)

> Abstractness is usually inverse to the distance to the system’s clients. A graphical interface is highly abstract with its intuitive windows, forms, and scrollbars, and it is the part of the software which the users interact with. The opposite end of the system hosts device drivers which operate in cryptic bits and registers. Nevertheless, the reality is more complex: to draw UI windows on the screen the software still needs help from graphic card drivers deep inside the OS. Likewise, there are several layers of routing and proxies between a web page that you see in your browser and the server-side logic which that page allows you to access. Even though those intermediate layers are not highly abstract, we still draw them in the upper part of diagrams between a system and its clients to keep the diagrams [simple and stupid](https://en.wikipedia.org/wiki/KISS_principle).

## Map and reduce

Now that we have the generic coordinates which seem to fit any architectural pattern, we can start mapping our set of architectural patterns into that coordinate system to reduce the multidimensional design space down to the few dimensions of structural diagrams which we were actually looking for. Then, after filtering out minor details, our hundred or so published patterns should yield a score of [[wiki/concepts/source/introduction/system-topologies|*topologies*]] – clusters of geometrically equivalent diagrams – just because there are very few simple systems that one can draw on a plane before repeating oneself. Each topology will represent an *architectural metapattern* – a generalization of architectural patterns of similar structure and function.

Let’s return for a second to our requirements for classifying a set of patterns. The importance (point 1) of architectural patterns was proved before. The reasonable size of the resulting classification (point 2) is granted by the existence of only a few simple 2D or 3D shapes (topologies). The completeness of the analysis (point 3) comes from, on one hand, the geometrical approach which makes any blank spaces (possible geometries with no known patterns) obvious, and on the other – from the large sample of architectural patterns which we are classifying.

Godspeed!

## An example of metapatterns

Let’s consider the following structure:


![Two high-level components interact with one low-level component.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Example-Undefined.png)


It features two (or more in real life) high-level modules that communicate with/via a lower-level module. Which patterns does it match?

- [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] – a software that provides means of communication between other components.
- [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] – a space for other components to store and exchange data.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller*]] – a platform-agnostic business logic with customized means of input and output.


![Diagrams for Services with a Middleware, Services with a shared database and Model-View-Controller.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Intro/Example-Defined.png)


My idea of grouping patterns by structure seems to have backfired – we got three distinct patterns that have similar structural diagrams. The first two of them are related – both implement indirect communication, and their distinction is fading as a *Middleware* may feature a persistent storage for messages while a table in a *Shared Database* may be used to orchestrate services. The third one is very different – primarily because the bulk of its code, that is its *business logic*, resides in the lower layer, leaving the upper-level components a minor role.

Notwithstanding, each of the patterns we found is a part of a distinct cluster:

- *Middleware* is also known as *(Message) Broker* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]], [[wiki/concepts/source/appendices/books-referenced|EIP]], [[wiki/concepts/source/appendices/books-referenced|MP]]\] and is an integral part of [[wiki/concepts/source/extension-metapatterns/middleware|*Message Bus*]] \[[wiki/concepts/source/appendices/books-referenced|[EIP]]\], [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], [[wiki/concepts/source/extension-metapatterns/middleware|*Event Mediator*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], [[wiki/concepts/source/extension-metapatterns/middleware|*Enterprise Service Bus*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], and [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\].
- *Shared Database* is a kind of [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] \[[wiki/concepts/source/appendices/books-referenced|[POSA4]]\] ([[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Memory*]], [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared File System*]]), and the foundation for [[wiki/concepts/source/extension-metapatterns/shared-repository|*Blackboard*]] \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\], [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\], and [[wiki/concepts/source/extension-metapatterns/sandwich|*Service-Based Architecture*]] \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\].
- *Model-View-Controller* \[[wiki/concepts/source/appendices/books-referenced|[POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA4]]\] is a special kind of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] (aka [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Ports and Adapters*]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Onion Architecture*, and *Clean Architecture*]]) which itself is derived from [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] \[[wiki/concepts/source/appendices/books-referenced|[PEAA]]\] (*Addons*, *Plug-In Architecture* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\], or the [[wiki/concepts/source/analytics/ambiguous-patterns|misnomer]] *Microkernel Architecture* \[[wiki/concepts/source/appendices/books-referenced|[SAP]], [[wiki/concepts/source/appendices/books-referenced|FSA]]\]).


Our touching on a single topology revealed a web of twenty or so pattern names that spreads all around. With such a pace there is a hope of exploring the whole fabric which is known as *pattern language* \[[wiki/concepts/source/appendices/books-referenced|[GoF]], [[wiki/concepts/source/appendices/books-referenced|POSA1]], [[wiki/concepts/source/appendices/books-referenced|POSA2]], [[wiki/concepts/source/appendices/books-referenced|POSA5]]\].

There are three lessons to learn:

- The distribution of business logic is a crucial aspect of topologies.
- Metapatterns are interrelated in multiple ways, forming a pattern language.
- Each metapattern includes several well-established patterns.


## What does that mean

Chemistry has the [periodic table](https://en.wikipedia.org/wiki/Periodic_table). Biology has the [tree of life](https://en.wikipedia.org/wiki/Tree_of_life_(biology)). This book strives towards building something of that kind for software and systems architecture. You can say “That makes no sense! Chemistry and biology are empirical sciences while software architecture isn’t!” Is it?


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/introduction/system-topologies.md ===== -->

---
title: "System topologies"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Introduction/System topologies.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Introduction/System%20topologies
source_license_note: "See namespace README; preserve attribution and source links."
---

# System topologies

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Introduction/System topologies.md`.

In the [[wiki/concepts/source/introduction/metapatterns|previous chapter]] we started with architectural patterns and grouped them in accordance with their structure and function into *metapatterns*. Now let’s traverse in the opposite direction: from *topology* (the structure of a system) to the patterns which describe it. We will draw and analyze a map of common system topologies and along the way outline the scope of this book.

## Methodology

We will rely on our finding that any system has a characteristic representation in the [[wiki/concepts/source/introduction/metapatterns|abstractness-subdomain-sharding space]]. The amounts of a system’s partitioning along each of the three dimensions can be used as its coordinates on a map of system topologies:

- *Abstractness* corresponds to the *technical partitioning* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] – subdivision of a system into [[wiki/concepts/source/basic-metapatterns/layers|*layers*]] with different roles and technologies. Any use case will likely involve all the layers.
- *Subdomain* represents the *domain partitioning* \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] – segregation of a system into [[wiki/concepts/source/basic-metapatterns/services|*modules* or *services*]] that encapsulate distinct parts of the business knowledge. A use case is often localized in one or two subdomains.
- *Sharding* is about running multiple instances ([[wiki/concepts/source/basic-metapatterns/shards|*shards*]] or [[wiki/concepts/source/basic-metapatterns/shards|*replicas*]]) of a component.


![Technical partitioning into Layers, domain partitioning into Services, and multiple instances of a system.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Partitioning.png)


### From theory to practice

Having a distribution of architectures in a 3D space sounds great, but how do we represent it as human-readable media?

There are at least the following issues:

- Many system topologies feature similar levels of segregation into layers and services, meaning that they belong to the same neighborhood on the map.
- It makes a difference whether a system’s business logic or its infrastructure is subdivided because business logic comprises the bulk of the code. Therefore we cannot estimate a system’s coordinates only from the number of layers or services it contains, which means that we are limited to something like “major layering” and “minor layering” instead of numeric values.
- Sharding of many architectures varies widely and is hard to represent on a flat drawing.


As a result, the following adjustments were necessary to make the map of system topologies comprehensible:

- Sharding is omitted, transforming 3D coordinates into a flat map. Yes, much information is lost, but *too much information is no information*. Now the map is easier to read.
- I took the liberty of shifting topologies from their real positions to resolve overlaps.
- Even worse, I moved some of the topologies around to group similar architectures.
- Exotic (e.g. [[wiki/concepts/source/implementation-metapatterns/mesh|*Leaf-Spine Architecture*]]) and duplicate (e.g. [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]]) topologies are omitted.


## The map of system topologies


![A map of system topologies arranged according to the amount of their partitioning into layers and services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Topologies%20Map.png)


The map contains only basic architectures which are easy to apprehend and name. Any complex system is very likely to be a combination of these simple topologies.

I somewhat arbitrarily divided the map of system topologies into five partially overlapping regions:

- [*Monolithic*](#monolithic-systems), where the bulk of the system is kept in a single component.
- [*Layered*](#layered-architectures), with mostly technical partitioning and specialized components (drawn in one or two colors which correspond to different kinds of code).
- [*Services*](#services-area) with domain partitioning, meaning that each of the main components includes several kinds of code.
- [*Fragmented*](#fragmented-patterns) *systems* built of many smaller parts.
- [*Plugins*](#plugins-family) that usually have a cohesive core and external modular layers.


This grouping allows us to study the topologies piecemeal without getting lost in their numbers and features.

## Monolithic systems

In the simplest cases a project is too small for any internal structure to be justified – you can code it in a couple of hours without any preliminary design. In other cases the domain is known to be so cohesive that you cannot find good module boundaries – any internal interfaces result in much boilerplate code or degrade performance. Or there is no time left for a thoughtful design!

### True Monoliths


![Diagrams of Monolith, Shards, and Replicas.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/True%20Monoliths.png)


Few system topologies are truly monolithic with one kind of system components:

- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] keeps everything together in a single cohesive application which makes sense for small, one-off projects. A long-running *Monolith* may need to handle inputs and events, for which there are several options:
  - [[wiki/concepts/source/basic-metapatterns/monolith|*Reactor*]] uses a thread for each request and blocks on calls to the OS or other components. This is the simplest server-side implementation.
  - [[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]] relies on callbacks that all run in a single thread to achieve real-time latency and avoid locks. It is widely used in embedded programming.
  - [[wiki/concepts/source/basic-metapatterns/monolith|*Half-Sync/Half-Async*]] is an internally layered approach that allocates a coroutine or fiber to each task. It is more resource-efficient than [[wiki/concepts/source/basic-metapatterns/monolith|*Reactor*]] but lacks the real-time responsiveness and flexibility of [[wiki/concepts/source/basic-metapatterns/monolith|*Proactor*]].
- [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] are multiple instances of a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]], each owning a slice of the system’s data. A client must know which shard to access either through storing its address or by querying an [[wiki/concepts/source/extension-metapatterns/proxy|*Ambassador Proxy*]] library written by the team that deploys the shards. This is the architecture of choice when clients are independent from each other but the entire dataset is too large to fit in a single server.
- [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]] are instances of a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] with identical data used to achieve fault tolerance and high throughput. Any writes to one replica must be propagated to the other replicas:
  - With [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|semi-specialized replicas]] all write requests go to a single *leader* instance which publishes the changes for the other replicas, called *followers*, to apply to their datasets. Read requests usually go to the followers, and the more read traffic there is, the more followers are deployed.
  - If all the replicas are identical, any of them can handle a write request and publish the update for the other replicas to apply. This scales write throughput but involves the chance of data conflicts when the same data record is simultaneously changed on multiple replicas. See [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid* of *Space-Based Architecture*]].


### Monoliths with auxiliary layers


![Diagrams of Monolith with Backends for Frontends, Managed Shards, Peer-to-Peer Mesh, Monolith with a database, and Monolith with Polyglot Persistence.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Monoliths%20with%20Layers.png)


In other kinds of systems, common in server-side programming, some functionality moves to a dedicated layer while the business logic remains monolithic:

- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] *with a database* relies on an external [[wiki/concepts/source/basic-metapatterns/layers|data storage component]] for persistence.
- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] *with* [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] uses specialized databases to improve performance.
- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] *with* [*Backends for Frontends*](<Backends for Frontends (BFF)>) employs a [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] for each kind of client to address variations in the clients’ protocols and security.
- *Managed* [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] run behind a single [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] which connects each system’s client to the shard that has that client’s data thus isolating the clients from the knowledge of the system’s internal composition.
- [[wiki/concepts/source/implementation-metapatterns/mesh|*Peer-to-Peer Mesh*]] interconnects multiple instances of an application, acting as a distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]].


### Monoliths with Plugins


![Diagrams of Monolith with Plugins, Model-View-Controller, and Hexagonal Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Monoliths%20with%20Plugins.png)


A monolithic core can be extended with disposable additions:

- [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] allow for parts of the core’s workflow to be supplied by internal or external teams, customizing the experience of the system’s users without modifications to its main code.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller* and related patterns]] provide a [[wiki/concepts/source/extension-metapatterns/proxy|*presentation layer*]] that isolates the main code from dependencies on the UI framework or network protocol, thus minimizing the effort of porting the software to another platform.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] keeps the entire business logic self-sufficient by wrapping every dependency with a dedicated [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]], which not only improves portability but also helps with testing and allows for changing vendors late in the development cycle.


### Underdeveloped Moduliths


![Diagrams of Monolith with libraries and Modulith with shared code.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Underdeveloped%20Moduliths.png)


If a [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] evolves for a long time, it will likely become segmented into subdomain components, yielding a [[wiki/concepts/source/basic-metapatterns/services|*Modulith*]]. As that process is not instantaneous, there are a couple of transitional architectures:

- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] *with* [[wiki/concepts/source/basic-metapatterns/layers|*libraries*]] involves subdomain-specific third-party components which are called by its cohesive business logic.
- [[wiki/concepts/source/basic-metapatterns/services|*Modulith*]] *with shared code* has the business logic largely separated into subdomain modules which still rely on a common codebase for shared functionality.


## Layered architectures

Layering enables the use of specialized technologies and third-party components while avoiding the [risky](https://martinfowler.com/bliki/MonolithFirst.html) subdivision of business logic. It also allows for parts of the system to [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|differ in their qualities, placement, and scalability]]. All of that makes layered architectures suitable for full-featured, medium-sized projects run by one or two teams where both the speed of development and supportability matter.

### Ordinary Layers


![Diagrams of DDD-Style Layers, Layers with Polyglot Persistence, Layers with Backends for Frontends, and Monolith with a database.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Ordinary%20Layers.png)


Typical layered architectures include:

- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] of various composition, for example:
  - [[wiki/concepts/source/basic-metapatterns/layers|*Entity-Control-Boundary*]] which represent the [[wiki/concepts/source/basic-metapatterns/layers|*domain model*]], [[wiki/concepts/source/basic-metapatterns/layers|*use cases*]], and [[wiki/concepts/source/basic-metapatterns/layers|*interface*]], respectively. This pattern originated in the age of complex desktop applications.
  - [[wiki/concepts/source/basic-metapatterns/layers|*Domain-Driven Design* decomposition]] into *presentation* (interface), *application* (use cases), *domain* (business rules), and *infrastructure* (communication and persistence). It targets enterprise systems.
  - [[wiki/concepts/source/basic-metapatterns/layers|*Embedded systems*]] with pairs of UI \+ HMI, SDK \+ HAL, and FW \+ HW implemented by distinct parties in the supply chain.
- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] *with* [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] where the [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] layer involves multiple databases, usually chosen for their performance with specialized payloads.
- [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] *with* [*Backends for Frontends*](<Backends for Frontends (BFF)>) with a dedicated [[wiki/concepts/source/basic-metapatterns/layers|*interface*]] and/or [[wiki/concepts/source/basic-metapatterns/layers|*application*]] component for each kind of client when the clients differ in their protocols and/or workflows.
- [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] *with a* [[wiki/concepts/source/basic-metapatterns/layers|*database*]] as a case of rudimentary layering of server-side systems.


### Scaled Layers


![Diagrams of Three-Tier System, MapReduce, Managed Shards, Scaled Service, and Peer-to-Peer Mesh.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Scaled%20Layers.png)


Several layered architectures build around scalability:

- [[wiki/concepts/source/basic-metapatterns/layers|*Three-Tier Architecture*]] contains a frontend layer with an instance per system’s user, scaled backend, and non-scaled database. It exploits the physical distribution of the system to reap [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|cost, performance, and security benefits]].
- [[wiki/concepts/source/basic-metapatterns/services|*Scaled service*]] runs multiple instances of a stateless application between a [[wiki/concepts/source/extension-metapatterns/proxy|*Load Balancer*]], which evenly distributes user requests among the instances, and a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]]. It is the default approach for scaling a server-side service.
- [[wiki/concepts/source/extension-metapatterns/orchestrator|*MapReduce* or *Scatter-Gather*]] runs a coupled part of a calculation in a non-scaled layer while mutually independent parts are delegated to multiple worker shards.
- *Managed* [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]] rely on a [[wiki/concepts/source/extension-metapatterns/proxy|*Sharding Proxy*]] layer to connect a client to the appropriate shard. This removes the need for the client to know which shard contains its data.
- [[wiki/concepts/source/implementation-metapatterns/mesh|*Peer-to-Peer Mesh*]] builds a distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] layer that interconnects instances of a client application.


### Other layered systems


![Diagrams of Model-View-Presenter, Onion Architecture, and Sandwich.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Other%20Layered.png)


Besides that, there are a few peculiar layered systems:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Presenter* family of patterns]] features layered user interfaces which decouple the main system from a GUI or web framework with the goal of being able to easily switch to another framework version or vendor.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Onion Architecture* or *Clean Architecture*]] is a [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] (see [below](#hexagonal-architecture)) with a layered core structured along the ideas of [[wiki/concepts/source/basic-metapatterns/layers|*Domain-Driven Design*]].
- [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] architectures are [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]] with the [[wiki/concepts/source/basic-metapatterns/layers|*domain logic* layer]] split into subdomains. It is a pragmatic low effort approach to tackle complexity in quickly evolving projects that can afford several development teams. It also addresses [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|data-centric]] domains.


## Plugins family

Some architectures specialize in separating complex core logic from miscellaneous details to make the *core* independent and reusable under changing conditions. In most cases the core contains monolithic business logic but that may vary among patterns. This family of topologies is prevalent in long-living or highly customizable products whose codebases are too expensive to rewrite to address every trend or fad.

### Plugin Architecture


![A plugin, library, and extension called by a core.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Plugin%20Architecture.png)


[[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]] are external components which supply predefined parts of a host component’s workflow. They may be created by the company that makes the product, often for the sake of selling several flavors with limited or specialized functionality. Or they may come from external programmers, as codecs in video players or customizations for accounting software, to extend the usefulness of a product without overburdening its core codebase.

### Separated Presentation


![Diagrams of Model-View-Presenter and Model-View-Controller.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Separated%20Presentation.png)


[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Separated Presentation*]] extracts the [[wiki/concepts/source/basic-metapatterns/layers|user or network interface]] functionality into a dedicated layer which is often further subdivided. This makes the main codebase reusable in different environments:

- The [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Controller* family of patterns]] has separate modules for platform-specific input and for output which is beneficial when there is no web or GUI framework that can provide a unified high-level user interface.
- The [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Model-View-Presenter* family]] builds on top of a pre-existing platform-specific [[wiki/concepts/source/basic-metapatterns/layers|presentation layer]]. Most of these patterns add an intermediate [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] between the platform-dependent code and the core application.


### Control patterns


![Diagrams of Pedestal and Microkernel.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Control%20Patterns.png)


A couple of topologies originate with embedded or systems programming where it is important to abstract the business logic from the hardware components which tend to quickly go out of production and thus need to be replaced with incompatible models:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Pedestal*]] wraps each hardware component in a system with a dedicated driver to reduce the dependency of the business logic on hardware specifications thus allowing for the software to be reused with different hardware setups.
- [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel Architecture*]] relies on an eponymous layer to mediate between resource consumers and resource producers which implement generic interfaces and thus are replaceable. This approach is surprisingly ubiquitous:
  - [[wiki/concepts/source/implementation-metapatterns/microkernel|*Operating systems*]] are the origin of [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]], with user space applications competing for system resources owned by the device drivers.
  - [[wiki/concepts/source/implementation-metapatterns/microkernel|*Interpreters*]] run user scripts in a sandbox and provide them access to installed libraries.
  - [[wiki/concepts/source/implementation-metapatterns/microkernel|*Software frameworks*]] follow a similar approach, building a [*Facade*](https://refactoring.guru/design-patterns/facade) to grant user code a managed access to the framework’s internal components.
  - [[wiki/concepts/source/implementation-metapatterns/microkernel|*Hypervisors*, *Virtualizers*, and *Distributed Runtimes*]] abstract a guest operating system or applications from the platform they run on.


### Hexagonal Architecture


![Diagrams of Ports and Adapters and Onion Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Hexagonal%20Architecture.png)


A few architectures fully isolate business logic from its environment, resulting in great portability, simpler automated testing and improved separation of concerns:

- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Ports and Adapters*]] (the original [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]]) inserts an [[wiki/concepts/source/extension-metapatterns/proxy|*Adapter*]] into every communication pathway in or out of its business logic core but does not specify the structure of the core itself, which makes the pattern universally applicable.
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Onion Architecture* or *Clean Architecture*]] structures the core in accordance with the [[wiki/concepts/source/basic-metapatterns/layers|rules of *Domain-Driven Design*]], limiting the applicability of this topology to enterprise systems or complex backends.


### Cell


![Several intercommunicating subservices are wrapped with a cell gateway that receives client requests, adapters for outgoing communication, and a plugin.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Variants/4/Cell.png)


[[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cell*]] is a building block of huge systems that follow [*Domain-Oriented Microservice Architecture*](<Service-Oriented Architecture (SOA)#domain-oriented-microservice-architecture-doma>) or [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]]. It is a kind of [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]] with a modular and often distributed core. The internals of a *Cell* are hidden behind a [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]] which implements the *Cell*’s public interface. Any outgoing communication, initiated from inside the *Cell*, goes through its [[wiki/concepts/source/extension-metapatterns/proxy|*Adapters*]] or through [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins* supplied by peer *Cells*]].

## Services area

Partitioning a system into [[wiki/concepts/source/basic-metapatterns/services|*modules*]] or [[wiki/concepts/source/basic-metapatterns/services|*services*]] which match its subdomains and assigning the components to dedicated teams greatly reduces the cognitive load that the programmers face as each person needs to comprehend only the service they work on. Given that it is [cognitive load that determines development speed](https://realmensch.org/2018/05/04/we-are-all-10x-developers/), most large projects have service-based topologies.

However, full domain partitioning \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] is [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|beneficial only when the system’s subdomains are weakly coupled]] along every level of their functionality, which is why many real-world topologies mix cohesive system-wide layers and decoupled subdomain services.

### Barebone services


![Diagrams of Services, Three-Layered Services, Pipeline, and Two-Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Barebone%20Services.png)


A few architectures are completely segmented into subdomains:

- Distributed [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or in-process [[wiki/concepts/source/basic-metapatterns/services|*Modules*]] rely on [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*mutual orchestration*]]. They come in several kinds:
  - [[wiki/concepts/source/basic-metapatterns/services|*Service-Based Architecture*]] tends to employ single instances of services which cover entire subdomains. It is used for multi-team server-side projects with no special performance considerations.
  - [[wiki/concepts/source/basic-metapatterns/services|*Modulith*]] (*Modular Monolith*) runs subdomain-sized components in a single process, sacrificing fault tolerance for consistency and operational costs. This architecture fits smaller Internet businesses.
  - [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] with highly scalable sub-subdomain components implement high load and high budget systems with well-established domain knowledge but frequently changing business needs.
  - [[wiki/concepts/source/basic-metapatterns/services|*Actors*]] are asynchronous objects used for real-time tasks that range from embedded telephony to instant messengers to financial systems. Consider them if you benefit from modeling every user of your system as a lightweight independently acting entity.
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Three-Layered Services*]] subdivide each service into the [[wiki/concepts/source/basic-metapatterns/layers|*use cases*]], [[wiki/concepts/source/basic-metapatterns/layers|*domain logic*]], and [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] layers, allowing for further specialization of staff and technologies.
- [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] is a [[wiki/concepts/source/foundations-of-software-architecture/choreography|*choreographed*]] system where each component implements a single stage of data or event processing:
  - [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipes and Filters*]] is a local and usually linear [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] that processes a data stream. It is the architecture of choice for systems with customizable workflows and polymorphic algorithms such as video capture or replay.
  - [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]] runs multiple branched [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]], each implementing a single use case, over a shared set of services. It is an easily extendable alternative to [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] for domains with a few highly loaded yet simple scenarios.
  - [[wiki/concepts/source/basic-metapatterns/pipeline|*Data Mesh*]] collects, transforms, and processes analytical data from a system of services.
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Two-Layered Services*]] split each component of a [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]] (usually a [[wiki/concepts/source/basic-metapatterns/pipeline|*Choreographed Event-Driven Architecture*]]) into [[wiki/concepts/source/basic-metapatterns/layers|*domain logic*]] and [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] layers, emphasizing the use of databases private to their services. Noticeably, the [[wiki/concepts/source/basic-metapatterns/layers|*use case logic*]] is present only through the connections between the services.


### Services with extensions


![Diagrams of Services with a Gateway; Orchestrated Services; Services with: an API Gateway, Backends for Frontends, Shared Repository, Middleware, and Pplyglot Persistence; and of Service Mesh.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Services%20with%20Extensions.png)


[[wiki/concepts/source/basic-metapatterns/services|*Services*]] become simpler when common aspects are extracted to a dedicated layer:

- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with a* [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] rely on an external [[wiki/concepts/source/basic-metapatterns/layers|transport and deployment layer]] which is usually a framework available off-the-shelf:
  - [[wiki/concepts/source/extension-metapatterns/middleware|*Service Mesh*]] is a distributed [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] for highly scalable systems.
  - [[wiki/concepts/source/extension-metapatterns/middleware|*Message Bus*]] interconnects services that use different communication technologies by translating between their protocols. It is useful in integration of legacy systems.
  - [[wiki/concepts/source/extension-metapatterns/middleware|*Event Mediator*]] drives communication in [[wiki/concepts/source/basic-metapatterns/pipeline|*Event-Driven Architectures*]].
  - [[wiki/concepts/source/extension-metapatterns/middleware|*Enterprise Service Bus*]] is an [[wiki/concepts/source/foundations-of-software-architecture/orchestration|*orchestrating*]] [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] that unites several historically separate subsystems into an [*Enterprise Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)#enterprise-soa>).
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with a* [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] share a [[wiki/concepts/source/basic-metapatterns/layers|data storage or exchange layer]] and are eligible to implement [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|data-centric]] domains:
  - [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] simplifies architectural design and makes data synchronization trivial (see [[wiki/concepts/source/extension-metapatterns/sandwich|*Service-Based Architecture*]]).
  - [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared File System*]] is among the simplest methods of organizing [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipelines*]] for processing large volumes of data records.
  - [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Memory*]] is the fastest method of data exchange especially suitable for low latency software.
  - [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]] is a highly scalable, distributed in-memory data store of [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]].
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with* [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] employ several data stores, usually to improve performance by using each data store in the role it is optimized for.
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with a* [[wiki/concepts/source/extension-metapatterns/proxy|*Gateway*]] rely on a shared [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] layer to handle [[wiki/concepts/source/basic-metapatterns/layers|communication with clients]]. Third-party *Proxies* reliably cover security and networking concerns with very little effort from the programmers’ side.
- In [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrated Services*]] it is the [[wiki/concepts/source/basic-metapatterns/layers|*use cases*]] which are extracted into a system-wide layer. Such subdivision of business logic saves the day when there are many complex system-wide scenarios while the business rules are specific to particular subdomains.
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with an* [[wiki/concepts/source/extension-metapatterns/proxy|*API Gateway*]] implement public-API-related tasks – both [[wiki/concepts/source/basic-metapatterns/layers|protocol support]] and [[wiki/concepts/source/basic-metapatterns/layers|basic orchestration]] – in a single component which calls underlying services with the [[wiki/concepts/source/basic-metapatterns/layers|domain logic]]. This is a simplified architecture for ordinary server-side systems.
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with* [*Backends for Frontends*](<Backends for Frontends (BFF)>) have a layer of client-specific components that encapsulate clients’ [[wiki/concepts/source/basic-metapatterns/layers|protocols]] and/or [[wiki/concepts/source/basic-metapatterns/layers|scenarios]] and are useful when a system serves drastically different kinds of clients.


### Hierarchies of services


![Diagrams of Cell-Based Architecture and Hierarchical Middleware.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Hierarchies%20of%20Services.png)


Services are building blocks for a couple of hierarchical architectures used in huge projects:

- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] is a system of clusters of (often co-deployed) services called [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Cells*]]. Recursive decomposition lowers the top-level system complexity and decouples the subdomains by making their interdependencies explicit.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchical Middleware*]] interconnects several subsystems of services which belong to different organizations or physical networks.


### Partially merged services


![Diagrams of Sandwich and Modulith with shared code.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Partially%20Merged%20Services.png)


There are systems in-between [[wiki/concepts/source/basic-metapatterns/services|*Services*]] and [[wiki/concepts/source/basic-metapatterns/monolith|*Monolith*]] or [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]]:

- In [[wiki/concepts/source/basic-metapatterns/services|*Modulith*]] *with shared code* the business logic is split into subdomains but still relies on a shared codebase. It is a transitional architecture often seen in growing projects that [explore subdomain boundaries](https://martinfowler.com/bliki/MonolithFirst.html).
- In [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] only the [[wiki/concepts/source/basic-metapatterns/layers|*domain logic* layer]], which is usually the largest part of the codebase, is segmented into subdomains. This is the most natural subdivision for many real-world systems, which inspires multiple architectures:
  - [[wiki/concepts/source/extension-metapatterns/sandwich|*Service-Based Architecture*]] – the pragmatic approach to server-side development – often uses a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Database*]] and an [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]].
  - [[wiki/concepts/source/extension-metapatterns/sandwich|*Space-Based Architecture*]] provides unparalleled elasticity and scalability for data-centric domains with its *replicated cache* called [[wiki/concepts/source/extension-metapatterns/shared-repository|*Data Grid*]].
  - [[wiki/concepts/source/extension-metapatterns/sandwich|*Blackboard Architecture*]] schedules specialized algorithms to solve ill-structured problems.
  - [[wiki/concepts/source/extension-metapatterns/sandwich|*Nanoservices*]] are independently scalable functions that run in a cloud and share an [[wiki/concepts/source/extension-metapatterns/orchestrator|*(API) Gateway*]] and a [[wiki/concepts/source/extension-metapatterns/shared-repository|database]].


## Fragmented patterns

Finally, some architectures are subdivided into both layers of abstraction and subdomains, resulting in topologies containing many small components. This happens when interacting parts of a system vary in their qualities and technologies and thus should stay separate, ordinary decomposition results in components too large for comfortable development, or both.

### Layers of services


![Diagrams of Services with Polyglot Persistence, Services with Backends for Frontends, and Service-Oriented Architecture.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Layers%20of%20Services.png)


A few topologies are made of layers, each of which is subdivided into services:

- In [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with* [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] there are several specialized data stores with shared access. This topology may emerge from a [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|performance optimization]] of [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with a* [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]].
- [[wiki/concepts/source/basic-metapatterns/services|*Services*]] *with* [*Backends for Frontends*](<Backends for Frontends (BFF)>) employ a dedicated [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]], [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]], or [[wiki/concepts/source/extension-metapatterns/orchestrator|*API Gateway*]] for each kind of client. This makes sense when the system's clients have very little in common.
- [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) features fragmented application, domain, and utility layers, with each component of a higher level calling multiple components from a layer below it. It enables code reuse, for better or worse, and has reasonably small services even in huge projects but suffers from slow development caused by extensive interdependencies between teams.


### Layered services


![Diagrams of Orchestrated Three-Layered Services and Choreographed Two-Layered Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Topologies/Layered%20Services.png)


More often than not, services are layered internally:

- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Orchestrated Three-Layered Services*]] distinguish between the [[wiki/concepts/source/basic-metapatterns/layers|*application*]] (use cases), [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] (business rules), and [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] (database) layers.
- [[wiki/concepts/source/fragmented-metapatterns/layered-services|*Choreographed Two-Layered Services*]] contain only the [[wiki/concepts/source/basic-metapatterns/layers|*domain*]] and [[wiki/concepts/source/basic-metapatterns/layers|*persistence*]] layers because the [[wiki/concepts/source/basic-metapatterns/layers|*application*]] logic resides in the graph of connections between the services.


### Hierarchies


![Diagrams of Orchestrator of Orchestrators, Middleware of Middlewares, and Services of Services.](/pixi-wiki/wiki/software-architecture-metapatterns/assets/images/Relations/Hierarchy.png)


Finally, there are [[wiki/concepts/source/fragmented-metapatterns/hierarchy|hierarchical]] topologies with recursive partitioning:

- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Top-Down Hierarchy*]] is arguably the best way to implement a system that involves many kinds of somewhat related entities. It emerges in domains as diverse as compilers, industrial automation, graphical user interfaces, and online marketplaces.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchical Middleware*]] interconnects subsystems that differ in their communication protocols.
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Cell-Based Architecture*]] splits every large subdomain service into a group of subservices encapsulated with a [[wiki/concepts/source/extension-metapatterns/proxy|*Cell Gateway*]]. This keeps individual services small without spreading hundreds of them into the system level.


## Common motifs

Every area of the topologies map highlights certain design principles:

- Small and simple systems may stay cohesive as [[wiki/concepts/source/basic-metapatterns/monolith|*Monoliths*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Shards*]].
- Medium-sized software benefits from functional partitioning \[[wiki/concepts/source/appendices/books-referenced|[FSA]]\] into [[wiki/concepts/source/basic-metapatterns/layers|*Layers*]].
- Long-lived projects become stabilized by extracting any volatile code into expendable modules. Different applications of this principle yield [[wiki/concepts/source/implementation-metapatterns/plugins|*Plugins*]], [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|*Hexagonal Architecture*]], and [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]].
- Large software is decomposed into subdomains owned by dedicated teams. See [[wiki/concepts/source/basic-metapatterns/services|*Services*]] and [[wiki/concepts/source/basic-metapatterns/pipeline|*Pipeline*]].
- Huge systems require recursive decomposition as found in [*Service-Oriented Architecture*](<Service-Oriented Architecture (SOA)>) and [[wiki/concepts/source/fragmented-metapatterns/hierarchy|*Hierarchy*]].


Other motifs are harder to notice as they apply to both scaled layered systems and those subdivided into services:

- There is often a *managing layer* that makes use of underlying components:
  - A [[wiki/concepts/source/extension-metapatterns/proxy|*Proxy*]] is an [[wiki/concepts/source/basic-metapatterns/layers|*interface*]] that receives and pre-processes client input, then forwards the resulting request to whatever is behind it.
  - An [[wiki/concepts/source/extension-metapatterns/orchestrator|*Orchestrator*]] is an [[wiki/concepts/source/basic-metapatterns/layers|*application*]] that implements complex use cases which turn a single event or client request into a chain of calls to the lower layer.
  - [*Backends for Frontends*](<Backends for Frontends (BFF)>) segment a managing layer into client-specific services.
- A *platform layer* provides some functionality to other system components:
  - A [[wiki/concepts/source/extension-metapatterns/middleware|*Middleware*]] deploys and [[wiki/concepts/source/basic-metapatterns/layers|interconnects]] [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]].
  - A [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] stores the system’s [[wiki/concepts/source/basic-metapatterns/layers|data]], offering consistency and persistence.
  - [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]] subdivides a [[wiki/concepts/source/extension-metapatterns/shared-repository|*Shared Repository*]] layer.
- [[wiki/concepts/source/extension-metapatterns/sandwich|*Sandwich*]] wraps [[wiki/concepts/source/basic-metapatterns/services|*Services*]] or [[wiki/concepts/source/basic-metapatterns/shards|*Replicas*]] with both managing and platform layers.
- A [[wiki/concepts/source/implementation-metapatterns/mesh|*Mesh*]] interconnects any components that use it.


As we see, [[wiki/concepts/source/introduction/metapatterns|metapatterns]] emerge as archetypes shared among system topologies.

## Summary

There are many system topologies with various degrees of segregation into layers and subdomains. No single architecture is a silver bullet, each topology has its use depending on the circumstances. The following chapters of this book explore archetypes shared among topologies which are called *metapatterns*.


<!-- ===== software-architecture-metapatterns/wiki/concepts/source/root/home.md ===== -->

---
title: "Source Wiki Home"
created: 2026-07-02
updated: 2026-07-02
type: source-page
status: imported
namespace: software-architecture-metapatterns
source_repository: https://github.com/denyspoltorak/metapatterns
source_wiki: https://github.com/denyspoltorak/metapatterns/wiki
source_path: "Home.md"
source_url: https://github.com/denyspoltorak/metapatterns/wiki/Home
source_license_note: "See namespace README; preserve attribution and source links."
---

# Source Wiki Home

> Imported source page from Denys Poltorak's *Architectural Metapatterns* wiki. Source path: `Home.md`.

# Architectural Patterns Wiki

This site has multiple goals:

1. #### Become a wiki of architectural patterns

   There are many patterns here. I invested over a year in collecting architectural patterns and styles that relate to the structure of a system.

   You will find here [[wiki/concepts/source/basic-metapatterns/services|*Microservices*]] and [[wiki/concepts/source/implementation-metapatterns/microkernel|*Microkernel*]] but not [*Test-Driven Development*](https://herbertograca.com/2018/08/27/distillation-of-tdd-where-did-it-all-go-wrong/) (which is a methodology pattern) or [*Dead Letter Channel*](https://www.enterpriseintegrationpatterns.com/patterns/messaging/DeadLetterChannel.html) (a communication pattern).

2. #### Show that patterns make a hierarchy

   There are way too many patterns. Thus some of them are similar, as there are only so many different things a human mind can invent. This wiki groups patterns according to their structure and function, and describes specific features, use cases, benefits and drawbacks for each group of patterns as a whole to outline the big picture and avoid repetition.

   For example, [[wiki/concepts/source/extension-metapatterns/orchestrator|*Scatter-Gather* and *MapReduce*]] are almost identical (*Scatter-Gather* lacks the Reduce step) while their relation to [[wiki/concepts/source/extension-metapatterns/orchestrator|*Saga*]] is more remote but still traceable (each of the three patterns coordinates components of a system).

3. #### Provide an intuitive way to study patterns

   Having patterns arranged into a hierarchy greatly reduces the amount of information one must remember to learn a new pattern as it differs from others in its group in minor details.

   Also, if we can enumerate patterns and see how they relate to each other, then we can [[wiki/concepts/source/analytics/comparison-of-architectural-patterns|compare them]] and even spot empty spaces in our knowledge - which is how I discovered [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|*Polyglot Persistence*]].

Places to start:

* [[wiki/concepts/source/appendices/index-of-patterns|Index of patterns]]
* [[wiki/concepts/source/introduction/about-this-book|Diagrams and notation]]
* [[wiki/concepts/source/introduction/metapatterns|The underlying theory]]

You can download this as a book from [GitHub](https://github.com/denyspoltorak/metapatterns) or [Leanpub](https://leanpub.com/metapatterns) (which also features a few testimonials and a detailed table of contents). The work is licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).

Any help with the content, including adding new patterns or correcting the ones already described, is appreciated.

## Table of Contents:

### [[wiki/concepts/source/introduction/introduction|Introduction]]

- [[wiki/concepts/source/introduction/about-this-book|About this book]]
- [[wiki/concepts/source/introduction/metapatterns|Metapatterns]]
- [[wiki/concepts/source/introduction/system-topologies|System topologies]]

### [[wiki/concepts/source/foundations-of-software-architecture/foundations-of-software-architecture|Foundations of software architecture]]

- [[wiki/concepts/source/foundations-of-software-architecture/modules-and-complexity|Modules and complexity]]
- [[wiki/concepts/source/foundations-of-software-architecture/forces-asynchronicity-and-distribution|Forces, asynchronicity, and distribution]]
- [[wiki/concepts/source/foundations-of-software-architecture/four-kinds-of-software|Four kinds of software]]
- [[wiki/concepts/source/foundations-of-software-architecture/arranging-communication|Arranging communication]]
  - [[wiki/concepts/source/foundations-of-software-architecture/programming-and-architectural-paradigms|Programming and architectural paradigms]]
  - [[wiki/concepts/source/foundations-of-software-architecture/orchestration|Orchestration]]
  - [[wiki/concepts/source/foundations-of-software-architecture/choreography|Choreography]]
  - [[wiki/concepts/source/foundations-of-software-architecture/shared-data|Shared data]]
  - [[wiki/concepts/source/foundations-of-software-architecture/comparison-of-communication-styles|Comparison of communication styles]]

### [[wiki/concepts/source/basic-metapatterns/basic-metapatterns|Basic metapatterns]]

- [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]]
- [[wiki/concepts/source/basic-metapatterns/shards|Shards]]
- [[wiki/concepts/source/basic-metapatterns/layers|Layers]]
- [[wiki/concepts/source/basic-metapatterns/services|Services]]
- [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]]

### [[wiki/concepts/source/extension-metapatterns/extension-metapatterns|Extension metapatterns]]

- [[wiki/concepts/source/extension-metapatterns/middleware|Middleware]]
- [[wiki/concepts/source/extension-metapatterns/shared-repository|Shared Repository]]
- [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]
- [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]
- [[wiki/concepts/source/extension-metapatterns/sandwich|Sandwich]]

### [[wiki/concepts/source/fragmented-metapatterns/fragmented-metapatterns|Fragmented metapatterns]]

- [[wiki/concepts/source/fragmented-metapatterns/layered-services|Layered Services]]
- [[wiki/concepts/source/fragmented-metapatterns/polyglot-persistence|Polyglot Persistence]]
- [Backends for Frontends (BFF)](<Backends for Frontends (BFF)>)
- [Service-Oriented Architecture (SOA)](<Service-Oriented Architecture (SOA)>)
- [[wiki/concepts/source/fragmented-metapatterns/hierarchy|Hierarchy]]

### [[wiki/concepts/source/implementation-metapatterns/implementation-metapatterns|Implementation metapatterns]]

- [[wiki/concepts/source/implementation-metapatterns/plugins|Plugins]]
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]
- [[wiki/concepts/source/implementation-metapatterns/microkernel|Microkernel]]
- [[wiki/concepts/source/implementation-metapatterns/mesh|Mesh]]

### [[wiki/concepts/source/analytics/analytics|Analytics]]

- [[wiki/concepts/source/analytics/comparison-of-architectural-patterns|Comparison of architectural patterns]]
  - [[wiki/concepts/source/analytics/sharing-functionality-or-data-among-services|Sharing functionality or data among services]]
  - [[wiki/concepts/source/analytics/pipelines-in-architectural-patterns|Pipelines in architectural patterns]]
  - [[wiki/concepts/source/analytics/dependency-inversion-in-architectural-patterns|Dependency inversion in architectural patterns]]
  - [[wiki/concepts/source/analytics/indirection-in-commands-and-queries|Indirection in commands and queries]]
- [[wiki/concepts/source/analytics/ambiguous-patterns|Ambiguous patterns]]
- [[wiki/concepts/source/analytics/architecture-and-product-life-cycle|Architecture and product life cycle]]
- [[wiki/concepts/source/analytics/real-world-inspirations-for-architectural-patterns|Real-world inspirations for architectural patterns]]
- [[wiki/concepts/source/analytics/the-heart-of-software-architecture|The heart of software architecture]]
  - [[wiki/concepts/source/analytics/cohesers-and-decouplers|Cohesers and decouplers]]
  - [[wiki/concepts/source/analytics/deconstructing-patterns|Deconstructing patterns]]
  - [[wiki/concepts/source/analytics/choose-your-own-architecture|Choose your own architecture]]

### [[wiki/concepts/source/appendices/appendices|Appendices]]

- [[wiki/concepts/source/appendices/acknowledgements|Acknowledgements]]
- [[wiki/concepts/source/appendices/books-referenced|Books referenced]]
- [[wiki/concepts/source/appendices/copyright|Copyright]]
- [[wiki/concepts/source/appendices/disclaimer|Disclaimer]]
- [[wiki/concepts/source/appendices/evolutions-of-architectures|Evolutions of architectures]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-lead-to-shards|Evolutions of a Monolith that lead to Shards]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-result-in-layers|Evolutions of a Monolith that result in Layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-make-services|Evolutions of a Monolith that make Services]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-monolith-that-rely-on-plugins|Evolutions of a Monolith that rely on Plugins]]
  - [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-data|Evolutions of Shards that share data]]
  - [[wiki/concepts/source/appendices/evolutions-of-shards-that-share-logic|Evolutions of Shards that share logic]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-that-make-more-layers|Evolutions of Layers that make more layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-that-help-large-projects|Evolutions of Layers that help large projects]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-to-improve-performance|Evolutions of Layers to improve performance]]
  - [[wiki/concepts/source/appendices/evolutions-of-layers-to-gain-flexibility|Evolutions of Layers to gain flexibility]]
  - [[wiki/concepts/source/appendices/evolutions-of-services-that-restructure-services|Evolutions of Services that restructure services]]
  - [[wiki/concepts/source/appendices/evolutions-of-services-that-add-layers|Evolutions of Services that add layers]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-pipeline|Evolutions of a Pipeline]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-middleware|Evolutions of a Middleware]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-shared-repository|Evolutions of a Shared Repository]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-proxy|Evolutions of a Proxy]]
  - [[wiki/concepts/source/appendices/evolutions-of-an-orchestrator|Evolutions of an Orchestrator]]
  - [[wiki/concepts/source/appendices/evolutions-of-a-sandwich|Evolutions of a Sandwich]]
- [[wiki/concepts/source/appendices/format-of-a-metapattern|Format of a metapattern]]
- [[wiki/concepts/source/appendices/glossary|Glossary]]
- [[wiki/concepts/source/appendices/history-of-changes|History of changes]]
- [[wiki/concepts/source/appendices/index-of-patterns|Index of patterns]]


<!-- ===== software-architecture-metapatterns/wiki/index.md ===== -->

---
title: "Software Architecture Metapatterns — Master Index"
created: 2026-07-02
updated: 2026-07-02
type: index
status: compiled
namespace: software-architecture-metapatterns
---

# Software Architecture Metapatterns — Master Index

> Compiled index for `software-architecture-metapatterns`.

## Agent Entrypoints

- [[summaries/for-agents-software-architecture-retrieval|For Agents — Software Architecture Retrieval]] — Retrieval and comparison contract for architecture reasoning.
- [[syntheses/architecture-metapatterns-fit-for-pixi|Architecture Metapatterns — Fit for Pixi]] — Why this corpus belongs in Pixi Wiki under Knowledge Systems.
- [[summaries/license-and-provenance|License and Provenance]] — Source roots, license ambiguity, and attribution guardrails.

## Imported Corpus

Imported source Markdown pages: 79.

### Source Sections

- `analytics`: 13 imported pages
- `appendices`: 28 imported pages
- `basic-metapatterns`: 6 imported pages
- `extension-metapatterns`: 6 imported pages
- `foundations-of-software-architecture`: 10 imported pages
- `fragmented-metapatterns`: 6 imported pages
- `implementation-metapatterns`: 5 imported pages
- `introduction`: 4 imported pages
- `root`: 1 imported pages

### Representative Starting Points

- [[wiki/concepts/source/appendices/evolutions-of-architectures|Evolutions of architectures]]
- [[wiki/concepts/source/appendices/index-of-patterns|Index of patterns]]
- [[wiki/concepts/source/basic-metapatterns/layers|Layers]]
- [[wiki/concepts/source/basic-metapatterns/monolith|Monolith]]
- [[wiki/concepts/source/basic-metapatterns/pipeline|Pipeline]]
- [[wiki/concepts/source/basic-metapatterns/services|Services]]
- [[wiki/concepts/source/extension-metapatterns/orchestrator|Orchestrator]]
- [[wiki/concepts/source/extension-metapatterns/proxy|Proxy]]
- [[wiki/concepts/source/implementation-metapatterns/hexagonal-architecture|Hexagonal Architecture]]
- [[wiki/concepts/source/introduction/metapatterns|Metapatterns]]
- [[wiki/concepts/source/introduction/system-topologies|System topologies]]

## Source Roots

- `https://github.com/denyspoltorak/metapatterns`
- `https://github.com/denyspoltorak/metapatterns/wiki`
- `https://metapatterns.io/`

## Maintenance

- Refresh with `scripts/import_metapatterns_wiki.py` from this namespace directory.
- Preserve `source_repository`, `source_wiki`, `source_path`, and `source_url` metadata.
- Keep license/provenance notes visible in README and source pages.


<!-- ===== software-architecture-metapatterns/wiki/log.md ===== -->

---
title: "Software Architecture Metapatterns — Activity Log"
created: 2026-07-02
updated: 2026-07-02
type: log
status: active
namespace: software-architecture-metapatterns
---

# Software Architecture Metapatterns — Activity Log

## 2026-07-02

- Created the `software-architecture-metapatterns` namespace under Knowledge Systems.
- Imported 79 Markdown source pages from `denyspoltorak/metapatterns.wiki`.
- Added provenance/license guardrails and agent-facing software architecture retrieval guidance.
- Mirrored source diagrams into namespace-local `assets/images/` and rewrote raw GitHub `<img>` HTML into Markdown image links for Pixi Wiki rendering.


<!-- ===== software-architecture-metapatterns/wiki/summaries/for-agents-software-architecture-retrieval.md ===== -->

---
title: For Agents — Software Architecture Retrieval
created: 2026-07-02
updated: 2026-07-02
type: summary
status: compiled
namespace: software-architecture-metapatterns
sources:
  - README.md
  - wiki/concepts/source/
---

# For Agents — Software Architecture Retrieval

Use this namespace as a software-architecture reasoning source, not as a menu of fashionable shapes.

## Retrieval Loop

1. Clarify the design target: product surface, service, module, workflow, data system, integration boundary, or whole codebase.
2. Identify the current forces: latency, throughput, dependency churn, deployment boundaries, data ownership, team ownership, extensibility, testability, and migration risk.
3. Retrieve 3–8 relevant pages from `software-architecture-metapatterns` by pattern name, alias, force, or evolution path.
4. Compare candidates by:
   - structural shape
   - communication style
   - dependency direction
   - where business logic lives
   - performance tradeoff
   - operational/team cost
   - possible next evolution
5. Produce a recommendation with citations to source pages and a small verification checklist.

## Output Shape

```text
Design target:
Observed forces:
Relevant metapatterns:
- Metapattern/source page: reason selected
Recommendation:
- preferred shape and why
Avoid:
- shapes that are overkill or mismatched
Evolution path:
- safe next step, rollback, and later split point
Verification checklist:
- concrete checks tied to dependency, performance, and ownership assumptions
License note:
- source is attributed external reference material; preserve provenance
```

## Useful Starting Queries

- `monolith layers services migration`
- `hexagonal architecture dependency inversion adapters`
- `orchestrator choreography saga event mediator`
- `pipeline throughput latency batch stream`
- `proxy gateway backend for frontend adapter`
- `polyglot persistence data ownership shared repository`

## Pixi/Jamie Use

- For codebase review: use this namespace to name the current shape before proposing changes.
- For product prototypes: prefer simple monolith/layers unless forces justify distribution.
- For agent work: cite the metapattern pages that shaped the plan so Pixoid can review the reasoning.
- For migration: retrieve the relevant evolution pages before recommending a split.


<!-- ===== software-architecture-metapatterns/wiki/summaries/license-and-provenance.md ===== -->

---
title: License and Provenance
created: 2026-07-02
updated: 2026-07-02
type: summary
status: compiled
namespace: software-architecture-metapatterns
sources:
  - https://github.com/denyspoltorak/metapatterns
  - https://github.com/denyspoltorak/metapatterns/wiki
---

# License and Provenance

## Source Roots

- Repository: `https://github.com/denyspoltorak/metapatterns`
- GitHub wiki: `https://github.com/denyspoltorak/metapatterns/wiki`
- Website: `https://metapatterns.io/`
- Latest release inspected: `https://github.com/denyspoltorak/metapatterns/releases/tag/v1.2`

## License Notes

Observed source signals are not perfectly uniform:

- The repository root `LICENSE` is Creative Commons Attribution-NonCommercial-ShareAlike 4.0.
- `ArchitecturalMetapatterns/LICENSE` is Creative Commons Attribution 4.0.
- The GitHub wiki `Appendices/Copyright.md` describes Creative Commons Attribution 4.0.
- The repo README says the book's diagrams and ODT file are available under CC BY.

## Conservative Guardrail

Pixi Wiki should preserve attribution, source links, and license notes. Do not present the imported corpus as unrestricted commercial training data. For public summaries, describe it as an attributed external reference corpus.


<!-- ===== software-architecture-metapatterns/wiki/syntheses/architecture-metapatterns-fit-for-pixi.md ===== -->

---
title: Architecture Metapatterns — Fit for Pixi
created: 2026-07-02
updated: 2026-07-02
type: synthesis
status: compiled
namespace: software-architecture-metapatterns
sources:
  - README.md
  - wiki/concepts/source/root/source-wiki-home.md
  - wiki/concepts/source/introduction/metapatterns.md
---

# Architecture Metapatterns — Fit for Pixi

This corpus belongs under Knowledge Systems because it is a system for organizing software architecture knowledge, not just a pile of definitions.

## Why It Fits

- It turns scattered architecture pattern names into a navigable pattern language.
- It groups aliases and near-duplicates by structure and function.
- It includes dependency, performance, applicability, relation, and evolution framing.
- It helps agents reason about architecture forces before suggesting implementation moves.

## Best Pixi Uses

- Architecture review vocabulary for Tinker/Pixoid.
- Migration planning from monolith/layers/services/pipeline/proxy/orchestrator shapes.
- Agent retrieval before recommending hexagonal architecture, service splits, BFFs, eventing, or plugin systems.
- Crosslinks to `agent-workflows` when architecture choices affect agent-built software delivery.

## Boundary

Keep the imported source corpus separate from Jamie-authored architecture decisions. Use it to support review and reasoning; do not let it override live code evidence or project constraints.


<!-- ===== ui-patterns/CLAUDE.md ===== -->

# UI Patterns Namespace Instructions

This is a compiled namespace source under `pixi-vault/wikis/ui-patterns/`.

## Rules

- Follow the root `Wiki Compiler Maps/Namespace Wiki Compiler Map.md`.
- Preserve the UI Patterns source URL and copyright boundary on every imported page.
- Do not republish full source pattern bodies, screenshots, comments, or paid card-deck material.
- Use pattern pages as routing handles for design review and product critique.
- For exact wording/examples, retrieve the original source page and quote only bounded snippets when necessary.
- Update `wiki/index.md` and `wiki/log.md` whenever the import is refreshed.


<!-- ===== ui-patterns/README.md ===== -->

---
title: "UI Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "namespace-overview"
status: "active"
category: "product-design"
namespace: "ui-patterns"
confidence: "medium"
source_url: "https://ui-patterns.com/patterns"
source_copyright_note: "UI Patterns site footer says All rights reserved; this namespace publishes a catalog/retrieval map, not full pattern text or screenshots."
---
# UI Patterns

> Product and persuasive interface pattern catalog for agents, compiled as a provenance-forward navigation layer over [ui-patterns.com](https://ui-patterns.com/patterns).

## Scope

### Covers

The `ui-patterns` namespace covers the public UI Patterns pattern catalog structure: pattern titles, source URLs, UI/persuasive taxonomy, section availability, example counts, provenance, copyright boundary, and agent-facing retrieval guidance for product/design review.

### Not Covered

This namespace does not republish full source pattern bodies, screenshots, comments, paid card-deck content, or commercial-clean training data. For exact wording and examples, retrieve the original source page and quote only bounded snippets when necessary.

### Current As

2026-07-02 — Initial import cataloged 170 pattern pages across 2 tracks and 11 groups from `https://ui-patterns.com/patterns`. Robots.txt allows `/patterns` crawling and disallows `/search`; the source footer says all rights reserved, so the public wiki remains a catalog and retrieval map.

## Canonical Source Roots

- Pattern index: `https://ui-patterns.com/patterns`
- Source site: `https://ui-patterns.com`
- Robots policy checked: `https://ui-patterns.com/robots.txt`
- Retrieved at: `2026-07-02T18:23:09+00:00`

## Agent Use Contract

- Start with [[summaries/for-agents-ui-patterns-retrieval|For Agents — UI Patterns Retrieval]].
- Search by pattern title, group, subgroup, or track.
- Open the source URL before relying on exact source wording, screenshot details, or nuanced usage limits.
- Treat this namespace as a design-review routing layer, not a license to bulk-copy the source site.
- Cite the source URL and this namespace page when turning a pattern into product recommendations.

## Public Output Contract

When published to `pixi-wiki`, this namespace should expose:

```text
/raw/ui-patterns/README.md
/raw/ui-patterns/wiki/index.md
/wiki/ui-patterns/README.md.html
/wiki/ui-patterns/wiki/index.md.html
/wiki/ui-patterns/llms.txt
```


<!-- ===== ui-patterns/wiki/concepts/patterns/accordion-menu.md ===== -->

---
title: "Accordion Menu"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/AccordionMenu"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/AccordionMenu"
source_slug: "AccordionMenu"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Menus"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 11
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Accordion Menu

> Catalog pointer for the UI Patterns source page: [Accordion Menu](https://ui-patterns.com/patterns/AccordionMenu).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Menus
- Source breadcrumb: Design Patterns > Navigation > Menus > Accordion Menu

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/AccordionMenu
- Page title: Accordion Menu design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 11
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 62 words on source page
- Usage: 61 words on source page
- Solution: 72 words on source page
- Rationale: 75 words on source page

## Source Navigation

- Previous source navigation: Horizontal Dropdown Menu
- Next source navigation: Forgiving Format


<!-- ===== ui-patterns/wiki/concepts/patterns/account-registration.md ===== -->

---
title: "Account Registration"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/AccountRegistration"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/AccountRegistration"
source_slug: "AccountRegistration"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Registration"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Is account registration necessary? And when?"
  - "Why should the user register?"
  - "Asking too many (unnecessary) questions"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Account Registration

> Catalog pointer for the UI Patterns source page: [Account Registration](https://ui-patterns.com/patterns/AccountRegistration).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Registration
- Source breadcrumb: Design Patterns > Onboarding > Registration > Account Registration

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/AccountRegistration
- Page title: Account Registration design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Is account registration necessary? And when?, Why should the user register?, Asking too many (unnecessary) questions
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 21 words on source page
- Example: 96 words on source page
- Usage: 69 words on source page
- Solution: 355 words on source page
- Rationale: 120 words on source page
- Discussion: 454 words on source page
- Is account registration necessary? And when?: 178 words on source page
- Why should the user register?: 94 words on source page
- Asking too many (unnecessary) questions: 156 words on source page

## Source Navigation

- Previous source navigation: Vote To Promote
- Next source navigation: Input Feedback


<!-- ===== ui-patterns/wiki/concepts/patterns/achievements.md ===== -->

---
title: "Achievements"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Achievements"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Achievements"
source_slug: "Achievements"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Why do achievements work?"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Achievements

> Catalog pointer for the UI Patterns source page: [Achievements](https://ui-patterns.com/patterns/Achievements).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Achievements

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Achievements
- Page title: Achievements design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Why do achievements work?
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 81 words on source page
- Usage: 69 words on source page
- Solution: 165 words on source page
- Rationale: 616 words on source page
- Why do achievements work?: 407 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/activity-stream.md ===== -->

---
title: "Activity Stream"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ActivityStream"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ActivityStream"
source_slug: "ActivityStream"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "The details of an activity stream"
  - "Aggregated activities"
  - "Verbs"
  - "Rationale"
  - "Discussion"
  - "Avoiding negatives"
  - "Keeping it relevant"
  - "Activity streams attract momentary action"
  - "Make it easy to scan"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Activity Stream

> Catalog pointer for the UI Patterns source page: [Activity Stream](https://ui-patterns.com/patterns/ActivityStream).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Activity Stream

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ActivityStream
- Page title: Activity Stream design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, The details of an activity stream, Aggregated activities, Verbs, Rationale, Discussion, Avoiding negatives, Keeping it relevant, Activity streams attract momentary action, Make it easy to scan
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 21 words on source page
- Example: 85 words on source page
- Usage: 79 words on source page
- Solution: 334 words on source page
- The details of an activity stream: 35 words on source page
- Aggregated activities: 44 words on source page
- Verbs: 15 words on source page
- Rationale: 189 words on source page
- Discussion: 435 words on source page
- Avoiding negatives: 51 words on source page
- Keeping it relevant: 95 words on source page
- Activity streams attract momentary action: 133 words on source page
- Make it easy to scan: 87 words on source page

## Source Navigation

- Previous source navigation: Progressive Disclosure
- Next source navigation: Calendar Picker


<!-- ===== ui-patterns/wiki/concepts/patterns/adaptable-view.md ===== -->

---
title: "Adaptable View"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/AdaptableView"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/AdaptableView"
source_slug: "AdaptableView"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Adaptable View

> Catalog pointer for the UI Patterns source page: [Adaptable View](https://ui-patterns.com/patterns/AdaptableView).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Adaptable View

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/AdaptableView
- Page title: Adaptable View design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 140 words on source page
- Usage: 132 words on source page
- Solution: 162 words on source page
- Rationale: 30 words on source page
- Discussion: 173 words on source page

## Source Navigation

- Previous source navigation: Image Zoom
- Next source navigation: Wizard


<!-- ===== ui-patterns/wiki/concepts/patterns/alternating-row-colors.md ===== -->

---
title: "Alternating Row Colors"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/AlternatingRowColors"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/AlternatingRowColors"
source_slug: "AlternatingRowColors"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Tables"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 7
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Alternating Row Colors

> Catalog pointer for the UI Patterns source page: [Alternating Row Colors](https://ui-patterns.com/patterns/AlternatingRowColors).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Tables
- Source breadcrumb: Design Patterns > Dealing with data > Tables > Alternating Row Colors

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/AlternatingRowColors
- Page title: Alternating Row Colors design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 7
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 39 words on source page
- Usage: 38 words on source page
- Solution: 74 words on source page
- Rationale: 96 words on source page

## Source Navigation

- Previous source navigation: Sort By Column
- Next source navigation: Copy Box


<!-- ===== ui-patterns/wiki/concepts/patterns/anchoring.md ===== -->

---
title: "Anchoring"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Anchoring"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Anchoring"
source_slug: "Anchoring"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Contrast anchoring"
  - "Assimilation anchoring"
  - "What qualifies as an anchor"
example_count: 11
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Anchoring

> Catalog pointer for the UI Patterns source page: [Anchoring](https://ui-patterns.com/patterns/Anchoring).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Anchoring

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Anchoring
- Page title: Anchoring design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Contrast anchoring, Assimilation anchoring, What qualifies as an anchor
- Example screenshots detected at source: 11
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 51 words on source page
- Usage: 35 words on source page
- Solution: 198 words on source page
- Rationale: 253 words on source page
- Discussion: 281 words on source page
- Contrast anchoring: 31 words on source page
- Assimilation anchoring: 44 words on source page
- What qualifies as an anchor: 27 words on source page

## Source Navigation

- Previous source navigation: Tunnelling
- Next source navigation: Serial Positioning Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/appointment-dynamic.md ===== -->

---
title: "Appointment Dynamic"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/appointment-dynamic"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/appointment-dynamic"
source_slug: "appointment-dynamic"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Appointment Dynamic

> Catalog pointer for the UI Patterns source page: [Appointment Dynamic](https://ui-patterns.com/patterns/appointment-dynamic).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Appointment Dynamic

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/appointment-dynamic
- Page title: Appointment Dynamic design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 57 words on source page
- Usage: 39 words on source page
- Solution: 123 words on source page
- Rationale: 149 words on source page

## Source Navigation

- Previous source navigation: Halo Effect
- Next source navigation: Autonomy


<!-- ===== ui-patterns/wiki/concepts/patterns/appropriate-challenge.md ===== -->

---
title: "Appropriate Challenge"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Appropriate-challenge"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Appropriate-challenge"
source_slug: "Appropriate-challenge"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Appropriate Challenge

> Catalog pointer for the UI Patterns source page: [Appropriate Challenge](https://ui-patterns.com/patterns/Appropriate-challenge).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Appropriate Challenge

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Appropriate-challenge
- Page title: Appropriate Challenge design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 8 words on source page
- Example: 43 words on source page
- Usage: 42 words on source page
- Solution: 269 words on source page
- Rationale: 435 words on source page

## Source Navigation

- Previous source navigation: Cognitive Dissonance
- Next source navigation: Drag and drop


<!-- ===== ui-patterns/wiki/concepts/patterns/archive.md ===== -->

---
title: "Archive"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Archive"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Archive"
source_slug: "Archive"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Archive

> Catalog pointer for the UI Patterns source page: [Archive](https://ui-patterns.com/patterns/Archive).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Archive

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Archive
- Page title: Archive design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 87 words on source page
- Usage: 86 words on source page
- Solution: 94 words on source page
- Rationale: 53 words on source page

## Source Navigation

- Previous source navigation: Pagination
- Next source navigation: Search Filters


<!-- ===== ui-patterns/wiki/concepts/patterns/article-list.md ===== -->

---
title: "Article List"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ArticleList"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ArticleList"
source_slug: "ArticleList"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Design tips for designing great article lists"
  - "Common pitfalls of article list design"
  - "The elements of an article list item"
  - "Rationale"
  - "Discussion"
  - "Think from the user’s perspective – not your own"
example_count: 17
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Article List

> Catalog pointer for the UI Patterns source page: [Article List](https://ui-patterns.com/patterns/ArticleList).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Article List

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ArticleList
- Page title: Article List design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Design tips for designing great article lists, Common pitfalls of article list design, The elements of an article list item, Rationale, Discussion, Think from the user’s perspective – not your own
- Example screenshots detected at source: 17
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 92 words on source page
- Usage: 68 words on source page
- Solution: 1396 words on source page
- Design tips for designing great article lists: 1031 words on source page
- Common pitfalls of article list design: 147 words on source page
- The elements of an article list item: 132 words on source page
- Rationale: 77 words on source page
- Discussion: 146 words on source page
- Think from the user’s perspective – not your own: 135 words on source page

## Source Navigation

- Previous source navigation: Autocomplete
- Next source navigation: Event Calendar


<!-- ===== ui-patterns/wiki/concepts/patterns/authority-bias.md ===== -->

---
title: "Authority Bias"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Authority"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Authority"
source_slug: "Authority"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Communicate authority"
  - "Rationale"
  - "Identifying with Authority Figures"
  - "Discussion"
  - "The study"
  - "Powerful pairings"
  - "Ethical Recommendations"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Authority Bias

> Catalog pointer for the UI Patterns source page: [Authority Bias](https://ui-patterns.com/patterns/Authority).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Authority Bias

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Authority
- Page title: Authority Bias design pattern
- Section headings available at source: Problem summary, Usage, Solution, Communicate authority, Rationale, Identifying with Authority Figures, Discussion, The study, Powerful pairings, Ethical Recommendations
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 194 words on source page
- Usage: 183 words on source page
- Solution: 237 words on source page
- Communicate authority: 146 words on source page
- Rationale: 471 words on source page
- Identifying with Authority Figures: 235 words on source page
- Discussion: 1148 words on source page
- The study: 88 words on source page
- Powerful pairings: 249 words on source page
- Ethical Recommendations: 335 words on source page

## Source Navigation

- Previous source navigation: Goal-Gradient Effect
- Next source navigation: Tailoring


<!-- ===== ui-patterns/wiki/concepts/patterns/auto-sharing.md ===== -->

---
title: "Auto-sharing"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/auto-sharing"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/auto-sharing"
source_slug: "auto-sharing"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Auto-sharing

> Catalog pointer for the UI Patterns source page: [Auto-sharing](https://ui-patterns.com/patterns/auto-sharing).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Auto-sharing

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/auto-sharing
- Page title: Auto-sharing design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 79 words on source page
- Usage: 60 words on source page
- Solution: 59 words on source page
- Rationale: 81 words on source page

## Source Navigation

- Previous source navigation: Testimonials
- Next source navigation: Invite friends


<!-- ===== ui-patterns/wiki/concepts/patterns/autocomplete.md ===== -->

---
title: "Autocomplete"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Autocomplete"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Autocomplete"
source_slug: "Autocomplete"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Search"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Implementation details"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Autocomplete

> Catalog pointer for the UI Patterns source page: [Autocomplete](https://ui-patterns.com/patterns/Autocomplete).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Search
- Source breadcrumb: Design Patterns > Dealing with data > Search > Autocomplete

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Autocomplete
- Page title: Autocomplete design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Implementation details, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 139 words on source page
- Usage: 132 words on source page
- Solution: 369 words on source page
- Implementation details: 154 words on source page
- Rationale: 270 words on source page
- Discussion: 105 words on source page

## Source Navigation

- Previous source navigation: Calendar Picker
- Next source navigation: Article List


<!-- ===== ui-patterns/wiki/concepts/patterns/autonomy.md ===== -->

---
title: "Autonomy"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/autonomy"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/autonomy"
source_slug: "autonomy"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Autonomy

> Catalog pointer for the UI Patterns source page: [Autonomy](https://ui-patterns.com/patterns/autonomy).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Autonomy

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/autonomy
- Page title: Autonomy design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 38 words on source page
- Usage: 31 words on source page
- Solution: 133 words on source page
- Rationale: 158 words on source page

## Source Navigation

- Previous source navigation: Appointment Dynamic
- Next source navigation: Fresh Start Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/autosave.md ===== -->

---
title: "Autosave"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/autosave"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/autosave"
source_slug: "autosave"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "The save button"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Autosave

> Catalog pointer for the UI Patterns source page: [Autosave](https://ui-patterns.com/patterns/autosave).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Autosave

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/autosave
- Page title: Autosave design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, The save button, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 21 words on source page
- Example: 24 words on source page
- Usage: 23 words on source page
- Solution: 113 words on source page
- The save button: 41 words on source page
- Rationale: 45 words on source page
- Discussion: 67 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/blank-slate.md ===== -->

---
title: "Blank Slate"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/BlankSlate"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/BlankSlate"
source_slug: "BlankSlate"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Blank Slate

> Catalog pointer for the UI Patterns source page: [Blank Slate](https://ui-patterns.com/patterns/BlankSlate).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Blank Slate

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/BlankSlate
- Page title: Blank Slate design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 35 words on source page
- Example: 102 words on source page
- Usage: 78 words on source page
- Solution: 157 words on source page
- Rationale: 139 words on source page

## Source Navigation

- Previous source navigation: Shopping Cart
- Next source navigation: Continuous Scrolling


<!-- ===== ui-patterns/wiki/concepts/patterns/breadcrumbs.md ===== -->

---
title: "Breadcrumbs"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Breadcrumbs"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Breadcrumbs"
source_slug: "Breadcrumbs"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Breadcrumbs

> Catalog pointer for the UI Patterns source page: [Breadcrumbs](https://ui-patterns.com/patterns/Breadcrumbs).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Breadcrumbs

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Breadcrumbs
- Page title: Breadcrumbs design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 26 words on source page
- Example: 155 words on source page
- Usage: 139 words on source page
- Solution: 95 words on source page
- Rationale: 152 words on source page

## Source Navigation

- Previous source navigation: Navigation Tabs
- Next source navigation: Shortcut Dropdown


<!-- ===== ui-patterns/wiki/concepts/patterns/calendar-picker.md ===== -->

---
title: "Calendar Picker"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/CalendarPicker"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/CalendarPicker"
source_slug: "CalendarPicker"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Shortcuts"
  - "Locking-in the period of selection"
  - "Two ways of inputting data: speedy and easy"
  - "Good defaults"
  - "Check date range validity"
  - "Display complete weeks"
  - "Make link targets big"
  - "Rationale"
  - "Discussion"
  - "International considerations"
example_count: 8
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Calendar Picker

> Catalog pointer for the UI Patterns source page: [Calendar Picker](https://ui-patterns.com/patterns/CalendarPicker).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Calendar Picker

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/CalendarPicker
- Page title: Calendar Picker design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Shortcuts, Locking-in the period of selection, Two ways of inputting data: speedy and easy, Good defaults, Check date range validity, Display complete weeks, Make link targets big, Rationale, Discussion, International considerations
- Example screenshots detected at source: 8
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 95 words on source page
- Usage: 87 words on source page
- Solution: 487 words on source page
- Shortcuts: 41 words on source page
- Locking-in the period of selection: 39 words on source page
- Two ways of inputting data: speedy and easy: 109 words on source page
- Good defaults: 77 words on source page
- Check date range validity: 45 words on source page
- Display complete weeks: 32 words on source page
- Make link targets big: 13 words on source page
- Rationale: 33 words on source page
- Discussion: 94 words on source page
- International considerations: 82 words on source page

## Source Navigation

- Previous source navigation: Activity Stream
- Next source navigation: Autocomplete


<!-- ===== ui-patterns/wiki/concepts/patterns/captcha.md ===== -->

---
title: "Captcha"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Captcha"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Captcha"
source_slug: "Captcha"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Captcha

> Catalog pointer for the UI Patterns source page: [Captcha](https://ui-patterns.com/patterns/Captcha).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Captcha

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Captcha
- Page title: Captcha design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 172 words on source page
- Usage: 171 words on source page
- Solution: 121 words on source page
- Rationale: 135 words on source page

## Source Navigation

- Previous source navigation: Good Defaults
- Next source navigation: Sort By Column


<!-- ===== ui-patterns/wiki/concepts/patterns/cards.md ===== -->

---
title: "Cards"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/cards"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/cards"
source_slug: "cards"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Cards can be manipulated"
  - "Rationale"
  - "Why use cards?"
  - "Discussion"
  - "When to use cards"
  - "When you shouldn’t use cards"
  - "The problem of visual overload"
  - "How to improve design and interaction with cards"
  - "Cards design and visual signifiers"
example_count: 11
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Cards

> Catalog pointer for the UI Patterns source page: [Cards](https://ui-patterns.com/patterns/cards).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Cards

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/cards
- Page title: Cards design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Cards can be manipulated, Rationale, Why use cards?, Discussion, When to use cards, When you shouldn’t use cards, The problem of visual overload, How to improve design and interaction with cards, Cards design and visual signifiers
- Example screenshots detected at source: 11
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 152 words on source page
- Usage: 128 words on source page
- Solution: 186 words on source page
- Cards can be manipulated: 81 words on source page
- Rationale: 410 words on source page
- Why use cards?: 263 words on source page
- Discussion: 1065 words on source page
- When to use cards: 250 words on source page
- When you shouldn’t use cards: 194 words on source page
- The problem of visual overload: 47 words on source page
- How to improve design and interaction with cards: 369 words on source page
- Cards design and visual signifiers: 73 words on source page

## Source Navigation

- Previous source navigation: Drag and drop
- Next source navigation: Retaliation


<!-- ===== ui-patterns/wiki/concepts/patterns/carousel.md ===== -->

---
title: "Carousel"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Carousel"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Carousel"
source_slug: "Carousel"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Carousel

> Catalog pointer for the UI Patterns source page: [Carousel](https://ui-patterns.com/patterns/Carousel).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Carousel

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Carousel
- Page title: Carousel design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 121 words on source page
- Usage: 120 words on source page
- Solution: 123 words on source page
- Rationale: 123 words on source page

## Source Navigation

- Previous source navigation: Table Filter
- Next source navigation: Coupon


<!-- ===== ui-patterns/wiki/concepts/patterns/cashless-effect.md ===== -->

---
title: "Cashless Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/cashless-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/cashless-effect"
source_slug: "cashless-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Cashless Effect

> Catalog pointer for the UI Patterns source page: [Cashless Effect](https://ui-patterns.com/patterns/cashless-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Cashless Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/cashless-effect
- Page title: Cashless Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Usage: 8 words on source page
- Solution: 109 words on source page
- Rationale: 216 words on source page

## Source Navigation

- Previous source navigation: Zeigarnik Effect
- Next source navigation: Picture Superiority Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/categorization.md ===== -->

---
title: "Categorization"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/categorization"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/categorization"
source_slug: "categorization"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Categorization

> Catalog pointer for the UI Patterns source page: [Categorization](https://ui-patterns.com/patterns/categorization).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Categorization

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/categorization
- Page title: Categorization design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 42 words on source page
- Usage: 16 words on source page
- Solution: 30 words on source page
- Rationale: 105 words on source page

## Source Navigation

- Previous source navigation: Frequently Asked Questions (FAQ)
- Next source navigation: Pull to refresh


<!-- ===== ui-patterns/wiki/concepts/patterns/chat.md ===== -->

---
title: "Chat"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/direct-messaging"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/direct-messaging"
source_slug: "direct-messaging"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Chat

> Catalog pointer for the UI Patterns source page: [Chat](https://ui-patterns.com/patterns/direct-messaging).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Chat

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/direct-messaging
- Page title: Chat design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 62 words on source page
- Usage: 51 words on source page
- Solution: 77 words on source page
- Rationale: 46 words on source page

## Source Navigation

- Previous source navigation: Testimonials
- Next source navigation: Invite friends


<!-- ===== ui-patterns/wiki/concepts/patterns/choice-closure.md ===== -->

---
title: "Choice Closure"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/choice-closure"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/choice-closure"
source_slug: "choice-closure"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Choice Closure

> Catalog pointer for the UI Patterns source page: [Choice Closure](https://ui-patterns.com/patterns/choice-closure).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Choice Closure

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/choice-closure
- Page title: Choice Closure design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 41 words on source page
- Usage: 26 words on source page
- Solution: 158 words on source page
- Rationale: 160 words on source page

## Source Navigation

- Previous source navigation: Zeigarnik Effect
- Next source navigation: Picture Superiority Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/chunking.md ===== -->

---
title: "Chunking"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Chunking"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Chunking"
source_slug: "Chunking"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "How far should I chunk – and what?"
  - "So always 4 to 5 menu items?"
  - "When to chunk…"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Chunking

> Catalog pointer for the UI Patterns source page: [Chunking](https://ui-patterns.com/patterns/Chunking).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Chunking

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Chunking
- Page title: Chunking design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, How far should I chunk – and what?, So always 4 to 5 menu items?, When to chunk…, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 119 words on source page
- Usage: 70 words on source page
- Solution: 454 words on source page
- How far should I chunk – and what?: 62 words on source page
- So always 4 to 5 menu items?: 57 words on source page
- When to chunk…: 192 words on source page
- Rationale: 237 words on source page

## Source Navigation

- Previous source navigation: Tunnelling
- Next source navigation: Serial Positioning Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/coachmarks.md ===== -->

---
title: "Coachmarks"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/coachmarks"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/coachmarks"
source_slug: "coachmarks"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Address underlying issues first"
example_count: 5
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Coachmarks

> Catalog pointer for the UI Patterns source page: [Coachmarks](https://ui-patterns.com/patterns/coachmarks).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Coachmarks

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/coachmarks
- Page title: Coachmarks design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Address underlying issues first
- Example screenshots detected at source: 5
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 18 words on source page
- Solution: 46 words on source page
- Rationale: 33 words on source page
- Discussion: 273 words on source page
- Address underlying issues first: 106 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/cognitive-dissonance.md ===== -->

---
title: "Cognitive Dissonance"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/cognitive-dissonance"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/cognitive-dissonance"
source_slug: "cognitive-dissonance"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Strategies"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Cognitive Dissonance

> Catalog pointer for the UI Patterns source page: [Cognitive Dissonance](https://ui-patterns.com/patterns/cognitive-dissonance).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Cognitive Dissonance

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/cognitive-dissonance
- Page title: Cognitive Dissonance design pattern
- Section headings available at source: Problem summary, Usage, Solution, Strategies, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 346 words on source page
- Usage: 329 words on source page
- Solution: 841 words on source page
- Strategies: 644 words on source page
- Rationale: 158 words on source page
- Discussion: 406 words on source page

## Source Navigation

- Previous source navigation: Modal
- Next source navigation: Appropriate Challenge


<!-- ===== ui-patterns/wiki/concepts/patterns/collectible-achievements.md ===== -->

---
title: "Collectible Achievements"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/CollectibleAchievements"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/CollectibleAchievements"
source_slug: "CollectibleAchievements"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Reputation"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Families of collectibles"
  - "It should be attractive to be rewarded"
  - "Combine easy successes with hard challenges"
  - "Types of achievements"
  - "What are you awarding?"
  - "Rationale"
  - "Discussion"
  - "Quality"
  - "Get people started"
  - "Is it mine forever?"
  - "Fraud"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Collectible Achievements

> Catalog pointer for the UI Patterns source page: [Collectible Achievements](https://ui-patterns.com/patterns/CollectibleAchievements).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Reputation
- Source breadcrumb: Design Patterns > Social > Reputation > Collectible Achievements

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/CollectibleAchievements
- Page title: Collectible Achievements design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Families of collectibles, It should be attractive to be rewarded, Combine easy successes with hard challenges, Types of achievements, What are you awarding?, Rationale, Discussion, Quality, Get people started, Is it mine forever?, Fraud
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 25 words on source page
- Example: 161 words on source page
- Usage: 139 words on source page
- Solution: 887 words on source page
- Families of collectibles: 130 words on source page
- It should be attractive to be rewarded: 144 words on source page
- Combine easy successes with hard challenges: 70 words on source page
- Types of achievements: 370 words on source page
- What are you awarding?: 92 words on source page
- Rationale: 141 words on source page
- Discussion: 688 words on source page
- Quality: 357 words on source page
- Get people started: 40 words on source page
- Is it mine forever?: 92 words on source page
- Fraud: 85 words on source page

## Source Navigation

- Previous source navigation: Completeness meter
- Next source navigation: Progressive Disclosure


<!-- ===== ui-patterns/wiki/concepts/patterns/commitment-and-consistency.md ===== -->

---
title: "Commitment & Consistency"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Commitment-consistency"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Commitment-consistency"
source_slug: "Commitment-consistency"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Getting commitments to work"
  - "Getting it Right"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Commitment & Consistency

> Catalog pointer for the UI Patterns source page: [Commitment & Consistency](https://ui-patterns.com/patterns/Commitment-consistency).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Commitment & Consistency

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Commitment-consistency
- Page title: Commitment & Consistency design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Getting commitments to work, Getting it Right, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 73 words on source page
- Usage: 28 words on source page
- Solution: 562 words on source page
- Getting commitments to work: 93 words on source page
- Getting it Right: 244 words on source page
- Rationale: 221 words on source page
- Discussion: 352 words on source page

## Source Navigation

- Previous source navigation: Cognitive Dissonance
- Next source navigation: Drag and drop


<!-- ===== ui-patterns/wiki/concepts/patterns/competition.md ===== -->

---
title: "Competition"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Competition"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Competition"
source_slug: "Competition"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Competition

> Catalog pointer for the UI Patterns source page: [Competition](https://ui-patterns.com/patterns/Competition).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Competition

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Competition
- Page title: Competition design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 25 words on source page
- Usage: 9 words on source page
- Solution: 117 words on source page
- Rationale: 64 words on source page
- Discussion: 83 words on source page

## Source Navigation

- Previous source navigation: Sequencing
- Next source navigation: Pricing table


<!-- ===== ui-patterns/wiki/concepts/patterns/completeness-meter.md ===== -->

---
title: "Completeness meter"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/CompletenessMeter"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/CompletenessMeter"
source_slug: "CompletenessMeter"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Explaining the process"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Completeness meter

> Catalog pointer for the UI Patterns source page: [Completeness meter](https://ui-patterns.com/patterns/CompletenessMeter).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Explaining the process
- Source breadcrumb: Design Patterns > Getting input > Explaining the process > Completeness meter

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/CompletenessMeter
- Page title: Completeness meter design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 104 words on source page
- Usage: 89 words on source page
- Solution: 224 words on source page
- Rationale: 104 words on source page
- Discussion: 101 words on source page

## Source Navigation

- Previous source navigation: Wizard
- Next source navigation: Collectible Achievements


<!-- ===== ui-patterns/wiki/concepts/patterns/conceptual-metaphor.md ===== -->

---
title: "Conceptual Metaphor"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Conceptual-metaphor"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Conceptual-metaphor"
source_slug: "Conceptual-metaphor"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Conceptual Metaphor

> Catalog pointer for the UI Patterns source page: [Conceptual Metaphor](https://ui-patterns.com/patterns/Conceptual-metaphor).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Conceptual Metaphor

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Conceptual-metaphor
- Page title: Conceptual Metaphor design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 36 words on source page
- Usage: 23 words on source page
- Solution: 104 words on source page
- Rationale: 178 words on source page

## Source Navigation

- Previous source navigation: Tunnelling
- Next source navigation: Serial Positioning Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/continuous-scrolling.md ===== -->

---
title: "Continuous Scrolling"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ContinuousScrolling"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ContinuousScrolling"
source_slug: "ContinuousScrolling"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Continuous Scrolling

> Catalog pointer for the UI Patterns source page: [Continuous Scrolling](https://ui-patterns.com/patterns/ContinuousScrolling).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Continuous Scrolling

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ContinuousScrolling
- Page title: Continuous Scrolling design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 47 words on source page
- Example: 34 words on source page
- Usage: 33 words on source page
- Solution: 112 words on source page
- Rationale: 186 words on source page

## Source Navigation

- Previous source navigation: Blank Slate
- Next source navigation: Archive


<!-- ===== ui-patterns/wiki/concepts/patterns/copy-box.md ===== -->

---
title: "Copy Box"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/CopyBox"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/CopyBox"
source_slug: "CopyBox"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Formatting data"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 10
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Copy Box

> Catalog pointer for the UI Patterns source page: [Copy Box](https://ui-patterns.com/patterns/CopyBox).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Formatting data
- Source breadcrumb: Design Patterns > Dealing with data > Formatting data > Copy Box

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/CopyBox
- Page title: Copy Box design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 10
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 9 words on source page
- Example: 47 words on source page
- Usage: 46 words on source page
- Solution: 121 words on source page
- Rationale: 60 words on source page

## Source Navigation

- Previous source navigation: Table Filter
- Next source navigation: Coupon


<!-- ===== ui-patterns/wiki/concepts/patterns/coupon.md ===== -->

---
title: "Coupon"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Coupon"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Coupon"
source_slug: "Coupon"
track: "User Interface Design Patterns"
group: "Miscellaneous"
subgroup: "Shopping"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Types of coupon offers"
  - "Rationale"
example_count: 9
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Coupon

> Catalog pointer for the UI Patterns source page: [Coupon](https://ui-patterns.com/patterns/Coupon).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Miscellaneous
- Subgroup: Shopping
- Source breadcrumb: Design Patterns > Miscellaneous > Shopping > Coupon

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Coupon
- Page title: Coupon design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Types of coupon offers, Rationale
- Example screenshots detected at source: 9
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 114 words on source page
- Usage: 76 words on source page
- Solution: 197 words on source page
- Types of coupon offers: 129 words on source page
- Rationale: 140 words on source page

## Source Navigation

- Previous source navigation: Shopping Cart
- Next source navigation: Continuous Scrolling


<!-- ===== ui-patterns/wiki/concepts/patterns/curiosity.md ===== -->

---
title: "Curiosity"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/curiosity"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/curiosity"
source_slug: "curiosity"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Curiosity

> Catalog pointer for the UI Patterns source page: [Curiosity](https://ui-patterns.com/patterns/curiosity).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Curiosity

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/curiosity
- Page title: Curiosity design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 31 words on source page
- Usage: 12 words on source page
- Solution: 93 words on source page
- Rationale: 176 words on source page

## Source Navigation

- Previous source navigation: Paywall
- Next source navigation: Auto-sharing


<!-- ===== ui-patterns/wiki/concepts/patterns/dashboard.md ===== -->

---
title: "Dashboard"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/dashboard"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/dashboard"
source_slug: "dashboard"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Formatting data"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Types of dashboards"
  - "Rationale"
example_count: 6
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Dashboard

> Catalog pointer for the UI Patterns source page: [Dashboard](https://ui-patterns.com/patterns/dashboard).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Formatting data
- Source breadcrumb: Design Patterns > Dealing with data > Formatting data > Dashboard

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/dashboard
- Page title: Dashboard design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Types of dashboards, Rationale
- Example screenshots detected at source: 6
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 46 words on source page
- Usage: 18 words on source page
- Solution: 223 words on source page
- Types of dashboards: 185 words on source page
- Rationale: 95 words on source page

## Source Navigation

- Previous source navigation: Paywall
- Next source navigation: Auto-sharing


<!-- ===== ui-patterns/wiki/concepts/patterns/decoy-effect.md ===== -->

---
title: "Decoy Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/decoy-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/decoy-effect"
source_slug: "decoy-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Decoy Effect

> Catalog pointer for the UI Patterns source page: [Decoy Effect](https://ui-patterns.com/patterns/decoy-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Decoy Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/decoy-effect
- Page title: Decoy Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 48 words on source page
- Usage: 38 words on source page
- Solution: 235 words on source page
- Rationale: 73 words on source page
- Discussion: 341 words on source page

## Source Navigation

- Previous source navigation: Present Bias


<!-- ===== ui-patterns/wiki/concepts/patterns/delay-discounting.md ===== -->

---
title: "Delay Discounting"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/delay-discounting"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/delay-discounting"
source_slug: "delay-discounting"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Delay Discounting

> Catalog pointer for the UI Patterns source page: [Delay Discounting](https://ui-patterns.com/patterns/delay-discounting).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Delay Discounting

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/delay-discounting
- Page title: Delay Discounting design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 21 words on source page
- Solution: 133 words on source page
- Rationale: 106 words on source page

## Source Navigation

- Previous source navigation: Fresh Start Effect
- Next source navigation: Inaction Inertia Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/delighters.md ===== -->

---
title: "Delighters"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/delighters"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/delighters"
source_slug: "delighters"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Delighters

> Catalog pointer for the UI Patterns source page: [Delighters](https://ui-patterns.com/patterns/delighters).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Delighters

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/delighters
- Page title: Delighters design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 28 words on source page
- Usage: 16 words on source page
- Solution: 123 words on source page
- Rationale: 55 words on source page
- Discussion: 251 words on source page

## Source Navigation

- Previous source navigation: Periodic Events
- Next source navigation: Flagging & Reporting


<!-- ===== ui-patterns/wiki/concepts/patterns/drag-and-drop.md ===== -->

---
title: "Drag and drop"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/drag-and-drop"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/drag-and-drop"
source_slug: "drag-and-drop"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Drag and drop

> Catalog pointer for the UI Patterns source page: [Drag and drop](https://ui-patterns.com/patterns/drag-and-drop).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Drag and drop

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/drag-and-drop
- Page title: Drag and drop design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 58 words on source page
- Usage: 47 words on source page
- Solution: 13 words on source page
- Rationale: 59 words on source page
- Discussion: 24 words on source page

## Source Navigation

- Previous source navigation: Playthrough
- Next source navigation: Cards


<!-- ===== ui-patterns/wiki/concepts/patterns/endowment-effect.md ===== -->

---
title: "Endowment Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Endowment-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Endowment-effect"
source_slug: "Endowment-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Endowment Effect

> Catalog pointer for the UI Patterns source page: [Endowment Effect](https://ui-patterns.com/patterns/Endowment-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Endowment Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Endowment-effect
- Page title: Endowment Effect design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 71 words on source page
- Usage: 27 words on source page
- Solution: 42 words on source page
- Rationale: 302 words on source page
- Discussion: 136 words on source page

## Source Navigation

- Previous source navigation: Storytelling
- Next source navigation: Peak-end rule


<!-- ===== ui-patterns/wiki/concepts/patterns/event-calendar.md ===== -->

---
title: "Event Calendar"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/EventCalendar"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/EventCalendar"
source_slug: "EventCalendar"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "The elements of an event list"
  - "Rationale"
  - "Discussion"
  - "Buckets of time"
  - "Common pitfalls of event calendar design"
  - "Thinking in outlook and the calendar box"
  - "Listing events without a start time"
  - "Missing other relevant data"
  - "Impossible to scan"
  - "Huge lists"
  - "No filtering options"
  - "Use the user’s abstractions – not your own"
example_count: 15
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Event Calendar

> Catalog pointer for the UI Patterns source page: [Event Calendar](https://ui-patterns.com/patterns/EventCalendar).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Event Calendar

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/EventCalendar
- Page title: Event Calendar design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, The elements of an event list, Rationale, Discussion, Buckets of time, Common pitfalls of event calendar design, Thinking in outlook and the calendar box, Listing events without a start time, Missing other relevant data, Impossible to scan, Huge lists, No filtering options, Use the user’s abstractions – not your own
- Example screenshots detected at source: 15
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 32 words on source page
- Example: 64 words on source page
- Usage: 45 words on source page
- Solution: 338 words on source page
- The elements of an event list: 93 words on source page
- Rationale: 23 words on source page
- Discussion: 892 words on source page
- Buckets of time: 138 words on source page
- Common pitfalls of event calendar design: 16 words on source page
- Thinking in outlook and the calendar box: 97 words on source page
- Listing events without a start time: 155 words on source page
- Missing other relevant data: 81 words on source page
- Impossible to scan: 144 words on source page
- Huge lists: 54 words on source page
- No filtering options: 61 words on source page
- Use the user’s abstractions – not your own: 94 words on source page

## Source Navigation

- Previous source navigation: Article List
- Next source navigation: Intentional Gaps


<!-- ===== ui-patterns/wiki/concepts/patterns/expandable-input.md ===== -->

---
title: "Expandable Input"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/expandable-input"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/expandable-input"
source_slug: "expandable-input"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Expandable Input

> Catalog pointer for the UI Patterns source page: [Expandable Input](https://ui-patterns.com/patterns/expandable-input).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Expandable Input

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/expandable-input
- Page title: Expandable Input design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 68 words on source page
- Usage: 30 words on source page
- Solution: 56 words on source page
- Rationale: 40 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/fat-footer.md ===== -->

---
title: "Fat Footer"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/FatFooter"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/FatFooter"
source_slug: "FatFooter"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Fat Footer

> Catalog pointer for the UI Patterns source page: [Fat Footer](https://ui-patterns.com/patterns/FatFooter).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Fat Footer

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/FatFooter
- Page title: Fat Footer design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 101 words on source page
- Usage: 78 words on source page
- Solution: 236 words on source page
- Rationale: 96 words on source page
- Discussion: 86 words on source page

## Source Navigation

- Previous source navigation: Home Link
- Next source navigation: Accordion Menu


<!-- ===== ui-patterns/wiki/concepts/patterns/favorites.md ===== -->

---
title: "Favorites"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/favorites"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/favorites"
source_slug: "favorites"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Favorites

> Catalog pointer for the UI Patterns source page: [Favorites](https://ui-patterns.com/patterns/favorites).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Favorites

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/favorites
- Page title: Favorites design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 39 words on source page
- Usage: 26 words on source page
- Solution: 171 words on source page
- Rationale: 50 words on source page

## Source Navigation

- Previous source navigation: Frequently Asked Questions (FAQ)
- Next source navigation: Pull to refresh


<!-- ===== ui-patterns/wiki/concepts/patterns/feedback-loops.md ===== -->

---
title: "Feedback Loops"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Feedback-loops"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Feedback-loops"
source_slug: "Feedback-loops"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Positive feedback loops"
  - "Negative feedback loops"
  - "Things are connected"
  - "The four distinct stages of a feedback loop"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Feedback Loops

> Catalog pointer for the UI Patterns source page: [Feedback Loops](https://ui-patterns.com/patterns/Feedback-loops).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Feedback Loops

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Feedback-loops
- Page title: Feedback Loops design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Positive feedback loops, Negative feedback loops, Things are connected, The four distinct stages of a feedback loop
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 113 words on source page
- Usage: 15 words on source page
- Solution: 66 words on source page
- Rationale: 20 words on source page
- Discussion: 568 words on source page
- Positive feedback loops: 23 words on source page
- Negative feedback loops: 31 words on source page
- Things are connected: 85 words on source page
- The four distinct stages of a feedback loop: 229 words on source page

## Source Navigation

- Previous source navigation: Negativity bias
- Next source navigation: Reciprocation


<!-- ===== ui-patterns/wiki/concepts/patterns/fill-in-the-blanks.md ===== -->

---
title: "Fill in the Blanks"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/FillInTheBlanks"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/FillInTheBlanks"
source_slug: "FillInTheBlanks"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Fill in the Blanks

> Catalog pointer for the UI Patterns source page: [Fill in the Blanks](https://ui-patterns.com/patterns/FillInTheBlanks).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Fill in the Blanks

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/FillInTheBlanks
- Page title: Fill in the Blanks design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 9 words on source page
- Example: 161 words on source page
- Usage: 160 words on source page
- Solution: 196 words on source page
- Rationale: 191 words on source page

## Source Navigation

- Previous source navigation: Structured Format
- Next source navigation: Input Prompt


<!-- ===== ui-patterns/wiki/concepts/patterns/fixed-rewards.md ===== -->

---
title: "Fixed rewards"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Fixed-rewards"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Fixed-rewards"
source_slug: "Fixed-rewards"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Fundamentals of rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Fixed rewards"
  - "The right reward at the right time and amount"
  - "Types of rewards"
  - "Rationale"
  - "Discussion"
  - "Positive and negative rewards (and punishments)"
  - "Primary and secondary rewards"
  - "Notes"
example_count: 5
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Fixed rewards

> Catalog pointer for the UI Patterns source page: [Fixed rewards](https://ui-patterns.com/patterns/Fixed-rewards).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Fundamentals of rewards
- Source breadcrumb: Design Patterns > Game mechanics > Fundamentals of rewards > Fixed rewards

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Fixed-rewards
- Page title: Fixed rewards design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Fixed rewards, The right reward at the right time and amount, Types of rewards, Rationale, Discussion, Positive and negative rewards (and punishments), Primary and secondary rewards, Notes
- Example screenshots detected at source: 5
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 86 words on source page
- Usage: 41 words on source page
- Solution: 393 words on source page
- Fixed rewards: 139 words on source page
- The right reward at the right time and amount: 190 words on source page
- Types of rewards: 31 words on source page
- Rationale: 13 words on source page
- Discussion: 210 words on source page
- Positive and negative rewards (and punishments): 69 words on source page
- Primary and secondary rewards: 44 words on source page
- Notes: 18 words on source page

## Source Navigation

- Previous source navigation: Event Calendar
- Next source navigation: Loss Aversion


<!-- ===== ui-patterns/wiki/concepts/patterns/flagging-and-reporting.md ===== -->

---
title: "Flagging & Reporting"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/flagging-and-reporting"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/flagging-and-reporting"
source_slug: "flagging-and-reporting"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Community driven"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Flagging & Reporting

> Catalog pointer for the UI Patterns source page: [Flagging & Reporting](https://ui-patterns.com/patterns/flagging-and-reporting).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Community driven
- Source breadcrumb: Design Patterns > Getting input > Community driven > Flagging & Reporting

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/flagging-and-reporting
- Page title: Flagging & Reporting design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 9 words on source page
- Example: 26 words on source page
- Usage: 25 words on source page
- Solution: 6 words on source page
- Rationale: 56 words on source page

## Source Navigation

- Previous source navigation: Delighters
- Next source navigation: Keyboard Shortcuts


<!-- ===== ui-patterns/wiki/concepts/patterns/follow.md ===== -->

---
title: "Follow"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/follow"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/follow"
source_slug: "follow"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Follow

> Catalog pointer for the UI Patterns source page: [Follow](https://ui-patterns.com/patterns/follow).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Follow

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/follow
- Page title: Follow design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 34 words on source page
- Usage: 19 words on source page
- Solution: 137 words on source page
- Rationale: 101 words on source page
- Discussion: 33 words on source page

## Source Navigation

- Previous source navigation: Testimonials
- Next source navigation: Invite friends


<!-- ===== ui-patterns/wiki/concepts/patterns/forgiving-format.md ===== -->

---
title: "Forgiving Format"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ForgivingFormat"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ForgivingFormat"
source_slug: "ForgivingFormat"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 6
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Forgiving Format

> Catalog pointer for the UI Patterns source page: [Forgiving Format](https://ui-patterns.com/patterns/ForgivingFormat).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Forgiving Format

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ForgivingFormat
- Page title: Forgiving Format design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 6
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 109 words on source page
- Usage: 108 words on source page
- Solution: 99 words on source page
- Rationale: 70 words on source page

## Source Navigation

- Previous source navigation: Accordion Menu
- Next source navigation: Structured Format


<!-- ===== ui-patterns/wiki/concepts/patterns/framing.md ===== -->

---
title: "Framing"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/framing"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/framing"
source_slug: "framing"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Framing

> Catalog pointer for the UI Patterns source page: [Framing](https://ui-patterns.com/patterns/framing).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Framing

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/framing
- Page title: Framing design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Usage: 7 words on source page
- Solution: 119 words on source page
- Rationale: 188 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/frequently-asked-questions-faq.md ===== -->

---
title: "Frequently Asked Questions (FAQ)"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/frequently-asked-questions-faq"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/frequently-asked-questions-faq"
source_slug: "frequently-asked-questions-faq"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Formatting data"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Focus on information"
  - "Designing longer FAQs"
  - "Card sorting"
  - "Let users ask new questions"
  - "Few people go to the FAQ front page directly"
example_count: 11
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Frequently Asked Questions (FAQ)

> Catalog pointer for the UI Patterns source page: [Frequently Asked Questions (FAQ)](https://ui-patterns.com/patterns/frequently-asked-questions-faq).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Formatting data
- Source breadcrumb: Design Patterns > Dealing with data > Formatting data > Frequently Asked Questions (FAQ)

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/frequently-asked-questions-faq
- Page title: Frequently Asked Questions (FAQ) design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Focus on information, Designing longer FAQs, Card sorting, Let users ask new questions, Few people go to the FAQ front page directly
- Example screenshots detected at source: 11
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 45 words on source page
- Usage: 30 words on source page
- Solution: 492 words on source page
- Focus on information: 53 words on source page
- Designing longer FAQs: 167 words on source page
- Card sorting: 43 words on source page
- Let users ask new questions: 46 words on source page
- Few people go to the FAQ front page directly: 78 words on source page

## Source Navigation

- Previous source navigation: Inline Hints
- Next source navigation: Categorization


<!-- ===== ui-patterns/wiki/concepts/patterns/fresh-start-effect.md ===== -->

---
title: "Fresh Start Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/fresh-start-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/fresh-start-effect"
source_slug: "fresh-start-effect"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Fresh Start Effect

> Catalog pointer for the UI Patterns source page: [Fresh Start Effect](https://ui-patterns.com/patterns/fresh-start-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Fresh Start Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/fresh-start-effect
- Page title: Fresh Start Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 52 words on source page
- Usage: 35 words on source page
- Solution: 93 words on source page
- Rationale: 216 words on source page

## Source Navigation

- Previous source navigation: Priming Effect
- Next source navigation: Delay Discounting


<!-- ===== ui-patterns/wiki/concepts/patterns/friend-list.md ===== -->

---
title: "Friend list"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/friend-list"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/friend-list"
source_slug: "friend-list"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Friend list

> Catalog pointer for the UI Patterns source page: [Friend list](https://ui-patterns.com/patterns/friend-list).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Friend list

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/friend-list
- Page title: Friend list design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 21 words on source page
- Example: 83 words on source page
- Usage: 77 words on source page
- Solution: 20 words on source page
- Rationale: 89 words on source page

## Source Navigation

- Previous source navigation: Testimonials
- Next source navigation: Invite friends


<!-- ===== ui-patterns/wiki/concepts/patterns/friend.md ===== -->

---
title: "Friend"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/friend"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/friend"
source_slug: "friend"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Friend

> Catalog pointer for the UI Patterns source page: [Friend](https://ui-patterns.com/patterns/friend).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Friend

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/friend
- Page title: Friend design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 33 words on source page
- Usage: 23 words on source page
- Solution: 57 words on source page

## Source Navigation

- Previous source navigation: Frequently Asked Questions (FAQ)
- Next source navigation: Pull to refresh


<!-- ===== ui-patterns/wiki/concepts/patterns/gallery.md ===== -->

---
title: "Gallery"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Gallery"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Gallery"
source_slug: "Gallery"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Images"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Navigation options often include"
  - "Tips for designing a gallery"
  - "Reload the entire page or change only the important parts"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Gallery

> Catalog pointer for the UI Patterns source page: [Gallery](https://ui-patterns.com/patterns/Gallery).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Images
- Source breadcrumb: Design Patterns > Dealing with data > Images > Gallery

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Gallery
- Page title: Gallery design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Navigation options often include, Tips for designing a gallery, Reload the entire page or change only the important parts, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 111 words on source page
- Usage: 65 words on source page
- Solution: 465 words on source page
- Navigation options often include: 144 words on source page
- Tips for designing a gallery: 155 words on source page
- Reload the entire page or change only the important parts: 61 words on source page
- Rationale: 135 words on source page

## Source Navigation

- Previous source navigation: Walkthrough
- Next source navigation: Slideshow


<!-- ===== ui-patterns/wiki/concepts/patterns/goal-gradient-effect.md ===== -->

---
title: "Goal-Gradient Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Completion"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Completion"
source_slug: "Completion"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Set and communicate expectations and progress."
  - "Making the completion official"
  - "Provide artificial progress"
  - "Beware of the post-reward reset effect"
  - "Divide larger tasks into sub-tasks"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Goal-Gradient Effect

> Catalog pointer for the UI Patterns source page: [Goal-Gradient Effect](https://ui-patterns.com/patterns/Completion).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Goal-Gradient Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Completion
- Page title: Goal-Gradient Effect design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Set and communicate expectations and progress., Making the completion official, Provide artificial progress, Beware of the post-reward reset effect, Divide larger tasks into sub-tasks, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 72 words on source page
- Usage: 50 words on source page
- Solution: 362 words on source page
- Set and communicate expectations and progress.: 112 words on source page
- Making the completion official: 71 words on source page
- Provide artificial progress: 39 words on source page
- Beware of the post-reward reset effect: 32 words on source page
- Divide larger tasks into sub-tasks: 7 words on source page
- Rationale: 257 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/good-defaults.md ===== -->

---
title: "Good Defaults"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/GoodDefaults"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/GoodDefaults"
source_slug: "GoodDefaults"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 8
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Good Defaults

> Catalog pointer for the UI Patterns source page: [Good Defaults](https://ui-patterns.com/patterns/GoodDefaults).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Good Defaults

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/GoodDefaults
- Page title: Good Defaults design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 8
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 153 words on source page
- Usage: 104 words on source page
- Solution: 108 words on source page
- Rationale: 92 words on source page

## Source Navigation

- Previous source navigation: Fill in the Blanks
- Next source navigation: Captcha


<!-- ===== ui-patterns/wiki/concepts/patterns/guided-tour.md ===== -->

---
title: "Guided Tour"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Guided-tour"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Guided-tour"
source_slug: "Guided-tour"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Product-guided vs User-guided."
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Guided Tour

> Catalog pointer for the UI Patterns source page: [Guided Tour](https://ui-patterns.com/patterns/Guided-tour).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Guided Tour

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Guided-tour
- Page title: Guided Tour design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Product-guided vs User-guided.
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 58 words on source page
- Usage: 36 words on source page
- Solution: 184 words on source page
- Product-guided vs User-guided.: 57 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/halo-effect.md ===== -->

---
title: "Halo Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/halo-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/halo-effect"
source_slug: "halo-effect"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Halo Effect

> Catalog pointer for the UI Patterns source page: [Halo Effect](https://ui-patterns.com/patterns/halo-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Halo Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/halo-effect
- Page title: Halo Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 20 words on source page
- Solution: 74 words on source page
- Rationale: 96 words on source page
- Discussion: 150 words on source page

## Source Navigation

- Previous source navigation: Rule Builder
- Next source navigation: Sunk Cost Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/hedonic-adaptation.md ===== -->

---
title: "Hedonic Adaptation"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/hedonic-adaptation"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/hedonic-adaptation"
source_slug: "hedonic-adaptation"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Hedonic Adaptation

> Catalog pointer for the UI Patterns source page: [Hedonic Adaptation](https://ui-patterns.com/patterns/hedonic-adaptation).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Hedonic Adaptation

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/hedonic-adaptation
- Page title: Hedonic Adaptation design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 40 words on source page
- Usage: 25 words on source page
- Solution: 153 words on source page
- Rationale: 185 words on source page

## Source Navigation

- Previous source navigation: Present Bias


<!-- ===== ui-patterns/wiki/concepts/patterns/home-link.md ===== -->

---
title: "Home Link"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/HomeLink"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/HomeLink"
source_slug: "HomeLink"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Home Link

> Catalog pointer for the UI Patterns source page: [Home Link](https://ui-patterns.com/patterns/HomeLink).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Home Link

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/HomeLink
- Page title: Home Link design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 35 words on source page
- Usage: 34 words on source page
- Solution: 89 words on source page
- Rationale: 65 words on source page

## Source Navigation

- Previous source navigation: Shortcut Dropdown
- Next source navigation: Fat Footer


<!-- ===== ui-patterns/wiki/concepts/patterns/horizontal-dropdown-menu.md ===== -->

---
title: "Horizontal Dropdown Menu"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/HorizontalDropdownMenu"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/HorizontalDropdownMenu"
source_slug: "HorizontalDropdownMenu"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Menus"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Other issues you want to take notice of"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Horizontal Dropdown Menu

> Catalog pointer for the UI Patterns source page: [Horizontal Dropdown Menu](https://ui-patterns.com/patterns/HorizontalDropdownMenu).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Menus
- Source breadcrumb: Design Patterns > Navigation > Menus > Horizontal Dropdown Menu

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/HorizontalDropdownMenu
- Page title: Horizontal Dropdown Menu design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Other issues you want to take notice of, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 55 words on source page
- Usage: 54 words on source page
- Solution: 264 words on source page
- Other issues you want to take notice of: 66 words on source page
- Rationale: 66 words on source page

## Source Navigation

- Previous source navigation: Home Link
- Next source navigation: Accordion Menu


<!-- ===== ui-patterns/wiki/concepts/patterns/ikea-effect.md ===== -->

---
title: "IKEA effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ikea-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ikea-effect"
source_slug: "ikea-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# IKEA effect

> Catalog pointer for the UI Patterns source page: [IKEA effect](https://ui-patterns.com/patterns/ikea-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > IKEA effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ikea-effect
- Page title: IKEA effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 57 words on source page
- Usage: 45 words on source page
- Solution: 156 words on source page
- Rationale: 252 words on source page

## Source Navigation

- Previous source navigation: Present Bias


<!-- ===== ui-patterns/wiki/concepts/patterns/illusion-of-control.md ===== -->

---
title: "Illusion of control"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Illusion-of-control"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Illusion-of-control"
source_slug: "Illusion-of-control"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Illusion of control

> Catalog pointer for the UI Patterns source page: [Illusion of control](https://ui-patterns.com/patterns/Illusion-of-control).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Illusion of control

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Illusion-of-control
- Page title: Illusion of control design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 13 words on source page
- Solution: 28 words on source page
- Rationale: 361 words on source page

## Source Navigation

- Previous source navigation: Peak-end rule
- Next source navigation: Kairos


<!-- ===== ui-patterns/wiki/concepts/patterns/image-zoom.md ===== -->

---
title: "Image Zoom"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ImageZoom"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ImageZoom"
source_slug: "ImageZoom"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Images"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Image Zoom

> Catalog pointer for the UI Patterns source page: [Image Zoom](https://ui-patterns.com/patterns/ImageZoom).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Images
- Source breadcrumb: Design Patterns > Dealing with data > Images > Image Zoom

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ImageZoom
- Page title: Image Zoom design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 171 words on source page
- Usage: 139 words on source page
- Solution: 98 words on source page
- Rationale: 95 words on source page

## Source Navigation

- Previous source navigation: Rate Content
- Next source navigation: Adaptable View


<!-- ===== ui-patterns/wiki/concepts/patterns/inaction-inertia-effect.md ===== -->

---
title: "Inaction Inertia Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/inaction-inertia-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/inaction-inertia-effect"
source_slug: "inaction-inertia-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Inaction Inertia Effect

> Catalog pointer for the UI Patterns source page: [Inaction Inertia Effect](https://ui-patterns.com/patterns/inaction-inertia-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Inaction Inertia Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/inaction-inertia-effect
- Page title: Inaction Inertia Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 54 words on source page
- Usage: 40 words on source page
- Solution: 160 words on source page
- Rationale: 173 words on source page

## Source Navigation

- Previous source navigation: Zeigarnik Effect
- Next source navigation: Picture Superiority Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/inline-help-box.md ===== -->

---
title: "Inline Help Box"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/InlineHelpBox"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/InlineHelpBox"
source_slug: "InlineHelpBox"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Explaining the process"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Inline Help Box

> Catalog pointer for the UI Patterns source page: [Inline Help Box](https://ui-patterns.com/patterns/InlineHelpBox).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Explaining the process
- Source breadcrumb: Design Patterns > Getting input > Explaining the process > Inline Help Box

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/InlineHelpBox
- Page title: Inline Help Box design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 93 words on source page
- Usage: 92 words on source page
- Solution: 180 words on source page
- Rationale: 70 words on source page

## Source Navigation

- Previous source navigation: Tag Cloud
- Next source navigation: Password Strength Meter


<!-- ===== ui-patterns/wiki/concepts/patterns/inline-hints.md ===== -->

---
title: "Inline Hints"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/inline-hints"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/inline-hints"
source_slug: "inline-hints"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Inline Hints

> Catalog pointer for the UI Patterns source page: [Inline Hints](https://ui-patterns.com/patterns/inline-hints).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Inline Hints

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/inline-hints
- Page title: Inline Hints design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 99 words on source page
- Usage: 83 words on source page
- Solution: 202 words on source page
- Rationale: 39 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/inplace-editor.md ===== -->

---
title: "Inplace Editor"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/InplaceEditor"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/InplaceEditor"
source_slug: "InplaceEditor"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Inplace Editor

> Catalog pointer for the UI Patterns source page: [Inplace Editor](https://ui-patterns.com/patterns/InplaceEditor).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Inplace Editor

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/InplaceEditor
- Page title: Inplace Editor design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 13 words on source page
- Example: 67 words on source page
- Usage: 66 words on source page
- Solution: 309 words on source page
- Rationale: 60 words on source page

## Source Navigation

- Previous source navigation: Good Defaults
- Next source navigation: Sort By Column


<!-- ===== ui-patterns/wiki/concepts/patterns/input-feedback.md ===== -->

---
title: "Input Feedback"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/InputFeedback"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/InputFeedback"
source_slug: "InputFeedback"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Provide clear feedback after every action"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Input Feedback

> Catalog pointer for the UI Patterns source page: [Input Feedback](https://ui-patterns.com/patterns/InputFeedback).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Input Feedback

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/InputFeedback
- Page title: Input Feedback design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Provide clear feedback after every action
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 66 words on source page
- Usage: 48 words on source page
- Solution: 459 words on source page
- Rationale: 128 words on source page
- Discussion: 130 words on source page
- Provide clear feedback after every action: 50 words on source page

## Source Navigation

- Previous source navigation: Account Registration
- Next source navigation: Rate Content


<!-- ===== ui-patterns/wiki/concepts/patterns/input-prompt.md ===== -->

---
title: "Input Prompt"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/InputPrompt"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/InputPrompt"
source_slug: "InputPrompt"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Input Prompt

> Catalog pointer for the UI Patterns source page: [Input Prompt](https://ui-patterns.com/patterns/InputPrompt).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Input Prompt

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/InputPrompt
- Page title: Input Prompt design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 9 words on source page
- Example: 82 words on source page
- Usage: 81 words on source page
- Solution: 146 words on source page
- Rationale: 152 words on source page

## Source Navigation

- Previous source navigation: Fill in the Blanks
- Next source navigation: Captcha


<!-- ===== ui-patterns/wiki/concepts/patterns/intentional-gaps.md ===== -->

---
title: "Intentional Gaps"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Intentional-gaps"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Intentional-gaps"
source_slug: "Intentional-gaps"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Intentional Gaps

> Catalog pointer for the UI Patterns source page: [Intentional Gaps](https://ui-patterns.com/patterns/Intentional-gaps).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Intentional Gaps

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Intentional-gaps
- Page title: Intentional Gaps design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 12 words on source page
- Example: 58 words on source page
- Usage: 40 words on source page
- Solution: 152 words on source page
- Rationale: 149 words on source page

## Source Navigation

- Previous source navigation: Event Calendar
- Next source navigation: Loss Aversion


<!-- ===== ui-patterns/wiki/concepts/patterns/investment-loops.md ===== -->

---
title: "Investment Loops"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/investment-loops"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/investment-loops"
source_slug: "investment-loops"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Investment Loops

> Catalog pointer for the UI Patterns source page: [Investment Loops](https://ui-patterns.com/patterns/investment-loops).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Investment Loops

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/investment-loops
- Page title: Investment Loops design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 13 words on source page
- Example: 24 words on source page
- Usage: 23 words on source page
- Solution: 209 words on source page
- Rationale: 125 words on source page

## Source Navigation

- Previous source navigation: Temptation Bundling
- Next source navigation: Hedonic Adaptation


<!-- ===== ui-patterns/wiki/concepts/patterns/invite-friends.md ===== -->

---
title: "Invite friends"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/invite-friends"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/invite-friends"
source_slug: "invite-friends"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 10
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Invite friends

> Catalog pointer for the UI Patterns source page: [Invite friends](https://ui-patterns.com/patterns/invite-friends).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Invite friends

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/invite-friends
- Page title: Invite friends design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 10
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 63 words on source page
- Usage: 33 words on source page
- Solution: 99 words on source page
- Rationale: 39 words on source page

## Source Navigation

- Previous source navigation: Chat
- Next source navigation: Modal


<!-- ===== ui-patterns/wiki/concepts/patterns/isolation-effect.md ===== -->

---
title: "Isolation Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/isolation-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/isolation-effect"
source_slug: "isolation-effect"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Attention"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Isolation Effect

> Catalog pointer for the UI Patterns source page: [Isolation Effect](https://ui-patterns.com/patterns/isolation-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Attention
- Source breadcrumb: Design Patterns > Perception and memory > Attention > Isolation Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/isolation-effect
- Page title: Isolation Effect design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 10 words on source page
- Example: 28 words on source page
- Usage: 14 words on source page
- Solution: 191 words on source page
- Rationale: 76 words on source page
- Discussion: 215 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/kairos.md ===== -->

---
title: "Kairos"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Kairos"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Kairos"
source_slug: "Kairos"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Kairos comes in patterns"
  - "Map it out"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Kairos

> Catalog pointer for the UI Patterns source page: [Kairos](https://ui-patterns.com/patterns/Kairos).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Kairos

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Kairos
- Page title: Kairos design pattern
- Section headings available at source: Problem summary, Usage, Solution, Kairos comes in patterns, Map it out, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 59 words on source page
- Usage: 46 words on source page
- Solution: 441 words on source page
- Kairos comes in patterns: 166 words on source page
- Map it out: 142 words on source page
- Rationale: 243 words on source page

## Source Navigation

- Previous source navigation: Negativity bias
- Next source navigation: Reciprocation


<!-- ===== ui-patterns/wiki/concepts/patterns/keyboard-shortcuts.md ===== -->

---
title: "Keyboard Shortcuts"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/keyboard-shortcuts"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/keyboard-shortcuts"
source_slug: "keyboard-shortcuts"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Keyboard shortcut strategies"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Keyboard Shortcuts

> Catalog pointer for the UI Patterns source page: [Keyboard Shortcuts](https://ui-patterns.com/patterns/keyboard-shortcuts).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Keyboard Shortcuts

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/keyboard-shortcuts
- Page title: Keyboard Shortcuts design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Keyboard shortcut strategies
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 8 words on source page
- Example: 32 words on source page
- Usage: 15 words on source page
- Solution: 82 words on source page
- Rationale: 86 words on source page
- Discussion: 110 words on source page
- Keyboard shortcut strategies: 96 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/lazy-registration.md ===== -->

---
title: "Lazy Registration"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/LazyRegistration"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/LazyRegistration"
source_slug: "LazyRegistration"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Registration"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Lazy Registration

> Catalog pointer for the UI Patterns source page: [Lazy Registration](https://ui-patterns.com/patterns/LazyRegistration).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Registration
- Source breadcrumb: Design Patterns > Onboarding > Registration > Lazy Registration

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/LazyRegistration
- Page title: Lazy Registration design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 195 words on source page
- Usage: 166 words on source page
- Solution: 260 words on source page
- Rationale: 206 words on source page
- Discussion: 129 words on source page

## Source Navigation

- Previous source navigation: Password Strength Meter
- Next source navigation: Vote To Promote


<!-- ===== ui-patterns/wiki/concepts/patterns/leaderboard.md ===== -->

---
title: "Leaderboard"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/leaderboard"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/leaderboard"
source_slug: "leaderboard"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Reputation"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Multiple views"
  - "More design tips"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Leaderboard

> Catalog pointer for the UI Patterns source page: [Leaderboard](https://ui-patterns.com/patterns/leaderboard).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Reputation
- Source breadcrumb: Design Patterns > Social > Reputation > Leaderboard

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/leaderboard
- Page title: Leaderboard design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Multiple views, More design tips
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 73 words on source page
- Usage: 64 words on source page
- Solution: 256 words on source page
- Multiple views: 47 words on source page
- More design tips: 118 words on source page

## Source Navigation

- Previous source navigation: Paywall
- Next source navigation: Auto-sharing


<!-- ===== ui-patterns/wiki/concepts/patterns/levels.md ===== -->

---
title: "Levels"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Levels"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Levels"
source_slug: "Levels"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Levels

> Catalog pointer for the UI Patterns source page: [Levels](https://ui-patterns.com/patterns/Levels).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Levels

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Levels
- Page title: Levels design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 22 words on source page
- Solution: 147 words on source page
- Rationale: 123 words on source page

## Source Navigation

- Previous source navigation: Event Calendar
- Next source navigation: Loss Aversion


<!-- ===== ui-patterns/wiki/concepts/patterns/liking.md ===== -->

---
title: "Liking"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Liking"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Liking"
source_slug: "Liking"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Physical attractiveness"
  - "Similarity"
  - "Compliments"
  - "Contact"
  - "Cooperation rather than competition"
  - "Conditioning & association"
  - "Rationale"
  - "Discussion"
  - "Powerful Pairings"
  - "Ethical Recommendations"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Liking

> Catalog pointer for the UI Patterns source page: [Liking](https://ui-patterns.com/patterns/Liking).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Liking

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Liking
- Page title: Liking design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Physical attractiveness, Similarity, Compliments, Contact, Cooperation rather than competition, Conditioning & association, Rationale, Discussion, Powerful Pairings, Ethical Recommendations
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 89 words on source page
- Usage: 42 words on source page
- Solution: 759 words on source page
- Physical attractiveness: 120 words on source page
- Similarity: 75 words on source page
- Compliments: 91 words on source page
- Contact: 90 words on source page
- Cooperation rather than competition: 235 words on source page
- Conditioning & association: 102 words on source page
- Rationale: 235 words on source page
- Discussion: 1234 words on source page
- Powerful Pairings: 335 words on source page
- Ethical Recommendations: 282 words on source page

## Source Navigation

- Previous source navigation: Product page
- Next source navigation: Walkthrough


<!-- ===== ui-patterns/wiki/concepts/patterns/limited-choice.md ===== -->

---
title: "Limited Choice"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Limited-choice"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Limited-choice"
source_slug: "Limited-choice"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Scarcity"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Limited Choice

> Catalog pointer for the UI Patterns source page: [Limited Choice](https://ui-patterns.com/patterns/Limited-choice).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Scarcity
- Source breadcrumb: Design Patterns > Cognition > Scarcity > Limited Choice

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Limited-choice
- Page title: Limited Choice design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 49 words on source page
- Usage: 32 words on source page
- Solution: 138 words on source page
- Rationale: 190 words on source page

## Source Navigation

- Previous source navigation: Goal-Gradient Effect
- Next source navigation: Tailoring


<!-- ===== ui-patterns/wiki/concepts/patterns/limited-duration.md ===== -->

---
title: "Limited duration"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Limited-duration"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Limited-duration"
source_slug: "Limited-duration"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Scarcity"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Limited duration

> Catalog pointer for the UI Patterns source page: [Limited duration](https://ui-patterns.com/patterns/Limited-duration).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Scarcity
- Source breadcrumb: Design Patterns > Cognition > Scarcity > Limited duration

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Limited-duration
- Page title: Limited duration design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 9 words on source page
- Example: 80 words on source page
- Usage: 45 words on source page
- Solution: 115 words on source page
- Rationale: 80 words on source page

## Source Navigation

- Previous source navigation: Variable Rewards
- Next source navigation: Self-Expression


<!-- ===== ui-patterns/wiki/concepts/patterns/loss-aversion.md ===== -->

---
title: "Loss Aversion"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Loss-aversion"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Loss-aversion"
source_slug: "Loss-aversion"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Thaler’s 4 principles"
  - "How to apply loss aversion to your product"
  - "Rationale"
  - "Example: Discounts and trial periods"
  - "Discussion"
  - "Example: Lazy registration"
  - "Background"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Loss Aversion

> Catalog pointer for the UI Patterns source page: [Loss Aversion](https://ui-patterns.com/patterns/Loss-aversion).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Loss Aversion

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Loss-aversion
- Page title: Loss Aversion design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Thaler’s 4 principles, How to apply loss aversion to your product, Rationale, Example: Discounts and trial periods, Discussion, Example: Lazy registration, Background
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 72 words on source page
- Usage: 33 words on source page
- Solution: 586 words on source page
- Thaler’s 4 principles: 282 words on source page
- How to apply loss aversion to your product: 177 words on source page
- Rationale: 360 words on source page
- Example: Discounts and trial periods: 122 words on source page
- Discussion: 347 words on source page
- Example: Lazy registration: 117 words on source page
- Background: 68 words on source page

## Source Navigation

- Previous source navigation: Storytelling
- Next source navigation: Peak-end rule


<!-- ===== ui-patterns/wiki/concepts/patterns/modal.md ===== -->

---
title: "Modal"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/modal-windows"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/modal-windows"
source_slug: "modal-windows"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Matching titles"
  - "Allow escape"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Modal

> Catalog pointer for the UI Patterns source page: [Modal](https://ui-patterns.com/patterns/modal-windows).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Modal

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/modal-windows
- Page title: Modal design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Matching titles, Allow escape, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 46 words on source page
- Usage: 32 words on source page
- Solution: 151 words on source page
- Matching titles: 48 words on source page
- Allow escape: 65 words on source page
- Rationale: 35 words on source page
- Discussion: 142 words on source page

## Source Navigation

- Previous source navigation: Undo
- Next source navigation: Cognitive Dissonance


<!-- ===== ui-patterns/wiki/concepts/patterns/module-tabs.md ===== -->

---
title: "Module Tabs"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ModuleTabs"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ModuleTabs"
source_slug: "ModuleTabs"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Tabs"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 9
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Module Tabs

> Catalog pointer for the UI Patterns source page: [Module Tabs](https://ui-patterns.com/patterns/ModuleTabs).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Tabs
- Source breadcrumb: Design Patterns > Navigation > Tabs > Module Tabs

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ModuleTabs
- Page title: Module Tabs design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 9
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 27 words on source page
- Example: 113 words on source page
- Usage: 112 words on source page
- Solution: 138 words on source page
- Rationale: 88 words on source page

## Source Navigation

- Next source navigation: Navigation Tabs


<!-- ===== ui-patterns/wiki/concepts/patterns/morphing-controls.md ===== -->

---
title: "Morphing Controls"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/morphing-controls"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/morphing-controls"
source_slug: "morphing-controls"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Morphing Controls

> Catalog pointer for the UI Patterns source page: [Morphing Controls](https://ui-patterns.com/patterns/morphing-controls).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Morphing Controls

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/morphing-controls
- Page title: Morphing Controls design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 69 words on source page
- Usage: 39 words on source page
- Solution: 98 words on source page

## Source Navigation

- Previous source navigation: Inline Hints
- Next source navigation: Categorization


<!-- ===== ui-patterns/wiki/concepts/patterns/navigation-tabs.md ===== -->

---
title: "Navigation Tabs"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/NavigationTabs"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/NavigationTabs"
source_slug: "NavigationTabs"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Tabs"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Navigation Tabs

> Catalog pointer for the UI Patterns source page: [Navigation Tabs](https://ui-patterns.com/patterns/NavigationTabs).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Tabs
- Source breadcrumb: Design Patterns > Navigation > Tabs > Navigation Tabs

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/NavigationTabs
- Page title: Navigation Tabs design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 106 words on source page
- Usage: 105 words on source page
- Solution: 148 words on source page
- Rationale: 77 words on source page

## Source Navigation

- Previous source navigation: Module Tabs
- Next source navigation: Breadcrumbs


<!-- ===== ui-patterns/wiki/concepts/patterns/need-for-closure.md ===== -->

---
title: "Need for Closure"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Need-for-closure"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Need-for-closure"
source_slug: "Need-for-closure"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Need for Closure

> Catalog pointer for the UI Patterns source page: [Need for Closure](https://ui-patterns.com/patterns/Need-for-closure).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Need for Closure

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Need-for-closure
- Page title: Need for Closure design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 57 words on source page
- Usage: 43 words on source page
- Solution: 137 words on source page
- Rationale: 142 words on source page
- Discussion: 258 words on source page

## Source Navigation

- Previous source navigation: Peak-end rule
- Next source navigation: Kairos


<!-- ===== ui-patterns/wiki/concepts/patterns/negativity-bias.md ===== -->

---
title: "Negativity bias"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Negativity-bias"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Negativity-bias"
source_slug: "Negativity-bias"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Negativity bias

> Catalog pointer for the UI Patterns source page: [Negativity bias](https://ui-patterns.com/patterns/Negativity-bias).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Negativity bias

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Negativity-bias
- Page title: Negativity bias design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 46 words on source page
- Usage: 23 words on source page
- Solution: 233 words on source page
- Rationale: 132 words on source page
- Discussion: 169 words on source page

## Source Navigation

- Previous source navigation: Peak-end rule
- Next source navigation: Kairos


<!-- ===== ui-patterns/wiki/concepts/patterns/noble-edge-effect.md ===== -->

---
title: "Noble Edge Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/noble-edge-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/noble-edge-effect"
source_slug: "noble-edge-effect"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Noble Edge Effect

> Catalog pointer for the UI Patterns source page: [Noble Edge Effect](https://ui-patterns.com/patterns/noble-edge-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Noble Edge Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/noble-edge-effect
- Page title: Noble Edge Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 39 words on source page
- Usage: 29 words on source page
- Solution: 110 words on source page
- Rationale: 172 words on source page

## Source Navigation

- Previous source navigation: Temptation Bundling
- Next source navigation: Hedonic Adaptation


<!-- ===== ui-patterns/wiki/concepts/patterns/nostalgia-effect.md ===== -->

---
title: "Nostalgia Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/nostalgia-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/nostalgia-effect"
source_slug: "nostalgia-effect"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Nostalgia Effect

> Catalog pointer for the UI Patterns source page: [Nostalgia Effect](https://ui-patterns.com/patterns/nostalgia-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Nostalgia Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/nostalgia-effect
- Page title: Nostalgia Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 30 words on source page
- Usage: 21 words on source page
- Solution: 116 words on source page
- Rationale: 59 words on source page
- Discussion: 148 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/notifications.md ===== -->

---
title: "Notifications"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/notifications"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/notifications"
source_slug: "notifications"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Across devices"
  - "Minimize interruption"
  - "Allow escape"
  - "Provide summaries"
  - "Provide actions"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Notifications

> Catalog pointer for the UI Patterns source page: [Notifications](https://ui-patterns.com/patterns/notifications).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Notifications

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/notifications
- Page title: Notifications design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Across devices, Minimize interruption, Allow escape, Provide summaries, Provide actions
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 79 words on source page
- Usage: 70 words on source page
- Solution: 324 words on source page
- Across devices: 50 words on source page
- Minimize interruption: 63 words on source page
- Allow escape: 17 words on source page
- Provide summaries: 35 words on source page
- Provide actions: 59 words on source page

## Source Navigation

- Previous source navigation: Paywall
- Next source navigation: Auto-sharing


<!-- ===== ui-patterns/wiki/concepts/patterns/optimism-bias.md ===== -->

---
title: "Optimism Bias"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/optimism-bias"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/optimism-bias"
source_slug: "optimism-bias"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Optimism Bias

> Catalog pointer for the UI Patterns source page: [Optimism Bias](https://ui-patterns.com/patterns/optimism-bias).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Optimism Bias

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/optimism-bias
- Page title: Optimism Bias design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 40 words on source page
- Usage: 30 words on source page
- Solution: 95 words on source page
- Rationale: 180 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/pagination.md ===== -->

---
title: "Pagination"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Pagination"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Pagination"
source_slug: "Pagination"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Pagination

> Catalog pointer for the UI Patterns source page: [Pagination](https://ui-patterns.com/patterns/Pagination).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Pagination

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Pagination
- Page title: Pagination design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 49 words on source page
- Usage: 42 words on source page
- Solution: 86 words on source page
- Rationale: 159 words on source page

## Source Navigation

- Previous source navigation: Blank Slate
- Next source navigation: Archive


<!-- ===== ui-patterns/wiki/concepts/patterns/password-strength-meter.md ===== -->

---
title: "Password Strength Meter"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/PasswordStrengthMeter"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/PasswordStrengthMeter"
source_slug: "PasswordStrengthMeter"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "How strong a password?"
  - "What is a strong password?"
  - "Dictionary attacks"
  - "Choosing an appropriate level of password strength"
  - "General guidelines on choosing a password"
  - "Rationale"
example_count: 6
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Password Strength Meter

> Catalog pointer for the UI Patterns source page: [Password Strength Meter](https://ui-patterns.com/patterns/PasswordStrengthMeter).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Password Strength Meter

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/PasswordStrengthMeter
- Page title: Password Strength Meter design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, How strong a password?, What is a strong password?, Dictionary attacks, Choosing an appropriate level of password strength, General guidelines on choosing a password, Rationale
- Example screenshots detected at source: 6
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 73 words on source page
- Usage: 72 words on source page
- Solution: 619 words on source page
- How strong a password?: 107 words on source page
- What is a strong password?: 114 words on source page
- Dictionary attacks: 101 words on source page
- Choosing an appropriate level of password strength: 48 words on source page
- General guidelines on choosing a password: 143 words on source page
- Rationale: 105 words on source page

## Source Navigation

- Previous source navigation: Inline Help Box
- Next source navigation: Lazy Registration


<!-- ===== ui-patterns/wiki/concepts/patterns/pattern-recognition.md ===== -->

---
title: "Pattern Recognition"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Pattern-recognition"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Pattern-recognition"
source_slug: "Pattern-recognition"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Pattern Recognition

> Catalog pointer for the UI Patterns source page: [Pattern Recognition](https://ui-patterns.com/patterns/Pattern-recognition).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Pattern Recognition

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Pattern-recognition
- Page title: Pattern Recognition design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 32 words on source page
- Usage: 16 words on source page
- Solution: 160 words on source page
- Rationale: 141 words on source page

## Source Navigation

- Previous source navigation: Tunnelling
- Next source navigation: Serial Positioning Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/pay-to-promote.md ===== -->

---
title: "Pay To Promote"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/pay-to-promote"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/pay-to-promote"
source_slug: "pay-to-promote"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Community driven"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Discussion"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Pay To Promote

> Catalog pointer for the UI Patterns source page: [Pay To Promote](https://ui-patterns.com/patterns/pay-to-promote).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Community driven
- Source breadcrumb: Design Patterns > Getting input > Community driven > Pay To Promote

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/pay-to-promote
- Page title: Pay To Promote design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Discussion
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 59 words on source page
- Usage: 42 words on source page
- Solution: 114 words on source page
- Discussion: 41 words on source page

## Source Navigation

- Previous source navigation: Testimonials
- Next source navigation: Invite friends


<!-- ===== ui-patterns/wiki/concepts/patterns/paywall.md ===== -->

---
title: "Paywall"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Paywall"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Paywall"
source_slug: "Paywall"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Registration"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Strategies"
  - "Payment doesn’t have to be monetary"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Paywall

> Catalog pointer for the UI Patterns source page: [Paywall](https://ui-patterns.com/patterns/Paywall).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Registration
- Source breadcrumb: Design Patterns > Onboarding > Registration > Paywall

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Paywall
- Page title: Paywall design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Strategies, Payment doesn’t have to be monetary, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 103 words on source page
- Usage: 75 words on source page
- Solution: 416 words on source page
- Strategies: 119 words on source page
- Payment doesn’t have to be monetary: 225 words on source page
- Rationale: 55 words on source page

## Source Navigation

- Previous source navigation: Slideshow
- Next source navigation: Leaderboard


<!-- ===== ui-patterns/wiki/concepts/patterns/peak-end-rule.md ===== -->

---
title: "Peak-end rule"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Peakend-rule"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Peakend-rule"
source_slug: "Peakend-rule"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Why the peak is memorable"
  - "Why the end is memorable"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Peak-end rule

> Catalog pointer for the UI Patterns source page: [Peak-end rule](https://ui-patterns.com/patterns/Peakend-rule).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Peak-end rule

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Peakend-rule
- Page title: Peak-end rule design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Why the peak is memorable, Why the end is memorable
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 30 words on source page
- Usage: 29 words on source page
- Solution: 246 words on source page
- Rationale: 426 words on source page
- Discussion: 381 words on source page
- Why the peak is memorable: 43 words on source page
- Why the end is memorable: 57 words on source page

## Source Navigation

- Previous source navigation: Scarcity
- Next source navigation: Social Proof


<!-- ===== ui-patterns/wiki/concepts/patterns/periodic-events.md ===== -->

---
title: "Periodic Events"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/periodic-events"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/periodic-events"
source_slug: "periodic-events"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Periodic Events

> Catalog pointer for the UI Patterns source page: [Periodic Events](https://ui-patterns.com/patterns/periodic-events).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Periodic Events

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/periodic-events
- Page title: Periodic Events design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 31 words on source page
- Usage: 14 words on source page
- Solution: 136 words on source page
- Rationale: 134 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/picture-superiority-effect.md ===== -->

---
title: "Picture Superiority Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/picture-superiority-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/picture-superiority-effect"
source_slug: "picture-superiority-effect"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Attention"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Picture Superiority Effect

> Catalog pointer for the UI Patterns source page: [Picture Superiority Effect](https://ui-patterns.com/patterns/picture-superiority-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Attention
- Source breadcrumb: Design Patterns > Perception and memory > Attention > Picture Superiority Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/picture-superiority-effect
- Page title: Picture Superiority Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 25 words on source page
- Solution: 104 words on source page
- Rationale: 197 words on source page

## Source Navigation

- Previous source navigation: Temptation Bundling
- Next source navigation: Hedonic Adaptation


<!-- ===== ui-patterns/wiki/concepts/patterns/playthrough.md ===== -->

---
title: "Playthrough"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/playthrough"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/playthrough"
source_slug: "playthrough"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Let users learn through real tasks"
  - "Continue the experience seamlessly into the full product"
  - "Provide a skip option"
  - "Don’t drag it out"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Playthrough

> Catalog pointer for the UI Patterns source page: [Playthrough](https://ui-patterns.com/patterns/playthrough).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Playthrough

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/playthrough
- Page title: Playthrough design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Let users learn through real tasks, Continue the experience seamlessly into the full product, Provide a skip option, Don’t drag it out, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 202 words on source page
- Usage: 165 words on source page
- Solution: 291 words on source page
- Let users learn through real tasks: 38 words on source page
- Continue the experience seamlessly into the full product: 30 words on source page
- Provide a skip option: 20 words on source page
- Don’t drag it out: 45 words on source page
- Rationale: 68 words on source page

## Source Navigation

- Previous source navigation: Cognitive Dissonance
- Next source navigation: Drag and drop


<!-- ===== ui-patterns/wiki/concepts/patterns/positive-mimicry.md ===== -->

---
title: "Positive Mimicry"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Positive-mimicry"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Positive-mimicry"
source_slug: "Positive-mimicry"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Powerful Pairings"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Positive Mimicry

> Catalog pointer for the UI Patterns source page: [Positive Mimicry](https://ui-patterns.com/patterns/Positive-mimicry).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Positive Mimicry

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Positive-mimicry
- Page title: Positive Mimicry design pattern
- Section headings available at source: Problem summary, Usage, Solution, Powerful Pairings, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 35 words on source page
- Usage: 23 words on source page
- Solution: 696 words on source page
- Powerful Pairings: 204 words on source page
- Rationale: 176 words on source page
- Discussion: 508 words on source page

## Source Navigation

- Previous source navigation: Variable Rewards
- Next source navigation: Self-Expression


<!-- ===== ui-patterns/wiki/concepts/patterns/praise.md ===== -->

---
title: "Praise"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Praise"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Praise"
source_slug: "Praise"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Praise

> Catalog pointer for the UI Patterns source page: [Praise](https://ui-patterns.com/patterns/Praise).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Praise

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Praise
- Page title: Praise design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 66 words on source page
- Usage: 45 words on source page
- Solution: 170 words on source page
- Rationale: 32 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/present-bias.md ===== -->

---
title: "Present Bias"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/present-bias"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/present-bias"
source_slug: "present-bias"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Present Bias

> Catalog pointer for the UI Patterns source page: [Present Bias](https://ui-patterns.com/patterns/present-bias).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Present Bias

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/present-bias
- Page title: Present Bias design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 47 words on source page
- Usage: 33 words on source page
- Solution: 104 words on source page
- Rationale: 208 words on source page

## Source Navigation

- Previous source navigation: Temptation Bundling
- Next source navigation: Hedonic Adaptation


<!-- ===== ui-patterns/wiki/concepts/patterns/preview.md ===== -->

---
title: "Preview"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/LivePreview"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/LivePreview"
source_slug: "LivePreview"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Preview

> Catalog pointer for the UI Patterns source page: [Preview](https://ui-patterns.com/patterns/LivePreview).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Preview

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/LivePreview
- Page title: Preview design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 62 words on source page
- Usage: 61 words on source page
- Solution: 58 words on source page
- Rationale: 81 words on source page

## Source Navigation

- Previous source navigation: Wiki
- Next source navigation: Tagging


<!-- ===== ui-patterns/wiki/concepts/patterns/pricing-table.md ===== -->

---
title: "Pricing table"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/PricingTable"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/PricingTable"
source_slug: "PricingTable"
track: "User Interface Design Patterns"
group: "Miscellaneous"
subgroup: "Shopping"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Apply hooks"
  - "Highlight why users should pay for your product"
  - "First one free"
  - "Order plans by descending price"
  - "Add decoys"
  - "The Goldilocks effect: We are aversive toward extremes"
  - "Let people know what they’re missing"
  - "Showcase differences with extremes"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Pricing table

> Catalog pointer for the UI Patterns source page: [Pricing table](https://ui-patterns.com/patterns/PricingTable).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Miscellaneous
- Subgroup: Shopping
- Source breadcrumb: Design Patterns > Miscellaneous > Shopping > Pricing table

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/PricingTable
- Page title: Pricing table design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Apply hooks, Highlight why users should pay for your product, First one free, Order plans by descending price, Add decoys, The Goldilocks effect: We are aversive toward extremes, Let people know what they’re missing, Showcase differences with extremes
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 83 words on source page
- Usage: 82 words on source page
- Solution: 233 words on source page
- Rationale: 33 words on source page
- Discussion: 840 words on source page
- Apply hooks: 308 words on source page
- Highlight why users should pay for your product: 59 words on source page
- First one free: 61 words on source page
- Order plans by descending price: 95 words on source page
- Add decoys: 30 words on source page
- The Goldilocks effect: We are aversive toward extremes: 102 words on source page
- Let people know what they’re missing: 34 words on source page
- Showcase differences with extremes: 42 words on source page

## Source Navigation

- Previous source navigation: Competition
- Next source navigation: Product page


<!-- ===== ui-patterns/wiki/concepts/patterns/priming-effect.md ===== -->

---
title: "Priming Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/priming-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/priming-effect"
source_slug: "priming-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Priming Effect

> Catalog pointer for the UI Patterns source page: [Priming Effect](https://ui-patterns.com/patterns/priming-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Priming Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/priming-effect
- Page title: Priming Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 38 words on source page
- Usage: 27 words on source page
- Solution: 61 words on source page
- Rationale: 59 words on source page
- Discussion: 259 words on source page

## Source Navigation

- Previous source navigation: Appointment Dynamic
- Next source navigation: Fresh Start Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/privileges.md ===== -->

---
title: "Privileges"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Powers"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Powers"
source_slug: "Powers"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Reward the contributor and curator roles"
  - "Grant roles"
  - "Instil a sense of self-determination"
  - "Common powers given to users"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Privileges

> Catalog pointer for the UI Patterns source page: [Privileges](https://ui-patterns.com/patterns/Powers).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Privileges

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Powers
- Page title: Privileges design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Reward the contributor and curator roles, Grant roles, Instil a sense of self-determination, Common powers given to users, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 64 words on source page
- Usage: 35 words on source page
- Solution: 370 words on source page
- Reward the contributor and curator roles: 124 words on source page
- Grant roles: 36 words on source page
- Instil a sense of self-determination: 60 words on source page
- Common powers given to users: 74 words on source page
- Rationale: 161 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/product-page.md ===== -->

---
title: "Product page"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ProductPage"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ProductPage"
source_slug: "ProductPage"
track: "User Interface Design Patterns"
group: "Miscellaneous"
subgroup: "Shopping"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Product page

> Catalog pointer for the UI Patterns source page: [Product page](https://ui-patterns.com/patterns/ProductPage).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Miscellaneous
- Subgroup: Shopping
- Source breadcrumb: Design Patterns > Miscellaneous > Shopping > Product page

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ProductPage
- Page title: Product page design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 64 words on source page
- Usage: 35 words on source page
- Solution: 155 words on source page
- Rationale: 31 words on source page
- Discussion: 452 words on source page

## Source Navigation

- Previous source navigation: Pricing table
- Next source navigation: Liking


<!-- ===== ui-patterns/wiki/concepts/patterns/progressive-disclosure.md ===== -->

---
title: "Progressive Disclosure"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ProgressiveDisclosure"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ProgressiveDisclosure"
source_slug: "ProgressiveDisclosure"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Progressive Disclosure

> Catalog pointer for the UI Patterns source page: [Progressive Disclosure](https://ui-patterns.com/patterns/ProgressiveDisclosure).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Progressive Disclosure

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ProgressiveDisclosure
- Page title: Progressive Disclosure design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 27 words on source page
- Example: 54 words on source page
- Usage: 10 words on source page
- Solution: 62 words on source page
- Rationale: 227 words on source page

## Source Navigation

- Previous source navigation: Collectible Achievements
- Next source navigation: Activity Stream


<!-- ===== ui-patterns/wiki/concepts/patterns/prolonged-play.md ===== -->

---
title: "Prolonged Play"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Prolonged-play"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Prolonged-play"
source_slug: "Prolonged-play"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Examples"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Prolonged Play

> Catalog pointer for the UI Patterns source page: [Prolonged Play](https://ui-patterns.com/patterns/Prolonged-play).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Prolonged Play

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Prolonged-play
- Page title: Prolonged Play design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Examples, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 36 words on source page
- Usage: 12 words on source page
- Solution: 443 words on source page
- Examples: 136 words on source page
- Rationale: 134 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/pull-to-refresh.md ===== -->

---
title: "Pull to refresh"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/pull-to-refresh"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/pull-to-refresh"
source_slug: "pull-to-refresh"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Gestures"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Immediate visual feedback after the action"
  - "Refresh indicator should only be triggered by user action"
  - "Meaningful state transitions"
  - "Rationale"
  - "Why should we use pull to refresh?"
  - "Discussion"
  - "Visible “refresh” button vs Hidden pull-to-refresh gesture"
  - "When you should use visible “Refresh” button or auto-update instead of Pull-to-refresh"
  - "Thumb-reach issue on iPad"
  - "Augmented Pull-to-refresh"
example_count: 11
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Pull to refresh

> Catalog pointer for the UI Patterns source page: [Pull to refresh](https://ui-patterns.com/patterns/pull-to-refresh).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Gestures
- Source breadcrumb: Design Patterns > Navigation > Gestures > Pull to refresh

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/pull-to-refresh
- Page title: Pull to refresh design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Immediate visual feedback after the action, Refresh indicator should only be triggered by user action, Meaningful state transitions, Rationale, Why should we use pull to refresh?, Discussion, Visible “refresh” button vs Hidden pull-to-refresh gesture, When you should use visible “Refresh” button or auto-update instead of Pull-to-refresh, Thumb-reach issue on iPad, Augmented Pull-to-refresh
- Example screenshots detected at source: 11
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 86 words on source page
- Usage: 63 words on source page
- Solution: 231 words on source page
- Immediate visual feedback after the action: 80 words on source page
- Refresh indicator should only be triggered by user action: 42 words on source page
- Meaningful state transitions: 47 words on source page
- Rationale: 263 words on source page
- Why should we use pull to refresh?: 256 words on source page
- Discussion: 561 words on source page
- Visible “refresh” button vs Hidden pull-to-refresh gesture: 75 words on source page
- When you should use visible “Refresh” button or auto-update instead of Pull-to-refresh: 199 words on source page
- Thumb-reach issue on iPad: 56 words on source page
- Augmented Pull-to-refresh: 121 words on source page

## Source Navigation

- Previous source navigation: Friend
- Next source navigation: Rule Builder


<!-- ===== ui-patterns/wiki/concepts/patterns/rate-content.md ===== -->

---
title: "Rate Content"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/RateContent"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/RateContent"
source_slug: "RateContent"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Community driven"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Rate Content

> Catalog pointer for the UI Patterns source page: [Rate Content](https://ui-patterns.com/patterns/RateContent).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Community driven
- Source breadcrumb: Design Patterns > Getting input > Community driven > Rate Content

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/RateContent
- Page title: Rate Content design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 160 words on source page
- Usage: 126 words on source page
- Solution: 362 words on source page
- Rationale: 63 words on source page
- Discussion: 436 words on source page

## Source Navigation

- Previous source navigation: Input Feedback
- Next source navigation: Image Zoom


<!-- ===== ui-patterns/wiki/concepts/patterns/reaction.md ===== -->

---
title: "Reaction"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/reaction"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/reaction"
source_slug: "reaction"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Social interactions"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Reaction

> Catalog pointer for the UI Patterns source page: [Reaction](https://ui-patterns.com/patterns/reaction).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Social interactions
- Source breadcrumb: Design Patterns > Social > Social interactions > Reaction

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/reaction
- Page title: Reaction design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 64 words on source page
- Usage: 42 words on source page
- Solution: 44 words on source page
- Rationale: 23 words on source page

## Source Navigation

- Previous source navigation: Frequently Asked Questions (FAQ)
- Next source navigation: Pull to refresh


<!-- ===== ui-patterns/wiki/concepts/patterns/reciprocation.md ===== -->

---
title: "Reciprocation"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Reciprocation"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Reciprocation"
source_slug: "Reciprocation"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Reciprocity Decay"
  - "Powerful Pairings"
  - "Ethical Recommendations"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Reciprocation

> Catalog pointer for the UI Patterns source page: [Reciprocation](https://ui-patterns.com/patterns/Reciprocation).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Reciprocation

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Reciprocation
- Page title: Reciprocation design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion, Reciprocity Decay, Powerful Pairings, Ethical Recommendations
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 8 words on source page
- Example: 43 words on source page
- Usage: 19 words on source page
- Solution: 129 words on source page
- Rationale: 93 words on source page
- Discussion: 1166 words on source page
- Reciprocity Decay: 112 words on source page
- Powerful Pairings: 280 words on source page
- Ethical Recommendations: 246 words on source page

## Source Navigation

- Previous source navigation: Simulation
- Next source navigation: Variable Rewards


<!-- ===== ui-patterns/wiki/concepts/patterns/recognition-over-recall.md ===== -->

---
title: "Recognition over Recall"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Recognition-over-recall"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Recognition-over-recall"
source_slug: "Recognition-over-recall"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Minimize need to recall"
  - "Rationale"
  - "Recognition vs Recall"
  - "Recognition doesn’t involve origin, context, or relevance"
example_count: 12
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Recognition over Recall

> Catalog pointer for the UI Patterns source page: [Recognition over Recall](https://ui-patterns.com/patterns/Recognition-over-recall).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Recognition over Recall

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Recognition-over-recall
- Page title: Recognition over Recall design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Minimize need to recall, Rationale, Recognition vs Recall, Recognition doesn’t involve origin, context, or relevance
- Example screenshots detected at source: 12
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 98 words on source page
- Usage: 78 words on source page
- Solution: 195 words on source page
- Minimize need to recall: 26 words on source page
- Rationale: 324 words on source page
- Recognition vs Recall: 96 words on source page
- Recognition doesn’t involve origin, context, or relevance: 78 words on source page

## Source Navigation

- Previous source navigation: Tunnelling
- Next source navigation: Serial Positioning Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/reduction.md ===== -->

---
title: "Reduction"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Reduction"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Reduction"
source_slug: "Reduction"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Attention"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Reduction implied to navigation."
  - "Reduction based on what other users did"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Reduction

> Catalog pointer for the UI Patterns source page: [Reduction](https://ui-patterns.com/patterns/Reduction).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Attention
- Source breadcrumb: Design Patterns > Perception and memory > Attention > Reduction

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Reduction
- Page title: Reduction design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Reduction implied to navigation., Reduction based on what other users did, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 88 words on source page
- Usage: 57 words on source page
- Solution: 355 words on source page
- Reduction implied to navigation.: 17 words on source page
- Reduction based on what other users did: 194 words on source page
- Rationale: 224 words on source page

## Source Navigation

- Previous source navigation: Limited Choice
- Next source navigation: Anchoring


<!-- ===== ui-patterns/wiki/concepts/patterns/reputation.md ===== -->

---
title: "Reputation"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/reputation"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/reputation"
source_slug: "reputation"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Using Aristotle’s triad of appeals to communicate Reputation"
  - "Getting a design that showcases reputation right"
  - "Powerful pairings"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Reputation

> Catalog pointer for the UI Patterns source page: [Reputation](https://ui-patterns.com/patterns/reputation).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Reputation

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/reputation
- Page title: Reputation design pattern
- Section headings available at source: Problem summary, Usage, Solution, Using Aristotle’s triad of appeals to communicate Reputation, Getting a design that showcases reputation right, Powerful pairings, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 104 words on source page
- Usage: 87 words on source page
- Solution: 1106 words on source page
- Using Aristotle’s triad of appeals to communicate Reputation: 290 words on source page
- Getting a design that showcases reputation right: 425 words on source page
- Powerful pairings: 148 words on source page
- Rationale: 115 words on source page
- Discussion: 419 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/retaliation.md ===== -->

---
title: "Retaliation"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/revenge"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/revenge"
source_slug: "revenge"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Powerful pairings"
  - "Ethical Recommendations"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Retaliation

> Catalog pointer for the UI Patterns source page: [Retaliation](https://ui-patterns.com/patterns/revenge).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Retaliation

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/revenge
- Page title: Retaliation design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion, Powerful pairings, Ethical Recommendations
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 65 words on source page
- Usage: 60 words on source page
- Solution: 103 words on source page
- Rationale: 291 words on source page
- Discussion: 1030 words on source page
- Powerful pairings: 207 words on source page
- Ethical Recommendations: 273 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/role-playing.md ===== -->

---
title: "Role Playing"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Roleplaying"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Roleplaying"
source_slug: "Roleplaying"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Role Playing

> Catalog pointer for the UI Patterns source page: [Role Playing](https://ui-patterns.com/patterns/Roleplaying).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Role Playing

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Roleplaying
- Page title: Role Playing design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 48 words on source page
- Usage: 41 words on source page
- Solution: 125 words on source page
- Rationale: 173 words on source page

## Source Navigation

- Previous source navigation: Event Calendar
- Next source navigation: Loss Aversion


<!-- ===== ui-patterns/wiki/concepts/patterns/rule-builder.md ===== -->

---
title: "Rule Builder"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/rule-builder"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/rule-builder"
source_slug: "rule-builder"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Any or all"
  - "Treat each rule type differently?"
  - "Adding and removing rules"
  - "Rationale"
  - "Discussion"
  - "Pattern authors"
example_count: 6
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Rule Builder

> Catalog pointer for the UI Patterns source page: [Rule Builder](https://ui-patterns.com/patterns/rule-builder).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Rule Builder

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/rule-builder
- Page title: Rule Builder design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Any or all, Treat each rule type differently?, Adding and removing rules, Rationale, Discussion, Pattern authors
- Example screenshots detected at source: 6
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 110 words on source page
- Usage: 85 words on source page
- Solution: 284 words on source page
- Any or all: 63 words on source page
- Treat each rule type differently?: 95 words on source page
- Adding and removing rules: 81 words on source page
- Rationale: 82 words on source page
- Discussion: 23 words on source page
- Pattern authors: 4 words on source page

## Source Navigation

- Previous source navigation: Pull to refresh
- Next source navigation: Halo Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/scarcity.md ===== -->

---
title: "Scarcity"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Scarcity"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Scarcity"
source_slug: "Scarcity"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Scarcity"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Time-based scarcity"
  - "Stock scarcity"
  - "Restrictions on information (or merely scarce)"
  - "Rationale"
  - "Our weakness for shortcuts"
  - "We hate to loose the freedoms we already have"
  - "Discussion"
  - "Optimal conditions for scarcity to work"
  - "Make a decision today or loose out forever"
  - "Origins of the term Scarcity"
example_count: 7
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Scarcity

> Catalog pointer for the UI Patterns source page: [Scarcity](https://ui-patterns.com/patterns/Scarcity).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Scarcity
- Source breadcrumb: Design Patterns > Cognition > Scarcity > Scarcity

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Scarcity
- Page title: Scarcity design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Time-based scarcity, Stock scarcity, Restrictions on information (or merely scarce), Rationale, Our weakness for shortcuts, We hate to loose the freedoms we already have, Discussion, Optimal conditions for scarcity to work, Make a decision today or loose out forever, Origins of the term Scarcity
- Example screenshots detected at source: 7
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 73 words on source page
- Usage: 63 words on source page
- Solution: 297 words on source page
- Time-based scarcity: 111 words on source page
- Stock scarcity: 92 words on source page
- Restrictions on information (or merely scarce): 76 words on source page
- Rationale: 257 words on source page
- Our weakness for shortcuts: 46 words on source page
- We hate to loose the freedoms we already have: 66 words on source page
- Discussion: 544 words on source page
- Optimal conditions for scarcity to work: 174 words on source page
- Make a decision today or loose out forever: 223 words on source page
- Origins of the term Scarcity: 45 words on source page

## Source Navigation

- Previous source navigation: Storytelling
- Next source navigation: Peak-end rule


<!-- ===== ui-patterns/wiki/concepts/patterns/search-filters.md ===== -->

---
title: "Search Filters"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/LiveFilter"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/LiveFilter"
source_slug: "LiveFilter"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Search"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 10
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Search Filters

> Catalog pointer for the UI Patterns source page: [Search Filters](https://ui-patterns.com/patterns/LiveFilter).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Search
- Source breadcrumb: Design Patterns > Dealing with data > Search > Search Filters

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/LiveFilter
- Page title: Search Filters design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 10
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 56 words on source page
- Usage: 45 words on source page
- Solution: 105 words on source page
- Rationale: 121 words on source page

## Source Navigation

- Previous source navigation: Archive
- Next source navigation: Wiki


<!-- ===== ui-patterns/wiki/concepts/patterns/self-expression.md ===== -->

---
title: "Self-Expression"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Self-expression"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Self-expression"
source_slug: "Self-expression"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Self-Expression

> Catalog pointer for the UI Patterns source page: [Self-Expression](https://ui-patterns.com/patterns/Self-expression).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Self-Expression

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Self-expression
- Page title: Self-Expression design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 29 words on source page
- Usage: 18 words on source page
- Solution: 191 words on source page
- Rationale: 194 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/self-monitoring.md ===== -->

---
title: "Self-Monitoring"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/self-monitoring"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/self-monitoring"
source_slug: "self-monitoring"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Self-Monitoring

> Catalog pointer for the UI Patterns source page: [Self-Monitoring](https://ui-patterns.com/patterns/self-monitoring).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Self-Monitoring

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/self-monitoring
- Page title: Self-Monitoring design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 28 words on source page
- Usage: 17 words on source page
- Solution: 102 words on source page
- Rationale: 66 words on source page
- Discussion: 147 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/sequencing.md ===== -->

---
title: "Sequencing"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Sequencing"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Sequencing"
source_slug: "Sequencing"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Sequencing

> Catalog pointer for the UI Patterns source page: [Sequencing](https://ui-patterns.com/patterns/Sequencing).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Sequencing

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Sequencing
- Page title: Sequencing design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 44 words on source page
- Usage: 33 words on source page
- Solution: 165 words on source page
- Rationale: 145 words on source page

## Source Navigation

- Previous source navigation: Pattern Recognition
- Next source navigation: Competition


<!-- ===== ui-patterns/wiki/concepts/patterns/serial-positioning-effect.md ===== -->

---
title: "Serial Positioning Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Serial-positioning-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Serial-positioning-effect"
source_slug: "Serial-positioning-effect"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Comprehension"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Serial Positioning Effect

> Catalog pointer for the UI Patterns source page: [Serial Positioning Effect](https://ui-patterns.com/patterns/Serial-positioning-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Comprehension
- Source breadcrumb: Design Patterns > Perception and memory > Comprehension > Serial Positioning Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Serial-positioning-effect
- Page title: Serial Positioning Effect design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 16 words on source page
- Example: 53 words on source page
- Usage: 30 words on source page
- Solution: 266 words on source page
- Rationale: 170 words on source page
- Discussion: 166 words on source page

## Source Navigation

- Previous source navigation: Pattern Recognition
- Next source navigation: Competition


<!-- ===== ui-patterns/wiki/concepts/patterns/set-completion.md ===== -->

---
title: "Set Completion"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/set-completion"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/set-completion"
source_slug: "set-completion"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Set Completion

> Catalog pointer for the UI Patterns source page: [Set Completion](https://ui-patterns.com/patterns/set-completion).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Set Completion

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/set-completion
- Page title: Set Completion design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 53 words on source page
- Usage: 36 words on source page
- Solution: 98 words on source page
- Rationale: 225 words on source page

## Source Navigation

- Previous source navigation: Cards
- Next source navigation: Delighters


<!-- ===== ui-patterns/wiki/concepts/patterns/settings.md ===== -->

---
title: "Settings"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/settings"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/settings"
source_slug: "settings"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Provide an overview"
  - "Good Defaults"
  - "When to group"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Settings

> Catalog pointer for the UI Patterns source page: [Settings](https://ui-patterns.com/patterns/settings).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Settings

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/settings
- Page title: Settings design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Provide an overview, Good Defaults, When to group
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Example: 83 words on source page
- Usage: 64 words on source page
- Solution: 193 words on source page
- Provide an overview: 39 words on source page
- Good Defaults: 20 words on source page
- When to group: 69 words on source page

## Source Navigation

- Previous source navigation: Flagging & Reporting
- Next source navigation: Morphing Controls


<!-- ===== ui-patterns/wiki/concepts/patterns/shaping.md ===== -->

---
title: "Shaping"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/shaping"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/shaping"
source_slug: "shaping"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Fundamentals of rewards"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Shaping

> Catalog pointer for the UI Patterns source page: [Shaping](https://ui-patterns.com/patterns/shaping).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Fundamentals of rewards
- Source breadcrumb: Design Patterns > Game mechanics > Fundamentals of rewards > Shaping

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/shaping
- Page title: Shaping design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 33 words on source page
- Usage: 25 words on source page
- Solution: 127 words on source page
- Rationale: 160 words on source page

## Source Navigation

- Previous source navigation: Temptation Bundling
- Next source navigation: Hedonic Adaptation


<!-- ===== ui-patterns/wiki/concepts/patterns/shopping-cart.md ===== -->

---
title: "Shopping Cart"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ShoppingCart"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ShoppingCart"
source_slug: "ShoppingCart"
track: "User Interface Design Patterns"
group: "Miscellaneous"
subgroup: "Shopping"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Shopping Cart

> Catalog pointer for the UI Patterns source page: [Shopping Cart](https://ui-patterns.com/patterns/ShoppingCart).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Miscellaneous
- Subgroup: Shopping
- Source breadcrumb: Design Patterns > Miscellaneous > Shopping > Shopping Cart

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ShoppingCart
- Page title: Shopping Cart design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 13 words on source page
- Example: 109 words on source page
- Usage: 108 words on source page
- Solution: 166 words on source page
- Rationale: 103 words on source page

## Source Navigation

- Previous source navigation: Table Filter
- Next source navigation: Coupon


<!-- ===== ui-patterns/wiki/concepts/patterns/shortcut-dropdown.md ===== -->

---
title: "Shortcut Dropdown"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/ShortcutDropdown"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/ShortcutDropdown"
source_slug: "ShortcutDropdown"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Jumping in hierarchy"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Shortcut Dropdown

> Catalog pointer for the UI Patterns source page: [Shortcut Dropdown](https://ui-patterns.com/patterns/ShortcutDropdown).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Jumping in hierarchy
- Source breadcrumb: Design Patterns > Navigation > Jumping in hierarchy > Shortcut Dropdown

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/ShortcutDropdown
- Page title: Shortcut Dropdown design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 79 words on source page
- Usage: 78 words on source page
- Solution: 62 words on source page
- Rationale: 55 words on source page

## Source Navigation

- Previous source navigation: Breadcrumbs
- Next source navigation: Home Link


<!-- ===== ui-patterns/wiki/concepts/patterns/simulation.md ===== -->

---
title: "Simulation"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Simulation"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Simulation"
source_slug: "Simulation"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Simulation

> Catalog pointer for the UI Patterns source page: [Simulation](https://ui-patterns.com/patterns/Simulation).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Simulation

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Simulation
- Page title: Simulation design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 46 words on source page
- Usage: 34 words on source page
- Solution: 115 words on source page
- Rationale: 157 words on source page

## Source Navigation

- Previous source navigation: Negativity bias
- Next source navigation: Reciprocation


<!-- ===== ui-patterns/wiki/concepts/patterns/slideshow.md ===== -->

---
title: "Slideshow"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Slideshow"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Slideshow"
source_slug: "Slideshow"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Images"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Transitions"
  - "Numbers, bullets, or thumbnails"
  - "Focus attention"
  - "Buttons and good callout texts"
  - "Navigation"
  - "Full image or tabs with title"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Slideshow

> Catalog pointer for the UI Patterns source page: [Slideshow](https://ui-patterns.com/patterns/Slideshow).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Images
- Source breadcrumb: Design Patterns > Dealing with data > Images > Slideshow

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Slideshow
- Page title: Slideshow design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Transitions, Numbers, bullets, or thumbnails, Focus attention, Buttons and good callout texts, Navigation, Full image or tabs with title, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 97 words on source page
- Usage: 91 words on source page
- Solution: 564 words on source page
- Transitions: 51 words on source page
- Numbers, bullets, or thumbnails: 94 words on source page
- Focus attention: 107 words on source page
- Buttons and good callout texts: 83 words on source page
- Navigation: 69 words on source page
- Full image or tabs with title: 114 words on source page
- Rationale: 71 words on source page

## Source Navigation

- Previous source navigation: Gallery
- Next source navigation: Paywall


<!-- ===== ui-patterns/wiki/concepts/patterns/social-proof.md ===== -->

---
title: "Social Proof"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Social-proof"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Social-proof"
source_slug: "Social-proof"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "6 ways to use Social Proof"
  - "Appeal to logic, emotions, and to ethical character"
  - "Rationale"
  - "Related studies"
  - "Discussion"
  - "Getting social proof right"
  - "Keeping a balance: social proof boosters and killers"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Social Proof

> Catalog pointer for the UI Patterns source page: [Social Proof](https://ui-patterns.com/patterns/Social-proof).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Social Proof

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Social-proof
- Page title: Social Proof design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, 6 ways to use Social Proof, Appeal to logic, emotions, and to ethical character, Rationale, Related studies, Discussion, Getting social proof right, Keeping a balance: social proof boosters and killers
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 53 words on source page
- Usage: 52 words on source page
- Solution: 553 words on source page
- 6 ways to use Social Proof: 123 words on source page
- Appeal to logic, emotions, and to ethical character: 350 words on source page
- Rationale: 315 words on source page
- Related studies: 86 words on source page
- Discussion: 469 words on source page
- Getting social proof right: 199 words on source page
- Keeping a balance: social proof boosters and killers: 133 words on source page

## Source Navigation

- Previous source navigation: Peak-end rule
- Next source navigation: Kairos


<!-- ===== ui-patterns/wiki/concepts/patterns/sort-by-column.md ===== -->

---
title: "Sort By Column"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/SortByColumn"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/SortByColumn"
source_slug: "SortByColumn"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Tables"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Sort By Column

> Catalog pointer for the UI Patterns source page: [Sort By Column](https://ui-patterns.com/patterns/SortByColumn).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Tables
- Source breadcrumb: Design Patterns > Dealing with data > Tables > Sort By Column

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/SortByColumn
- Page title: Sort By Column design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 72 words on source page
- Usage: 71 words on source page
- Solution: 112 words on source page
- Rationale: 39 words on source page

## Source Navigation

- Previous source navigation: Inplace Editor
- Next source navigation: Alternating Row Colors


<!-- ===== ui-patterns/wiki/concepts/patterns/status-quo-bias.md ===== -->

---
title: "Status-Quo Bias"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Statusquo-bias"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Statusquo-bias"
source_slug: "Statusquo-bias"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Apply the status-quo bias"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Status-Quo Bias

> Catalog pointer for the UI Patterns source page: [Status-Quo Bias](https://ui-patterns.com/patterns/Statusquo-bias).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Status-Quo Bias

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Statusquo-bias
- Page title: Status-Quo Bias design pattern
- Section headings available at source: Problem summary, Usage, Solution, Apply the status-quo bias, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 50 words on source page
- Usage: 32 words on source page
- Solution: 388 words on source page
- Apply the status-quo bias: 150 words on source page
- Rationale: 159 words on source page
- Discussion: 308 words on source page

## Source Navigation

- Previous source navigation: Storytelling
- Next source navigation: Peak-end rule


<!-- ===== ui-patterns/wiki/concepts/patterns/status.md ===== -->

---
title: "Status"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Status"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Status"
source_slug: "Status"
track: "Persuasive Design Patterns"
group: "Social"
subgroup: "Social biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Status

> Catalog pointer for the UI Patterns source page: [Status](https://ui-patterns.com/patterns/Status).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Social
- Subgroup: Social biases
- Source breadcrumb: Design Patterns > Social > Social biases > Status

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Status
- Page title: Status design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 32 words on source page
- Usage: 17 words on source page
- Solution: 194 words on source page
- Rationale: 118 words on source page

## Source Navigation

- Previous source navigation: Goal-Gradient Effect
- Next source navigation: Tailoring


<!-- ===== ui-patterns/wiki/concepts/patterns/steps-left.md ===== -->

---
title: "Steps Left"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/StepsLeft"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/StepsLeft"
source_slug: "StepsLeft"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Explaining the process"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Steps Left

> Catalog pointer for the UI Patterns source page: [Steps Left](https://ui-patterns.com/patterns/StepsLeft).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Explaining the process
- Source breadcrumb: Design Patterns > Getting input > Explaining the process > Steps Left

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/StepsLeft
- Page title: Steps Left design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 96 words on source page
- Usage: 79 words on source page
- Solution: 70 words on source page
- Rationale: 137 words on source page

## Source Navigation

- Previous source navigation: Shopping Cart
- Next source navigation: Continuous Scrolling


<!-- ===== ui-patterns/wiki/concepts/patterns/storytelling.md ===== -->

---
title: "Storytelling"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Storytelling"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Storytelling"
source_slug: "Storytelling"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay design"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Aristotle’s Poetics"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Storytelling

> Catalog pointer for the UI Patterns source page: [Storytelling](https://ui-patterns.com/patterns/Storytelling).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay design
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay design > Storytelling

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Storytelling
- Page title: Storytelling design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion, Aristotle’s Poetics
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 15 words on source page
- Solution: 156 words on source page
- Rationale: 70 words on source page
- Discussion: 718 words on source page
- Aristotle’s Poetics: 575 words on source page

## Source Navigation

- Previous source navigation: Event Calendar
- Next source navigation: Loss Aversion


<!-- ===== ui-patterns/wiki/concepts/patterns/structured-format.md ===== -->

---
title: "Structured Format"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/StructuredFormat"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/StructuredFormat"
source_slug: "StructuredFormat"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Structured Format

> Catalog pointer for the UI Patterns source page: [Structured Format](https://ui-patterns.com/patterns/StructuredFormat).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Structured Format

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/StructuredFormat
- Page title: Structured Format design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 22 words on source page
- Example: 112 words on source page
- Usage: 111 words on source page
- Solution: 110 words on source page
- Rationale: 136 words on source page

## Source Navigation

- Previous source navigation: Forgiving Format
- Next source navigation: Fill in the Blanks


<!-- ===== ui-patterns/wiki/concepts/patterns/sunk-cost-effect.md ===== -->

---
title: "Sunk Cost Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/sunk-cost-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/sunk-cost-effect"
source_slug: "sunk-cost-effect"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Loss Aversion"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Sunk Cost Effect

> Catalog pointer for the UI Patterns source page: [Sunk Cost Effect](https://ui-patterns.com/patterns/sunk-cost-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Loss Aversion
- Source breadcrumb: Design Patterns > Cognition > Loss Aversion > Sunk Cost Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/sunk-cost-effect
- Page title: Sunk Cost Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 45 words on source page
- Usage: 31 words on source page
- Solution: 123 words on source page
- Rationale: 275 words on source page

## Source Navigation

- Previous source navigation: Halo Effect
- Next source navigation: Autonomy


<!-- ===== ui-patterns/wiki/concepts/patterns/table-filter.md ===== -->

---
title: "Table Filter"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/TableFilter"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/TableFilter"
source_slug: "TableFilter"
track: "User Interface Design Patterns"
group: "Dealing with data"
subgroup: "Tables"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 6
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Table Filter

> Catalog pointer for the UI Patterns source page: [Table Filter](https://ui-patterns.com/patterns/TableFilter).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Dealing with data
- Subgroup: Tables
- Source breadcrumb: Design Patterns > Dealing with data > Tables > Table Filter

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/TableFilter
- Page title: Table Filter design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 6
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 37 words on source page
- Usage: 36 words on source page
- Solution: 89 words on source page
- Rationale: 37 words on source page

## Source Navigation

- Previous source navigation: Sort By Column
- Next source navigation: Copy Box


<!-- ===== ui-patterns/wiki/concepts/patterns/tag-cloud.md ===== -->

---
title: "Tag Cloud"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/TagCloud"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/TagCloud"
source_slug: "TagCloud"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Tag Cloud

> Catalog pointer for the UI Patterns source page: [Tag Cloud](https://ui-patterns.com/patterns/TagCloud).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Tag Cloud

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/TagCloud
- Page title: Tag Cloud design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 13 words on source page
- Example: 43 words on source page
- Usage: 42 words on source page
- Solution: 141 words on source page
- Rationale: 57 words on source page

## Source Navigation

- Previous source navigation: Preview
- Next source navigation: Inline Help Box


<!-- ===== ui-patterns/wiki/concepts/patterns/tagging.md ===== -->

---
title: "Tagging"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Tag"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Tag"
source_slug: "Tag"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Tagging

> Catalog pointer for the UI Patterns source page: [Tagging](https://ui-patterns.com/patterns/Tag).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Tagging

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Tag
- Page title: Tagging design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 13 words on source page
- Example: 78 words on source page
- Usage: 42 words on source page
- Solution: 100 words on source page
- Rationale: 112 words on source page

## Source Navigation

- Previous source navigation: Preview
- Next source navigation: Inline Help Box


<!-- ===== ui-patterns/wiki/concepts/patterns/tailoring.md ===== -->

---
title: "Tailoring"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Tailoring"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Tailoring"
source_slug: "Tailoring"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
  - "Cultural differences"
  - "Harmony strategy"
  - "Group Opinion strategy"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Tailoring

> Catalog pointer for the UI Patterns source page: [Tailoring](https://ui-patterns.com/patterns/Tailoring).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Tailoring

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Tailoring
- Page title: Tailoring design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion, Cultural differences, Harmony strategy, Group Opinion strategy
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Solution: 123 words on source page
- Rationale: 61 words on source page
- Discussion: 154 words on source page
- Cultural differences: 10 words on source page
- Harmony strategy: 17 words on source page
- Group Opinion strategy: 18 words on source page

## Source Navigation

- Previous source navigation: Limited Choice
- Next source navigation: Anchoring


<!-- ===== ui-patterns/wiki/concepts/patterns/temptation-bundling.md ===== -->

---
title: "Temptation Bundling"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/temptation-bundling"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/temptation-bundling"
source_slug: "temptation-bundling"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Temptation Bundling

> Catalog pointer for the UI Patterns source page: [Temptation Bundling](https://ui-patterns.com/patterns/temptation-bundling).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Temptation Bundling

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/temptation-bundling
- Page title: Temptation Bundling design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 34 words on source page
- Usage: 21 words on source page
- Solution: 146 words on source page
- Rationale: 187 words on source page

## Source Navigation

- Previous source navigation: Zeigarnik Effect
- Next source navigation: Picture Superiority Effect


<!-- ===== ui-patterns/wiki/concepts/patterns/testimonials.md ===== -->

---
title: "Testimonials"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/testimonials"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/testimonials"
source_slug: "testimonials"
track: "User Interface Design Patterns"
group: "Social"
subgroup: "Reputation"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Testimonials

> Catalog pointer for the UI Patterns source page: [Testimonials](https://ui-patterns.com/patterns/testimonials).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Social
- Subgroup: Reputation
- Source breadcrumb: Design Patterns > Social > Reputation > Testimonials

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/testimonials
- Page title: Testimonials design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Example: 9 words on source page
- Solution: 12 words on source page
- Rationale: 44 words on source page

## Source Navigation

- Previous source navigation: Paywall
- Next source navigation: Auto-sharing


<!-- ===== ui-patterns/wiki/concepts/patterns/thumbnail.md ===== -->

---
title: "Thumbnail"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Thumbnail"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Thumbnail"
source_slug: "Thumbnail"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Content"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Thumbnail

> Catalog pointer for the UI Patterns source page: [Thumbnail](https://ui-patterns.com/patterns/Thumbnail).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Content
- Source breadcrumb: Design Patterns > Navigation > Content > Thumbnail

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Thumbnail
- Page title: Thumbnail design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 20 words on source page
- Example: 94 words on source page
- Usage: 93 words on source page
- Solution: 105 words on source page
- Rationale: 66 words on source page

## Source Navigation

- Previous source navigation: Table Filter
- Next source navigation: Coupon


<!-- ===== ui-patterns/wiki/concepts/patterns/tip-a-friend.md ===== -->

---
title: "Tip A Friend"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/TipAFriend"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/TipAFriend"
source_slug: "TipAFriend"
track: "User Interface Design Patterns"
group: "Miscellaneous"
subgroup: "Increasing frequency"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Tip A Friend

> Catalog pointer for the UI Patterns source page: [Tip A Friend](https://ui-patterns.com/patterns/TipAFriend).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Miscellaneous
- Subgroup: Increasing frequency
- Source breadcrumb: Design Patterns > Miscellaneous > Increasing frequency > Tip A Friend

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/TipAFriend
- Page title: Tip A Friend design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 11 words on source page
- Example: 48 words on source page
- Usage: 47 words on source page
- Solution: 73 words on source page
- Rationale: 112 words on source page

## Source Navigation

- Previous source navigation: Shopping Cart
- Next source navigation: Continuous Scrolling


<!-- ===== ui-patterns/wiki/concepts/patterns/trigger.md ===== -->

---
title: "Trigger"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Trigger"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Trigger"
source_slug: "Trigger"
track: "Persuasive Design Patterns"
group: "Feedback"
subgroup: "Timing"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Trigger

> Catalog pointer for the UI Patterns source page: [Trigger](https://ui-patterns.com/patterns/Trigger).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Feedback
- Subgroup: Timing
- Source breadcrumb: Design Patterns > Feedback > Timing > Trigger

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Trigger
- Page title: Trigger design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 24 words on source page
- Usage: 9 words on source page
- Solution: 154 words on source page
- Rationale: 255 words on source page

## Source Navigation

- Previous source navigation: Goal-Gradient Effect
- Next source navigation: Tailoring


<!-- ===== ui-patterns/wiki/concepts/patterns/tunnelling.md ===== -->

---
title: "Tunnelling"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Tunnelling"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Tunnelling"
source_slug: "Tunnelling"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Attention"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Tunnelling

> Catalog pointer for the UI Patterns source page: [Tunnelling](https://ui-patterns.com/patterns/Tunnelling).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Attention
- Source breadcrumb: Design Patterns > Perception and memory > Attention > Tunnelling

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Tunnelling
- Page title: Tunnelling design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 14 words on source page
- Example: 126 words on source page
- Usage: 73 words on source page
- Solution: 239 words on source page
- Rationale: 167 words on source page

## Source Navigation

- Previous source navigation: Limited Choice
- Next source navigation: Anchoring


<!-- ===== ui-patterns/wiki/concepts/patterns/undo.md ===== -->

---
title: "Undo"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/undo"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/undo"
source_slug: "undo"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Undo

> Catalog pointer for the UI Patterns source page: [Undo](https://ui-patterns.com/patterns/undo).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > Undo

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/undo
- Page title: Undo design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 8 words on source page
- Example: 80 words on source page
- Usage: 53 words on source page
- Solution: 8 words on source page
- Rationale: 55 words on source page
- Discussion: 94 words on source page

## Source Navigation

- Previous source navigation: Chat
- Next source navigation: Modal


<!-- ===== ui-patterns/wiki/concepts/patterns/unlock-features.md ===== -->

---
title: "Unlock Features"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Unlock-features"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Unlock-features"
source_slug: "Unlock-features"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Gameplay rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Example: Karma points at Hacker News"
  - "Other ways of quantifying the criteria for unlocking features"
  - "Rationale"
  - "Discussion"
  - "Gaming the system"
  - "Drowning out new users"
  - "Acclimation to rewards"
  - "The end of the road"
example_count: 3
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Unlock Features

> Catalog pointer for the UI Patterns source page: [Unlock Features](https://ui-patterns.com/patterns/Unlock-features).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Gameplay rewards
- Source breadcrumb: Design Patterns > Game mechanics > Gameplay rewards > Unlock Features

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Unlock-features
- Page title: Unlock Features design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Example: Karma points at Hacker News, Other ways of quantifying the criteria for unlocking features, Rationale, Discussion, Gaming the system, Drowning out new users, Acclimation to rewards, The end of the road
- Example screenshots detected at source: 3
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 82 words on source page
- Usage: 55 words on source page
- Solution: 538 words on source page
- Example: Karma points at Hacker News: 131 words on source page
- Other ways of quantifying the criteria for unlocking features: 95 words on source page
- Rationale: 197 words on source page
- Discussion: 591 words on source page
- Gaming the system: 94 words on source page
- Drowning out new users: 69 words on source page
- Acclimation to rewards: 114 words on source page
- The end of the road: 120 words on source page

## Source Navigation

- Previous source navigation: Value Attribution
- Next source navigation: Trigger


<!-- ===== ui-patterns/wiki/concepts/patterns/value-attribution.md ===== -->

---
title: "Value Attribution"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Value-attribution"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Value-attribution"
source_slug: "Value-attribution"
track: "Persuasive Design Patterns"
group: "Cognition"
subgroup: "Other cognitive biases"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
  - "Discussion"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Value Attribution

> Catalog pointer for the UI Patterns source page: [Value Attribution](https://ui-patterns.com/patterns/Value-attribution).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Cognition
- Subgroup: Other cognitive biases
- Source breadcrumb: Design Patterns > Cognition > Other cognitive biases > Value Attribution

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Value-attribution
- Page title: Value Attribution design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale, Discussion
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 28 words on source page
- Usage: 16 words on source page
- Solution: 145 words on source page
- Rationale: 67 words on source page
- Discussion: 313 words on source page

## Source Navigation

- Previous source navigation: Variable Rewards
- Next source navigation: Self-Expression


<!-- ===== ui-patterns/wiki/concepts/patterns/variable-rewards.md ===== -->

---
title: "Variable Rewards"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Variable-rewards"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Variable-rewards"
source_slug: "Variable-rewards"
track: "Persuasive Design Patterns"
group: "Game mechanics"
subgroup: "Fundamentals of rewards"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Example: Lomography.com"
  - "Rationale"
  - "Fixed vs variable ratios"
  - "Fixed vs variable intervals"
  - "Discussion"
  - "Extinction"
  - "Avoidance"
example_count: 2
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Variable Rewards

> Catalog pointer for the UI Patterns source page: [Variable Rewards](https://ui-patterns.com/patterns/Variable-rewards).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Game mechanics
- Subgroup: Fundamentals of rewards
- Source breadcrumb: Design Patterns > Game mechanics > Fundamentals of rewards > Variable Rewards

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Variable-rewards
- Page title: Variable Rewards design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Example: Lomography.com, Rationale, Fixed vs variable ratios, Fixed vs variable intervals, Discussion, Extinction, Avoidance
- Example screenshots detected at source: 2
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 19 words on source page
- Example: 66 words on source page
- Usage: 25 words on source page
- Solution: 412 words on source page
- Example: Lomography.com: 155 words on source page
- Rationale: 566 words on source page
- Fixed vs variable ratios: 277 words on source page
- Fixed vs variable intervals: 184 words on source page
- Discussion: 296 words on source page
- Extinction: 61 words on source page
- Avoidance: 46 words on source page

## Source Navigation

- Previous source navigation: Reciprocation
- Next source navigation: Limited duration


<!-- ===== ui-patterns/wiki/concepts/patterns/vertical-dropdown-menu.md ===== -->

---
title: "Vertical Dropdown Menu"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/VerticalDropdownMenu"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/VerticalDropdownMenu"
source_slug: "VerticalDropdownMenu"
track: "User Interface Design Patterns"
group: "Navigation"
subgroup: "Menus"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Other issues you want to take notice of:"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Vertical Dropdown Menu

> Catalog pointer for the UI Patterns source page: [Vertical Dropdown Menu](https://ui-patterns.com/patterns/VerticalDropdownMenu).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Navigation
- Subgroup: Menus
- Source breadcrumb: Design Patterns > Navigation > Menus > Vertical Dropdown Menu

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/VerticalDropdownMenu
- Page title: Vertical Dropdown Menu design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Other issues you want to take notice of:, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 18 words on source page
- Example: 55 words on source page
- Usage: 54 words on source page
- Solution: 285 words on source page
- Other issues you want to take notice of:: 1 words on source page
- Rationale: 70 words on source page

## Source Navigation

- Previous source navigation: Home Link
- Next source navigation: Accordion Menu


<!-- ===== ui-patterns/wiki/concepts/patterns/vote-to-promote.md ===== -->

---
title: "Vote To Promote"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/VoteToPromote"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/VoteToPromote"
source_slug: "VoteToPromote"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Community driven"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "4 Mechanisms working together"
  - "Let users submit"
  - "Make voting embeddable"
  - "Rationale"
  - "Discussion"
  - "Wisdom of crowds"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Vote To Promote

> Catalog pointer for the UI Patterns source page: [Vote To Promote](https://ui-patterns.com/patterns/VoteToPromote).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Community driven
- Source breadcrumb: Design Patterns > Getting input > Community driven > Vote To Promote

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/VoteToPromote
- Page title: Vote To Promote design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, 4 Mechanisms working together, Let users submit, Make voting embeddable, Rationale, Discussion, Wisdom of crowds
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 21 words on source page
- Example: 113 words on source page
- Usage: 72 words on source page
- Solution: 354 words on source page
- 4 Mechanisms working together: 156 words on source page
- Let users submit: 45 words on source page
- Make voting embeddable: 78 words on source page
- Rationale: 41 words on source page
- Discussion: 452 words on source page
- Wisdom of crowds: 138 words on source page

## Source Navigation

- Previous source navigation: Lazy Registration
- Next source navigation: Account Registration


<!-- ===== ui-patterns/wiki/concepts/patterns/walkthrough.md ===== -->

---
title: "Walkthrough"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Tour"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Tour"
source_slug: "Tour"
track: "User Interface Design Patterns"
group: "Onboarding"
subgroup: "Guidance"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Focus on users’ tasks"
  - "Provide visual references"
  - "Include direct links"
  - "Address issues or concerns up front"
  - "Rationale"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Walkthrough

> Catalog pointer for the UI Patterns source page: [Walkthrough](https://ui-patterns.com/patterns/Tour).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Onboarding
- Subgroup: Guidance
- Source breadcrumb: Design Patterns > Onboarding > Guidance > Walkthrough

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Tour
- Page title: Walkthrough design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Focus on users’ tasks, Provide visual references, Include direct links, Address issues or concerns up front, Rationale
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 25 words on source page
- Example: 96 words on source page
- Usage: 76 words on source page
- Solution: 425 words on source page
- Focus on users’ tasks: 123 words on source page
- Provide visual references: 57 words on source page
- Include direct links: 52 words on source page
- Address issues or concerns up front: 60 words on source page
- Rationale: 119 words on source page

## Source Navigation

- Previous source navigation: Liking
- Next source navigation: Gallery


<!-- ===== ui-patterns/wiki/concepts/patterns/wiki.md ===== -->

---
title: "Wiki"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Wiki"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Wiki"
source_slug: "Wiki"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Community driven"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 4
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Wiki

> Catalog pointer for the UI Patterns source page: [Wiki](https://ui-patterns.com/patterns/Wiki).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Community driven
- Source breadcrumb: Design Patterns > Getting input > Community driven > Wiki

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Wiki
- Page title: Wiki design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 4
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 23 words on source page
- Example: 97 words on source page
- Usage: 96 words on source page
- Solution: 147 words on source page
- Rationale: 42 words on source page

## Source Navigation

- Previous source navigation: Search Filters
- Next source navigation: WYSIWYG


<!-- ===== ui-patterns/wiki/concepts/patterns/wizard.md ===== -->

---
title: "Wizard"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/Wizard"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/Wizard"
source_slug: "Wizard"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Explaining the process"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Buttons"
  - "Keep the purpose clear: explain"
  - "Use plain language"
  - "Summarize choices"
  - "Good defaults"
  - "Rationale"
  - "Minimum of training"
  - "Discussion"
  - "Keep the amount of screens low"
  - "Be careful not to make each step too long"
  - "Allow alternatives to using the wizard"
  - "Sources"
example_count: 13
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Wizard

> Catalog pointer for the UI Patterns source page: [Wizard](https://ui-patterns.com/patterns/Wizard).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Explaining the process
- Source breadcrumb: Design Patterns > Getting input > Explaining the process > Wizard

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/Wizard
- Page title: Wizard design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Buttons, Keep the purpose clear: explain, Use plain language, Summarize choices, Good defaults, Rationale, Minimum of training, Discussion, Keep the amount of screens low, Be careful not to make each step too long, Allow alternatives to using the wizard, Sources
- Example screenshots detected at source: 13
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 17 words on source page
- Example: 243 words on source page
- Usage: 161 words on source page
- Solution: 614 words on source page
- Buttons: 221 words on source page
- Keep the purpose clear: explain: 59 words on source page
- Use plain language: 33 words on source page
- Summarize choices: 100 words on source page
- Good defaults: 37 words on source page
- Rationale: 256 words on source page
- Minimum of training: 40 words on source page
- Discussion: 498 words on source page
- Keep the amount of screens low: 39 words on source page
- Be careful not to make each step too long: 128 words on source page
- Allow alternatives to using the wizard: 152 words on source page
- Sources: 50 words on source page

## Source Navigation

- Previous source navigation: Adaptable View
- Next source navigation: Completeness meter


<!-- ===== ui-patterns/wiki/concepts/patterns/wysiwyg.md ===== -->

---
title: "WYSIWYG"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/WYSIWYG"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/WYSIWYG"
source_slug: "WYSIWYG"
track: "User Interface Design Patterns"
group: "Getting input"
subgroup: "Forms"
section_headings:
  - "Problem summary"
  - "Example"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 1
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# WYSIWYG

> Catalog pointer for the UI Patterns source page: [WYSIWYG](https://ui-patterns.com/patterns/WYSIWYG).

## Taxonomy

- Track: User Interface Design Patterns
- Group: Getting input
- Subgroup: Forms
- Source breadcrumb: Design Patterns > Getting input > Forms > WYSIWYG

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/WYSIWYG
- Page title: WYSIWYG design pattern
- Section headings available at source: Problem summary, Example, Usage, Solution, Rationale
- Example screenshots detected at source: 1
- Primary example image detected: yes

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 23 words on source page
- Example: 203 words on source page
- Usage: 202 words on source page
- Solution: 86 words on source page
- Rationale: 89 words on source page

## Source Navigation

- Previous source navigation: Wiki
- Next source navigation: Tagging


<!-- ===== ui-patterns/wiki/concepts/patterns/zeigarnik-effect.md ===== -->

---
title: "Zeigarnik Effect"
created: "2026-07-02"
updated: "2026-07-02"
type: "concept"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns/zeigarnik-effect"
source_site: "UI Patterns"
source_copyright_note: "Source site footer says All rights reserved; this page is a catalog pointer, not a republication."
source_path: "/patterns/zeigarnik-effect"
source_slug: "zeigarnik-effect"
track: "Persuasive Design Patterns"
group: "Perception and memory"
subgroup: "Attention"
section_headings:
  - "Problem summary"
  - "Usage"
  - "Solution"
  - "Rationale"
example_count: 0
retrieved_at: "2026-07-02T18:23:09+00:00"
confidence: "medium"
---
# Zeigarnik Effect

> Catalog pointer for the UI Patterns source page: [Zeigarnik Effect](https://ui-patterns.com/patterns/zeigarnik-effect).

## Taxonomy

- Track: Persuasive Design Patterns
- Group: Perception and memory
- Subgroup: Attention
- Source breadcrumb: Design Patterns > Perception and memory > Attention > Zeigarnik Effect

## Source Page Inventory

- Source URL: https://ui-patterns.com/patterns/zeigarnik-effect
- Page title: Zeigarnik Effect design pattern
- Section headings available at source: Problem summary, Usage, Solution, Rationale
- Example screenshots detected at source: 0
- Primary example image detected: no

## Retrieval Notes

Use this page as a routing handle, then open the source URL when you need the full pattern explanation, screenshot examples, or exact wording. For public Pixi Wiki use, prefer paraphrased design implications over long source quotes.

Useful retrieval frame:

- Ask what user behavior or interface decision this pattern is meant to shape.
- Check the source page sections before prescribing it; many pages distinguish usage, solution, rationale, and examples.
- Compare nearby patterns in the same subgroup before choosing one.
- Cite this catalog page plus the source URL when using the pattern in design review.

## Source Shape

- Problem summary: 63 words on source page
- Usage: 52 words on source page
- Solution: 98 words on source page
- Rationale: 147 words on source page

## Source Navigation

- Previous source navigation: Fresh Start Effect
- Next source navigation: Inaction Inertia Effect


<!-- ===== ui-patterns/wiki/entities/categories/persuasive-design-patterns-cognition.md ===== -->

---
title: "Cognition — Persuasive Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "Persuasive Design Patterns"
group: "Cognition"
pattern_count: 25
confidence: "medium"
---
# Cognition — Persuasive Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 25 cataloged source pages under `Cognition` / `Persuasive Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Loss Aversion

- [[decoy-effect|Decoy Effect]] — [source](https://ui-patterns.com/patterns/decoy-effect)
- [[endowment-effect|Endowment Effect]] — [source](https://ui-patterns.com/patterns/Endowment-effect)
- [[framing|Framing]] — [source](https://ui-patterns.com/patterns/framing)
- [[ikea-effect|IKEA effect]] — [source](https://ui-patterns.com/patterns/ikea-effect)
- [[loss-aversion|Loss Aversion]] — [source](https://ui-patterns.com/patterns/Loss-aversion)
- [[negativity-bias|Negativity bias]] — [source](https://ui-patterns.com/patterns/Negativity-bias)
- [[optimism-bias|Optimism Bias]] — [source](https://ui-patterns.com/patterns/optimism-bias)
- [[status-quo-bias|Status-Quo Bias]] — [source](https://ui-patterns.com/patterns/Statusquo-bias)
- [[sunk-cost-effect|Sunk Cost Effect]] — [source](https://ui-patterns.com/patterns/sunk-cost-effect)
### Other cognitive biases

- [[cashless-effect|Cashless Effect]] — [source](https://ui-patterns.com/patterns/cashless-effect)
- [[choice-closure|Choice Closure]] — [source](https://ui-patterns.com/patterns/choice-closure)
- [[curiosity|Curiosity]] — [source](https://ui-patterns.com/patterns/curiosity)
- [[delay-discounting|Delay Discounting]] — [source](https://ui-patterns.com/patterns/delay-discounting)
- [[illusion-of-control|Illusion of control]] — [source](https://ui-patterns.com/patterns/Illusion-of-control)
- [[inaction-inertia-effect|Inaction Inertia Effect]] — [source](https://ui-patterns.com/patterns/inaction-inertia-effect)
- [[need-for-closure|Need for Closure]] — [source](https://ui-patterns.com/patterns/Need-for-closure)
- [[peak-end-rule|Peak-end rule]] — [source](https://ui-patterns.com/patterns/Peakend-rule)
- [[present-bias|Present Bias]] — [source](https://ui-patterns.com/patterns/present-bias)
- [[priming-effect|Priming Effect]] — [source](https://ui-patterns.com/patterns/priming-effect)
- [[set-completion|Set Completion]] — [source](https://ui-patterns.com/patterns/set-completion)
- [[temptation-bundling|Temptation Bundling]] — [source](https://ui-patterns.com/patterns/temptation-bundling)
- [[value-attribution|Value Attribution]] — [source](https://ui-patterns.com/patterns/Value-attribution)
### Scarcity

- [[limited-choice|Limited Choice]] — [source](https://ui-patterns.com/patterns/Limited-choice)
- [[limited-duration|Limited duration]] — [source](https://ui-patterns.com/patterns/Limited-duration)
- [[scarcity|Scarcity]] — [source](https://ui-patterns.com/patterns/Scarcity)


<!-- ===== ui-patterns/wiki/entities/categories/persuasive-design-patterns-feedback.md ===== -->

---
title: "Feedback — Persuasive Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "Persuasive Design Patterns"
group: "Feedback"
pattern_count: 6
confidence: "medium"
---
# Feedback — Persuasive Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 6 cataloged source pages under `Feedback` / `Persuasive Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Timing

- [[feedback-loops|Feedback Loops]] — [source](https://ui-patterns.com/patterns/Feedback-loops)
- [[fresh-start-effect|Fresh Start Effect]] — [source](https://ui-patterns.com/patterns/fresh-start-effect)
- [[kairos|Kairos]] — [source](https://ui-patterns.com/patterns/Kairos)
- [[simulation|Simulation]] — [source](https://ui-patterns.com/patterns/Simulation)
- [[tailoring|Tailoring]] — [source](https://ui-patterns.com/patterns/Tailoring)
- [[trigger|Trigger]] — [source](https://ui-patterns.com/patterns/Trigger)


<!-- ===== ui-patterns/wiki/entities/categories/persuasive-design-patterns-game-mechanics.md ===== -->

---
title: "Game mechanics — Persuasive Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "Persuasive Design Patterns"
group: "Game mechanics"
pattern_count: 19
confidence: "medium"
---
# Game mechanics — Persuasive Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 19 cataloged source pages under `Game mechanics` / `Persuasive Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Fundamentals of rewards

- [[fixed-rewards|Fixed rewards]] — [source](https://ui-patterns.com/patterns/Fixed-rewards)
- [[shaping|Shaping]] — [source](https://ui-patterns.com/patterns/shaping)
- [[variable-rewards|Variable Rewards]] — [source](https://ui-patterns.com/patterns/Variable-rewards)
### Gameplay design

- [[appropriate-challenge|Appropriate Challenge]] — [source](https://ui-patterns.com/patterns/Appropriate-challenge)
- [[hedonic-adaptation|Hedonic Adaptation]] — [source](https://ui-patterns.com/patterns/hedonic-adaptation)
- [[intentional-gaps|Intentional Gaps]] — [source](https://ui-patterns.com/patterns/Intentional-gaps)
- [[investment-loops|Investment Loops]] — [source](https://ui-patterns.com/patterns/investment-loops)
- [[levels|Levels]] — [source](https://ui-patterns.com/patterns/Levels)
- [[periodic-events|Periodic Events]] — [source](https://ui-patterns.com/patterns/periodic-events)
- [[self-monitoring|Self-Monitoring]] — [source](https://ui-patterns.com/patterns/self-monitoring)
- [[storytelling|Storytelling]] — [source](https://ui-patterns.com/patterns/Storytelling)
### Gameplay rewards

- [[achievements|Achievements]] — [source](https://ui-patterns.com/patterns/Achievements)
- [[appointment-dynamic|Appointment Dynamic]] — [source](https://ui-patterns.com/patterns/appointment-dynamic)
- [[delighters|Delighters]] — [source](https://ui-patterns.com/patterns/delighters)
- [[goal-gradient-effect|Goal-Gradient Effect]] — [source](https://ui-patterns.com/patterns/Completion)
- [[praise|Praise]] — [source](https://ui-patterns.com/patterns/Praise)
- [[privileges|Privileges]] — [source](https://ui-patterns.com/patterns/Powers)
- [[prolonged-play|Prolonged Play]] — [source](https://ui-patterns.com/patterns/Prolonged-play)
- [[unlock-features|Unlock Features]] — [source](https://ui-patterns.com/patterns/Unlock-features)


<!-- ===== ui-patterns/wiki/entities/categories/persuasive-design-patterns-perception-and-memory.md ===== -->

---
title: "Perception and memory — Persuasive Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "Persuasive Design Patterns"
group: "Perception and memory"
pattern_count: 12
confidence: "medium"
---
# Perception and memory — Persuasive Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 12 cataloged source pages under `Perception and memory` / `Persuasive Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Attention

- [[isolation-effect|Isolation Effect]] — [source](https://ui-patterns.com/patterns/isolation-effect)
- [[picture-superiority-effect|Picture Superiority Effect]] — [source](https://ui-patterns.com/patterns/picture-superiority-effect)
- [[reduction|Reduction]] — [source](https://ui-patterns.com/patterns/Reduction)
- [[tunnelling|Tunnelling]] — [source](https://ui-patterns.com/patterns/Tunnelling)
- [[zeigarnik-effect|Zeigarnik Effect]] — [source](https://ui-patterns.com/patterns/zeigarnik-effect)
### Comprehension

- [[anchoring|Anchoring]] — [source](https://ui-patterns.com/patterns/Anchoring)
- [[chunking|Chunking]] — [source](https://ui-patterns.com/patterns/Chunking)
- [[conceptual-metaphor|Conceptual Metaphor]] — [source](https://ui-patterns.com/patterns/Conceptual-metaphor)
- [[pattern-recognition|Pattern Recognition]] — [source](https://ui-patterns.com/patterns/Pattern-recognition)
- [[recognition-over-recall|Recognition over Recall]] — [source](https://ui-patterns.com/patterns/Recognition-over-recall)
- [[sequencing|Sequencing]] — [source](https://ui-patterns.com/patterns/Sequencing)
- [[serial-positioning-effect|Serial Positioning Effect]] — [source](https://ui-patterns.com/patterns/Serial-positioning-effect)


<!-- ===== ui-patterns/wiki/entities/categories/persuasive-design-patterns-social.md ===== -->

---
title: "Social — Persuasive Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "Persuasive Design Patterns"
group: "Social"
pattern_count: 17
confidence: "medium"
---
# Social — Persuasive Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 17 cataloged source pages under `Social` / `Persuasive Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Social biases

- [[authority-bias|Authority Bias]] — [source](https://ui-patterns.com/patterns/Authority)
- [[autonomy|Autonomy]] — [source](https://ui-patterns.com/patterns/autonomy)
- [[cognitive-dissonance|Cognitive Dissonance]] — [source](https://ui-patterns.com/patterns/cognitive-dissonance)
- [[commitment-and-consistency|Commitment & Consistency]] — [source](https://ui-patterns.com/patterns/Commitment-consistency)
- [[competition|Competition]] — [source](https://ui-patterns.com/patterns/Competition)
- [[halo-effect|Halo Effect]] — [source](https://ui-patterns.com/patterns/halo-effect)
- [[liking|Liking]] — [source](https://ui-patterns.com/patterns/Liking)
- [[noble-edge-effect|Noble Edge Effect]] — [source](https://ui-patterns.com/patterns/noble-edge-effect)
- [[nostalgia-effect|Nostalgia Effect]] — [source](https://ui-patterns.com/patterns/nostalgia-effect)
- [[positive-mimicry|Positive Mimicry]] — [source](https://ui-patterns.com/patterns/Positive-mimicry)
- [[reciprocation|Reciprocation]] — [source](https://ui-patterns.com/patterns/Reciprocation)
- [[reputation|Reputation]] — [source](https://ui-patterns.com/patterns/reputation)
- [[retaliation|Retaliation]] — [source](https://ui-patterns.com/patterns/revenge)
- [[role-playing|Role Playing]] — [source](https://ui-patterns.com/patterns/Roleplaying)
- [[self-expression|Self-Expression]] — [source](https://ui-patterns.com/patterns/Self-expression)
- [[social-proof|Social Proof]] — [source](https://ui-patterns.com/patterns/Social-proof)
- [[status|Status]] — [source](https://ui-patterns.com/patterns/Status)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-dealing-with-data.md ===== -->

---
title: "Dealing with data — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Dealing with data"
pattern_count: 11
confidence: "medium"
---
# Dealing with data — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 11 cataloged source pages under `Dealing with data` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Formatting data

- [[copy-box|Copy Box]] — [source](https://ui-patterns.com/patterns/CopyBox)
- [[dashboard|Dashboard]] — [source](https://ui-patterns.com/patterns/dashboard)
- [[frequently-asked-questions-faq|Frequently Asked Questions (FAQ)]] — [source](https://ui-patterns.com/patterns/frequently-asked-questions-faq)
### Images

- [[gallery|Gallery]] — [source](https://ui-patterns.com/patterns/Gallery)
- [[image-zoom|Image Zoom]] — [source](https://ui-patterns.com/patterns/ImageZoom)
- [[slideshow|Slideshow]] — [source](https://ui-patterns.com/patterns/Slideshow)
### Search

- [[autocomplete|Autocomplete]] — [source](https://ui-patterns.com/patterns/Autocomplete)
- [[search-filters|Search Filters]] — [source](https://ui-patterns.com/patterns/LiveFilter)
### Tables

- [[alternating-row-colors|Alternating Row Colors]] — [source](https://ui-patterns.com/patterns/AlternatingRowColors)
- [[sort-by-column|Sort By Column]] — [source](https://ui-patterns.com/patterns/SortByColumn)
- [[table-filter|Table Filter]] — [source](https://ui-patterns.com/patterns/TableFilter)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-getting-input.md ===== -->

---
title: "Getting input — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Getting input"
pattern_count: 29
confidence: "medium"
---
# Getting input — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 29 cataloged source pages under `Getting input` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Community driven

- [[flagging-and-reporting|Flagging & Reporting]] — [source](https://ui-patterns.com/patterns/flagging-and-reporting)
- [[pay-to-promote|Pay To Promote]] — [source](https://ui-patterns.com/patterns/pay-to-promote)
- [[rate-content|Rate Content]] — [source](https://ui-patterns.com/patterns/RateContent)
- [[vote-to-promote|Vote To Promote]] — [source](https://ui-patterns.com/patterns/VoteToPromote)
- [[wiki|Wiki]] — [source](https://ui-patterns.com/patterns/Wiki)
### Explaining the process

- [[completeness-meter|Completeness meter]] — [source](https://ui-patterns.com/patterns/CompletenessMeter)
- [[inline-help-box|Inline Help Box]] — [source](https://ui-patterns.com/patterns/InlineHelpBox)
- [[steps-left|Steps Left]] — [source](https://ui-patterns.com/patterns/StepsLeft)
- [[wizard|Wizard]] — [source](https://ui-patterns.com/patterns/Wizard)
### Forms

- [[autosave|Autosave]] — [source](https://ui-patterns.com/patterns/autosave)
- [[calendar-picker|Calendar Picker]] — [source](https://ui-patterns.com/patterns/CalendarPicker)
- [[captcha|Captcha]] — [source](https://ui-patterns.com/patterns/Captcha)
- [[drag-and-drop|Drag and drop]] — [source](https://ui-patterns.com/patterns/drag-and-drop)
- [[expandable-input|Expandable Input]] — [source](https://ui-patterns.com/patterns/expandable-input)
- [[fill-in-the-blanks|Fill in the Blanks]] — [source](https://ui-patterns.com/patterns/FillInTheBlanks)
- [[forgiving-format|Forgiving Format]] — [source](https://ui-patterns.com/patterns/ForgivingFormat)
- [[good-defaults|Good Defaults]] — [source](https://ui-patterns.com/patterns/GoodDefaults)
- [[inplace-editor|Inplace Editor]] — [source](https://ui-patterns.com/patterns/InplaceEditor)
- [[input-feedback|Input Feedback]] — [source](https://ui-patterns.com/patterns/InputFeedback)
- [[input-prompt|Input Prompt]] — [source](https://ui-patterns.com/patterns/InputPrompt)
- [[keyboard-shortcuts|Keyboard Shortcuts]] — [source](https://ui-patterns.com/patterns/keyboard-shortcuts)
- [[morphing-controls|Morphing Controls]] — [source](https://ui-patterns.com/patterns/morphing-controls)
- [[password-strength-meter|Password Strength Meter]] — [source](https://ui-patterns.com/patterns/PasswordStrengthMeter)
- [[preview|Preview]] — [source](https://ui-patterns.com/patterns/LivePreview)
- [[rule-builder|Rule Builder]] — [source](https://ui-patterns.com/patterns/rule-builder)
- [[settings|Settings]] — [source](https://ui-patterns.com/patterns/settings)
- [[structured-format|Structured Format]] — [source](https://ui-patterns.com/patterns/StructuredFormat)
- [[undo|Undo]] — [source](https://ui-patterns.com/patterns/undo)
- [[wysiwyg|WYSIWYG]] — [source](https://ui-patterns.com/patterns/WYSIWYG)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-miscellaneous.md ===== -->

---
title: "Miscellaneous — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Miscellaneous"
pattern_count: 5
confidence: "medium"
---
# Miscellaneous — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 5 cataloged source pages under `Miscellaneous` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Increasing frequency

- [[tip-a-friend|Tip A Friend]] — [source](https://ui-patterns.com/patterns/TipAFriend)
### Shopping

- [[coupon|Coupon]] — [source](https://ui-patterns.com/patterns/Coupon)
- [[pricing-table|Pricing table]] — [source](https://ui-patterns.com/patterns/PricingTable)
- [[product-page|Product page]] — [source](https://ui-patterns.com/patterns/ProductPage)
- [[shopping-cart|Shopping Cart]] — [source](https://ui-patterns.com/patterns/ShoppingCart)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-navigation.md ===== -->

---
title: "Navigation — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Navigation"
pattern_count: 26
confidence: "medium"
---
# Navigation — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 26 cataloged source pages under `Navigation` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Content

- [[adaptable-view|Adaptable View]] — [source](https://ui-patterns.com/patterns/AdaptableView)
- [[archive|Archive]] — [source](https://ui-patterns.com/patterns/Archive)
- [[article-list|Article List]] — [source](https://ui-patterns.com/patterns/ArticleList)
- [[cards|Cards]] — [source](https://ui-patterns.com/patterns/cards)
- [[carousel|Carousel]] — [source](https://ui-patterns.com/patterns/Carousel)
- [[categorization|Categorization]] — [source](https://ui-patterns.com/patterns/categorization)
- [[continuous-scrolling|Continuous Scrolling]] — [source](https://ui-patterns.com/patterns/ContinuousScrolling)
- [[event-calendar|Event Calendar]] — [source](https://ui-patterns.com/patterns/EventCalendar)
- [[favorites|Favorites]] — [source](https://ui-patterns.com/patterns/favorites)
- [[pagination|Pagination]] — [source](https://ui-patterns.com/patterns/Pagination)
- [[progressive-disclosure|Progressive Disclosure]] — [source](https://ui-patterns.com/patterns/ProgressiveDisclosure)
- [[tag-cloud|Tag Cloud]] — [source](https://ui-patterns.com/patterns/TagCloud)
- [[tagging|Tagging]] — [source](https://ui-patterns.com/patterns/Tag)
- [[thumbnail|Thumbnail]] — [source](https://ui-patterns.com/patterns/Thumbnail)
### Gestures

- [[pull-to-refresh|Pull to refresh]] — [source](https://ui-patterns.com/patterns/pull-to-refresh)
### Jumping in hierarchy

- [[breadcrumbs|Breadcrumbs]] — [source](https://ui-patterns.com/patterns/Breadcrumbs)
- [[fat-footer|Fat Footer]] — [source](https://ui-patterns.com/patterns/FatFooter)
- [[home-link|Home Link]] — [source](https://ui-patterns.com/patterns/HomeLink)
- [[modal|Modal]] — [source](https://ui-patterns.com/patterns/modal-windows)
- [[notifications|Notifications]] — [source](https://ui-patterns.com/patterns/notifications)
- [[shortcut-dropdown|Shortcut Dropdown]] — [source](https://ui-patterns.com/patterns/ShortcutDropdown)
### Menus

- [[accordion-menu|Accordion Menu]] — [source](https://ui-patterns.com/patterns/AccordionMenu)
- [[horizontal-dropdown-menu|Horizontal Dropdown Menu]] — [source](https://ui-patterns.com/patterns/HorizontalDropdownMenu)
- [[vertical-dropdown-menu|Vertical Dropdown Menu]] — [source](https://ui-patterns.com/patterns/VerticalDropdownMenu)
### Tabs

- [[module-tabs|Module Tabs]] — [source](https://ui-patterns.com/patterns/ModuleTabs)
- [[navigation-tabs|Navigation Tabs]] — [source](https://ui-patterns.com/patterns/NavigationTabs)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-onboarding.md ===== -->

---
title: "Onboarding — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Onboarding"
pattern_count: 9
confidence: "medium"
---
# Onboarding — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 9 cataloged source pages under `Onboarding` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Guidance

- [[blank-slate|Blank Slate]] — [source](https://ui-patterns.com/patterns/BlankSlate)
- [[coachmarks|Coachmarks]] — [source](https://ui-patterns.com/patterns/coachmarks)
- [[guided-tour|Guided Tour]] — [source](https://ui-patterns.com/patterns/Guided-tour)
- [[inline-hints|Inline Hints]] — [source](https://ui-patterns.com/patterns/inline-hints)
- [[playthrough|Playthrough]] — [source](https://ui-patterns.com/patterns/playthrough)
- [[walkthrough|Walkthrough]] — [source](https://ui-patterns.com/patterns/Tour)
### Registration

- [[account-registration|Account Registration]] — [source](https://ui-patterns.com/patterns/AccountRegistration)
- [[lazy-registration|Lazy Registration]] — [source](https://ui-patterns.com/patterns/LazyRegistration)
- [[paywall|Paywall]] — [source](https://ui-patterns.com/patterns/Paywall)


<!-- ===== ui-patterns/wiki/entities/categories/user-interface-design-patterns-social.md ===== -->

---
title: "Social — User Interface Design Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "ui-patterns"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
source_site: "UI Patterns"
track: "User Interface Design Patterns"
group: "Social"
pattern_count: 11
confidence: "medium"
---
# Social — User Interface Design Patterns

> Category map imported from [UI Patterns](https://ui-patterns.com/patterns).

## Scope

This category groups 11 cataloged source pages under `Social` / `User Interface Design Patterns`. It is a navigation layer, not a copy of the source site.

## Patterns

### Reputation

- [[collectible-achievements|Collectible Achievements]] — [source](https://ui-patterns.com/patterns/CollectibleAchievements)
- [[leaderboard|Leaderboard]] — [source](https://ui-patterns.com/patterns/leaderboard)
- [[testimonials|Testimonials]] — [source](https://ui-patterns.com/patterns/testimonials)
### Social interactions

- [[activity-stream|Activity Stream]] — [source](https://ui-patterns.com/patterns/ActivityStream)
- [[auto-sharing|Auto-sharing]] — [source](https://ui-patterns.com/patterns/auto-sharing)
- [[chat|Chat]] — [source](https://ui-patterns.com/patterns/direct-messaging)
- [[follow|Follow]] — [source](https://ui-patterns.com/patterns/follow)
- [[friend|Friend]] — [source](https://ui-patterns.com/patterns/friend)
- [[friend-list|Friend list]] — [source](https://ui-patterns.com/patterns/friend-list)
- [[invite-friends|Invite friends]] — [source](https://ui-patterns.com/patterns/invite-friends)
- [[reaction|Reaction]] — [source](https://ui-patterns.com/patterns/reaction)


<!-- ===== ui-patterns/wiki/entities/source-site-ui-patterns.md ===== -->

---
title: "Source Site — UI Patterns"
created: "2026-07-02"
updated: "2026-07-02"
type: "entity"
status: "compiled"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com"
---
# Source Site — UI Patterns

UI Patterns is the source site for this namespace's catalog records.

## Source Facts Captured

- Base URL: https://ui-patterns.com
- Pattern index URL: https://ui-patterns.com/patterns
- Retrieved at: 2026-07-02T18:23:09+00:00
- Pattern pages cataloged: 170
- Tracks cataloged: Persuasive Design Patterns, User Interface Design Patterns

## Pixi Wiki Role

Pixi Wiki provides an agent-readable index, category map, and retrieval contract over the source site. It does not replace the source site.


<!-- ===== ui-patterns/wiki/index.md ===== -->

---
title: "UI Patterns KB — Master Index"
created: "2026-07-02"
updated: "2026-07-02"
type: "wiki"
status: "active"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
---
# UI Patterns KB — Master Index

## Start Here

- [[summaries/for-agents-ui-patterns-retrieval|For Agents — UI Patterns Retrieval]]
- [[summaries/provenance-and-copyright-boundary|Provenance and Copyright Boundary]]
- [[summaries/source-taxonomy|Source Taxonomy]]
- [[entities/source-site-ui-patterns|Source Site — UI Patterns]]

## Category Maps

- [[entities/categories/persuasive-design-patterns-cognition|Cognition — Persuasive Design Patterns]]
- [[entities/categories/persuasive-design-patterns-feedback|Feedback — Persuasive Design Patterns]]
- [[entities/categories/persuasive-design-patterns-game-mechanics|Game mechanics — Persuasive Design Patterns]]
- [[entities/categories/persuasive-design-patterns-perception-and-memory|Perception and memory — Persuasive Design Patterns]]
- [[entities/categories/persuasive-design-patterns-social|Social — Persuasive Design Patterns]]
- [[entities/categories/user-interface-design-patterns-dealing-with-data|Dealing with data — User Interface Design Patterns]]
- [[entities/categories/user-interface-design-patterns-getting-input|Getting input — User Interface Design Patterns]]
- [[entities/categories/user-interface-design-patterns-miscellaneous|Miscellaneous — User Interface Design Patterns]]
- [[entities/categories/user-interface-design-patterns-navigation|Navigation — User Interface Design Patterns]]
- [[entities/categories/user-interface-design-patterns-onboarding|Onboarding — User Interface Design Patterns]]
- [[entities/categories/user-interface-design-patterns-social|Social — User Interface Design Patterns]]

## Pattern Catalog

- [[concepts/patterns/accordion-menu|Accordion Menu]] — User Interface Design Patterns / Navigation / Menus
- [[concepts/patterns/account-registration|Account Registration]] — User Interface Design Patterns / Onboarding / Registration
- [[concepts/patterns/achievements|Achievements]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/activity-stream|Activity Stream]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/adaptable-view|Adaptable View]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/alternating-row-colors|Alternating Row Colors]] — User Interface Design Patterns / Dealing with data / Tables
- [[concepts/patterns/anchoring|Anchoring]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/appointment-dynamic|Appointment Dynamic]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/appropriate-challenge|Appropriate Challenge]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/archive|Archive]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/article-list|Article List]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/authority-bias|Authority Bias]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/auto-sharing|Auto-sharing]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/autocomplete|Autocomplete]] — User Interface Design Patterns / Dealing with data / Search
- [[concepts/patterns/autonomy|Autonomy]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/autosave|Autosave]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/blank-slate|Blank Slate]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/breadcrumbs|Breadcrumbs]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/calendar-picker|Calendar Picker]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/captcha|Captcha]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/cards|Cards]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/carousel|Carousel]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/cashless-effect|Cashless Effect]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/categorization|Categorization]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/chat|Chat]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/choice-closure|Choice Closure]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/chunking|Chunking]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/coachmarks|Coachmarks]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/cognitive-dissonance|Cognitive Dissonance]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/collectible-achievements|Collectible Achievements]] — User Interface Design Patterns / Social / Reputation
- [[concepts/patterns/commitment-and-consistency|Commitment & Consistency]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/competition|Competition]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/completeness-meter|Completeness meter]] — User Interface Design Patterns / Getting input / Explaining the process
- [[concepts/patterns/conceptual-metaphor|Conceptual Metaphor]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/continuous-scrolling|Continuous Scrolling]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/copy-box|Copy Box]] — User Interface Design Patterns / Dealing with data / Formatting data
- [[concepts/patterns/coupon|Coupon]] — User Interface Design Patterns / Miscellaneous / Shopping
- [[concepts/patterns/curiosity|Curiosity]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/dashboard|Dashboard]] — User Interface Design Patterns / Dealing with data / Formatting data
- [[concepts/patterns/decoy-effect|Decoy Effect]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/delay-discounting|Delay Discounting]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/delighters|Delighters]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/drag-and-drop|Drag and drop]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/endowment-effect|Endowment Effect]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/event-calendar|Event Calendar]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/expandable-input|Expandable Input]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/fat-footer|Fat Footer]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/favorites|Favorites]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/feedback-loops|Feedback Loops]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/fill-in-the-blanks|Fill in the Blanks]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/fixed-rewards|Fixed rewards]] — Persuasive Design Patterns / Game mechanics / Fundamentals of rewards
- [[concepts/patterns/flagging-and-reporting|Flagging & Reporting]] — User Interface Design Patterns / Getting input / Community driven
- [[concepts/patterns/follow|Follow]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/forgiving-format|Forgiving Format]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/framing|Framing]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/frequently-asked-questions-faq|Frequently Asked Questions (FAQ)]] — User Interface Design Patterns / Dealing with data / Formatting data
- [[concepts/patterns/fresh-start-effect|Fresh Start Effect]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/friend|Friend]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/friend-list|Friend list]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/gallery|Gallery]] — User Interface Design Patterns / Dealing with data / Images
- [[concepts/patterns/goal-gradient-effect|Goal-Gradient Effect]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/good-defaults|Good Defaults]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/guided-tour|Guided Tour]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/halo-effect|Halo Effect]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/hedonic-adaptation|Hedonic Adaptation]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/home-link|Home Link]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/horizontal-dropdown-menu|Horizontal Dropdown Menu]] — User Interface Design Patterns / Navigation / Menus
- [[concepts/patterns/ikea-effect|IKEA effect]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/illusion-of-control|Illusion of control]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/image-zoom|Image Zoom]] — User Interface Design Patterns / Dealing with data / Images
- [[concepts/patterns/inaction-inertia-effect|Inaction Inertia Effect]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/inline-help-box|Inline Help Box]] — User Interface Design Patterns / Getting input / Explaining the process
- [[concepts/patterns/inline-hints|Inline Hints]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/inplace-editor|Inplace Editor]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/input-feedback|Input Feedback]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/input-prompt|Input Prompt]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/intentional-gaps|Intentional Gaps]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/investment-loops|Investment Loops]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/invite-friends|Invite friends]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/isolation-effect|Isolation Effect]] — Persuasive Design Patterns / Perception and memory / Attention
- [[concepts/patterns/kairos|Kairos]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/keyboard-shortcuts|Keyboard Shortcuts]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/lazy-registration|Lazy Registration]] — User Interface Design Patterns / Onboarding / Registration
- [[concepts/patterns/leaderboard|Leaderboard]] — User Interface Design Patterns / Social / Reputation
- [[concepts/patterns/levels|Levels]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/liking|Liking]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/limited-choice|Limited Choice]] — Persuasive Design Patterns / Cognition / Scarcity
- [[concepts/patterns/limited-duration|Limited duration]] — Persuasive Design Patterns / Cognition / Scarcity
- [[concepts/patterns/loss-aversion|Loss Aversion]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/modal|Modal]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/module-tabs|Module Tabs]] — User Interface Design Patterns / Navigation / Tabs
- [[concepts/patterns/morphing-controls|Morphing Controls]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/navigation-tabs|Navigation Tabs]] — User Interface Design Patterns / Navigation / Tabs
- [[concepts/patterns/need-for-closure|Need for Closure]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/negativity-bias|Negativity bias]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/noble-edge-effect|Noble Edge Effect]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/nostalgia-effect|Nostalgia Effect]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/notifications|Notifications]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/optimism-bias|Optimism Bias]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/pagination|Pagination]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/password-strength-meter|Password Strength Meter]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/pattern-recognition|Pattern Recognition]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/pay-to-promote|Pay To Promote]] — User Interface Design Patterns / Getting input / Community driven
- [[concepts/patterns/paywall|Paywall]] — User Interface Design Patterns / Onboarding / Registration
- [[concepts/patterns/peak-end-rule|Peak-end rule]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/periodic-events|Periodic Events]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/picture-superiority-effect|Picture Superiority Effect]] — Persuasive Design Patterns / Perception and memory / Attention
- [[concepts/patterns/playthrough|Playthrough]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/positive-mimicry|Positive Mimicry]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/praise|Praise]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/present-bias|Present Bias]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/preview|Preview]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/pricing-table|Pricing table]] — User Interface Design Patterns / Miscellaneous / Shopping
- [[concepts/patterns/priming-effect|Priming Effect]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/privileges|Privileges]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/product-page|Product page]] — User Interface Design Patterns / Miscellaneous / Shopping
- [[concepts/patterns/progressive-disclosure|Progressive Disclosure]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/prolonged-play|Prolonged Play]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/pull-to-refresh|Pull to refresh]] — User Interface Design Patterns / Navigation / Gestures
- [[concepts/patterns/rate-content|Rate Content]] — User Interface Design Patterns / Getting input / Community driven
- [[concepts/patterns/reaction|Reaction]] — User Interface Design Patterns / Social / Social interactions
- [[concepts/patterns/reciprocation|Reciprocation]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/recognition-over-recall|Recognition over Recall]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/reduction|Reduction]] — Persuasive Design Patterns / Perception and memory / Attention
- [[concepts/patterns/reputation|Reputation]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/retaliation|Retaliation]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/role-playing|Role Playing]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/rule-builder|Rule Builder]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/scarcity|Scarcity]] — Persuasive Design Patterns / Cognition / Scarcity
- [[concepts/patterns/search-filters|Search Filters]] — User Interface Design Patterns / Dealing with data / Search
- [[concepts/patterns/self-expression|Self-Expression]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/self-monitoring|Self-Monitoring]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/sequencing|Sequencing]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/serial-positioning-effect|Serial Positioning Effect]] — Persuasive Design Patterns / Perception and memory / Comprehension
- [[concepts/patterns/set-completion|Set Completion]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/settings|Settings]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/shaping|Shaping]] — Persuasive Design Patterns / Game mechanics / Fundamentals of rewards
- [[concepts/patterns/shopping-cart|Shopping Cart]] — User Interface Design Patterns / Miscellaneous / Shopping
- [[concepts/patterns/shortcut-dropdown|Shortcut Dropdown]] — User Interface Design Patterns / Navigation / Jumping in hierarchy
- [[concepts/patterns/simulation|Simulation]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/slideshow|Slideshow]] — User Interface Design Patterns / Dealing with data / Images
- [[concepts/patterns/social-proof|Social Proof]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/sort-by-column|Sort By Column]] — User Interface Design Patterns / Dealing with data / Tables
- [[concepts/patterns/status|Status]] — Persuasive Design Patterns / Social / Social biases
- [[concepts/patterns/status-quo-bias|Status-Quo Bias]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/steps-left|Steps Left]] — User Interface Design Patterns / Getting input / Explaining the process
- [[concepts/patterns/storytelling|Storytelling]] — Persuasive Design Patterns / Game mechanics / Gameplay design
- [[concepts/patterns/structured-format|Structured Format]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/sunk-cost-effect|Sunk Cost Effect]] — Persuasive Design Patterns / Cognition / Loss Aversion
- [[concepts/patterns/table-filter|Table Filter]] — User Interface Design Patterns / Dealing with data / Tables
- [[concepts/patterns/tag-cloud|Tag Cloud]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/tagging|Tagging]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/tailoring|Tailoring]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/temptation-bundling|Temptation Bundling]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/testimonials|Testimonials]] — User Interface Design Patterns / Social / Reputation
- [[concepts/patterns/thumbnail|Thumbnail]] — User Interface Design Patterns / Navigation / Content
- [[concepts/patterns/tip-a-friend|Tip A Friend]] — User Interface Design Patterns / Miscellaneous / Increasing frequency
- [[concepts/patterns/trigger|Trigger]] — Persuasive Design Patterns / Feedback / Timing
- [[concepts/patterns/tunnelling|Tunnelling]] — Persuasive Design Patterns / Perception and memory / Attention
- [[concepts/patterns/undo|Undo]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/unlock-features|Unlock Features]] — Persuasive Design Patterns / Game mechanics / Gameplay rewards
- [[concepts/patterns/value-attribution|Value Attribution]] — Persuasive Design Patterns / Cognition / Other cognitive biases
- [[concepts/patterns/variable-rewards|Variable Rewards]] — Persuasive Design Patterns / Game mechanics / Fundamentals of rewards
- [[concepts/patterns/vertical-dropdown-menu|Vertical Dropdown Menu]] — User Interface Design Patterns / Navigation / Menus
- [[concepts/patterns/vote-to-promote|Vote To Promote]] — User Interface Design Patterns / Getting input / Community driven
- [[concepts/patterns/walkthrough|Walkthrough]] — User Interface Design Patterns / Onboarding / Guidance
- [[concepts/patterns/wiki|Wiki]] — User Interface Design Patterns / Getting input / Community driven
- [[concepts/patterns/wizard|Wizard]] — User Interface Design Patterns / Getting input / Explaining the process
- [[concepts/patterns/wysiwyg|WYSIWYG]] — User Interface Design Patterns / Getting input / Forms
- [[concepts/patterns/zeigarnik-effect|Zeigarnik Effect]] — Persuasive Design Patterns / Perception and memory / Attention


<!-- ===== ui-patterns/wiki/log.md ===== -->

---
title: "UI Patterns — Activity Log"
created: "2026-07-02"
updated: "2026-07-02"
type: "wiki"
status: "active"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
---
# UI Patterns — Activity Log

## 2026-07-02

- Checked robots policy: `User-agent: *`, `Disallow: /search`.
- Imported the `/patterns` catalog as 170 pattern routing pages.
- Preserved taxonomy, source URLs, detected source sections, example counts, and provenance notes.
- Avoided republishing full source bodies/screenshots because the source site footer says all rights reserved.


<!-- ===== ui-patterns/wiki/summaries/for-agents-ui-patterns-retrieval.md ===== -->

---
title: "For Agents — UI Patterns Retrieval"
created: "2026-07-02"
updated: "2026-07-02"
type: "summaries"
status: "compiled"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
---
# For Agents — UI Patterns Retrieval

> Use this namespace to find candidate UI/product/persuasive design patterns, then retrieve the original source page for exact language and examples.

## Retrieval Loop

1. Identify the product moment: input, navigation, data display, social behavior, onboarding, persuasion, feedback, or game mechanic.
2. Search this namespace by track/group/subgroup/title.
3. Pull 3–8 nearby pattern pages rather than one isolated pattern.
4. Open the source URLs for the finalists before using exact claims, screenshots, or usage constraints.
5. Translate the pattern into product-specific guidance: trigger, user goal, risk, UI move, success/failure signal.
6. Cite pattern names plus source URLs in the recommendation.

## Good Uses

- Product critique and UX review.
- Generating design alternatives for a flow.
- Naming recurring interaction patterns in PRDs/specs.
- Checking persuasive mechanics for ethics/risk before implementation.

## Guardrails

- Do not imply the catalog is commercial-clean training data.
- Do not bulk-quote source pages into public docs.
- Do not treat persuasive patterns as default recommendations; apply Jamie's verb-first/product-urge lens and consider user trust.
- For screenshots, link to the source page instead of copying images.


<!-- ===== ui-patterns/wiki/summaries/provenance-and-copyright-boundary.md ===== -->

---
title: "Provenance and Copyright Boundary"
created: "2026-07-02"
updated: "2026-07-02"
type: "summaries"
status: "compiled"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
---
# Provenance and Copyright Boundary

## Source

- Site: [UI Patterns](https://ui-patterns.com)
- Pattern index: [Design patterns](https://ui-patterns.com/patterns)
- Robots policy: `/search` is disallowed; `/patterns` is not disallowed.
- Footer at retrieval time: `© 2007-2026 Learning Loop ApS. All rights reserved.`

## Boundary

This namespace is a public catalog and retrieval map. It keeps factual routing metadata: titles, taxonomy, URLs, detected section headings, example counts, and source-shape notes. It does not mirror full source explanations, screenshots, examples, comments, or paid product content.

## Allowed Agent Behavior

- Link to source pages.
- Use pattern names/taxonomy as retrieval handles.
- Paraphrase lessons after reading the source and applying them to a specific product context.
- Quote only short bounded snippets when the user explicitly needs exact wording.

## Avoid

- Republishing full pattern pages.
- Copying screenshots into Pixi Wiki.
- Presenting the corpus as a clean dataset for training or commercial redistribution.


<!-- ===== ui-patterns/wiki/summaries/source-taxonomy.md ===== -->

---
title: "Source Taxonomy"
created: "2026-07-02"
updated: "2026-07-02"
type: "summaries"
status: "compiled"
category: "product-design"
namespace: "ui-patterns"
source_url: "https://ui-patterns.com/patterns"
---
# Source Taxonomy

> Imported taxonomy from the UI Patterns `/patterns` page.

## Persuasive Design Patterns

- Cognition: 25 patterns across 3 subgroups
- Feedback: 6 patterns across 1 subgroups
- Game mechanics: 19 patterns across 3 subgroups
- Perception and memory: 12 patterns across 2 subgroups
- Social: 17 patterns across 1 subgroups
## User Interface Design Patterns

- Dealing with data: 11 patterns across 4 subgroups
- Getting input: 29 patterns across 3 subgroups
- Miscellaneous: 5 patterns across 2 subgroups
- Navigation: 26 patterns across 5 subgroups
- Onboarding: 9 patterns across 2 subgroups
- Social: 11 patterns across 2 subgroups