Solution designs
Where a reference architecture is a reusable pattern, a solution design describes how one concrete initiative will be built: its requirements, design, trade-offs, risks, and rollout. It's the document a delivery team and its architects agree on before the first line of code.
Solution designs are available on the Pro and Enterprise plans. Creating one needs the Member role or higher.
1. Create a solution design
- Open Solution Designs in the sidebar.
- Choose + New Solution Design.
- Fill in the form:
- Title: name the initiative, for example Real-time fraud scoring for checkout.
- Authors: add the people writing the design with you as co-authors.
- Diagram (Mermaid): required. See The diagram.
- Body (Markdown): pre-filled from your workspace's solution design template.
- Choose Create draft. The design starts in Draft.
2. The diagram
Every solution design leads with a Mermaid diagram, shown at the top of its page.
- Type or paste Mermaid source into Diagram (Mermaid). A live preview renders beside it.
- Paste the source only. Surrounding
```mermaidfences are removed for you. - While the box is empty, Add example diagram fills in a sample to edit.
You can include more diagrams in the body too: any ```mermaid code block
in the Markdown renders as a diagram, which is handy for sequence diagrams in
the detailed design.
3. Fill in the template
The built-in template walks through a complete design:
| Section | What to write |
|---|---|
| Summary | The problem and the proposed solution, in brief. |
| Requirements | Functional and non-functional requirements the design must meet. |
| Solution overview | The major components, walking through the diagram. |
| Detailed design | Components, data flows, integrations, and interfaces. |
| Decisions & trade-offs | Key choices, rejected alternatives, and why. Mention the related ADRs. |
| Non-functional considerations | Security, performance, scalability, availability, cost, and operability. |
| Risks & dependencies | Known risks, their mitigations, and external dependencies. |
| Rollout | Delivery phases, migration approach, and rollback plan. |
Admins can tailor the template for your workspace in Artifact types and templates.
4. Review and sign-off
While a design is in Draft or Changes Requested, its authors (and admins) can choose Edit and Save draft.
When it's ready:
- Choose Propose for review and pick a reviewer.
- The reviewer chooses Publish, Reject, or Request changes. Requested changes arrive as a checklist on the design.
- Work through the checklist, then choose Resubmit for review. It goes back to the same reviewer.
Every round is kept under Review history on the design's page. A published design can later be marked Superseded or Deprecated. See Reviewing and approving for the full flow.
5. Browse solution designs
The Solution Designs list has two views, switched with the List / Diagrams toggle:
- List: ref ID, title, status, reviewer, and last update, with a Rows per page picker.
- Diagrams: each design as a panel showing its live diagram, 10 per page.
ArchForge remembers your choice of view in this browser.