Templates & Tools

Overview

This section provides standardized templates and recommended tools for architecture work. Templates ensure consistency and completeness, while approved tools streamline the architecture process.

Templates

Architecture Documents

• Solution Architecture Document
• Technical Design Document
• Architecture Vision Document
• System Context Document

Architecture Artifacts

• Architecture Decision Record (ADR)
• Request for Comments (RFC)
• Non-Functional Requirements (NFR)
• Architecture Review Checklist

Diagrams

• C4 Model Templates
• Data Flow Diagrams
• Sequence Diagrams
• Infrastructure Diagrams

Project & Process

• Architecture Service Request Form
• ARB Submission Template
• Technology Evaluation Template
• Proof of Concept Template

Specialized Templates

• API Specification Template
• Security Architecture Template
• Data Architecture Template
• Migration Plan Template

Recommended Tools

Diagramming Tools

Structurizr (Primary)

• Purpose: C4 model diagrams as code
• License: Freemium (free for open source)
• Why: Purpose-built for C4, version control friendly
• Getting Started: Structurizr Guide

PlantUML (Primary)

• Purpose: Text-based diagrams (UML, C4, sequences, etc.)
• License: Open source
• Why: Diagrams as code, CI/CD integration, widely supported
• Getting Started: PlantUML Guide

Draw.io / Diagrams.net (Secondary)

• Purpose: General diagramming
• License: Free
• Why: Easy collaboration, templates available
• Getting Started: Draw.io Guide

Miro (Workshops)

• Purpose: Collaborative workshops and brainstorming
• License: Freemium
• Why: Real-time collaboration, great for workshops
• Getting Started: Miro Guide

Documentation Tools

Markdown (Primary)

• Purpose: All documentation
• Why: Simple, version control friendly, portable
• Standard: CommonMark with GitHub extensions

Confluence (Secondary)

• Purpose: Stakeholder-facing documentation
• Why: Good for collaboration, familiar to organization
• Integration: Export from Markdown to Confluence

GitHub/GitLab (Primary)

• Purpose: Documentation repository and ADRs
• Why: Co-located with code, PR workflow, search

Modeling Tools

ArchiMate (Enterprise Architecture)

• Purpose: Enterprise architecture modeling
• Tool: Archi (open source)
• When: Enterprise-level architecture

Enterprise Architect

• Purpose: UML and enterprise modeling
• License: Commercial
• When: Complex UML requirements

Cloud Architecture Tools

AWS Tools

• CloudFormation Designer: Infrastructure diagrams
• AWS Architecture Icons: Official icon set
• Well-Architected Tool: Architecture reviews
• AWS Tools Guide

Azure Tools

• Azure Architecture Center: Reference architectures
• Azure Icons: Official icon set
• Azure Advisor: Architecture recommendations
• Azure Tools Guide

Terraform

• Purpose: Infrastructure as Code
• Why: Multi-cloud, declarative, widely adopted
• Terraform Guide

API Tools

OpenAPI / Swagger

• Purpose: API specification and documentation
• Tools: Swagger Editor, Swagger UI
• OpenAPI Guide

Postman

• Purpose: API testing and documentation
• License: Freemium
• Postman Guide

AsyncAPI

• Purpose: Event-driven API documentation
• Why: Standard for async/event APIs
• AsyncAPI Guide

Analysis Tools

Architecture Decision Records (ADR) Tools

• log4brains: Web-based ADR management
• adr-tools: Command-line ADR tools
• ADR Tools Guide

Dependency Analysis

• Structure101: Architecture enforcement
• SonarQube: Code quality and architecture metrics
• ArchUnit: Architecture unit tests

Collaboration Tools

Slack

• Channels: #architecture, #architecture-reviews, #architecture-patterns
• Purpose: Quick discussions, Q&A, announcements

Microsoft Teams

• Team: Solution Architecture Practice
• Purpose: Meetings, file sharing, collaboration

Zoom

• Purpose: Architecture reviews, workshops, office hours

Tool Selection Criteria

When evaluating new tools, consider:

Must Have

• ✅ Supports version control / diagrams as code
• ✅ Enables collaboration
• ✅ Exports to portable formats
• ✅ Reasonable cost (prefer free/open source)
• ✅ Active maintenance and community

Nice to Have

• Integration with existing tools
• CI/CD integration
• API availability
• Cloud-based for accessibility
• Mobile support

Avoid

• ❌ Proprietary formats only
• ❌ No export capabilities
• ❌ Expensive licensing
• ❌ Desktop-only with no collaboration
• ❌ Abandoned/unmaintained

Template Usage Guidelines

When to Use Templates

Always Use:

• Solution Architecture Documents
• ADRs for significant decisions
• ARB submissions
• NFR specifications

Use When Appropriate:

• RFCs for major changes needing feedback
• Technology evaluations
• POC documentation
• Migration plans

Optional:

• Informal diagrams
• Quick sketches
• Exploratory work

Customizing Templates

Templates are starting points, not rigid requirements:

• ✅ Add sections relevant to your project
• ✅ Remove irrelevant sections
• ✅ Adapt language to your audience
• ❌ Don’t skip required sections without reason
• ❌ Don’t completely ignore the template structure

Template Governance

• Templates reviewed annually
• Feedback collected from architects
• Updates communicated to practice
• Old versions marked deprecated

Getting Help

Template Questions

• Post in #architecture Slack channel
• Architecture office hours
• Email solution-architecture@company.com

Tool Support

• Tool-specific channels in Slack
• IT helpdesk for license/access issues
• Tool champions within the practice

Training

• Monthly tool training sessions
• Self-paced guides in this section
• External vendor training when available

Contributing

Have a template or tool recommendation?

1. Create a proposal document
2. Share with Architecture Council
3. Pilot with a few projects
4. Submit for formal approval
5. Document and share with practice

---

Back to Home