cloudforge (Sagoyanfisic)

CloudForge

基于自然语言的人工智能AWS架构图

     ](https://www.docker.com)  

CloudForge生成 生产级AWS架构图 来自简单的英语描述。使用7级NLP管道，它将简单的描述转换为全面的多服务架构图，并进行AWS良好架构框架验证。

生成 20-27+服务架构 通过智能集群、自动服务命名更正和架构最佳实践实施。

______________________________________________________________________

✨ 核心功能

🎯 智能建筑一代

• 描述细化 --人工智能将简要描述扩展为全面的生产级架构（20-27+服务）
• AWS架构良好评估 --5个支柱的自动评分：卓越运营、安全性、可靠性、性能效率、成本优化
• 模式检测 -确定体系结构模式（RAG、无服务器API、数据管道、流分析、ML平台、事件驱动、CDN、物联网、Kubernetes、Generative AI、高可用性、数据仓库、安全性和合规性）

🔧 智能代码生成

• 动态服务映射 --30+自动服务名称更正（OpenSearch→ AmazonOpensearchService、EventBridge→ 事件桥等）
• 智能回退系统 --未映射的服务会自动使用带有服务标签的通用机架图标（防止20多个其他服务出现名称错误）
• LangGraph管道 --7节点状态机：模式检测→ 架构良好的评估→ 蓝图→ code → 验证→ 重试逻辑→ 渲染

📊 生产级可视化

• VPC集群 --VPC容器对服务进行逻辑封装；删除高级图表的细粒度VPC端点
• 稀疏连接 --15-30个有意义的连接，可提供20多种服务（不是每种服务都有）
• 逻辑分组 --集群：VPC、公共/私有子网、监控、安全和身份、集成和事件、存储和搜索
• 全图验证 --AST解析、安全扫描、执行前的AWS组件白名单

🛠️ 完整的管道

• 多代理NLP --架构师+评论家+评审员代理验证架构模式
• REST API+Web用户界面 --FastAPI后端与Streamlit前端，实现两步式工作流程
• 多种输出格式 --PNG、PDF、SVG渲染
• 错误恢复 --如果图表执行失败，智能重试逻辑将重新生成代码（总共最多9次尝试）

______________________________________________________________________

快速开始

先决条件

• Python 3.12+
• 紫外线 包管理器
• GraphViz(brew install graphviz / sudo apt install graphviz)
• 谷歌API密钥-获取一个

选项1:Docker Compose（推荐）

cp .env.example .env
# Edit .env and set GOOGLE_API_KEY=your_key

make build
make up
# Web UI: http://localhost:8501
# API docs: http://localhost:8000/docs

make down    # stop
make logs    # tail logs
make rebuild # full rebuild

选项2：局部（UV）

cp .env.example .env
# Edit .env and set GOOGLE_API_KEY=your_key

uv sync

# Terminal 1 — API
uv run python -m src.presentation.api --port 8000

# Terminal 2 — UI
uv run streamlit run ui/app.py --server.port 8501

______________________________________________________________________

🏗️ 建筑与管道

用户工作流

1. Enter description      →  "E-commerce platform with multi-tier services"
2. Click Refine           →  AI expands to 20-27+ services with best practices
3. Review well-architected assessment  →  See pillar scores and gaps
4. Review & approve       →  Edit refined description if needed
5. Generate               →  Diagram rendered with 30+ auto-corrections applied

7级NLP管道（LangGraph）

User Input
    │
    ▼
[1] AWS Pattern Detection  (AwsPatternSkill — Architect + Critic + Reviewer agents)
                           Identifies architecture patterns, validates design
    │
    ▼
[2] Well-Architected Evaluation  (WellArchitectedSkill)
                           Scores against 5 pillars: Operational Excellence, Security,
                           Reliability, Performance Efficiency, Cost Optimization
    │
    ▼
[3] Description Refinement  (DescriptionRefinerChain — Gemini 2.5-Flash)
                           Expands to 20+ services, adds data flows, layers, best practices
    │
    ▼
[4] Blueprint Generation  (BlueprintArchitectChain — Gemini 2.5-Flash)
                          Extracts services, relationships → structured JSON with clustering
    │
    ▼
[5] Code Generation  (DiagramCoderChain — Gemini 2.5-Flash)
                     JSON blueprint → Python diagrams code
    │
    ▼
[6] Validation & Auto-Fix  (DiagramValidator + 30+ regex auto-fixes)
                           AST parse · security scan · service name corrections
                           • 30+ explicit mappings (OpenSearch, EventBridge, etc.)
                           • Smart fallback: unmapped services → Rack("ServiceName")
    │
    ├─ [If code fails] ─→ Loop back to [5] (regenerate code, up to 3 times)
    │
    ▼
[7] Rendering  (DiagramGenerator — Wildcard imports + exec)
               Executes code with all diagrams symbols pre-imported
               PNG / PDF / SVG output

关键设计决策

📐 高层架构重点

• VPC作为容器 --服务显示为VPC成员（通过集群），而不是细粒度VPC端点
• 稀疏连接 --20多个服务有15-30个有意义的边（避免视觉混乱）
• 逻辑群集 --VPC、公共/私有子网、监控、安全、集成、存储（可视化层次结构）

🤖 智能服务处理

• 显式映射 --30个常用服务名称（OpenSearch、EventBridge、DynamoDB等）
• 智能回退 --使用未映射的服务（警卫、预报、基岩等） Rack("ServiceName") 通用图标
• 无代码故障 --防止名称错误；即使服务未知，图表也始终会呈现

✅ 生产级最佳实践

• 架构良好的框架 --代码生成前的集成支柱评估
• 架构模式 --13种模式模板（RAG、无服务器、数据管道、流媒体、机器学习、事件驱动、CDN、物联网、Kubernetes、生成式AI、HA/DR、数据仓库、安全）
• 多代理验证 --建筑师+评论家+评审员确保设计连贯性

______________________________________________________________________

🎯 真实世界的例子

示例1：电子商务生产平台（26项服务）

输入说明：

Enterprise e-commerce platform with multi-region support,
fraud detection, real-time inventory, and order processing.

生成的架构：

✅ Route53 (DNS failover)
✅ CloudFront (CDN global distribution)
✅ WAF + ALB (entry point security)
✅ ECS (4 containerized microservices)
✅ RDS (multi-AZ database)
✅ DynamoDB (sessions, cart state)
✅ ElastiCache (Redis for hot data)
✅ OpenSearch (product catalog search)
✅ S3 (static assets, inventory data)
✅ SQS + SNS (async order processing)
✅ EventBridge (event orchestration)
✅ Cognito (user authentication)
✅ Secrets Manager (credentials, API keys)
✅ KMS (encryption keys)
✅ GuardDuty (threat detection)
✅ CloudWatch + X-Ray (observability)
✅ CloudWatch Logs (centralized logging)
✅ NAT Gateway (outbound VPC traffic)
✅ IAM (least privilege access)
+ 7 more services across monitoring, security, integration layers

韵律学：

• 节点： 26服务
• 集群： 8（VPC、公共/私有子网、监控、安全、集成、存储等）
• 关系： 60+（稀疏但有意义）
• 应用了自动修复： DynamoDB→ DynamodbTable、EventBridge→ Eventbridge、OpenSearch→ 亚马逊开放搜索服务，警卫职责→ 机架（“警卫”）
• 结果： ✅ 生产级图，477KB PNG，60+逻辑连接

______________________________________________________________________

示例2：视频流平台（27项服务）

输入说明：

Global video streaming service with transcoding, caching,
adaptive bitrate delivery, and real-time analytics.

生成的架构：

✅ Route53 (geo-routing for global users)
✅ CloudFront (content delivery network)
✅ API Gateway + ALB (entry points)
✅ WAF (API protection)
✅ Lambda (compute for encoding, metadata)
✅ S3 (video storage, manifests)
✅ RDS (metadata, user accounts)
✅ DynamoDB (sessions, playback state)
✅ ElastiCache (cache layer)
✅ OpenSearch (video search indexing)
✅ SQS (transcode job queue)
✅ SNS (notification fan-out)
✅ EventBridge (pipeline orchestration)
✅ MediaConvert (video transcoding) → Auto-fixed to Rack("MediaConvert")
✅ SageMaker (ML for recommendations) → Auto-fixed to Rack("SageMaker")
✅ Cognito (user auth)
✅ Secrets Manager (API keys, DB passwords)
✅ KMS (data encryption)
✅ CloudWatch + X-Ray (monitoring)
+ 8 more services (IAM, Backup, monitoring, security)

韵律学：

• 节点： 27服务
• 集群： 7（可读性逻辑分组）
• 关系： 30（稀疏，仅主流）
• 应用了自动修复： 8+服务已纠正
• 结果： ✅ 清晰易读的图表，有30个连接

______________________________________________________________________

示例3:IoT监控平台（26项服务）

输入说明：

Real-time IoT device monitoring with anomaly detection,
remote control, and multi-tenant analytics.

生成的架构：

• 物联网服务： 物联网核心、物联网绿草、物联网分析、物联网活动、物联网SiteWise
• 处理： Lambda（流处理）
• 储存： S3（原始数据）、DynamoDB（设备状态）、RDS（分析）
• 分析： Kinesis（数据流）、OpenSearch（日志分析）
• 可视化： QuickSight（仪表板）
• 安全： Cognito，保密经理，守卫职责，KMS
• 监控： CloudWatch，X射线

结果： ✅ 处理所有物联网服务（一些自动固定到机架，功能齐全）

______________________________________________________________________

📊 性能和能力

______________________________________________________________________

🔍 架构良好的框架集成

每个架构都会根据以下标准进行评估 AWS的五大支柱 渲染前：

1. 卓越运营

• 推荐：CloudWatch、X-Ray、CloudWatch日志、EventBridge、系统管理器、配置
• 检查：监控、日志记录、自动化、运行手册

2. 安全

• 推荐：IAM、Cognito、秘密管理器、KMS、WAF、警卫职责、检查员、Macie、VPC
• 检查：访问控制、加密、威胁检测、合规性

3. 可靠性

• 建议：多AZ、自动缩放、RDS多AZ、Route 53、备份、SQS、SNS、DynamoDB全局表
• 检查：冗余、故障转移、备份、自动恢复

4. 性能效率

• 推荐：CloudFront、ElastiCache、RDS读取副本、DynamoDB按需、Lambda、全局加速器
• 检查：缓存、CDN、数据库优化、大小合适

5. 成本优化

• 建议：成本资源管理器、预算、计算优化器、节省计划、Spot实例、S3生命周期
• 检查：大小正确、保留容量、生命周期策略、标记

结果： 架构得分为每个支柱0-100分+总分+具体差距建议。

______________________________________________________________________

📡 API 参考

交互式文档： http://localhost:8000/docs

细化描述

通过模式检测和良好架构评估，将简要输入扩展到生产级架构（20-27项服务）：

curl -X POST http://localhost:8000/v1/diagrams/refine \
  -H "Content-Type: application/json" \
  -d '{
    "description": "E-commerce platform with real-time inventory and fraud detection"
  }'

答复：

{
  "success": true,
  "original": "E-commerce platform with real-time inventory and fraud detection",
  "refined": "Enterprise e-commerce platform featuring...\n- API Gateway + ALB entry points\n- ECS microservices\n- RDS multi-AZ database...",
  "pattern": "serverless_rest_api",
  "well_architected": {
    "pillars": [
      {
        "pillar": "Operational Excellence",
        "score": 78,
        "strengths": ["CloudWatch monitoring", "X-Ray tracing"],
        "gaps": ["Missing CloudWatch Logs aggregation", "No EventBridge automation"],
        "recommendations": ["Add CloudWatch Logs", "Implement EventBridge for ops events"]
      },
      ...
    ],
    "overall_score": 82,
    "summary": "Strong security posture with multi-AZ database..."
  },
  "message": "Description refined with 24 services, pattern detected, and architecture assessment complete"
}

生成图表

根据描述生成图表，并自动更正服务名称（30+个映射）：

curl -X POST http://localhost:8000/v1/diagrams/generate \
  -H "Content-Type: application/json" \
  -d '{
    "description": "E-commerce platform with Route53, CloudFront, API Gateway, Lambda, RDS, DynamoDB, ElastiCache, OpenSearch, SQS, SNS, EventBridge, Cognito, Secrets Manager, KMS, GuardDuty, CloudWatch, X-Ray, and more",
    "name": "ecommerce_platform"
  }'

答复：

{
  "success": true,
  "diagram_id": "ecommerce_platform_2024_02_27_143025",
  "name": "ecommerce_platform",
  "file_path": "/path/to/ecommerce_platform.png",
  "format": "png",
  "size_bytes": 487234,
  "services_count": 26,
  "clusters_count": 8,
  "relationships_count": 60,
  "auto_fixes_applied": [
    "OpenSearch() → AmazonOpensearchService()",
    "EventBridge() → Eventbridge()",
    "DynamoDB() → DynamodbTable()",
    "GuardDuty() → Rack('GuardDuty')",
    "...and 10+ more"
  ],
  "validation_report": {
    "ast_valid": true,
    "security_checks_passed": 15,
    "unauthorized_symbols": [],
    "execution_time_ms": 2847
  },
  "message": "Diagram generated successfully with 26 AWS services across 8 clusters"
}

列出最近的图表

curl http://localhost:8000/v1/diagrams/history?limit=10

获取具体图表

curl http://localhost:8000/v1/diagrams/ecommerce_platform_2024_02_27_143025

______________________________________________________________________

⚙️ 配置

复制 .env.example 到 .env:

cp .env.example .env
# Edit .env and set GOOGLE_API_KEY=your_key

环境变量

LangChain配置

管道用途 双子座2.5闪光灯 优化参数：

• temperature: 0.3 --确定性输出，可复制的图表
• max_output_tokens: 10000 --支持20-27+服务架构
• retry_policy: stop_after_attempt=2 --智能错误恢复

图表生成设置

• 最大服务： 27+（通过电子商务和视频流平台测试）
• 目标连接： 15-30（稀疏、有意义的关系）
• 集群： 8+（VPC、子网、逻辑分组）
• 自动修复： 30+服务名称更正
• 渲染时间： 2-5秒（GraphViz）

______________________________________________________________________

📁 项目结构

mcp-aws/
├── src/
│   ├── presentation/
│   │   ├── api.py                    # FastAPI app — /refine, /generate, /history
│   │   └── api_models.py             # Pydantic request/response models
│   ├── application/
│   │   └── services.py               # Use-case services + repository pattern
│   ├── infrastructure/
│   │   ├── nlp/                      # 🆕 NLP subpackage (refactored from monolithic chains)
│   │   │   ├── chains.py             # DescriptionRefiner, BlueprintArchitect, DiagramCoder
│   │   │   ├── skill.py              # AwsPatternSkill (Architect + Critic + Reviewer agents)
│   │   │   ├── outputs.py            # Pydantic models for LLM outputs
│   │   │   └── well_architected_skill.py  # 🆕 Well-Architected Framework evaluation
│   │   ├── skills/                   # 🆕 Prompt templates + skill definitions
│   │   │   ├── chains/
│   │   │   │   ├── refiner.md        # Description refinement (expand to 20+ services)
│   │   │   │   ├── pattern_skill.md  # Pattern detection instructions
│   │   │   │   ├── blueprint.md      # JSON blueprint generation rules
│   │   │   │   └── coder.md          # Python diagrams code generation (30+ service mappings)
│   │   │   ├── agents/
│   │   │   │   ├── architect.md      # Architect agent persona
│   │   │   │   ├── critic.md         # Critic agent (validates design)
│   │   │   │   └── reviewer.md       # Reviewer agent (final synthesis)
│   │   │   ├── aws_patterns.md       # 13 architecture patterns with Mermaid diagrams
│   │   │   └── well_architected.md   # 🆕 5-pillar framework guidelines (40+ service recommendations)
│   │   ├── langgraph_pipeline.py     # 7-node LangGraph state machine (with retry logic)
│   │   ├── generator.py              # Wildcard imports + diagram execution
│   │   ├── validator.py              # AST validation + security scan + 30+ auto-fixes
│   │   ├── storage.py                # File-based storage with JSON index
│   │   ├── aws_mcp_client.py         # AWS Documentation MCP client (optional)
│   │   ├── mcp_client.py             # MCP direct client
│   │   ├── server.py                 # MCP server tools
│   │   └── config.py                 # pydantic-settings configuration
│   └── domain/
│       └── models.py                 # Domain models + exceptions
├── ui/
│   ├── app.py                        # Streamlit 2-step UI with refinement + approval
│   └── api_client.py                 # HTTP client for the API
├── docker/
│   ├── Dockerfile.api
│   └── Dockerfile.ui
├── docker-compose.yml
├── Makefile
├── pyproject.toml
├── .env.example
└── .claude/
    └── projects/
        └── mcp-aws/
            └── memory/               # Session memory (architecture patterns, common errors)
                ├── MEMORY.md         # Latest session notes
                └── [topic-specific docs]

关键NLP模块

______________________________________________________________________

测试

# Run all tests
uv run pytest -xvs tests/

# Single file
uv run pytest -xvs tests/test_validator.py

# With coverage
uv run pytest --cov=src --cov-report=html tests/

______________________________________________________________________

🔧 高级主题

添加新的架构模式

1. 在中定义模式 aws_patterns.md:

   ## YourPattern

   **Flow:** User → Lambda → DynamoDB
   **Services:** Lambda, DynamoDB, API Gateway, CloudWatch, IAM
   **Checklist:**
   - [ ] Include monitoring (CloudWatch, X-Ray)
   - [ ] Add security layer (IAM, KMS)

1. 模式自动检测 通过awsPatterskill代理

1. 自动应用优化 模式中的最佳实践

扩展良好架构评估

1. 编辑 well_architected.md 添加/更新支柱指南
2. 修改 well_architected_skill.py 如果需要自定义评分逻辑
3. 自动评估 在代码生成之前运行

了解汽车修理

该系统适用 30+自动服务名称更正 分为两层：

第1层：显式映射 （in chains.py):

r'OpenSearch\(': 'AmazonOpensearchService(',
r'EventBridge\(': 'Eventbridge(',
r'DynamoDB\(': 'DynamodbTable(',

第二层：智能回退 （捕获所有正则表达式）：

# Any undefined CamelCase class → Rack("ServiceName")
r'\b([A-Z][a-zA-Z0-9]*)\('
  → 'Rack(' if not in known_classes

结果： 即使是未映射的服务（GuardDuty、Forecast、Bedrock、IoT服务）也能成功渲染。

自定义服务映射

要添加新的显式映射，请执行以下操作：

1. 编辑 src/infrastructure/nlp/chains.py 第275-330行（英寸 _fix_invalid_service_names):

   r'CustomService\(': 'CorrectService(',

1. 更新 coder.md 用于记录修复的服务映射表

1. 测试： 描述中使用CustomService的图表

调试LLM输出

1. 检查Docker日志：

   make logs  # Tails API logs

1. 启用调试日志记录：

   AWS_DIAGRAM_LOG_LEVEL=DEBUG make up

1. 检查生成的蓝图 （API响应包括完整的JSON）

1. 检查生成的代码 （日志显示执行前的Python代码）

______________________________________________________________________

🚀 故障排除指南

未找到GraphViz

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt install graphviz

# Verify installation
dot -V

diagrams 未找到模块

uv sync
# Or in Docker:
make rebuild

无法从UI访问API

# Check if API is running
curl http://localhost:8000/health

# Verify CLOUDFORGE_API_URL in .env
echo $CLOUDFORGE_API_URL
# Should match: http://localhost:8000

图表生成超时（>10s）

• 检查日志： make logs -查找LLM API延迟
• 验证GraphViz： dot -V 应立即完成
• 增加代币限额 在 chains.py 如果生成25+个服务

名称错误：未定义名称“SomeService”

• 预期： 智能回退使用 Rack("SomeService")
• 如果失败： 服务存在于 diagrams 图书馆，但没有被抓住

- 添加显式映射到 chains.py 第275-330行 - 在GitHub上用服务名称提交问题

“AST验证失败”或“未终止字符串”

• 可能原因： 服务标签中的无注释引号
• 检查： API响应中生成的代码（执行前）
• 修复： 编辑描述以使用不带特殊字符的简单名称

良好架构得分为0

• 检查： 精炼商API响应包括 well_architected 领域
• 调试： 手动呼叫 /v1/diagrams/refine 端点
• 验证： GOOGLE_API_KEY有效且有配额

Docker容器立即退出

# Check logs
docker logs mcp-aws-api-1

# Rebuild and restart
make rebuild
make up

未检测到图案

• 检查： 描述与模式关键字匹配
• 列表： aws_patterns.md 第5-12行显示了检测触发器
• 调试： 呼叫 /v1/diagrams/refine 查看检测到的响应模式

______________________________________________________________________

📚 支持的体系结构模式

CloudForge识别并优化 13种AWS架构模式:

1. RAG/语义搜索 --LLM+矢量数据库+检索
2. 无服务器REST API -API网关+Lambda+DynamoDB
3. 数据管道/ETL --S3+胶水+红移/DW
4. 实时流媒体分析 --Kinesis+Spark+BI
5. 机器学习平台/MLOps --SageMaker+S3+Lambda
6. 事件驱动架构 --EventBridge+Lambda+社交网络
7. 静态网站/CDN --S3+云前+路由53
8. 物联网平台 --物联网核心+绿草+分析
9. 容器平台/Kubernetes --ECS/EKS+ALB+RDS
10. 生成式AI/LLM应用 --基岩+RAG+Lambda
11. 高可用性/灾难恢复 --多AZ+故障切换+备份
12. 分析/数据仓库 --Redshift+胶水+QuickSight
13. 安全与合规 --警卫+安全中心+KMS+审计

每种模式都包括推荐服务、多代理验证和架构良好的检查。

______________________________________________________________________

🎓 描述的最佳实践

✅ 好的描述

"Enterprise e-commerce platform with:
- Multi-region global distribution
- Fraud detection and real-time inventory
- Microservice-based order processing
- Multi-tier security with SSO
- Real-time analytics and dashboards"

结果： 25-27项服务，8+集群，完整架构

❌ 描述不佳

"Shopping website"

结果： 只有5-8个服务，最低架构

提示： 使用触发良好架构支柱的关键字：

• 卓越运营： 监控、日志记录、自动化、运行手册
• 安全： 加密、身份验证、多因素、最小权限
• 可靠性： 故障转移、备份、多AZ、自动扩展
• 演出 缓存、CDN、读取副本、全局分发
• 成本： 正确的规模、生命周期策略、点实例、保留容量

______________________________________________________________________

📖 文档与技能

所有提示均为 外部可编辑 （Python中没有硬编码）。更改立即生效。

______________________________________________________________________

🤝 贡献

1. 修复服务映射： 编辑 chains.py + coder.md
2. 添加图案： 编辑 aws_patterns.md + refiner.md
3. 改善良好的架构： 编辑 well_architected.md
4. 报告错误： 包括描述、生成的代码和错误消息

______________________________________________________________________

📄 许可证

麻省理工学院——见 许可证.