title: ADR Creation Katas description: Streamlined practice for OSS edge computing architecture decision records author: Edge AI Team ms.date: 2025-09-18 ms.topic: kata-category estimated_reading_time: 5 difficulty: foundation to legendary duration: 45-90 minutes
category: adr-creation prerequisite_katas: [] role_relevance:
- solution-architect
- edge-engineer
- developer target_audience:
- Solution Architects
- Edge Engineers
- Software Developers
- Project Managers learning_objectives:
- Create structured Architecture Decision Records (ADRs) for edge computing technologies
- Apply decision criteria frameworks for technology selection
- Document architectural decisions with clear rationale and trade-offs
- Follow established ADR templates and formatting standards
content_type: hands-on real_world_application: Real-world technology decisions for edge computing projects using OSS technologies complexity_factors:
- Understanding multiple technology options and trade-offs
- Balancing technical and business requirements
- Documenting decisions clearly for future reference
uses_prompts: [] uses_instructions: [] uses_agents: [] repository_paths:
- project-adrs/
- docs/solution-adr-library/
- docs/solution-technology-paper-library/ repository_integration:
- "project-adrs/"
- ".github/copilot-instructions.md"
success_criteria:
- Complete ADR documents following established templates
- Clear documentation of decision criteria and rationale
- Proper use of ADR status and consequences sections
- Integration with project ADR library common_pitfalls:
- "Insufficient decision criteria": Ensure all relevant factors are considered and documented
- "Missing trade-off analysis": Document both pros and cons of each option
- "Poor formatting": Follow established ADR templates and markdown formatting
keywords:
- adr creation
- architectural decision records
- edge computing
- oss technologies tags:
- architecture
- documentation
- decision-making
ai_coaching_enabled: true validation_checkpoints:
- "ADR structure completion: Verify all required ADR sections are present and properly formatted"
- "Decision criteria validation: Confirm all relevant technical and business factors are documented"
- "Trade-off analysis quality: Ensure comprehensive pros/cons analysis for each option" extension_challenges:
- challenge_name: Multi-Technology Stack ADR description: Create comprehensive ADR for full edge computing stack including messaging, observability, and service mesh difficulty: advanced estimated_time: 60 minutes
- challenge_name: Cross-Team ADR Review description: Conduct peer review process for ADR validation and consensus building difficulty: intermediate estimated_time: 30 minutes troubleshooting_guide: | Common Issues:
- ADR format not recognized: Use the provided templates in project-adrs/adr-template.md
- Missing decision context: Include problem statement and constraints in context section
- Incomplete options analysis: Document at least 2-3 viable alternatives with clear trade-offs
Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions made during edge computing projects. These katas provide hands-on practice creating ADRs for real technology choices you'll encounter in edge AI implementations.
📊 Track Your Progress - Monitor your progress on your learning journey
This kata category includes AI coaching support to help guide you through:
- ADR structure and formatting best practices
- Decision criteria framework application
- Technology trade-off analysis techniques
- Real-world decision scenario guidance
By completing these ADR creation katas, you will:
- Learn ADR Structure: Create well-formatted Architecture Decision Records following industry standards
- Apply Decision Frameworks: Use systematic criteria to evaluate technology alternatives
- Analyze Trade-offs: Document technical, operational, and business implications of architectural choices
- Communicate Decisions: Write clear, concise ADRs that stakeholders can understand and act upon
- Build Decision Skills: Develop consistent approaches to architectural decision-making
These progressive katas prepare you for:
- Technology Selection: Systematic evaluation of edge computing technologies from messaging to AI platforms
- Stakeholder Communication: Clear documentation of architectural decisions with increasing sophistication
- Decision Tracking: Comprehensive ADR management in real projects across multiple domains
- Architecture Governance: Consistent decision-making processes for distributed systems
- Edge AI Architecture: Platform selection for computer vision, inference optimization, and MLOps at the edge
- Network Architecture: Site-to-site connectivity, VPN topology design, and industrial data flow patterns
Streamlined practice creating Architecture Decision Records (ADRs) for open-source edge computing technologies following Azure architecture decision guides. These optimized katas focus on real technology decisions you'll encounter in edge computing projects with minimal reading overhead.
- ADR Structure: Create well-formatted Architecture Decision Records following established templates
- Decision Criteria: Apply systematic frameworks to evaluate technology alternatives
- Trade-off Analysis: Document technical, operational, and business implications of architectural choices
- Stakeholder Communication: Write clear, concise ADRs that stakeholders can understand and act upon
Practice with real project ADR examples and templates:
- ADR Templates: Use solution ADR templates for structured decision documentation
- Real Examples: Study solution ADR library for practical patterns from customer projects
- Solution Libraries: Reference technology papers for decision context
| # | Kata Title | Difficulty | Duration | Prerequisites | Technology Focus | Scaffolding |
|---|---|---|---|---|---|---|
| 100 | 100 - Basic Messaging Architecture | ⭐ Foundation | 60 min | — | Architecture Decision Records, MQTT, Apache Kafka | Heavy |
| 200 | 200 - Advanced Observability Stack | ⭐⭐ Skill | 50 min | → 100 | comparing TIG vs TICK stack for edge observability and monitoring | Medium-Heavy |
| 400 | 400 - Service Mesh Selection | ⭐⭐⭐⭐ Expert | 90 min | → 200 | Istio, Linkerd, Open Service Mesh | Light |
| 500 | 500 - Cross-Site Industrial Data Architecture | ⭐⭐⭐⭐⭐ Legendary | 180 min | → 100, 200, 400 | Azure VPN Gateway, Azure IoT Operations, MQTT Broker | Light |
| 500 | 500 - Edge AI Inference Platform Selection | ⭐⭐⭐⭐⭐ Legendary | 150 min | → 100, 200, 400 | Azure IoT Edge, ONNX Runtime, NVIDIA Triton | Light |
- Focus: Learn foundational ADR creation through systematic evaluation and documentation of messaging technology decisions for distributed systems
- Skills: Architecture Decision Records, MQTT, Apache Kafka, GitHub Copilot
- Time-to-Practice: 1-2 hours
- Focus: Learn complex ADR creation through multi-component evaluation, comparing TIG vs TICK stack for edge observability and monitoring
- Skills: Telegraf, InfluxDB, Grafana, Chronograf, Kapacitor
- Time-to-Practice: Under 1 hour
- Focus: Create an ADR for service mesh technology selection in edge computing environments with industrial automation requirements
- Skills: Istio, Linkerd, Open Service Mesh, Kubernetes, Azure IoT Operations
- Time-to-Practice: 1-2 hours
- Focus: Design site-to-site VPN architecture for manufacturing data flow with Azure IoT Operations, MQTT bridging, and real-time operational requirements and Compare edge AI inference platforms for real-time drone defect detection with performance, MLOps, and connectivity resilience requirements
- Skills: Azure VPN Gateway, Azure IoT Operations, MQTT Broker, Site-to-Site VPN, Azure Arc
- Time-to-Practice: 6 hours
- Basic understanding of software architecture concepts
- Familiarity with edge computing scenarios (helpful but not required)
- Ready to engage with hands-on decision documentation practice
Before starting these ADR creation katas, ensure you have:
- Access to the project ADR templates and solution ADR library
- A text editor or IDE with Markdown support
- Basic familiarity with Architecture Decision Records format
- Understanding of edge computing technology categories (messaging, observability, networking, AI/ML)
These katas guide you through creating Architecture Decision Records for edge computing scenarios:
- Foundational ADR Skills: Learn core ADR structure using messaging technology selection scenarios
- Multi-Component Decisions: Practice evaluating complex observability stacks with multiple integrated components
- Advanced Architecture: Apply ADR methodology to service mesh selection and distributed system patterns
- Expert Integration: Develop expertise in cross-site networking and edge AI platform architecture decisions
Each kata provides progressive reduction in scaffolding, building your ability to independently create comprehensive ADRs.
You'll know you've successfully completed this kata category when you can:
- Create well-structured ADRs following established templates without guidance
- Apply systematic decision frameworks to evaluate technology alternatives
- Document comprehensive trade-off analyses for architectural choices
- Write clear, stakeholder-ready ADRs that communicate decisions effectively
- Leverage AI tools (agents, Ask mode) appropriately throughout the decision process
Ready to start practicing ADR creation?
📋 Begin with 01 - Basic Messaging Architecture
Learn architectural decision documentation through streamlined, focused practice.
🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.