Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Expert architecture documentation covering ADR (Architecture Decision Records) format, C4 model diagrams, system context diagrams, sequence diagrams, deployment diagrams, technology radar, architectural fitness functions, and documentation-as-code.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
491 lines · 2,241 words
This skill provides comprehensive expertise in documenting software architecture. Effective architecture documentation communicates the system's structure, decisions, and rationale to both current and future team members. This skill covers industry-standard formats and models including ADRs, C4 diagrams, deployment views, and the documentation-as-code approach that keeps architecture docs living and accurate.
Expert architecture documentation covering ADR (Architecture Decision Records) format, C4 model diagrams, system context diagrams, sequence diagrams, deployment diagrams, technology radar, architectural fitness functions, and documentation-as-code.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Architecture Documenter skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
Overview
Architecture Decision Records (ADRs)
C4 Model
Sequence Diagrams
Deployment Diagrams
Technology Radar
Architectural Fitness Functions
Documentation-as-Code
Documentation Quality Checklist
When to Use
Output Format
Example
Edge Cases
# ADR-0015: Use PostgreSQL as Primary Database
## Status
Accepted (2025-01-15)
Supersedes: ADR-0003 (Use MongoDB)
## Context
We need a persistent data store for our product catalog and order management
system. The data has strong relational characteristics (products belong to
categories, orders contain line items, users have addresses). We expect:
- 10M+ product records
- 50K+ orders per day
- Complex queries joining 3-5 tables
- Strong consistency requirements for financial data
- Full-text search on product names and descriptions
We evaluated: PostgreSQL, MySQL, MongoDB, and CockroachDB.
# ... (condensed) ...
- If we exceed 1TB of data, we may need to evaluate sharding strategies
or move to a distributed database. We will re-evaluate at 500GB.
## Follow-Up Actions
- [ ] Set up PostgreSQL 16 in staging environment
- [ ] Create database migration pipeline with Flyway
- [ ] Establish backup and point-in-time recovery procedures
- [ ] Document connection pooling strategy (PgBouncer)ADR States:
├── Proposed → Under discussion, not yet decided
├── Accepted → Decision made, implementation proceeding
├── Deprecated → No longer applies but was once valid
├── Superseded → Replaced by a newer ADR (link to replacement)
└── Rejected → Considered but not adopted (document why)
File Naming: docs/adr/XXXX-title-with-dashes.md
Example: docs/adr/0015-use-postgresql-as-primary-database.md
Index File: docs/adr/README.md
- List all ADRs with status, date, and one-line summary
- Group by domain (data, infrastructure, frontend, etc.)Write an ADR when:
├── Choosing a technology (database, framework, cloud provider)
├── Selecting an architecture pattern (microservices, CQRS, event sourcing)
├── Making a trade-off (consistency vs. availability, build vs. buy)
├── Establishing a standard (API style, error format, auth mechanism)
├── Changing a previous decision (must supersede the old ADR)
└── Making a decision that future team members will question
Do NOT write an ADR for:
├── Implementation details that can change without impact
├── Coding style preferences (use a linter config instead)
├── Trivial decisions with obvious answers
└── Temporary decisions (use a TODO or ticket instead)C4 Model Levels:
Level 1: System Context → "What is this system and who uses it?"
Level 2: Container → "What are the major building blocks?"
Level 3: Component → "What is inside each container?"
Level 4: Code → "How is a component implemented?" (rarely needed)
Key Principle: Each level zooms in on the previous level.
Audience shifts from business stakeholders (L1) to developers (L4).System Context Diagram Template (as code using Structurizr DSL):
workspace {
model {
customer = person "Customer" "A user who browses and purchases products"
admin = person "Admin" "Internal staff who manage the product catalog"
productSystem = softwareSystem "Product Catalog System" "Manages product listings, search, and inventory" {
tags "Primary"
}
paymentGateway = softwareSystem "Payment Gateway" "Processes credit card payments" {
tags "External"
}
emailService = softwareSystem "Email Service" "Sends transactional emails" {
tags "External"
}
analytics = softwareSystem "Analytics Platform" "Tracks user behavior" {
tags "External"
}
customer -> productSystem "Browses products, places orders"
admin -> productSystem "Manages catalog and inventory"
productSystem -> paymentGateway "Processes payments" "HTTPS/REST"
productSystem -> emailService "Sends order confirmations" "SMTP"
productSystem -> analytics "Sends events" "HTTPS"
}
views {
systemContext productSystem "SystemContext" {
include *
autoLayout
}
}
}Container Diagram Elements:
┌───────────────── Product Catalog System ─────────────────┐
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Web App │ │ Mobile │ │ Admin Dashboard │ │
│ │ (React) │ │ App (RN) │ │ (React + Vite) │ │
│ └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │
│ │ │ │ │
│ └──────────────┼────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ API Gateway │ │
│ │ (Kong) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌───────────┼───────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌─────────┐ ┌──────────┐ │
│ │ Product │ │ Order │ │ User │ │
│ │ Service │ │ Service │ │ Service │ │
# ... (condensed) ...
│ │(products)│ │ (orders) │ │ (users) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Redis │ │ RabbitMQ │ │
│ │ (cache) │ │ (events) │ │
│ └──────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────────┘## Order Placement Flow
\```mermaid
sequenceDiagram
actor Customer
participant Web as Web App
participant API as API Gateway
participant Order as Order Service
participant Product as Product Service
participant Payment as Payment Gateway
participant Email as Email Service
Customer->>Web: Click "Place Order"
Web->>API: POST /orders
API->>Order: Create order
Order->>Product: Check inventory
Product-->>Order: Inventory confirmed
Order->>Payment: Charge card
Payment-->>Order: Payment successful
Order->>Product: Decrement inventory
Order->>Email: Send confirmation
Email-->>Customer: Order confirmation email
Order-->>API: Order created (201)
API-->>Web: Order response
Web-->>Customer: Show confirmation page
\```Use sequence diagrams for:
├── Multi-service request flows (API calls across microservices)
├── Authentication/authorization flows (OAuth, JWT refresh)
├── Error handling flows (what happens when service X fails?)
├── Async workflows (event-driven processes)
└── Third-party integration flows (payment, shipping, etc.)
Keep diagrams focused:
├── Maximum 6-8 participants per diagram
├── Maximum 15-20 interactions per diagram
├── Split complex flows into sub-diagrams
└── Name the diagram after the scenario, not the system## Deployment Architecture
### Production Environment
\```
┌─────────────────── AWS us-east-1 ───────────────────────┐
│ │
│ ┌─── VPC 10.0.0.0/16 ────────────────────────────┐ │
│ │ │ │
│ │ ┌─── Public Subnet ──────┐ │ │
│ │ │ ALB (Application │ │ │
│ │ │ Load Balancer) │ │ │
│ │ │ ├── HTTPS:443 │ │ │
│ │ │ └── WAF attached │ │ │
│ │ └─────────┬───────────────┘ │ │
│ │ │ │ │
│ │ ┌─── Private Subnet ─────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ ECS Fargate Cluster │ │ │
│ │ │ ├── Product Service (3 tasks, 512MB) │ │ │
│ │ │ ├── Order Service (3 tasks, 1GB) │ │ │
│ │ │ └── User Service (2 tasks, 512MB) │ │ │
# ... (condensed) ...
| Aspect | Development | Staging | Production |
|--------|------------|---------|------------|
| Compute | Docker Compose | ECS (1 task each) | ECS (2-5 tasks each) |
| Database | PostgreSQL 16 (local) | RDS db.t3.medium | RDS db.r6g.xlarge (Multi-AZ) |
| Cache | Redis (local) | ElastiCache (1 node) | ElastiCache (3 nodes) |
| CDN | None | CloudFront | CloudFront |
| Monitoring | Console logs | CloudWatch | CloudWatch + Datadog |
| Cost | $0 | ~$500/mo | ~$3,500/mo |# Technology Radar - Q1 2025
## Adopt (Use in production with confidence)
| Technology | Category | Notes |
|-----------|----------|-------|
| TypeScript 5.x | Language | Standard for all new services |
| PostgreSQL 16 | Database | Primary relational store |
| React 19 | Frontend | Web application framework |
| GitHub Actions | CI/CD | All pipelines migrated |
| Terraform | Infrastructure | IaC standard |
## Trial (Use in non-critical projects to gain experience)
| Technology | Category | Notes |
|-----------|----------|-------|
| Bun | Runtime | Evaluate for build tooling |
| Drizzle ORM | Database | Evaluate vs. Prisma |
| htmx | Frontend | Evaluate for admin tools |
| OpenTelemetry | Observability | Pilot in one service |
## Assess (Research and prototype, not production yet)
# ... (condensed) ...
## Hold (Do not start new projects with these)
| Technology | Category | Notes |
|-----------|----------|-------|
| MongoDB | Database | Migrating away; poor fit for relational data |
| Express.js | Framework | Replaced by Fastify for new services |
| Jenkins | CI/CD | Fully replaced by GitHub Actions |
| Webpack | Bundler | Replaced by Vite |# Architectural Fitness Functions
Automated checks that verify the system conforms to architectural decisions.
## Dependency Rules
**Rule**: Domain layer must not depend on infrastructure layer.
\```python
# ArchUnit-style test (Python with import-linter)
# .importlinter config
[importlinter:contract:domain-independence]
name = Domain must not import from infrastructure
type = forbidden
source_modules =
app.domain
forbidden_modules =
app.infrastructure
sqlalchemy
redis
httpx
\```
# ... (condensed) ...
**Rule**: Frontend bundle must be under 250KB gzipped.
\```javascript
// webpack-bundle-analyzer or vite-plugin-inspect
// CI check:
// gzip -c dist/assets/*.js | wc -c must be < 256000
\```| Tool | Purpose | Format |
|---|---|---|
| Structurizr | C4 model diagrams | DSL (text-based) |
| Mermaid | Inline diagrams in Markdown | Markdown code blocks |
| PlantUML | UML diagrams | Text-based DSL |
| Docusaurus | Documentation site | Markdown + React |
| MkDocs | Documentation site | Markdown + YAML |
| AsciiDoc | Technical documents | Markup language |
docs/
├── adr/
│ ├── README.md # ADR index
│ ├── 0001-use-typescript.md
│ ├── 0002-microservices.md
│ └── template.md
├── architecture/
│ ├── overview.md # C4 Level 1 + Level 2
│ ├── data-model.md # ER diagrams, schema docs
│ ├── deployment.md # Deployment diagrams
│ └── security.md # Threat model, auth flows
├── api/
│ └── openapi.yaml # API specification
├── runbooks/
│ ├── incident-response.md
│ └── database-failover.md
├── onboarding/
│ ├── getting-started.md
│ └── architecture-overview.md
└── diagrams/
├── workspace.dsl # Structurizr workspace
└── generated/ # Generated diagram images# .github/workflows/docs.yml
name: Documentation
on:
push:
paths: ['docs/**']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint Markdown
run: npx markdownlint-cli docs/**/*.md
- name: Check links
run: npx markdown-link-check docs/**/*.md
- name: Generate diagrams
run: |
docker run --rm -v $(pwd):/usr/local/structurizr \
structurizr/cli export -w docs/diagrams/workspace.dsl -f mermaid
- name: Build docs site
run: npx docusaurus build
- name: Deploy
if: github.ref == 'refs/heads/main'
run: npx docusaurus deploySystem context diagram exists and is current
Container diagram shows all major building blocks
Key decisions are captured as ADRs
Sequence diagrams cover critical flows (auth, order, payment)
Deployment diagram matches actual infrastructure
Technology radar is updated quarterly
At least 3 architectural fitness functions are automated
Docs are version-controlled alongside code
Diagrams are generated from text (not manually drawn images)
New team members can understand the system within 1 day of reading docs
Stale documentation review scheduled quarterly
CI validates documentation on every change
Use this skill when:
Designing or implementing architecture documenter solutions
Reviewing or improving existing architecture documenter approaches
Making architectural or implementation decisions about architecture documenter
Learning architecture documenter patterns and best practices
Troubleshooting architecture documenter-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Architecture Documenter Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement architecture documenter for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended architecture documenter approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When architecture documenter must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
491 lines · 2,241 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Architecture Documenter bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for