Solution Architects Analysis Toolkit for Claude Code

A comprehensive suite of 11 specialized AI sub-agents that provide professional-grade software architecture analysis, design, validation, security assessment, documentation, and infrastructure generation.

SAAT (Solution Architects Analysis Toolkit) provides AI-powered architecture analysis through specialized sub-agents that can:

• 🔍 Discover existing codebases and identify architecture patterns
• 📋 Extract requirements from business documents
• 🏗️ Generate standardized C4 architecture models
• 📊 Analyze quality against 14 architecture characteristics
• ✅ Validate models for correctness and compliance
• 🔒 Audit security and identify vulnerabilities
• 📚 Document architecture with diagrams and ADRs
• 🏗️ Generate production-ready Terraform infrastructure
• 🎯 Orchestrate complete workflows tailored to your needs

Before installing SAAT, ensure you have:

• ✅ Claude Code installed and configured (Download here)
• ✅ Bash shell (Linux, macOS, or Windows with WSL2/Git Bash)
• ✅ Git (optional, for cloning - or download ZIP from GitHub)

Step 1: Get the repository

# Option A: Clone with Git
git clone https://github.com/DavidROliverBA/SAAT-ClaudeCode.git
cd SAAT-ClaudeCode

# Option B: Download and extract ZIP, then:
cd SAAT-ClaudeCode

Step 2: Run the installation script

./scripts/install.sh

What happens during installation:

• ✅ Creates ~/.claude/agents/ directory (if it doesn't exist)
• ✅ Copies all 11 SAAT agents globally
• ✅ Makes agents available across all your projects
• ✅ Takes less than 1 minute!

Step 3: Verify installation

# Check that agents are installed
ls -1 ~/.claude/agents/saat-*.md

# You should see 11 agent files

# Clone or download repository
cd SAAT-ClaudeCode

# Create global agents directory
mkdir -p ~/.claude/agents

# Copy all agents
cp agents/*.md ~/.claude/agents/

# Verify
ls -la ~/.claude/agents/saat-*.md

# Navigate to your project
cd /path/to/your/project

# Create project agents directory
mkdir -p .claude/agents

# Copy agents from SAAT repository
cp /path/to/SAAT-ClaudeCode/agents/*.md .claude/agents/

# Agents now available only in this project

# Clone repository
git clone https://github.com/DavidROliverBA/SAAT-ClaudeCode.git
cd SAAT-ClaudeCode

# Create agents directory
New-Item -Path "$env:USERPROFILE\.claude\agents" -ItemType Directory -Force

# Copy agents
Copy-Item -Path "agents\*.md" -Destination "$env:USERPROFILE\.claude\agents\"

# Verify
Get-ChildItem "$env:USERPROFILE\.claude\agents\saat-*.md"

Open Claude Code and invoke your first agent:

Method 1: Guided Experience (Recommended for beginners)

In Claude Code, use the Task tool:
  subagent_type: "saat-orchestrate"
  prompt: "I want to analyze my e-commerce platform for security and performance"

Method 2: Get Help

Task tool:
  subagent_type: "saat-help"
  prompt: "Show me all available SAAT commands"

Method 3: Quick Full Analysis

Task tool:
  subagent_type: "saat-full-pipeline"
  prompt: "Analyze /path/to/my/project"

The orchestrator will guide you through a personalized analysis workflow!

Issue: Script says "permission denied"

chmod +x scripts/install.sh
./scripts/install.sh

Issue: Agents not showing in Claude Code

• Restart Claude Code after installation
• Verify files exist: ls ~/.claude/agents/saat-*.md
• Check file permissions: chmod 644 ~/.claude/agents/saat-*.md

For more help: See INSTALLATION.md for comprehensive troubleshooting.

SAAT includes a modern web-based dashboard for managing projects, running agents, and visualizing results.

• 📁 Project Management: Add local folders or clone GitHub repositories
• 🤖 Agent Browser: Explore all 11 SAAT agents with detailed descriptions
• ⚡ Real-time Execution: Run agents with live progress updates via WebSocket
• 📊 Results Visualization: View analysis results and statistics
• 🔍 Search & Filter: Quickly find projects and agents

# Install dependencies
cd dashboard/backend && npm install
cd ../frontend && npm install

# Start backend (Terminal 1)
cd dashboard/backend
npm run dev

# Start frontend (Terminal 2)
cd dashboard/frontend
npm run dev

# Open http://localhost:3000

Full documentation: dashboard/README.md

Task(subagent_type="saat-discover", prompt="Analyze /path/to/my-app")
→ Task(subagent_type="saat-generate", prompt="Generate C4 from discovery.json")
→ Task(subagent_type="saat-security", prompt="Analyze security")

Or use the full pipeline:

Task(subagent_type="saat-full-pipeline", prompt="Analyze /path/to/my-app")

Task(subagent_type="saat-requirements", prompt="Extract from requirements.md")
→ Task(subagent_type="saat-generate", prompt="Generate C4 from requirements.json")
→ Task(subagent_type="saat-document", prompt="Create documentation")

Task(subagent_type="saat-security", prompt="Analyze architecture.json with threat modeling")

Task(subagent_type="saat-analyze-characteristics", prompt="Analyze architecture.json against characteristics.json")
→ Task(subagent_type="saat-validate", prompt="Validate architecture.json for PCI-DSS")

Task(subagent_type="saat-terraform", prompt="Generate AWS infrastructure from architecture.json")

SAAT evaluates 14 standard architecture characteristics based on Mark Richards' methodology:

• Availability, Scalability, Performance, Security, Reliability, Fault Tolerance, Recoverability

• Maintainability, Testability, Deployability, Configurability, Extensibility

• Interoperability, Usability

• saat-orchestrator - AI-powered guidance and workflow orchestration
• saat-discover - Automated codebase analysis and pattern detection
• saat-requirements - Intelligent requirements extraction
• saat-generate - C4 architecture model generation with criticality assignment
• saat-analyze-characteristics - Quality evaluation against 14 characteristics
• saat-validate - Model validation and compliance checking
• saat-security - Deep security audit with STRIDE threat modeling
• saat-document - Comprehensive documentation generation
• saat-terraform - Multi-cloud infrastructure as code
• saat-full-pipeline - Complete workflow automation
• saat-help - Interactive help and reference system

• 5 Domain-Specific Characteristics: E-commerce, Healthcare, Fintech, SaaS, Microservices
• Sample Outputs: Discovery, Architecture, Analysis, Validation, Security reports
• Requirements Documents: Complete examples with functional/non-functional requirements
• Learning Paths: Beginner → Intermediate → Advanced guides

• E-Commerce Platform (Brownfield, 6-hour walkthrough)
  • Monolith to microservices migration
  • PCI-DSS compliance focus
  • Active-active deployment strategies
• API Gateway (Greenfield, 4-hour walkthrough)
  • High-performance design (<10ms p99 latency)
  • Multi-cloud deployment (AWS + GCP)
  • API security patterns
• Healthcare Portal (HIPAA, 8-hour walkthrough)
  • HIPAA Security Rule compliance
  • Zero trust architecture
  • PHI protection strategies

• Project Management: Local folders and GitHub repositories
• Agent Browser: Explore and execute all 11 agents
• Real-time Updates: WebSocket-based progress tracking
• Analysis Visualization: View results and statistics
• RESTful API: Complete backend for automation

• Badge Generator: Create shields.io badges from analysis results
• GitHub Actions: CI/CD workflow template for automated analysis
• Shell Completions: Bash and Zsh tab completion
• Docker Image: Containerized SAAT with helper CLI
• Interactive Generator: Guided questionnaire for characteristics files

• Level 1 (Systems), Level 2 (Containers), Level 3 (Components)
• Relationships with protocols and data flows
• Criticality levels: CS1 (99.99%), CS2 (99.9%), SL1 (99.5%), SL2 (99%), STANDARD
• Owner assignment and team mapping
• Technology stack detection

• PCI-DSS: Payment Card Industry Data Security Standard
• HIPAA: Health Insurance Portability and Accountability Act
• GDPR: General Data Protection Regulation
• SOC2: Service Organization Control 2
• Custom Frameworks: Define your own compliance rules

• AWS: EKS, RDS, ElastiCache, ALB, VPC, CloudWatch, S3
• Azure: AKS, SQL Database, Redis Cache, Load Balancer, VNet
• GCP: GKE, Cloud SQL, Memorystore, Load Balancer, VPC
• Multi-region: Active-active, disaster recovery configurations

• Markdown: README, ARCHITECTURE, API docs, runbooks
• PlantUML: C4 diagrams with automatic generation
• Mermaid: GitHub-friendly diagrams
• ADRs: Architecture Decision Records with templates
• Confluence/Wiki: Export-ready formats

• Encryption gaps (at rest, in transit, key management)
• Authentication/authorization issues (OAuth, JWT, RBAC, ABAC)
• Data flow security analysis
• Infrastructure vulnerabilities
• STRIDE Threat Modeling: Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege
• Attack surface mapping
• CVSS scoring for findings

• Installation Guide - Complete installation instructions
• Agents Guide - Comprehensive reference for all agents
• Examples - See examples/ directory for sample files

• Claude Code (latest version recommended)
• Operating System: Linux, macOS, or Windows (WSL2/Git Bash)

• Git (for cloning repository)
• Terraform (for infrastructure deployment)
• Cloud CLI (AWS CLI, Azure CLI, gcloud - for infrastructure deployment)

Task(
  subagent_type="saat-full-pipeline",
  prompt="Analyze /home/user/projects/my-app, output to ./analysis, use AWS"
)

Generates:

• ✅ discovery.json
• ✅ architecture.json
• ✅ Quality analysis report
• ✅ Validation report
• ✅ Security audit
• ✅ Complete documentation
• ✅ Terraform infrastructure

Task(
  subagent_type="saat-orchestrate",
  prompt="I need to analyze my system for modernization"
)

The orchestrator will:

1. Ask about your situation
2. Understand your concerns
3. Create a personalized plan
4. Execute the workflow
5. Deliver actionable recommendations

# Step 1: Discover
Task(subagent_type="saat-discover", prompt="Analyze /path/to/repo")

# Step 2: Generate C4
Task(subagent_type="saat-generate", prompt="Generate from discovery.json")

# Step 3: Analyze Quality
Task(subagent_type="saat-analyze-characteristics", prompt="Analyze against characteristics.json")

# Step 4: Security Audit
Task(subagent_type="saat-security", prompt="Deep security analysis with threat modeling")

# Step 5: Document
Task(subagent_type="saat-document", prompt="Generate complete documentation")

SAAT-ClaudeCode/
├── agents/                              # 11 specialized sub-agents
│   ├── saat-orchestrator.md            # AI architecture consultant
│   ├── saat-discover.md                # Codebase analysis
│   ├── saat-requirements.md            # Requirements extraction
│   ├── saat-generate.md                # C4 model generation
│   ├── saat-analyze-characteristics.md # Quality analysis
│   ├── saat-validate.md                # Model validation
│   ├── saat-security.md                # Security audit
│   ├── saat-document.md                # Documentation generation
│   ├── saat-terraform.md               # Infrastructure generation
│   ├── saat-full-pipeline.md           # Complete workflow
│   └── saat-help.md                    # Help system
│
├── scripts/                             # Automation scripts
│   ├── install.sh                      # Install agents globally
│   ├── uninstall.sh                    # Remove agents
│   ├── generate-badges.sh              # Create shields.io badges
│   └── create-characteristics.sh       # Interactive generator
│
├── examples/                            # Comprehensive examples
│   ├── characteristics/                # 5 domain-specific examples
│   │   ├── ecommerce-characteristics.json
│   │   ├── healthcare-characteristics.json
│   │   ├── fintech-characteristics.json
│   │   ├── saas-characteristics.json
│   │   └── microservices-characteristics.json
│   ├── sample-outputs/                 # Analysis output samples
│   │   ├── discovery-sample.json
│   │   ├── architecture-sample.json
│   │   ├── archchar-analysis-sample.json
│   │   ├── archchar-analysis-sample.md
│   │   ├── validation-report-sample.json
│   │   └── security-report-sample.json
│   ├── requirements/                   # Requirements documents
│   │   └── ecommerce-requirements.md
│   └── README.md                       # Examples guide
│
├── reference-projects/                  # Complete walkthroughs
│   ├── ecommerce-platform/             # Brownfield migration
│   │   ├── README.md                   # Project overview
│   │   └── WALKTHROUGH.md              # 6-hour guide
│   ├── microservices-gateway/          # Greenfield design
│   │   ├── README.md                   # Project overview
│   │   └── WALKTHROUGH.md              # 4-hour guide
│   ├── healthcare-portal/              # HIPAA compliance
│   │   ├── README.md                   # Project overview
│   │   └── WALKTHROUGH.md              # 8-hour guide
│   └── README.md                       # Reference guide
│
├── dashboard/                           # Web dashboard (Beta)
│   ├── backend/                        # Node.js/Express API
│   │   ├── src/
│   │   │   ├── server.js
│   │   │   └── routes/                 # API routes
│   │   └── package.json
│   ├── frontend/                       # React/Vite app
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── pages/
│   │   │   └── context/
│   │   └── package.json
│   └── README.md                       # Dashboard docs
│
├── templates/                           # CI/CD templates
│   └── github-actions/
│       ├── saat-analysis.yml           # GitHub Action workflow
│       └── README.md                   # Setup guide
│
├── completions/                         # Shell completions
│   ├── saat-completion.bash            # Bash completion
│   ├── saat-completion.zsh             # Zsh completion
│   └── README.md                       # Installation guide
│
├── Dockerfile                           # Docker image
├── docker-compose.yml                   # Docker Compose setup
├── DOCKER.md                            # Docker documentation
├── INSTALLATION.md                      # Installation guide
├── AGENTS_GUIDE.md                      # Complete agents reference
├── ROADMAP.md                           # Development roadmap
└── README.md                            # This file

If you need to remove SAAT agents:

cd SAAT-ClaudeCode
./scripts/uninstall.sh

The script will:

• List all SAAT agents to be removed
• Ask for confirmation
• Remove all agents from ~/.claude/agents/

# Remove all SAAT agents
rm ~/.claude/agents/saat-*.md

# Or remove specific agent
rm ~/.claude/agents/saat-orchestrator.md

ls ~/.claude/agents/saat-*.md
# Should return: No such file or directory

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

To test agents locally before installation:

# Copy to project-specific directory
mkdir -p .claude/agents
cp agents/*.md .claude/agents/

MIT License - see LICENSE file for details.

Created by: David R. Oliver

Based on: Solution Architects Analysis Toolkit (SAAT) methodology

Powered by: Claude Code by Anthropic

• Issues: GitHub Issues
• Discussions: GitHub Discussions

1. Install: Run ./scripts/install.sh
2. Learn: Read AGENTS_GUIDE.md
3. Try: Invoke saat-orchestrate in Claude Code
4. Explore: Run saat-help for all commands

Ready to revolutionize your architecture analysis? Install SAAT and start architecting! 🚀

./scripts/install.sh

Then in Claude Code:

Task(subagent_type="saat-help", prompt="Show me what you can do")

Happy architecting! 🎉