Reference architectures
A reference architecture is a vetted, reusable blueprint for a recurring problem: a multi-region platform, an event-driven backbone, a zero-trust edge. Each one leads with a diagram and walks through the drivers, building blocks, and guidance teams need to adopt it.
Reference architectures are available on every plan (Free, Pro, and Enterprise). Creating one needs the Member role or higher.
1. Create a reference architecture
- Open Reference Architectures in the sidebar.
- Choose + New Reference Architecture.
- Fill in the form:
- Title: a short, specific name, for example Multi-region active-active platform.
- Authors: you are the author. Add co-authors to let them edit the draft with you.
- Diagram (Mermaid): required. See The diagram below.
- Body (Markdown): pre-filled from your workspace's reference architecture template.
- Choose Create draft. The new reference architecture starts in Draft.
2. The diagram
Every reference architecture carries a Mermaid diagram, and it is shown at the top of the page.
- Type or paste Mermaid source into the Diagram (Mermaid) box. A live preview renders beside it as you type.
- Paste the source only. If you do paste a block wrapped in
```mermaidfences, ArchForge removes the fences for you. - Starting from scratch? While the box is empty, choose Add example diagram to drop in a sample flowchart you can edit.
You can't create the draft without a diagram: the form shows Diagram is required until you add one.
3. Fill in the template
The body starts from your workspace's template. The built-in template has these sections:
| Section | What to write |
|---|---|
| Overview | What the architecture describes, and when to use it. |
| Context & drivers | Business and technical drivers, constraints, and assumptions. |
| Architecture | The recommended structure, walking through the diagram. |
| Building blocks | Each component with its responsibility and technology. |
| Patterns & guidance | Recommended patterns, anti-patterns, and key decisions. |
| Quality attributes | Security, scalability, availability, cost, and operability. |
| Adoption | How teams apply the architecture, and what they may tailor. |
Admins can change this template for your workspace. See Artifact types and templates.
4. Edit and propose for review
While a reference architecture is in Draft or Changes Requested, its authors (and admins) can choose Edit to change the title, authors, diagram, and body, then Save draft.
When it's ready, choose Propose for review and pick a reviewer. The reviewer can publish it, reject it, or request changes. Once Published, it can later be marked Superseded or Deprecated. The full flow is described in Reviewing and approving.
5. Browse the library
The Reference Architectures list offers two views. Switch between them with the List / Diagrams toggle next to the + New button:
- List: a table of ref ID, title, status, reviewer, and last update. Use Rows per page under the table to show 10 to 50 rows, or All.
- Diagrams: each reference architecture as a panel showing its live diagram, 10 per page.
ArchForge remembers your choice of view in this browser.
Used in composites
On the Enterprise plan, reference architectures can be combined into composite reference architectures. A reference architecture page lists every composite built from it under Used in composites, with each composite's status, so you can see what a change to the blueprint will affect.