๐ค AI-Powered Software Architecture Analysis & Quality Assurance Platform
- What is SAAT?
- Quick Start
- Installation
- Usage Guides
- Core Concepts
- Available Agents
- Documentation
- Examples
- Contributing
- Appendix
SAAT is an AI-powered architecture quality assurance platform that helps you:
- Analyze existing codebases (brownfield) - Discover architecture automatically
- Design new systems (greenfield) - Extract requirements and generate architecture
- Evaluate quality - Score architecture against 14 standard characteristics
- Validate compliance - Check against PCI-DSS, HIPAA, GDPR, SOC2
- Analyze security - Identify vulnerabilities and generate threat models
- Generate documentation - Create comprehensive docs in multiple formats
- Create infrastructure - Generate production-ready Terraform for AWS/Azure/GCP
Traditional architecture work is manual and time-consuming. SAAT automates the entire process:
Traditional Approach: SAAT Approach:
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Manual Analysis โ โ /saat-discover โ
โ (days/weeks) โ โ (minutes) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Draw Diagrams โ โ /saat-generate โ
โ (hours) โ โ (automatic) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Write Docs โ โ /saat-analyze โ
โ (days) โ โ (with scores) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ
9 Specialized AI Agents - Discovery, Generation, Requirements, Quality Analysis, Validation, Security, Documentation, Infrastructure, Orchestration
โ
Architecture Quality Analysis - Evaluate against 14 characteristics (Mark Richards methodology)
โ
Conversational Slash Commands - Type /saat- in Claude Code for guided workflows
โ
C4 Model Standard - Industry-standard architecture diagrams
โ
Multi-Model Support - Claude, GPT-4, Gemini, Ollama
โ
Human-in-the-Loop - Interactive approval with auto-approve mode
โ
Production Ready - Retry logic, streaming, error handling
- Install SAAT and configure Claude Code:
# Clone and install SAAT
git clone https://github.com/DavidROliverBA/SAAT.git
cd SAAT
pip install -e .
# Install Claude Code slash commands
./install-claude-commands.sh
# Set API key
export ANTHROPIC_API_KEY="your-key"- Analyze an existing project (Brownfield):
Open Claude Code in your project directory, then:
You: /saat-orchestrate
Claude: I'll help you analyze your architecture!
What would you like to do?
1. Analyze existing codebase (brownfield)
2. Design new system (greenfield)
3. Review specific architecture aspect
You: Analyze my existing codebase
Claude: [Runs discovery, generates C4 model, analyzes quality,
validates compliance, checks security, generates docs]
โ
Complete analysis finished!
๐ Results Summary:
- Architecture Model: 5 systems, 12 containers, 28 components
- Quality Score: 68/100 (Needs Improvement)
- Compliance: 85/100 (PCI-DSS)
- Security: 3 critical issues found
- Documentation: Generated in docs/
๐จ Top Priorities:
1. Fix critical security issue: Unencrypted database connection
2. Add load balancer for availability (currently 55/100)
3. Implement auto-scaling for scalability
Next: Would you like me to generate Terraform to deploy fixes?
- Design a new system (Greenfield):
You: /saat-orchestrate
Claude: What would you like to do?
You: Design a new payment processing system
Claude: I'll guide you through designing your architecture.
Do you have requirements documents? If so, please provide paths.
Otherwise, I can help you capture requirements conversationally.
You: I have docs/requirements.md
Claude: [Extracts requirements, generates architecture, analyzes quality,
validates, checks security, generates infrastructure]
โ
Architecture design complete!
๐ Your New System:
- 3 systems, 8 containers, 15 components
- Quality Score: 82/100 (Good)
- Compliance: PCI-DSS ready (98/100)
- Security: All checks passed
- Infrastructure: AWS Terraform ready to deploy
Files created:
- architecture.json (C4 model)
- docs/ (comprehensive documentation)
- infrastructure/ (Terraform IaC)
You can now: terraform apply to deploy!
All commands are conversational and guide you step-by-step:
/saat-orchestrate- Start here! Recommends what to do based on your needs/saat-discover- Analyze existing codebase/saat-requirements- Extract requirements from documents/saat-generate- Create architecture model/saat-analyze-characteristics- Evaluate architecture quality/saat-validate- Check compliance/saat-security- Analyze security/saat-document- Generate documentation/saat-terraform- Create infrastructure code/saat-help- Show all commands
See: Complete Usage Guides for detailed walkthroughs.
# Clone repository
git clone https://github.com/DavidROliverBA/SAAT.git
cd SAAT
# Install with pip
pip install -e .
# Or with all extras (Logfire, OpenAI, Gemini)
pip install -e ".[all]"
# Or with Poetry
poetry install# Create .env file
cp .env.example .env
# Add your API key
echo "ANTHROPIC_API_KEY=your-key-here" >> .env
# Optional: Choose default model
echo "SAAT_MODEL=anthropic:claude-sonnet-4" >> .envOption A: Install Slash Commands Globally (Available in all projects)
./install-claude-commands.shOption B: Per-Project (Already available when you run Claude Code from SAAT directory)
# Commands are in .claude/commands/ - no installation needed!Configure MCP Server (Required for slash commands to work):
Add to ~/.config/claude/config.json:
{
"mcpServers": {
"saat": {
"command": "python",
"args": ["/path/to/SAAT/saat_mcp_server.py"],
"env": {
"ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}"
}
}
}
}Then restart Claude Code.
# Check SAAT CLI
saat --version
saat info
# In Claude Code, type:
# /saat-help
# You should see all available commandsThe Orchestrator (/saat-orchestrate) is your starting point. It will:
- Ask you what you want to do
- Recommend which agents to run
- Guide you through the entire process
- Keep you updated on progress
- Ask for help when it needs information
๐ Greenfield Guide - Designing a new system from scratch
- Extract requirements from documents
- Generate architecture automatically
- Evaluate quality before building
- Generate deployment infrastructure
- Complete walkthrough with examples
๐ Brownfield Guide - Analyzing existing codebases
- Discover architecture from code
- Identify quality issues
- Check compliance and security
- Generate missing documentation
- Create infrastructure-as-code
- Complete walkthrough with examples
๐ Customization Guide - Tailor SAAT to your needs
- Customize agent behavior
- Add custom validation rules
- Create custom architecture characteristics
- Extend with your own patterns
- Build custom agents
SAAT uses specialized AI agents, each expert in one area:
- ๐ฏ Orchestrator Agent โญ NEW - Coordinates all other agents, creates plans, guides users
- ๐ Discovery Agent - Analyzes codebases to discover architecture
- ๐ Requirements Agent - Extracts requirements from documents
- ๐๏ธ Generator Agent - Creates C4 architecture models
- ๐ Architecture Characteristics Agent - Evaluates quality against 14 standards
- โ Validation Agent - Validates compliance (PCI-DSS, HIPAA, GDPR, SOC2)
- ๐ Security Agent - Analyzes security and creates threat models
- ๐ Documentation Agent - Generates docs (Markdown, PlantUML, Mermaid, ADRs)
- ๐๏ธ Terraform Agent - Creates infrastructure-as-code
SAAT uses the C4 model for architecture:
- Level 1 - System Context: High-level view of systems and external dependencies
- Level 2 - Container: Applications, databases, microservices
- Level 3 - Component: Code-level modules and services
SAAT evaluates architecture against 14 standard characteristics from Mark Richards:
Operational (7): Availability, Scalability, Performance, Security, Reliability, Fault Tolerance, Recoverability
Structural (5): Maintainability, Testability, Deployability, Configurability, Extensibility
Cross-Cutting (2): Interoperability, Usability
Each characteristic gets:
- Score (0-100)
- Status (Fully Compliant, Mostly Compliant, Partially Compliant, Non-Compliant)
- Gap Analysis with severity levels (critical, high, medium, low)
- Recommendations with implementation steps
SAAT assigns criticality to guide infrastructure decisions:
| Level | Uptime | Infrastructure | Use Case |
|---|---|---|---|
| CS1 | 99.99% | Multi-AZ, auto-scaling 2-10, 35d backups | Mission critical (payments, auth) |
| CS2 | 99.9% | Multi-AZ, auto-scaling 2-5, 7d backups | Business critical (APIs, databases) |
| SL1 | 99.5% | Single-AZ, basic monitoring, 3d backups | Standard services |
| SL2 | 99% | Single-AZ, minimal config, 3d backups | Internal tools |
| STANDARD | Best effort | Minimal, no backups | Development, testing |
Purpose: Your AI architecture consultant that coordinates all other agents
The Orchestrator Agent is your primary interface to SAAT. It:
- Understands your goals through conversation
- Recommends what to do based on your situation
- Creates a plan and gets your approval
- Coordinates agents to execute the plan
- Keeps you updated with progress reports
- Asks for help when it needs documentation or clarification
Usage:
/saat-orchestrate
Example Conversation:
You: /saat-orchestrate
Orchestrator: Hello! I'm your SAAT architecture consultant.
I'll help you with architecture discovery, design,
quality analysis, validation, and infrastructure.
What brings you here today?
1. I have an existing codebase I want to analyze
2. I want to design a new system
3. I have an architecture I want to review
4. I'm not sure - help me figure it out
You: I want to analyze my existing payment processing application
Orchestrator: Great! I'll help you analyze your payment app.
First, let me understand your situation:
- Where is the codebase? (path)
- Do you have any existing architecture docs?
- What are your main concerns? (security, performance, etc.)
- Any compliance requirements? (PCI-DSS, etc.)
You: The code is in /app/payment-system, no existing docs,
I'm concerned about PCI-DSS compliance and security
Orchestrator: Perfect! Based on what you've told me, here's my plan:
๐ Analysis Plan:
1. โ
Discover architecture from /app/payment-system
2. โ
Generate C4 model
3. โ
Analyze architecture quality (14 characteristics)
4. โ
Validate PCI-DSS compliance
5. โ
Deep security analysis with threat modeling
6. โ
Generate comprehensive documentation
7. โ
Create infrastructure-as-code (if needed)
Estimated time: 5-10 minutes
Does this plan look good? (y/n)
You: yes
Orchestrator: Excellent! Starting analysis...
[1/7] ๐ Discovering architecture...
Found: 3 services (payment-api, auth-service, notification-service)
Technologies: Node.js, PostgreSQL, Redis, RabbitMQ
Pattern: Microservices with event-driven communication
โ
Discovery complete!
[2/7] ๐๏ธ Generating C4 model...
Created: 3 systems, 8 containers, 15 components
โ
Model generated!
[3/7] ๐ Analyzing architecture quality...
Overall Score: 68/100 (Needs Improvement)
Critical Issues: 2 (Availability, Security)
โ
Analysis complete!
[4/7] โ
Validating PCI-DSS compliance...
Compliance Score: 72/100
โ ๏ธ Found 5 compliance issues
โ
Validation complete!
[5/7] ๐ Running security analysis...
๐จ CRITICAL: Unencrypted database connections
๐จ CRITICAL: Missing authentication on admin endpoints
โ ๏ธ HIGH: Weak password hashing (MD5)
โ
Security scan complete!
[6/7] ๐ Generating documentation...
Created: README.md, architecture diagrams, ADRs
โ
Documentation complete!
[7/7] ๐๏ธ Creating infrastructure code...
Generated: AWS Terraform with PCI-DSS configuration
โ
Infrastructure code ready!
๐ Analysis Complete!
๐ Summary:
- Quality: 68/100 (Needs Improvement)
- Compliance: 72/100 (PCI-DSS)
- Security: ๐จ 2 CRITICAL, 1 HIGH, 3 MEDIUM issues
๐จ TOP PRIORITIES:
1. Fix unencrypted database connections (CRITICAL)
2. Add authentication to admin endpoints (CRITICAL)
3. Upgrade password hashing to bcrypt (HIGH)
4. Add load balancer for high availability
5. Implement auto-scaling
๐ Generated Files:
- architecture.json (C4 model)
- archchar-analysis.md (quality report)
- validation-report.json (PCI-DSS)
- security-report.json (threat model)
- docs/ (comprehensive documentation)
- infrastructure/ (Terraform)
What would you like to do next?
1. Review the security issues in detail
2. See recommendations for fixing availability
3. Deploy the infrastructure
4. Something else
See: docs/ORCHESTRATOR_GUIDE.md for complete guide.
The Orchestrator coordinates these specialized agents as needed:
- ๐ Discovery Agent - Analyzes codebases (brownfield)
- ๐ Requirements Agent - Extracts requirements (greenfield)
- ๐๏ธ Generator Agent - Creates C4 models
- ๐ Architecture Characteristics Agent - Evaluates quality
- โ Validation Agent - Checks compliance
- ๐ Security Agent - Analyzes security
- ๐ Documentation Agent - Generates docs
- ๐๏ธ Terraform Agent - Creates infrastructure
Each agent has its own slash command if you want to use it directly:
/saat-discover/saat-requirements/saat-generate/saat-analyze-characteristics/saat-validate/saat-security/saat-document/saat-terraform
For detailed documentation on each agent, see:
- docs/AGENTS_QUICK_REFERENCE.md - All agents overview
- Appendix: Agent API Reference - Python API for each agent
- README.md - This document (overview and quick start)
- GREENFIELD_GUIDE.md - Complete greenfield workflow
- BROWNFIELD_GUIDE.md - Complete brownfield workflow
- CUSTOMIZATION_GUIDE.md - How to customize SAAT
- ORCHESTRATOR_GUIDE.md - Complete orchestrator guide
- AGENTS_QUICK_REFERENCE.md - All agents overview
- ARCHITECTURE_CHARACTERISTICS_USAGE.md - Quality analysis guide
- ARCHCHAR_INTEGRATION_ANALYSIS.md - Integration patterns
- BAC4_INTEGRATION.md - Visual editor integration
- .claude/README.md - Slash commands reference
- ARCHITECTURE.md - SAAT system architecture
- CHANGELOG.md - Version history and roadmap
- RELEASE_NOTES.md - Release information
You: /saat-orchestrate
Orchestrator: What would you like to do?
You: Quick review of my microservices app in ./services
Orchestrator: [Runs discovery โ generate โ analyze โ validate โ security]
โ
Quick Review Complete!
Quality: 75/100 (Good)
Top Issues:
1. No load balancer (availability: 60/100)
2. Missing auto-scaling (scalability: 65/100)
3. No caching layer (performance: 70/100)
Recommendation: Add these to improve to 90/100
You: /saat-orchestrate
You: Design a PCI-DSS compliant payment system
Orchestrator: Do you have requirements docs?
You: Yes, in docs/requirements.md
Orchestrator: [Extracts requirements โ generates architecture โ
analyzes quality โ validates PCI-DSS โ
checks security โ generates infrastructure]
โ
Design Complete!
Your system:
- 3 systems, 8 containers, 15 components
- Quality: 88/100 (Excellent)
- PCI-DSS: 98/100 (Ready for certification)
- Infrastructure: AWS Terraform ready
You can deploy with: cd infrastructure && terraform apply
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
git clone https://github.com/DavidROliverBA/SAAT.git
cd SAAT
pip install -e ".[dev]"MIT License - See LICENSE file
- PydanticAI - Agent framework
- C4 Model - Architecture visualization methodology
- Mark Richards - Architecture characteristics methodology
- Structurizr - JSON schema for C4 models
Built with โค๏ธ using PydanticAI
For users who prefer command-line interface over conversational commands.
saat discover --path /repo --output discovery.json
saat generate --discovery discovery.json --output architecture.json
saat analyze --path /repo --output architecture.json # Combinedsaat discover-requirements \
-f docs/PRD.md \
-n "Project Name" \
-o requirements.jsonsaat analyze-characteristics \
-m architecture.json \
-c characteristics.json \
-o archchar-analysissaat validate-model -m architecture.json -f PCI-DSS
saat validate-model -m architecture.json -f HIPAAsaat security-scan -m architecture.json --threat-modelsaat generate-docs \
-m architecture.json \
-f markdown -f plantuml -f mermaid \
-o docs/saat generate-terraform -m architecture.json -p aws -r us-east-1 -o infrastructure/# Auto-approve (skip prompts)
saat -y validate-model -m architecture.json
# Use different model
saat --model openai:gpt-4 analyze --path /repoFull CLI documentation: Run saat --help or saat <command> --help
For developers integrating SAAT into other applications.
Available MCP tools:
orchestrate- Start orchestrated workflowdiscover_architecture- Analyze repositorydiscover_requirements- Extract requirementsgenerate_c4_model- Generate modelanalyze_architecture_characteristics- Evaluate qualityvalidate_model- Validate complianceanalyze_security- Security analysisgenerate_documentation- Create docsgenerate_terraform- Infrastructure codefull_analysis- Complete workflow
All tools use auto_approve=True for seamless integration.
For Python developers using SAAT programmatically.
from saat.agents import OrchestratorAgent
agent = OrchestratorAgent()
result = await agent.orchestrate(
user_goal="Analyze my payment system",
context={
"codebase_path": "/app/payment",
"compliance": ["PCI-DSS"],
"concerns": ["security"]
},
auto_approve=False
)from saat.agents import DiscoveryAgent
agent = DiscoveryAgent()
discovery = await agent.analyze_repository(
path="/path/to/repo",
max_depth=3,
auto_approve=False
)from saat.agents import GeneratorAgent
agent = GeneratorAgent()
model = await agent.generate_model(
discovery=discovery,
business_context=context,
auto_approve=False
)from saat.agents import RequirementsAgent
agent = RequirementsAgent()
result = await agent.discover_requirements(
file_paths=["docs/PRD.md"],
project_name="Payment Platform",
auto_approve=False
)from saat.agents import ArchCharAgent
agent = ArchCharAgent()
result = await agent.analyze_architecture(
model=c4_model,
characteristics_input=archchar_input,
auto_approve=False
)from saat.agents import ValidationAgent
agent = ValidationAgent()
result = await agent.validate_model(
model=c4_model,
framework="PCI-DSS",
auto_approve=False
)from saat.agents import SecurityAgent
agent = SecurityAgent()
result = await agent.analyze_security(
model=c4_model,
threat_model=True,
auto_approve=False
)from saat.agents import DocumentationAgent
agent = DocumentationAgent()
result = await agent.generate_documentation(
model=c4_model,
output_dir="docs/",
formats=["markdown", "plantuml", "mermaid"],
auto_approve=False
)from saat.agents import TerraformAgent
agent = TerraformAgent()
result = await agent.generate_terraform(
model=c4_model,
provider="aws",
region="us-east-1",
output_dir="infrastructure/",
auto_approve=False
)SAAT supports multiple AI models:
Anthropic Claude (Default)
export ANTHROPIC_API_KEY="your-key"
saat --model anthropic:claude-sonnet-4 analyze --path /repoOpenAI
export OPENAI_API_KEY="your-key"
saat --model openai:gpt-4 analyze --path /repoGoogle Gemini
export GEMINI_API_KEY="your-key"
saat --model gemini:gemini-1.5-pro analyze --path /repoLocal (Ollama)
ollama serve
ollama pull llama3.1
saat --model ollama:llama3.1 analyze --path /repoSAAT integrates with bac4-standalone for visual editing.
# Export to Structurizr format
saat export-structurizr -m architecture.json -o structurizr.json
# Import from Structurizr
saat import-structurizr -s structurizr.json -o architecture.jsonSee: BAC4_INTEGRATION.md for complete guide.
๐ฎ Coming in v2.1+: Agents that learn and improve over time
Each SAAT agent will gain experience from every analysis, building organizational knowledge:
- Pattern Recognition: Learn common patterns in your codebases
- Recommendation Quality: Improve suggestions based on what worked
- Domain Knowledge: Build expertise in your specific industry/domain
- Team Preferences: Learn your team's architecture preferences
- Historical Context: Remember past decisions and their outcomes
We're researching best practices in agent learning:
-
Memory Systems
- Vector databases for semantic memory (Pinecone, Weaviate)
- Graph databases for relationship memory (Neo4j)
- Time-series for evolution tracking
-
Feedback Loops
- User feedback on recommendations (๐/๐)
- Outcome tracking (did the fix work?)
- A/B testing different approaches
-
Knowledge Transfer
- Cross-project learning
- Industry best practices database
- Community-contributed patterns
-
Privacy-Preserving Learning
- Local-only learning mode
- Federated learning for team knowledge
- Opt-in cloud knowledge sharing
Phase 1: Memory Storage (v2.1)
- Store analysis history in local SQLite
- Track patterns and decisions
- Basic recommendation improvement
Phase 2: Learning from Feedback (v2.2)
- User feedback mechanism
- Outcome tracking
- Recommendation scoring
Phase 3: Advanced Learning (v2.3)
- Vector embeddings for pattern matching
- Cross-project knowledge transfer
- Community knowledge base (opt-in)
Phase 4: Adaptive Agents (v3.0)
- Agents that adapt to your organization
- Personalized recommendations
- Predictive architecture guidance
- MemGPT - Virtual context management for LLMs
- Voyager - Lifelong learning agents
- Reflexion - Self-reflection for agents
- RAG Systems - Retrieval-augmented generation
See: docs/AGENT_LEARNING.md for detailed research and design (coming soon)
๐ Support