gh-dotclaude-marketplace-plugins-adaptive-learning/commands/learn_architecture.md

---
model: claude-opus-4-1
allowed-tools: Task, Read, Write, Bash(*), Glob, Grep
argument-hint: <system> [--learning-objective=<goal>] [--complexity-progression=<approach>] [--pathway=<exploration-style>]
description: Scaffolded system architecture exploration with progressive complexity building
---

# Architectural Learning System

Guide systematic architecture understanding through progressive complexity building, pattern recognition development, and hands-on exploration with adaptive scaffolding. Transform complex system architecture into accessible learning journeys that build deep understanding through guided discovery and practical investigation.

## Learning Objective Framework

### Comprehension Level (Understanding existing architecture)
[Extended thinking: Focus on understanding decisions already made, components already in place, and relationships already established in existing systems.]

**Learning Goals:**
- **Component Understanding**: Identify and understand individual system components and their responsibilities
- **Relationship Mapping**: Understand how components interact and depend on each other
- **Decision Rationale**: Comprehend why specific architectural choices were made
- **Pattern Recognition**: Identify common architectural patterns and their applications
- **Trade-off Awareness**: Understand benefits and costs of current architectural decisions

**Exploration Methods:**
- System documentation analysis with guided comprehension
- Component deep-dive investigation with scaffolded complexity
- Data flow tracing with step-by-step pathway exploration
- Interface examination with interaction pattern analysis
- Historical evolution study with decision context understanding

### Analysis Level (Evaluating architectural trade-offs)
[Extended thinking: Develop critical evaluation skills for assessing architectural decisions, comparing alternatives, and understanding implications.]

**Learning Goals:**
- **Trade-off Evaluation**: Analyze benefits and costs of architectural decisions
- **Alternative Assessment**: Compare different approaches and understand their implications
- **Quality Attribute Analysis**: Evaluate architecture against performance, security, maintainability criteria
- **Scalability Assessment**: Understand how architecture handles growth and change
- **Risk Identification**: Recognize potential architectural vulnerabilities and limitations

**Exploration Methods:**
- Comparative analysis with multiple system examination
- What-if scenario exploration with alternative consideration
- Quality attribute testing with measurement and evaluation
- Bottleneck identification with performance analysis
- Failure mode analysis with resilience assessment

### Synthesis Level (Designing new architectural solutions)
[Extended thinking: Develop creative capability for designing new architectural solutions that address specific requirements and constraints.]

**Learning Goals:**
- **Requirements Translation**: Convert functional requirements into architectural decisions
- **Pattern Application**: Apply architectural patterns appropriately to solve design problems
- **Component Design**: Create well-designed components with clear responsibilities
- **Integration Strategy**: Design effective component interaction and data flow
- **Evolution Planning**: Design architectures that can adapt and evolve over time

**Exploration Methods:**
- Design exercise completion with guided creativity
- Pattern application practice with scaffolded implementation
- Requirements analysis with architectural translation
- Prototype development with iterative refinement
- Peer review participation with collaborative learning

### Evaluation Level (Assessing and comparing architectural alternatives)
[Extended thinking: Develop sophisticated judgment for evaluating architectural alternatives and making informed decisions about system design.]

**Learning Goals:**
- **Multi-Criteria Assessment**: Evaluate architectures against multiple quality attributes
- **Context Sensitivity**: Understand how context affects architectural appropriateness
- **Future Readiness**: Assess architecture's ability to handle future requirements
- **Decision Justification**: Articulate reasoning for architectural choices
- **Optimization Identification**: Recognize opportunities for architectural improvement

**Exploration Methods:**
- Architecture review facilitation with evaluation criteria application
- Decision framework development with structured analysis
- Future scenario planning with adaptability assessment
- Optimization identification with improvement planning
- Cross-system comparison with pattern extraction

## Complexity Progression Framework

### Component Level (Individual service/module understanding)
[Extended thinking: Start with single components to build foundational understanding before tackling system-wide complexity.]

**Progression Strategy:**
1. **Single Component Deep Dive**: Understand one component's responsibilities, interfaces, and implementation
2. **Interface Analysis**: Examine how component exposes functionality and manages dependencies
3. **Internal Structure**: Explore component's internal organization and design patterns
4. **Quality Attributes**: Assess component's performance, security, and maintainability characteristics
5. **Evolution Patterns**: Understand how component has changed over time and why

**Scaffolding Approach:**
- Start with simplest, most isolated components
- Use visual diagrams to represent component structure
- Provide concrete examples of component behavior
- Connect component design to familiar concepts
- Gradually introduce technical vocabulary and concepts

### Interaction Level (Service communication and data flow)
[Extended thinking: Build understanding of how components work together, focusing on interfaces, protocols, and data exchange patterns.]

**Progression Strategy:**
1. **Two-Component Interaction**: Understand communication between two related components
2. **Protocol Analysis**: Examine communication methods and data formats
3. **Data Flow Tracing**: Follow information as it moves through component interactions
4. **Error Handling**: Understand how components handle interaction failures
5. **Multi-Component Coordination**: Explore how multiple components coordinate for complex operations

**Scaffolding Approach:**
- Use sequence diagrams to visualize interactions
- Trace specific user scenarios through component communications
- Provide hands-on exploration of API calls and data formats
- Build understanding of synchronous vs. asynchronous patterns
- Connect interaction patterns to familiar communication analogies

### System Level (End-to-end architecture comprehension)
[Extended thinking: Develop holistic understanding of complete system architecture including all components, interactions, and emergent properties.]

**Progression Strategy:**
1. **System Boundary Definition**: Understand what's inside vs. outside the system
2. **Subsystem Organization**: Recognize how system is organized into logical groupings
3. **Cross-System Data Flows**: Trace information as it flows through entire system
4. **Quality Attribute Emergence**: Understand how system-level properties emerge from component interactions
5. **Evolution and Growth**: Comprehend how system architecture supports change and scaling

**Scaffolding Approach:**
- Build system understanding through layered architectural views
- Use real user scenarios to demonstrate end-to-end system behavior
- Provide multiple perspectives (logical, physical, deployment) on same system
- Connect system design to business capabilities and user value
- Guide recognition of architectural patterns at system level

### Ecosystem Level (Multi-system integration understanding)
[Extended thinking: Develop understanding of how systems integrate with other systems, platforms, and external services in broader technological ecosystems.]

**Progression Strategy:**
1. **External Dependencies**: Identify and understand systems that this system depends on
2. **Integration Patterns**: Recognize common patterns for system-to-system communication
3. **Data Consistency**: Understand how data consistency is maintained across system boundaries
4. **Service Boundaries**: Comprehend how responsibilities are divided between different systems
5. **Ecosystem Evolution**: Understand how multi-system architectures evolve and adapt over time

**Scaffolding Approach:**
- Map ecosystem relationships with visual system context diagrams
- Explore integration challenges through concrete failure scenarios
- Build understanding of distributed system patterns and trade-offs
- Connect ecosystem design to organizational and business considerations
- Guide recognition of industry-standard integration approaches

## Exploration Methodology

### Hands-On Investigation Protocol
[Extended thinking: Balance theoretical understanding with practical exploration through direct system interaction and experimentation.]

**Investigation Techniques:**
- **Code Archaeology**: Systematic exploration of system codebase with guided discovery
- **Runtime Exploration**: Live system investigation with monitoring and observability tools
- **Configuration Analysis**: Understanding system behavior through configuration examination
- **Interface Testing**: Hands-on exploration of system APIs and interfaces
- **Performance Profiling**: Empirical investigation of system performance characteristics

**Guided Discovery Process:**
1. **Hypothesis Formation**: Develop predictions about system behavior
2. **Investigation Design**: Plan systematic exploration to test hypotheses
3. **Evidence Collection**: Gather data through direct system interaction
4. **Pattern Recognition**: Identify recurring themes and architectural patterns
5. **Understanding Synthesis**: Integrate discoveries into coherent architectural comprehension

### Pattern Building Framework
[Extended thinking: Help learners recognize and understand common architectural patterns through systematic pattern exploration and application.]

**Pattern Learning Progression:**
1. **Pattern Recognition**: Identify pattern instances in familiar systems
2. **Pattern Abstraction**: Understand pattern's essential characteristics and motivations
3. **Pattern Variations**: Explore different implementations and adaptations of patterns
4. **Pattern Application**: Apply patterns to new contexts and problems
5. **Pattern Composition**: Understand how patterns combine in complex architectures

**Scaffolding Strategies:**
- Start with patterns visible in everyday technology experiences
- Use concrete examples before introducing abstract pattern definitions
- Provide pattern templates and checklists for recognition
- Encourage pattern spotting in multiple different systems
- Build personal pattern library with documented examples

## Execution Examples

### Example 1: Microservices Architecture Learning
```bash
learn_architecture "e-commerce platform microservices" --learning-objective=comprehension --complexity-progression=component --pathway=hands-on
```

**Learning Flow:**
1. **Component Focus**: Start with single service (e.g., Product Catalog Service)
   - Understand service responsibilities and boundaries
   - Explore service API and data models
   - Investigate internal service structure
   - Trace service's role in user scenarios

2. **Scaffolded Exploration**:
   - "Let's start with something familiar - think of an online store you use..."
   - "The Product Catalog Service is like the store's inventory system..."
   - "What information would you need to display a product page?"
   - "How might this service connect to other parts of the system?"

3. **Hands-On Investigation**:
   - Examine actual API endpoints with curl or Postman
   - Review service code structure and organization
   - Explore service configuration and deployment
   - Monitor service behavior with observability tools

### Example 2: Distributed System Trade-offs Analysis
```bash
learn_architecture "payment processing system" --learning-objective=analysis --complexity-progression=system --pathway=comparative
```

**Learning Flow:**
1. **System-Level Analysis**: Examine complete payment processing architecture
   - Map all components involved in payment processing
   - Understand different payment methods and their architectural implications
   - Analyze consistency, availability, and partition tolerance trade-offs
   - Evaluate security and compliance considerations

2. **Comparative Exploration**:
   - "How does this architecture compare to simpler, monolithic payment processing?"
   - "What trade-offs were made to achieve high availability?"
   - "How would you evaluate the security vs. performance balance?"
   - "What alternative approaches might address the same requirements?"

3. **Trade-off Assessment**:
   - Performance analysis with load testing and measurement
   - Failure scenario exploration with chaos engineering
   - Cost analysis with infrastructure and operational considerations
   - Scalability assessment with growth projection modeling

### Example 3: Architecture Design Practice
```bash
learn_architecture "social media platform design" --learning-objective=synthesis --complexity-progression=ecosystem --pathway=creative
```

**Learning Flow:**
1. **Ecosystem-Level Design**: Create architecture for large-scale social platform
   - Identify all major functional areas and their relationships
   - Design service boundaries and integration patterns
   - Plan for global scale and diverse user requirements
   - Consider ecosystem integration with external platforms

2. **Creative Design Process**:
   - "If you were building the next social platform, what would be your core architectural principles?"
   - "How would you handle the feed generation challenge at global scale?"
   - "What patterns would you use for user-generated content and moderation?"
   - "How would your architecture evolve as the platform grows?"

3. **Synthesis Practice**:
   - Requirements analysis with stakeholder perspective consideration
   - Architecture sketch development with iterative refinement
   - Pattern application with creative adaptation to specific requirements
   - Peer review and feedback integration with collaborative improvement

## Advanced Learning Features

### Adaptive Scaffolding System
[Extended thinking: Dynamically adjust learning support based on learner progress and comprehension signals.]

**Scaffolding Calibration:**
- **Novice Support**: Heavy visual aids, concrete examples, step-by-step guidance
- **Intermediate Adaptation**: Moderate scaffolding with guided discovery emphasis
- **Advanced Challenge**: Light guidance with peer-level collaboration
- **Expert Partnership**: Co-exploration with knowledge co-construction

**Dynamic Adjustment:**
- Monitor comprehension through question quality and insight depth
- Adjust complexity based on learner confidence and curiosity signals
- Modify exploration style based on learning preference indicators
- Provide additional support when confusion or frustration detected

### Metacognitive Development
[Extended thinking: Help learners understand their own learning process and develop self-directed architecture learning capabilities.]

**Self-Awareness Building:**
- "What aspects of architecture are most challenging for you?"
- "How do you approach understanding complex systems?"
- "What patterns help you organize architectural information?"
- "When do you feel most confident in your architectural understanding?"

**Learning Strategy Development:**
- Help learners identify effective personal learning approaches
- Build toolkit of investigation and analysis methods
- Develop pattern recognition and abstraction skills
- Foster curiosity and systematic exploration habits

## Success Indicators

### Understanding Quality Measures
- **Conceptual Clarity**: Clear comprehension of architectural concepts and relationships
- **Pattern Recognition**: Ability to identify and apply architectural patterns appropriately
- **Trade-off Awareness**: Understanding of architectural decision implications and alternatives
- **Transfer Capability**: Application of architectural understanding to new contexts
- **Critical Thinking**: Evaluation and critique of architectural approaches

### Learning Engagement
- **Curiosity Activation**: Questions and exploration drive beyond assigned investigation
- **Hands-on Participation**: Active engagement with systems and tools
- **Pattern Seeking**: Natural tendency to look for architectural patterns and connections
- **Creative Application**: Innovation in applying architectural understanding to new problems

The learn_architecture command transforms complex system architecture into accessible learning experiences, building deep understanding through progressive complexity, hands-on exploration, and pattern recognition development.