Initial commit
This commit is contained in:
Zhongwei Li
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"name": "architecture-design",
|
||||
"description": "Create comprehensive software architecture documentation through guided interviews.",
|
||||
"version": "2.0.1",
|
||||
"author": {
|
||||
"name": "Truong Vu",
|
||||
"email": "vukhanhtruong@gmail.com"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# architecture-design
|
||||
|
||||
Create comprehensive software architecture documentation through guided interviews.
|
||||
109
plugin.lock.json
Normal file
109
plugin.lock.json
Normal file
@@ -0,0 +1,109 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:vukhanhtruong/claude-rock:plugins/architecture-design",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "523a672446d07d31ba279030e7f8a83da5a8f53d",
|
||||
"treeHash": "a62b9bceae55fe8dcd5418bc182958dfa4bd6ab25df7b8e1ee1d93f6337ac883",
|
||||
"generatedAt": "2025-11-28T10:28:57.322760Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "architecture-design",
|
||||
"description": "Create comprehensive software architecture documentation through guided interviews.",
|
||||
"version": "2.0.1"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "beeaae03f5e72b1716d396437448a0eff4063c17977555fb993febf90d53775b"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "51a6805f1cbbb1792346219ca6d68b366f181d5c1bcc929aeac6b35ea7d04aea"
|
||||
},
|
||||
{
|
||||
"path": "skills/README.md",
|
||||
"sha256": "b19097f86ad9fe35ed42320287f7bdf39e5ca21bb83ba89d06b9af9f5deb4a44"
|
||||
},
|
||||
{
|
||||
"path": "skills/SKILL.md",
|
||||
"sha256": "2c4f5e7ae0f40462e531629529ac7774ff248e11822997b2b7f141021a85896b"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/workflows.md",
|
||||
"sha256": "a799af6c8b89eed76c2fb3677ecf418de5280591f226b584c68d14cbe2488f8a"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/python.md",
|
||||
"sha256": "74b7d333dc407f84f61fb3fdeec7bac166d9b90c40e2ae606d2cad42a12910ad"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/mermaid-diagrams.md",
|
||||
"sha256": "f3859bd144560a42341eb2f4be50173a7f0771f530ae984f41253ec3846c466f"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/java.md",
|
||||
"sha256": "761c3f6a147c1e8649df86d04033d423b4d32f3dbbb6eefbc60c0ac8dad3a792"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/microservices.md",
|
||||
"sha256": "06bfb666f8a0c88e7f285cdd74ac4568dc47b5f7831ecdb81d0ae46691102e4f"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/serverless.md",
|
||||
"sha256": "355fe7936cde653ffa085a4839a3c27a1d81b924631179c21e86084973777516"
|
||||
},
|
||||
{
|
||||
"path": "skills/references/nodejs.md",
|
||||
"sha256": "d804d3150d1383fd55318f4dabf9be78b9ce614d05b84092b86203eac8ebcb69"
|
||||
},
|
||||
{
|
||||
"path": "skills/scripts/create_package.py",
|
||||
"sha256": "05156e0cd89d8f75a07f936ec9321a694124ef03fbb7a798ae19c50d5265b69d"
|
||||
},
|
||||
{
|
||||
"path": "skills/scripts/validate_architecture.py",
|
||||
"sha256": "ce14906e53fe8203376f361d82752baf66f977b4b5b7f6d0da3fb7768a01f5b3"
|
||||
},
|
||||
{
|
||||
"path": "skills/scripts/generate_diagram.py",
|
||||
"sha256": "4ad0851a4ecd31c8f9ab7632d41e3db34a11503c8dbf81f17e48ec4ed0be1904"
|
||||
},
|
||||
{
|
||||
"path": "skills/scripts/generate_openapi.py",
|
||||
"sha256": "74fa299e1fb7822db60120f5286b900c3b34c519ce68c6251d18048fed87c869"
|
||||
},
|
||||
{
|
||||
"path": "skills/scripts/generate_mermaid.py",
|
||||
"sha256": "3417c410383a11bbfd82b9cb04f86a2a5bdb1581103e65e6cf873bad7b14882b"
|
||||
},
|
||||
{
|
||||
"path": "skills/assets/ARCHITECTURE.md",
|
||||
"sha256": "ec9ef9903a5dddda0670333fca9f38e106bc3685685dc1de6e46455e0b7c766d"
|
||||
},
|
||||
{
|
||||
"path": "skills/assets/ARCHITECTURE-microservices.md",
|
||||
"sha256": "3be42810874ff7eb02dcf58f032b2509e855cd1a3a5bd4cc859a545066b01c19"
|
||||
},
|
||||
{
|
||||
"path": "skills/assets/ARCHITECTURE-monolith.md",
|
||||
"sha256": "a3e3b7222e447696f6ae270a6e6f8989e276ec938bccd525ed50584bf719741b"
|
||||
}
|
||||
],
|
||||
"dirSha256": "a62b9bceae55fe8dcd5418bc182958dfa4bd6ab25df7b8e1ee1d93f6337ac883"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
225
skills/README.md
Normal file
225
skills/README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Architecture Design - Claude Skill
|
||||
|
||||
A comprehensive Claude skill for creating professional software architecture documentation through guided interviews and template-based generation.
|
||||
|
||||
## Overview
|
||||
|
||||
The Architecture Design skill transforms Claude into an expert architecture consultant capable of generating detailed, standardized ARCHITECTURE.md files. It helps development teams create comprehensive documentation that accelerates onboarding and improves system understanding.
|
||||
|
||||
[Sample architecture document](https://hackmd.io/@B0gg3-MvQL-KX7jvQ4KI8Q/rkErFMUCgl) for a Trello clone app with NextJS and Supbabase generated by this skill.
|
||||
|
||||
## Features
|
||||
|
||||
### Core Capabilities
|
||||
|
||||
- **Interactive Architecture Interviews**: Guided sessions to gather system information (5-7 questions)
|
||||
- **Template-Based Generation**: Generate comprehensive 11-section document
|
||||
|
||||
```sh
|
||||
1. Project Structure
|
||||
2. High-Level System Diagram
|
||||
3. Core Components
|
||||
4. Data Stores
|
||||
5. External Integrations / APIs
|
||||
6. Deployment & Infrastructure
|
||||
7. Security Considerations
|
||||
8. Development & Testing Environment
|
||||
9. Future Considerations / Roadmap
|
||||
10. Project Identification
|
||||
11. Glossary / Acronyms
|
||||
```
|
||||
|
||||
- **Visual Diagrams**: Generates system diagrams and C4 model representations
|
||||
- **Advanced Features**: Mermaid diagrams, OpenAPI spec
|
||||
|
||||
## Claude Code Installation
|
||||
|
||||
```
|
||||
|
||||
/plugin marketplace add vukhanhtruong/claude-rock
|
||||
|
||||
/plugin install architecture-design@claude-rock
|
||||
```
|
||||
|
||||
## Claude Chat Installation
|
||||
|
||||
### Step 1: Download the Skill
|
||||
|
||||
1. Download the [bundle zip](https://github.com/vukhanhtruong/claude-rock/raw/refs/heads/main/build/architecture-design.zip) file
|
||||
2. Save it to your computer
|
||||
|
||||
### Step 2: Upload to Claude
|
||||
|
||||
1. Go to [Settings > Capabilities](https://claude.ai/settings/capabilities)
|
||||
2. Click "Upload Skill"
|
||||
3. Select the file you downloaded
|
||||
4. Wait for the upload to complete
|
||||
|
||||
### Step 3: Enable the Skill
|
||||
|
||||
1. In the same Settings > Capabilities page
|
||||
2. Find "Architecture Design" in your skills list
|
||||
3. Toggle the switch to enable it
|
||||
4. The skill is now ready to use
|
||||
|
||||
## How to Use
|
||||
|
||||
### Trigger the Skill
|
||||
|
||||
Say any of these:
|
||||
|
||||
- "Create architecture documentation"
|
||||
- "Document my system architecture"
|
||||
- "Design a new architecture"
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```
|
||||
"Create architecture documentation for my Node.js e-commerce platform"
|
||||
```
|
||||
|
||||
```
|
||||
"Design an architecture for an e-commerce application using Java Spring Boot microservices"
|
||||
```
|
||||
|
||||
```
|
||||
"Create a full architecture documentation package for my serverless application on AWS"
|
||||
```
|
||||
|
||||
```
|
||||
"Generate architecture for my Python Django application"
|
||||
```
|
||||
|
||||
#### Need to update? Just say:
|
||||
|
||||
`"Update the architecture documentation"`
|
||||
|
||||
`"Add Redis cache to the architecture"`
|
||||
|
||||
`"Document the new services"`
|
||||
|
||||
### Answer Questions
|
||||
|
||||
The skill will ask 5-7 questions about:
|
||||
|
||||
- Architecture pattern (monolith/microservices/serverless)
|
||||
- Technology stack (Node.js/Python/Java/etc.)
|
||||
- Components and services
|
||||
- Data stores
|
||||
- Deployment infrastructure
|
||||
|
||||
### Receive Documentation
|
||||
|
||||
Get a complete ARCHITECTURE.md with:
|
||||
|
||||
- All 11 required sections
|
||||
- System diagrams
|
||||
- Technology-specific patterns
|
||||
- Best practices
|
||||
- Validated for completeness
|
||||
|
||||
## What You Get
|
||||
|
||||
### ARCHITECTURE.md File
|
||||
|
||||
- Comprehensive documentation
|
||||
- Professional format
|
||||
- Technology-specific patterns
|
||||
- Validated completeness
|
||||
- Ready to commit to repo
|
||||
|
||||
### Enhanced Features (when requested)
|
||||
|
||||
- **Visual Diagrams** - Mermaid.js diagrams (C4 Context, Container, Component, Data Flow, Deployment)
|
||||
- **API Specifications** - OpenAPI 3.0 compliant documentation
|
||||
|
||||
### System Diagrams
|
||||
|
||||
- ASCII-based (version control friendly)
|
||||
- Multiple diagram types
|
||||
- Clear component relationships
|
||||
- Data flow visualization
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
$(pwd)
|
||||
├── ARCHITECTURE.md # Main documentation
|
||||
├── openapi.json # API specification (if applicable)
|
||||
└── diagrams/ # Visual documentation
|
||||
├── 01-context.png # System context diagram
|
||||
├── 02-container.png # Container diagram
|
||||
├── 03-component.png # Component diagram
|
||||
├── 04-dataflow.png # Data flow diagram
|
||||
├── 05-deployment.png # Deployment diagram
|
||||
└── source/ # Editable source files
|
||||
├── 01-context.mmd
|
||||
├── 02-container.mmd
|
||||
├── 03-component.mmd
|
||||
├── 04-dataflow.mmd
|
||||
└── 05-deployment.mmd
|
||||
```
|
||||
|
||||
## Speed & Efficiency
|
||||
|
||||
- **Questions**: 5-7 focused questions
|
||||
- **Time**: 2-3 minutes to complete
|
||||
- **Output**: Comprehensive 11-section document
|
||||
- **Quality**: Professional, validated, complete
|
||||
|
||||
## Pro Tips
|
||||
|
||||
### For New Projects
|
||||
|
||||
- Be clear about your architecture goals
|
||||
- Mention any constraints upfront
|
||||
- Specify your tech preferences
|
||||
|
||||
### For Existing Systems
|
||||
|
||||
- Describe current pain points
|
||||
- Mention planned improvements
|
||||
- Identify undocumented areas
|
||||
|
||||
### For Best Results
|
||||
|
||||
- Answer questions completely
|
||||
- Provide specific names (not generic terms)
|
||||
- Mention actual tools and services you use
|
||||
- Let the skill know your deployment target
|
||||
|
||||
## Key Benefits
|
||||
|
||||
1. **Consistency**: Standard format every time
|
||||
2. **Completeness**: No missing sections
|
||||
3. **Specificity**: Your tech stack, your patterns
|
||||
4. **Speed**: Minutes instead of hours
|
||||
5. **Quality**: Industry best practices included
|
||||
6. **Validation**: Automatic checks for completeness
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill Not Working
|
||||
|
||||
1. Verify the skill is enabled in Settings > Capabilities
|
||||
2. Try refreshing Claude and starting a new conversation
|
||||
3. Check that you're using the correct trigger phrases
|
||||
|
||||
### PDF Generation Issues
|
||||
|
||||
- PDF generation requires optional tools (pandoc or WeasyPrint)
|
||||
- If tools aren't available, you'll get clear instructions to install them
|
||||
- The skill still works without PDF generation
|
||||
|
||||
### Diagram Rendering
|
||||
|
||||
- Mermaid diagrams can be rendered to PNG with `@mermaid-js/mermaid-cli`
|
||||
- If not available, you'll get the .mmd source files instead
|
||||
- These can be rendered later using online [Mermaid editors](https://mermaid.live)
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues:
|
||||
|
||||
1. Use the skill's built-in help: "Show architecture-design skill help"
|
||||
2. Create an issue on the skill's GitHub [repository](https://github.com/vukhanhtruong/claude-rock/issues)
|
||||
406
skills/SKILL.md
Normal file
406
skills/SKILL.md
Normal file
@@ -0,0 +1,406 @@
|
||||
---
|
||||
name: architecture-design
|
||||
description: Generate comprehensive software architecture documentation (ARCHITECTURE.md) with C4 diagrams, OpenAPI specs, and technology-specific guidance. This skill should be used when creating architecture documentation for new projects, documenting existing systems, or updating architectural specifications.
|
||||
---
|
||||
|
||||
# Architecture Design
|
||||
|
||||
Generate professional software architecture documentation with visual diagrams and API specifications through structured interviews. Create complete ARCHITECTURE.md files covering all required sections with technology-specific patterns, C4 model diagrams, and OpenAPI 3.0 specifications.
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Step 1: Assess Project Type
|
||||
|
||||
Determine the project type by asking the user:
|
||||
|
||||
- **New project?** Gather requirements and design architecture
|
||||
- **Existing system?** Document current state
|
||||
- **Update needed?** Identify changed components
|
||||
|
||||
### Step 2: Gather Essential Information
|
||||
|
||||
Conduct a brief interview (5-7 questions maximum) to collect:
|
||||
|
||||
1. **Architecture pattern:** Monolith, microservices, or serverless?
|
||||
2. **Primary technology:** Node.js, Python, Java, or other?
|
||||
3. **Key components:** Main services or modules?
|
||||
4. **Data stores:** Databases and caches?
|
||||
5. **Cloud provider:** AWS, GCP, Azure, or on-premise?
|
||||
6. **Deployment:** How is it deployed?
|
||||
7. **External integrations:** Third-party services?
|
||||
|
||||
### Step 3: Select Template and Load References
|
||||
|
||||
**Choose template based on architecture pattern:**
|
||||
|
||||
- Monolith → Use `assets/ARCHITECTURE-monolith.md`
|
||||
- Microservices → Use `assets/ARCHITECTURE-microservices.md`
|
||||
- Uncertain → Use `assets/ARCHITECTURE.md`
|
||||
|
||||
**Load technology-specific references:**
|
||||
|
||||
- Node.js projects → Load `references/nodejs.md` for Express, NestJS, Fastify patterns
|
||||
- Python projects → Load `references/python.md` for Django, Flask, FastAPI patterns
|
||||
- Java projects → Load `references/java.md` for Spring Boot, Jakarta EE patterns
|
||||
|
||||
**Load pattern-specific references when applicable:**
|
||||
|
||||
- Microservices → Load `references/microservices.md` for service boundaries and communication patterns
|
||||
- Serverless → Load `references/serverless.md` for function organization and event sources
|
||||
|
||||
### Step 4: Generate System Diagram
|
||||
|
||||
Generate appropriate diagrams using `scripts/generate_diagram.py`:
|
||||
|
||||
**For monolithic architectures:**
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py layered
|
||||
```
|
||||
|
||||
**For microservices architectures:**
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py flow
|
||||
```
|
||||
|
||||
**For simple systems:**
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py simple
|
||||
```
|
||||
|
||||
Customize diagrams with JSON configuration for specific components.
|
||||
|
||||
### Step 5: Populate Template
|
||||
|
||||
Complete the template sections in the specified order:
|
||||
|
||||
1. **Project Identification (Section 10)** - Add project name, repository, contact, date
|
||||
2. **Project Structure (Section 1)** - Define directory layout
|
||||
3. **System Diagram (Section 2)** - Insert generated diagram
|
||||
4. **Core Components (Section 3)** - Document components from interview
|
||||
5. **Data Stores (Section 4)** - Describe databases and caches
|
||||
6. **External Integrations (Section 5)** - List third-party services
|
||||
7. **Deployment (Section 6)** - Detail infrastructure setup
|
||||
8. **Security (Section 7)** - Specify authentication and encryption
|
||||
9. **Development (Section 8)** - Outline setup and testing procedures
|
||||
10. **Future Considerations (Section 9)** - Document roadmap items
|
||||
11. **Glossary (Section 11)** - Define domain terminology
|
||||
|
||||
Apply technology-specific patterns from loaded references to enhance each section.
|
||||
|
||||
### Step 6: Validate
|
||||
|
||||
Execute the validation script to ensure quality:
|
||||
|
||||
```bash
|
||||
python scripts/validate_architecture.py ARCHITECTURE.md
|
||||
```
|
||||
|
||||
Address any issues or warnings before delivering the documentation.
|
||||
|
||||
## Interview Best Practices
|
||||
|
||||
**Maintain focused questioning:**
|
||||
|
||||
- Ask 2-3 questions at a time
|
||||
- Build upon previous answers
|
||||
- Skip redundant questions
|
||||
|
||||
**Adapt communication style:**
|
||||
|
||||
- Technical users: Use precise terminology
|
||||
- Non-technical users: Simplify language
|
||||
- Uncertain users: Offer defaults or placeholders
|
||||
|
||||
**Handle information gaps:**
|
||||
|
||||
- Mark uncertain items for review
|
||||
- Add [TODO] for missing information
|
||||
- Suggest reasonable defaults based on context
|
||||
|
||||
## Technology-Specific Guidance
|
||||
|
||||
### Reference Loading Guidelines
|
||||
|
||||
**Load `references/nodejs.md` for:**
|
||||
|
||||
- Express, NestJS, Fastify projects
|
||||
- Node.js microservices
|
||||
- Serverless Node functions
|
||||
|
||||
**Load `references/python.md` for:**
|
||||
|
||||
- Django, Flask, FastAPI projects
|
||||
- Python microservices
|
||||
- Data pipelines and ML systems
|
||||
|
||||
**Load `references/java.md` for:**
|
||||
|
||||
- Spring Boot applications
|
||||
- Jakarta EE systems
|
||||
- Java microservices
|
||||
|
||||
**Load `references/workflows.md` for:**
|
||||
|
||||
- Complex interview scenarios
|
||||
- Detailed process guidance
|
||||
- Documentation update workflows
|
||||
|
||||
### Applying Technology Patterns
|
||||
|
||||
After loading references, apply the patterns to enhance:
|
||||
|
||||
- Project structure recommendations
|
||||
- Deployment configurations
|
||||
- Framework-specific best practices
|
||||
- Common library suggestions
|
||||
- Testing strategies and approaches
|
||||
|
||||
## Pattern-Specific Guidance
|
||||
|
||||
### Microservices Architecture
|
||||
|
||||
**Load `references/microservices.md` and include these elements:**
|
||||
|
||||
- Service boundaries and responsibilities
|
||||
- Communication patterns (synchronous vs asynchronous)
|
||||
- API gateway configuration
|
||||
- Service discovery mechanism
|
||||
- Data management approach
|
||||
- Observability and monitoring setup
|
||||
|
||||
**Use the microservices template** (`assets/ARCHITECTURE-microservices.md`) for proper structure.
|
||||
|
||||
### Serverless Architecture
|
||||
|
||||
**Load `references/serverless.md` and include these elements:**
|
||||
|
||||
- Function organization and boundaries
|
||||
- Event sources and triggers
|
||||
- State management approach
|
||||
- Cold start mitigation techniques
|
||||
- Cost optimization strategies
|
||||
|
||||
### Monolithic Architecture
|
||||
|
||||
**Use the monolith template** (`assets/ARCHITECTURE-monolith.md`) and emphasize:
|
||||
|
||||
- Layered architecture patterns
|
||||
- Module organization principles
|
||||
- Potential future refactoring paths
|
||||
- Scaling strategy and approaches
|
||||
|
||||
## Diagram Generation Examples
|
||||
|
||||
### Simple Architecture Diagram
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py simple '{"components": ["User", "API", "DB"], "connections": [["User", "API"], ["API", "DB"]]}'
|
||||
```
|
||||
|
||||
### Layered Architecture Diagram
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py layered '{"Presentation": ["Web UI"], "Business": ["API"], "Data": ["PostgreSQL"]}'
|
||||
```
|
||||
|
||||
### Flow Architecture Diagram
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py flow '[{"from": "Client", "to": "Gateway", "label": "HTTP"}, {"from": "Gateway", "to": "Service", "label": "route"}]'
|
||||
```
|
||||
|
||||
### C4 Context Diagram
|
||||
|
||||
```bash
|
||||
python scripts/generate_diagram.py c4 '{"system": "E-commerce Platform", "actors": ["Customer", "Admin"], "external_systems": ["Payment Gateway", "Email Service"]}'
|
||||
```
|
||||
|
||||
Integrate generated diagrams into Section 2 (System Diagram) of the ARCHITECTURE.md template.
|
||||
|
||||
## Validation
|
||||
|
||||
**Execute validation before delivering documentation:**
|
||||
|
||||
```bash
|
||||
python scripts/validate_architecture.py ARCHITECTURE.md
|
||||
```
|
||||
|
||||
**Validation checks performed:**
|
||||
|
||||
- Verify all 11 sections are present
|
||||
- Confirm required fields in Project Identification section
|
||||
- Ensure minimal content in each section
|
||||
- Count and report placeholder usage
|
||||
|
||||
**Address any warnings** about missing content or excessive placeholders.
|
||||
|
||||
## Documentation Update Workflow
|
||||
|
||||
**For incremental updates:**
|
||||
|
||||
1. Identify what has changed
|
||||
2. Update only affected sections
|
||||
3. Update the date in Section 10 (Project Identification)
|
||||
4. Re-run validation to ensure quality
|
||||
|
||||
**For major updates:**
|
||||
|
||||
1. Review the entire document
|
||||
2. Regenerate diagrams if structure has changed
|
||||
3. Update multiple sections as needed
|
||||
4. Consider adding version notes
|
||||
|
||||
## Mermaid Diagram Generation
|
||||
|
||||
After creating ARCHITECTURE.md, generate the complete set of 5 Mermaid diagrams.
|
||||
|
||||
### Load Mermaid Instructions
|
||||
|
||||
When users request diagrams or complete documentation packages:
|
||||
|
||||
```
|
||||
Load references/mermaid-diagrams.md
|
||||
```
|
||||
|
||||
### Generate Complete Diagram Set
|
||||
|
||||
Create all 5 diagrams following the guidance in mermaid-diagrams.md:
|
||||
|
||||
1. **C4 Context** (Level 1) - System in its broader context
|
||||
2. **C4 Container** (Level 2) - Main application containers
|
||||
3. **C4 Component** (Level 3) - Internal component structure
|
||||
4. **Data Flow** - How data moves through the system
|
||||
5. **C4 Deployment** - Infrastructure topology and deployment
|
||||
|
||||
Use `scripts/generate_mermaid.py` with system JSON configuration.
|
||||
|
||||
**Save diagrams as separate .mmd files:**
|
||||
|
||||
- `01-context.mmd`
|
||||
- `02-container.mmd`
|
||||
- `03-component.mmd`
|
||||
- `04-dataflow.mmd`
|
||||
- `05-deployment.mmd`
|
||||
|
||||
**Embed diagrams in ARCHITECTURE.md Section 2** as code blocks for easy viewing and editing.
|
||||
|
||||
## OpenAPI Specification Generation
|
||||
|
||||
For systems with REST APIs, generate comprehensive OpenAPI 3.0 specifications.
|
||||
|
||||
### Generate API Specifications
|
||||
|
||||
Use `scripts/generate_openapi.py` with appropriate parameters:
|
||||
|
||||
**For simple CRUD operations:**
|
||||
|
||||
```bash
|
||||
python scripts/generate_openapi.py "ResourceName"
|
||||
```
|
||||
|
||||
**For custom API specifications:**
|
||||
|
||||
```bash
|
||||
python scripts/generate_openapi.py '{"system_name": "...", "endpoints": [...]}'
|
||||
```
|
||||
|
||||
Save the generated specification as `openapi.json` in the project directory.
|
||||
|
||||
## Complete Documentation Workflow
|
||||
|
||||
Follow this end-to-end workflow for comprehensive architecture documentation:
|
||||
|
||||
1. **Conduct structured interview** (5-7 questions maximum)
|
||||
2. **Select appropriate template** and **load relevant references**
|
||||
3. **Setup work directory**: Use current working directory `$(pwd)`
|
||||
4. **Generate ARCHITECTURE.md** with all 11 sections completed
|
||||
5. **Generate Mermaid diagrams** (5 separate .mmd files) in work directory root
|
||||
6. **Generate OpenAPI specification** (if applicable) in work directory
|
||||
7. **Deliver all generated artifacts** to the user
|
||||
|
||||
## Deliverable Organization
|
||||
|
||||
Organize generated documentation files as follows:
|
||||
|
||||
```
|
||||
├── ARCHITECTURE.md # Main architecture document
|
||||
├── openapi.json # API specification (if applicable)
|
||||
├── *.mmd (5 files) # Mermaid diagram sources
|
||||
│ ├── 01-context.mmd
|
||||
│ ├── 02-container.mmd
|
||||
│ ├── 03-component.mmd
|
||||
│ ├── 04-dataflow.mmd
|
||||
│ └── 05-deployment.mmd
|
||||
└── diagrams/ (created during packaging)
|
||||
└── *.png (5 files, if rendered to images)
|
||||
```
|
||||
|
||||
## Example Usage
|
||||
|
||||
**User request:** "Create architecture documentation for my Node.js microservices project"
|
||||
|
||||
**Execution approach:**
|
||||
|
||||
1. Select microservices template (`assets/ARCHITECTURE-microservices.md`)
|
||||
2. Load `references/nodejs.md` and `references/microservices.md`
|
||||
3. Conduct focused interview: services, databases, communication patterns, deployment
|
||||
4. Generate flow diagram using `scripts/generate_diagram.py flow`
|
||||
5. Populate all sections with Node.js and microservices-specific patterns
|
||||
6. Validate using `scripts/validate_architecture.py`
|
||||
7. Create comprehensive ARCHITECTURE.md in work directory
|
||||
|
||||
## Common Usage Scenarios
|
||||
|
||||
### New Greenfield Projects
|
||||
|
||||
- Use base template (`assets/ARCHITECTURE.md`)
|
||||
- Focus on design decisions and architecture rationale
|
||||
- Include justification for technology choices
|
||||
- Emphasize planned architecture and future scalability
|
||||
|
||||
### Existing System Documentation
|
||||
|
||||
- Ask about current pain points and challenges
|
||||
- Document the as-is state accurately
|
||||
- Note planned improvements in Section 9 (Future Considerations)
|
||||
- Capture current technology stack and limitations
|
||||
|
||||
### Legacy System Analysis
|
||||
|
||||
- Identify undocumented or poorly understood areas
|
||||
- Mark uncertain items for further investigation
|
||||
- Suggest areas requiring clarification from stakeholders
|
||||
- Document assumptions and risks
|
||||
|
||||
### Architecture Reviews and Updates
|
||||
|
||||
- Update only sections that have changed
|
||||
- Preserve information that remains accurate
|
||||
- Add new components and relationships
|
||||
- Update date in Section 10 and note changes
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Efficient documentation creation:**
|
||||
|
||||
- Begin with known information and build incrementally
|
||||
- Use placeholders for unknown items to maintain momentum
|
||||
- Leverage technology references to save time and ensure accuracy
|
||||
- Validate frequently to catch issues early
|
||||
|
||||
**High-quality output standards:**
|
||||
|
||||
- Provide specific, concrete details rather than generic descriptions
|
||||
- Include actual technology stack versions and configurations
|
||||
- Use real service names, purposes, and data flows
|
||||
- Document concrete deployment infrastructure and environments
|
||||
|
||||
**Positive user experience:**
|
||||
|
||||
- Avoid overwhelming users with excessive questions
|
||||
- Explain the documentation process and next steps
|
||||
- Show progress through the 11 sections clearly
|
||||
- Offer refinement and improvement after initial delivery
|
||||
176
skills/assets/ARCHITECTURE-microservices.md
Normal file
176
skills/assets/ARCHITECTURE-microservices.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Architecture Overview - Microservices
|
||||
|
||||
This document serves as a comprehensive guide to the microservices architecture, enabling rapid understanding of service boundaries, communication patterns, and system design.
|
||||
|
||||
## 1. Project Structure
|
||||
|
||||
```
|
||||
[Project Root]/
|
||||
├── services/ # Microservices
|
||||
│ ├── api-gateway/ # Entry point for all requests
|
||||
│ ├── user-service/ # User management
|
||||
│ ├── [service-name]/ # Additional services
|
||||
│ └── shared/ # Shared libraries
|
||||
├── infrastructure/ # Infrastructure as code
|
||||
│ ├── k8s/ # Kubernetes manifests
|
||||
│ └── terraform/ # Terraform configs
|
||||
├── docs/ # Documentation
|
||||
└── scripts/ # DevOps scripts
|
||||
```
|
||||
|
||||
## 2. High-Level System Diagram
|
||||
|
||||
```
|
||||
[API Gateway] <--> [Service Mesh/Load Balancer]
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| | |
|
||||
[Service 1] [Service 2] [Service 3]
|
||||
| | |
|
||||
[Database 1] [Database 2] [Database 3]
|
||||
| |
|
||||
+-------------[Message Queue]-----------+
|
||||
```
|
||||
|
||||
## 3. Core Components
|
||||
|
||||
### 3.1. API Gateway
|
||||
|
||||
**Name:** [e.g., Kong, AWS API Gateway, Custom Gateway]
|
||||
|
||||
**Description:** Routes requests, handles authentication, rate limiting, and request aggregation
|
||||
|
||||
**Technologies:** [e.g., Kong, Express Gateway, Spring Cloud Gateway]
|
||||
|
||||
**Deployment:** [e.g., Kubernetes, AWS]
|
||||
|
||||
### 3.2. Microservices
|
||||
|
||||
#### 3.2.1. [Service Name]
|
||||
|
||||
**Name:** [e.g., User Service, Order Service]
|
||||
|
||||
**Description:** [Service responsibility and domain]
|
||||
|
||||
**Technologies:** [Language and framework]
|
||||
|
||||
**API Endpoints:** [Key endpoints this service exposes]
|
||||
|
||||
**Dependencies:** [Other services it calls]
|
||||
|
||||
**Database:** [Dedicated database if any]
|
||||
|
||||
**Deployment:** [Container registry, orchestration]
|
||||
|
||||
### 3.3. Service Mesh
|
||||
|
||||
**Name:** [e.g., Istio, Linkerd, Consul]
|
||||
|
||||
**Description:** Handles service-to-service communication, observability, and security
|
||||
|
||||
**Key Features:** [Traffic management, circuit breaking, etc.]
|
||||
|
||||
## 4. Data Stores
|
||||
|
||||
### 4.1. Service-Specific Databases
|
||||
|
||||
Each microservice has its own database following the database-per-service pattern.
|
||||
|
||||
#### [Service Name] Database
|
||||
|
||||
**Type:** [PostgreSQL, MongoDB, etc.]
|
||||
|
||||
**Purpose:** [Data domain this service owns]
|
||||
|
||||
**Key Schemas:** [Main tables/collections]
|
||||
|
||||
### 4.2. Shared Data Stores
|
||||
|
||||
**Name:** [e.g., Redis Cache, Message Queue]
|
||||
|
||||
**Type:** [Redis, RabbitMQ, Kafka]
|
||||
|
||||
**Purpose:** [Cross-service caching or messaging]
|
||||
|
||||
## 5. External Integrations / APIs
|
||||
|
||||
**Service Name:** [e.g., Payment Gateway, Email Service]
|
||||
|
||||
**Purpose:** [Functionality]
|
||||
|
||||
**Integration Method:** [REST, gRPC, Message Queue]
|
||||
|
||||
**Owning Service:** [Which microservice handles this integration]
|
||||
|
||||
## 6. Deployment & Infrastructure
|
||||
|
||||
**Cloud Provider:** [AWS, GCP, Azure]
|
||||
|
||||
**Orchestration:** [Kubernetes, Docker Swarm, ECS]
|
||||
|
||||
**Service Discovery:** [Consul, Eureka, Kubernetes DNS]
|
||||
|
||||
**CI/CD Pipeline:** [Jenkins, GitLab CI, GitHub Actions]
|
||||
|
||||
**Container Registry:** [Docker Hub, ECR, GCR]
|
||||
|
||||
**Monitoring & Logging:** [Prometheus, Grafana, ELK, Jaeger for tracing]
|
||||
|
||||
**Configuration Management:** [Consul, etcd, ConfigMap]
|
||||
|
||||
## 7. Security Considerations
|
||||
|
||||
**Authentication:** [OAuth2, JWT at API Gateway]
|
||||
|
||||
**Authorization:** [Service-level RBAC, mutual TLS]
|
||||
|
||||
**Service-to-Service Security:** [mTLS, API keys, service mesh policies]
|
||||
|
||||
**Data Encryption:** [TLS in transit, encrypted at rest]
|
||||
|
||||
**Secrets Management:** [Vault, AWS Secrets Manager, Kubernetes Secrets]
|
||||
|
||||
## 8. Development & Testing Environment
|
||||
|
||||
**Local Setup Instructions:** [Docker Compose, Minikube, or Skaffold]
|
||||
|
||||
**Testing Strategy:**
|
||||
- Unit Tests: [Per service]
|
||||
- Integration Tests: [Between services]
|
||||
- Contract Tests: [API contracts]
|
||||
- E2E Tests: [Full system tests]
|
||||
|
||||
**Testing Frameworks:** [Service-specific frameworks]
|
||||
|
||||
## 9. Future Considerations / Roadmap
|
||||
|
||||
- [e.g., Implement event sourcing for specific services]
|
||||
- [e.g., Add service mesh for better observability]
|
||||
- [e.g., Break down Service X into smaller services]
|
||||
- [e.g., Implement CQRS pattern]
|
||||
|
||||
## 10. Project Identification
|
||||
|
||||
**Project Name:** [Microservices System Name]
|
||||
|
||||
**Repository URL:** [Monorepo or organization URL]
|
||||
|
||||
**Primary Contact/Team:** [Platform Team]
|
||||
|
||||
**Date of Last Update:** [YYYY-MM-DD]
|
||||
|
||||
**Service Catalog:** [Link to service registry/documentation]
|
||||
|
||||
## 11. Glossary / Acronyms
|
||||
|
||||
**API Gateway:** Entry point for all external requests
|
||||
|
||||
**Service Mesh:** Infrastructure layer for service-to-service communication
|
||||
|
||||
**Circuit Breaker:** Pattern to prevent cascading failures
|
||||
|
||||
**CQRS:** Command Query Responsibility Segregation
|
||||
|
||||
**Event Sourcing:** Storing state changes as events
|
||||
|
||||
**[Add domain-specific terms]**
|
||||
214
skills/assets/ARCHITECTURE-monolith.md
Normal file
214
skills/assets/ARCHITECTURE-monolith.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Architecture Overview - Monolithic Application
|
||||
|
||||
This document describes the monolithic architecture, providing clear understanding of the application structure, module organization, and system design.
|
||||
|
||||
## 1. Project Structure
|
||||
|
||||
```
|
||||
[Project Root]/
|
||||
├── src/ # Source code
|
||||
│ ├── api/ # API layer (controllers, routes)
|
||||
│ ├── services/ # Business logic layer
|
||||
│ ├── models/ # Data models
|
||||
│ ├── repositories/ # Data access layer
|
||||
│ ├── middleware/ # Request processing middleware
|
||||
│ ├── utils/ # Utility functions
|
||||
│ └── config/ # Configuration files
|
||||
├── tests/ # Test suites
|
||||
│ ├── unit/
|
||||
│ ├── integration/
|
||||
│ └── e2e/
|
||||
├── migrations/ # Database migrations
|
||||
├── public/ # Static assets (if serving frontend)
|
||||
├── docs/ # Documentation
|
||||
└── scripts/ # Build and deployment scripts
|
||||
```
|
||||
|
||||
## 2. High-Level System Diagram
|
||||
|
||||
```
|
||||
[User/Client]
|
||||
|
|
||||
v
|
||||
[Load Balancer] (optional)
|
||||
|
|
||||
v
|
||||
[Application Server]
|
||||
|
|
||||
+-- [API Layer]
|
||||
| |
|
||||
| v
|
||||
+-- [Service Layer]
|
||||
| |
|
||||
| v
|
||||
+-- [Data Access Layer]
|
||||
| |
|
||||
| v
|
||||
+-- [Database]
|
||||
|
|
||||
+-- [Cache] (optional)
|
||||
|
|
||||
+-- [External Services]
|
||||
```
|
||||
|
||||
## 3. Core Components
|
||||
|
||||
### 3.1. Application Server
|
||||
|
||||
**Name:** [e.g., Main Application, Web Server]
|
||||
|
||||
**Description:** Single unified application handling all business logic
|
||||
|
||||
**Technologies:** [e.g., Node.js/Express, Python/Django, Java/Spring Boot, .NET]
|
||||
|
||||
**Deployment:** [e.g., AWS EC2, Heroku, Docker container]
|
||||
|
||||
### 3.2. Layered Architecture
|
||||
|
||||
#### 3.2.1. API/Controller Layer
|
||||
|
||||
**Description:** Handles HTTP requests, routing, and response formatting
|
||||
|
||||
**Key Modules:** [List main controllers/route groups]
|
||||
|
||||
**Responsibilities:** Request validation, authentication, response serialization
|
||||
|
||||
#### 3.2.2. Service/Business Logic Layer
|
||||
|
||||
**Description:** Core business logic and workflows
|
||||
|
||||
**Key Modules:** [List main service classes/modules]
|
||||
|
||||
**Responsibilities:** Business rules, transaction management, orchestration
|
||||
|
||||
#### 3.2.3. Data Access Layer
|
||||
|
||||
**Description:** Database interactions and data persistence
|
||||
|
||||
**Key Modules:** [List repositories/DAO classes]
|
||||
|
||||
**Responsibilities:** CRUD operations, query building, ORM management
|
||||
|
||||
### 3.3. Frontend (if integrated)
|
||||
|
||||
**Name:** [e.g., Web UI, Admin Panel]
|
||||
|
||||
**Description:** User interface served by the monolith
|
||||
|
||||
**Technologies:** [e.g., Server-side rendered with Jinja/EJS, or SPA with React/Vue]
|
||||
|
||||
**Location:** [public/ or templates/ directory]
|
||||
|
||||
## 4. Data Stores
|
||||
|
||||
### 4.1. Primary Database
|
||||
|
||||
**Name:** [e.g., Main Application Database]
|
||||
|
||||
**Type:** [PostgreSQL, MySQL, MongoDB, etc.]
|
||||
|
||||
**Purpose:** Stores all application data
|
||||
|
||||
**Key Schemas/Collections:**
|
||||
- users
|
||||
- [entity names]
|
||||
- [domain tables]
|
||||
|
||||
### 4.2. Cache (if used)
|
||||
|
||||
**Name:** [e.g., Redis Cache]
|
||||
|
||||
**Type:** Redis, Memcached
|
||||
|
||||
**Purpose:** Performance optimization, session storage
|
||||
|
||||
**Cached Data:** [What gets cached]
|
||||
|
||||
## 5. External Integrations / APIs
|
||||
|
||||
**Service Name:** [e.g., Payment Processor, Email Service]
|
||||
|
||||
**Purpose:** [Functionality]
|
||||
|
||||
**Integration Method:** [REST API, SDK, Webhook]
|
||||
|
||||
**Integration Location:** [Which service/module handles it]
|
||||
|
||||
## 6. Deployment & Infrastructure
|
||||
|
||||
**Cloud Provider:** [AWS, GCP, Azure, On-premise]
|
||||
|
||||
**Hosting:** [EC2, App Engine, Virtual Machine, Container]
|
||||
|
||||
**Database Hosting:** [RDS, Cloud SQL, Managed service]
|
||||
|
||||
**CI/CD Pipeline:** [GitHub Actions, Jenkins, GitLab CI]
|
||||
|
||||
**Load Balancing:** [ALB, nginx, Cloud Load Balancer]
|
||||
|
||||
**Monitoring & Logging:** [CloudWatch, Application Insights, ELK]
|
||||
|
||||
**Scaling Strategy:** [Vertical scaling, horizontal with load balancer]
|
||||
|
||||
## 7. Security Considerations
|
||||
|
||||
**Authentication:** [Session-based, JWT, OAuth2]
|
||||
|
||||
**Authorization:** [RBAC implementation, middleware]
|
||||
|
||||
**Data Encryption:** [TLS/HTTPS, database encryption]
|
||||
|
||||
**Security Practices:**
|
||||
- Input validation and sanitization
|
||||
- SQL injection prevention (ORM/parameterized queries)
|
||||
- CSRF protection
|
||||
- Rate limiting
|
||||
- Security headers
|
||||
|
||||
**Secrets Management:** [Environment variables, vault, cloud secrets]
|
||||
|
||||
## 8. Development & Testing Environment
|
||||
|
||||
**Local Setup Instructions:** [Steps to run locally]
|
||||
|
||||
**Development Database:** [Docker, local instance]
|
||||
|
||||
**Testing Frameworks:**
|
||||
- Unit: [e.g., Jest, Pytest, JUnit]
|
||||
- Integration: [e.g., Supertest, TestContainers]
|
||||
- E2E: [e.g., Cypress, Selenium]
|
||||
|
||||
**Code Quality Tools:** [ESLint, Prettier, SonarQube]
|
||||
|
||||
**Development Workflow:** [Git workflow, branch strategy]
|
||||
|
||||
## 9. Future Considerations / Roadmap
|
||||
|
||||
- [e.g., Consider extracting high-traffic modules into separate services]
|
||||
- [e.g., Implement caching layer for better performance]
|
||||
- [e.g., Add background job processing with queue]
|
||||
- [e.g., Evaluate migration to microservices if scaling demands increase]
|
||||
|
||||
## 10. Project Identification
|
||||
|
||||
**Project Name:** [Application Name]
|
||||
|
||||
**Repository URL:** [Git repository]
|
||||
|
||||
**Primary Contact/Team:** [Development team]
|
||||
|
||||
**Date of Last Update:** [YYYY-MM-DD]
|
||||
|
||||
**Application Version:** [Current version]
|
||||
|
||||
## 11. Glossary / Acronyms
|
||||
|
||||
**Monolith:** Single-tiered application where all components are tightly coupled
|
||||
|
||||
**ORM:** Object-Relational Mapping - translates between database and objects
|
||||
|
||||
**Repository Pattern:** Data access abstraction layer
|
||||
|
||||
**Service Layer:** Business logic layer between controllers and data access
|
||||
|
||||
**[Add application-specific terms]**
|
||||
121
skills/assets/ARCHITECTURE.md
Normal file
121
skills/assets/ARCHITECTURE.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Architecture Overview
|
||||
|
||||
This document serves as a critical, living template designed to equip agents with a rapid and comprehensive understanding of the codebase's architecture, enabling efficient navigation and effective contribution from day one. Update this document as the codebase evolves.
|
||||
|
||||
## 1. Project Structure
|
||||
|
||||
This section provides a high-level overview of the project's directory and file structure, categorised by architectural layer or major functional area.
|
||||
|
||||
```
|
||||
[Project Root]/
|
||||
├── [Add your project structure here]
|
||||
```
|
||||
|
||||
## 2. High-Level System Diagram
|
||||
|
||||
Provide a simple diagram showing major components and their interactions. Focus on data flow and key boundaries.
|
||||
|
||||
```
|
||||
[User] <--> [Component] <--> [Component] <--> [Data Store]
|
||||
```
|
||||
|
||||
## 3. Core Components
|
||||
|
||||
List and describe the main components of the system.
|
||||
|
||||
### 3.1. Frontend
|
||||
|
||||
**Name:** [e.g., Web App, Mobile App]
|
||||
|
||||
**Description:** [Describe primary purpose and key functionalities]
|
||||
|
||||
**Technologies:** [e.g., React, Vue.js, Angular, React Native]
|
||||
|
||||
**Deployment:** [e.g., Vercel, Netlify, S3/CloudFront]
|
||||
|
||||
### 3.2. Backend Services
|
||||
|
||||
#### 3.2.1. [Service Name]
|
||||
|
||||
**Name:** [e.g., API Service, User Service]
|
||||
|
||||
**Description:** [Describe purpose]
|
||||
|
||||
**Technologies:** [e.g., Node.js, Python, Java, Go]
|
||||
|
||||
**Deployment:** [e.g., AWS, Kubernetes, Cloud Run]
|
||||
|
||||
## 4. Data Stores
|
||||
|
||||
List databases and persistent storage solutions.
|
||||
|
||||
### 4.1. [Data Store Name]
|
||||
|
||||
**Name:** [e.g., Primary Database, Cache]
|
||||
|
||||
**Type:** [e.g., PostgreSQL, MongoDB, Redis]
|
||||
|
||||
**Purpose:** [Describe what data it stores and why]
|
||||
|
||||
**Key Schemas/Collections:** [List main tables/collections]
|
||||
|
||||
## 5. External Integrations / APIs
|
||||
|
||||
List third-party services and external APIs.
|
||||
|
||||
**Service Name:** [e.g., Stripe, SendGrid]
|
||||
|
||||
**Purpose:** [e.g., Payment processing]
|
||||
|
||||
**Integration Method:** [e.g., REST API, SDK]
|
||||
|
||||
## 6. Deployment & Infrastructure
|
||||
|
||||
**Cloud Provider:** [e.g., AWS, GCP, Azure]
|
||||
|
||||
**Key Services Used:** [e.g., EC2, Lambda, Kubernetes]
|
||||
|
||||
**CI/CD Pipeline:** [e.g., GitHub Actions, GitLab CI]
|
||||
|
||||
**Monitoring & Logging:** [e.g., Prometheus, CloudWatch]
|
||||
|
||||
## 7. Security Considerations
|
||||
|
||||
**Authentication:** [e.g., OAuth2, JWT, API Keys]
|
||||
|
||||
**Authorization:** [e.g., RBAC, ACLs]
|
||||
|
||||
**Data Encryption:** [e.g., TLS in transit, AES-256 at rest]
|
||||
|
||||
**Key Security Tools/Practices:** [e.g., WAF, security audits]
|
||||
|
||||
## 8. Development & Testing Environment
|
||||
|
||||
**Local Setup Instructions:** [Link or brief steps]
|
||||
|
||||
**Testing Frameworks:** [e.g., Jest, Pytest, JUnit]
|
||||
|
||||
**Code Quality Tools:** [e.g., ESLint, SonarQube]
|
||||
|
||||
## 9. Future Considerations / Roadmap
|
||||
|
||||
Note any known architectural debts or planned major changes.
|
||||
|
||||
- [e.g., Migrate to microservices]
|
||||
- [e.g., Implement caching layer]
|
||||
|
||||
## 10. Project Identification
|
||||
|
||||
**Project Name:** [Insert Project Name]
|
||||
|
||||
**Repository URL:** [Insert Repository URL]
|
||||
|
||||
**Primary Contact/Team:** [Insert Lead Developer/Team]
|
||||
|
||||
**Date of Last Update:** [YYYY-MM-DD]
|
||||
|
||||
## 11. Glossary / Acronyms
|
||||
|
||||
Define project-specific terms.
|
||||
|
||||
**[Term]:** [Definition]
|
||||
321
skills/references/java.md
Normal file
321
skills/references/java.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Java Architecture Patterns
|
||||
|
||||
## Table of Contents
|
||||
- Common Frameworks and Patterns
|
||||
- Project Structure Conventions
|
||||
- Deployment Considerations
|
||||
- Best Practices
|
||||
|
||||
## Common Frameworks and Patterns
|
||||
|
||||
### Spring Boot
|
||||
**Typical Structure:**
|
||||
```
|
||||
project/
|
||||
├── src/main/java/com/company/project/
|
||||
│ ├── Application.java # Main class
|
||||
│ ├── controller/ # REST controllers
|
||||
│ ├── service/ # Business logic
|
||||
│ ├── repository/ # Data access
|
||||
│ ├── model/entity/ # JPA entities
|
||||
│ ├── model/dto/ # DTOs
|
||||
│ ├── config/ # Configuration
|
||||
│ └── exception/ # Exception handling
|
||||
├── src/main/resources/
|
||||
│ ├── application.properties
|
||||
│ └── application-{env}.properties
|
||||
├── src/test/java/
|
||||
└── pom.xml or build.gradle
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- Convention over configuration
|
||||
- Auto-configuration
|
||||
- Embedded servers (Tomcat, Jetty)
|
||||
- Spring ecosystem integration
|
||||
- Dependency injection
|
||||
|
||||
### Jakarta EE (formerly Java EE)
|
||||
**Key Technologies:**
|
||||
- JAX-RS for REST APIs
|
||||
- JPA for persistence
|
||||
- CDI for dependency injection
|
||||
- EJB for business logic
|
||||
- Deployed to application servers (WildFly, Payara)
|
||||
|
||||
### Micronaut
|
||||
**Key Characteristics:**
|
||||
- Fast startup, low memory
|
||||
- Compile-time dependency injection
|
||||
- Native image support (GraalVM)
|
||||
- Cloud-native focus
|
||||
|
||||
### Quarkus
|
||||
**Key Characteristics:**
|
||||
- Kubernetes-native
|
||||
- Fast startup, low memory
|
||||
- Developer experience focused
|
||||
- GraalVM native images
|
||||
|
||||
## Project Structure Conventions
|
||||
|
||||
### Spring Boot Microservice
|
||||
```
|
||||
project/
|
||||
├── src/main/java/com/company/service/
|
||||
│ ├── ServiceApplication.java
|
||||
│ ├── api/ # API layer
|
||||
│ │ ├── controller/
|
||||
│ │ └── dto/
|
||||
│ ├── domain/ # Domain layer
|
||||
│ │ ├── model/
|
||||
│ │ └── service/
|
||||
│ ├── infrastructure/ # Infrastructure
|
||||
│ │ ├── repository/
|
||||
│ │ ├── client/
|
||||
│ │ └── config/
|
||||
│ └── common/ # Shared utilities
|
||||
├── src/main/resources/
|
||||
├── src/test/
|
||||
├── pom.xml
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
### Maven Multi-Module Project
|
||||
```
|
||||
parent-project/
|
||||
├── pom.xml # Parent POM
|
||||
├── api-module/
|
||||
│ ├── pom.xml
|
||||
│ └── src/
|
||||
├── service-module/
|
||||
│ ├── pom.xml
|
||||
│ └── src/
|
||||
├── common-module/
|
||||
│ ├── pom.xml
|
||||
│ └── src/
|
||||
└── integration-tests/
|
||||
├── pom.xml
|
||||
└── src/
|
||||
```
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### Build Tools
|
||||
- **Maven**: XML-based, widespread
|
||||
- **Gradle**: Groovy/Kotlin DSL, flexible, faster
|
||||
|
||||
### Application Servers
|
||||
- **Spring Boot**: Embedded Tomcat/Jetty/Undertow
|
||||
- **Traditional**: WildFly, Payara, WebLogic, WebSphere
|
||||
- **Lightweight**: Tomcat, Jetty as standalone
|
||||
|
||||
### Containerization
|
||||
```dockerfile
|
||||
# Multi-stage build
|
||||
FROM maven:3.9-eclipse-temurin-17 AS build
|
||||
WORKDIR /app
|
||||
COPY pom.xml .
|
||||
COPY src ./src
|
||||
RUN mvn clean package -DskipTests
|
||||
|
||||
FROM eclipse-temurin:17-jre-alpine
|
||||
WORKDIR /app
|
||||
COPY --from=build /app/target/*.jar app.jar
|
||||
EXPOSE 8080
|
||||
ENTRYPOINT ["java", "-jar", "app.jar"]
|
||||
```
|
||||
|
||||
### Common Deployment Platforms
|
||||
- **AWS**: Elastic Beanstalk, ECS, Lambda (with GraalVM)
|
||||
- **Google Cloud**: App Engine, Cloud Run, GKE
|
||||
- **Azure**: App Service, Container Instances, AKS
|
||||
- **Kubernetes**: Primary choice for microservices
|
||||
- **Traditional**: On-premise application servers
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Code Organization
|
||||
|
||||
**Layered Architecture:**
|
||||
- Controller → Service → Repository
|
||||
- DTOs for data transfer
|
||||
- Entities for persistence
|
||||
- Use interfaces for services
|
||||
|
||||
**Package by Feature:**
|
||||
```
|
||||
com.company.project/
|
||||
├── user/
|
||||
│ ├── UserController.java
|
||||
│ ├── UserService.java
|
||||
│ ├── UserRepository.java
|
||||
│ └── User.java
|
||||
├── order/
|
||||
└── product/
|
||||
```
|
||||
|
||||
### Database Integration
|
||||
|
||||
**Spring Data JPA:**
|
||||
```java
|
||||
public interface UserRepository extends JpaRepository<User, Long> {
|
||||
Optional<User> findByEmail(String email);
|
||||
}
|
||||
```
|
||||
|
||||
**Hibernate:** JPA implementation
|
||||
**Flyway/Liquibase:** Database migrations
|
||||
**Connection Pooling:** HikariCP (default in Spring Boot)
|
||||
|
||||
### Configuration
|
||||
|
||||
**Spring Boot application.properties:**
|
||||
```properties
|
||||
spring.datasource.url=${DB_URL}
|
||||
spring.jpa.hibernate.ddl-auto=validate
|
||||
server.port=${PORT:8080}
|
||||
```
|
||||
|
||||
**Profiles:** application-dev.properties, application-prod.properties
|
||||
**Environment variables:** For secrets and env-specific config
|
||||
**Spring Cloud Config:** Centralized configuration
|
||||
|
||||
### Security
|
||||
|
||||
**Spring Security:**
|
||||
- Authentication and authorization
|
||||
- JWT support
|
||||
- OAuth2/OpenID Connect
|
||||
- Method-level security
|
||||
|
||||
**Best Practices:**
|
||||
- Use BCrypt for passwords
|
||||
- Validate input with Bean Validation
|
||||
- Prevent SQL injection (use JPA)
|
||||
- CORS configuration
|
||||
- HTTPS in production
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Spring Boot:**
|
||||
```java
|
||||
@ControllerAdvice
|
||||
public class GlobalExceptionHandler {
|
||||
@ExceptionHandler(ResourceNotFoundException.class)
|
||||
public ResponseEntity<ErrorResponse> handleNotFound(
|
||||
ResourceNotFoundException ex) {
|
||||
return ResponseEntity.status(404)
|
||||
.body(new ErrorResponse(ex.getMessage()));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
**Frameworks:**
|
||||
- **JUnit 5**: Standard testing framework
|
||||
- **Mockito**: Mocking framework
|
||||
- **Spring Boot Test**: Integration testing
|
||||
- **RestAssured**: API testing
|
||||
- **TestContainers**: Database testing with containers
|
||||
|
||||
**Patterns:**
|
||||
- Unit tests with Mockito
|
||||
- Integration tests with @SpringBootTest
|
||||
- Slice tests (@WebMvcTest, @DataJpaTest)
|
||||
- Test coverage with JaCoCo
|
||||
|
||||
### Logging
|
||||
|
||||
**SLF4J + Logback (Spring Boot default):**
|
||||
```java
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
private static final Logger log =
|
||||
LoggerFactory.getLogger(MyClass.class);
|
||||
|
||||
log.info("Processing request for user {}", userId);
|
||||
```
|
||||
|
||||
**Structured Logging:** Logstash encoder for JSON logs
|
||||
|
||||
### API Documentation
|
||||
|
||||
**OpenAPI/Swagger:**
|
||||
- springdoc-openapi for automatic generation
|
||||
- Annotations for customization
|
||||
- Swagger UI for interactive docs
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
**Spring:**
|
||||
- Constructor injection (preferred)
|
||||
- @Autowired annotation
|
||||
- @Component, @Service, @Repository stereotypes
|
||||
- Java Config with @Configuration and @Bean
|
||||
|
||||
### Common Libraries
|
||||
|
||||
- **Lombok**: Reduce boilerplate
|
||||
- **MapStruct**: Object mapping
|
||||
- **Apache Commons**: Utility libraries
|
||||
- **Guava**: Google's core libraries
|
||||
- **Jackson**: JSON processing
|
||||
|
||||
## Technology-Specific Patterns
|
||||
|
||||
### Microservices
|
||||
|
||||
**Spring Cloud:**
|
||||
- Service Discovery: Eureka
|
||||
- API Gateway: Spring Cloud Gateway
|
||||
- Config: Spring Cloud Config
|
||||
- Circuit Breaker: Resilience4j
|
||||
- Distributed Tracing: Micrometer + Zipkin
|
||||
|
||||
### Messaging
|
||||
|
||||
- **Spring AMQP**: RabbitMQ integration
|
||||
- **Spring Kafka**: Kafka integration
|
||||
- **Spring JMS**: JMS support
|
||||
- **AWS SQS**: Cloud messaging
|
||||
|
||||
### Caching
|
||||
|
||||
- **Spring Cache**: Abstraction layer
|
||||
- **Redis**: Distributed cache
|
||||
- **Caffeine**: In-memory cache
|
||||
- **Hazelcast**: Distributed cache
|
||||
|
||||
### Reactive Programming
|
||||
|
||||
**Spring WebFlux:**
|
||||
- Non-blocking, event-driven
|
||||
- Project Reactor
|
||||
- Better for high concurrency
|
||||
- MongoDB/Cassandra reactive support
|
||||
|
||||
### GraphQL
|
||||
|
||||
- **Spring for GraphQL**: Official Spring support
|
||||
- Schema-first approach
|
||||
- DataFetchers for resolvers
|
||||
|
||||
### Monitoring
|
||||
|
||||
- **Spring Boot Actuator**: Health checks, metrics
|
||||
- **Micrometer**: Metrics facade
|
||||
- **Prometheus**: Metrics collection
|
||||
- **Grafana**: Visualization
|
||||
- **Zipkin/Jaeger**: Distributed tracing
|
||||
- **ELK Stack**: Logging
|
||||
|
||||
### Performance
|
||||
|
||||
- **Connection pooling**: HikariCP
|
||||
- **Query optimization**: Proper JPA fetch strategies
|
||||
- **Caching**: Redis, Caffeine
|
||||
- **Async processing**: @Async, CompletableFuture
|
||||
- **JVM tuning**: Heap size, GC configuration
|
||||
431
skills/references/mermaid-diagrams.md
Normal file
431
skills/references/mermaid-diagrams.md
Normal file
@@ -0,0 +1,431 @@
|
||||
# Generate 5 Essential Architecture Diagrams in Mermaid.js
|
||||
|
||||
## Including C4 Level 1, 2, 3, Data Flow, and C4 Deployment
|
||||
|
||||
---
|
||||
|
||||
Goal: generate **5 essential architecture diagrams** in Mermaid.js format based on the provided system information.
|
||||
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
Generate exactly **5 diagrams** in the following order. Each diagram should be complete, syntactically valid Mermaid code ready to render.
|
||||
|
||||
### Diagram 1: System Context Diagram (C4 Level 1)
|
||||
|
||||
**Purpose**: Show the big picture - your system in context with external users, systems, and services it connects to.
|
||||
|
||||
**Output Format**: Use C4Context Mermaid syntax
|
||||
|
||||
**Requirements**:
|
||||
|
||||
- Show the primary software system as the central element
|
||||
- Include all external users/actors who interact with the system
|
||||
- Include all external systems/services the system depends on
|
||||
- Label all relationships with interaction descriptions
|
||||
- Use clear, descriptive titles and descriptions
|
||||
|
||||
**Mermaid Syntax Template**:
|
||||
|
||||
```
|
||||
C4Context
|
||||
title System Context - [System Name]
|
||||
Person(customer, "Customer", "End user of the system")
|
||||
System(system, "[System Name]", "Core business functionality")
|
||||
System_Ext(external, "External System", "Third-party integration")
|
||||
Rel(customer, system, "uses")
|
||||
Rel(system, external, "calls API")
|
||||
```
|
||||
|
||||
**Key Elements to Include**:
|
||||
|
||||
- At least 1-2 external users
|
||||
- The primary system (your product)
|
||||
- 2-3 external systems/services it depends on
|
||||
|
||||
---
|
||||
|
||||
### Diagram 2: Container Diagram (C4 Level 2)
|
||||
|
||||
**Purpose**: Zoom into the primary system and show its main building blocks (containers) like web apps, APIs, databases, message queues, etc.
|
||||
|
||||
**Output Format**: Use C4Container Mermaid syntax
|
||||
|
||||
**Requirements**:
|
||||
|
||||
- Break down the system into logical containers (applications, services, databases)
|
||||
- Show technology choices for each container (e.g., "Node.js API", "PostgreSQL")
|
||||
- Show interactions between containers with labels
|
||||
- Keep external systems visible but less detailed
|
||||
- Include brief descriptions of what each container does
|
||||
|
||||
**Mermaid Syntax Template**:
|
||||
|
||||
```
|
||||
C4Container
|
||||
title Container Diagram - [System Name]
|
||||
Person(user, "User", "System end user")
|
||||
|
||||
System_Boundary(system, "[System Name]") {
|
||||
Container(web, "Web Application", "React", "Serves the UI")
|
||||
Container(api, "API Server", "Node.js", "Provides API services")
|
||||
Container(db, "Database", "PostgreSQL", "Stores application data")
|
||||
Container(cache, "Cache", "Redis", "Session and data caching")
|
||||
}
|
||||
|
||||
System_Ext(external, "External Service", "Third-party API")
|
||||
|
||||
Rel(user, web, "Uses [HTTPS]")
|
||||
Rel(web, api, "Calls [REST API]")
|
||||
Rel(api, db, "Reads/Writes [SQL]")
|
||||
Rel(api, cache, "Reads/Writes")
|
||||
Rel(api, external, "Calls [REST API]")
|
||||
```
|
||||
|
||||
**Key Elements to Include**:
|
||||
|
||||
- 3-5 main containers (apps, APIs, databases, services)
|
||||
- Technology stack for each container
|
||||
- Container-to-container relationships
|
||||
|
||||
---
|
||||
|
||||
### Diagram 3: Component Diagram (C4 Level 3)
|
||||
|
||||
**Purpose**: Zoom into a specific container and show its internal components/structure (controllers, services, repositories, etc.).
|
||||
|
||||
**Output Format**: Use C4Component Mermaid syntax
|
||||
|
||||
**Requirements**:
|
||||
|
||||
- Focus on ONE important container (usually the API or main service)
|
||||
- Show internal components/classes/modules within that container
|
||||
- Show technology/framework for each component
|
||||
- Show dependencies between components
|
||||
- Include clear descriptions of each component's responsibility
|
||||
- Keep it focused - don't show every single component, show the main 5-8
|
||||
|
||||
**Mermaid Syntax Template**:
|
||||
|
||||
```
|
||||
C4Component
|
||||
title Component Diagram - [Container Name]
|
||||
|
||||
Container_Boundary(container, "[Container Name]") {
|
||||
Component(ctrl, "API Controller", "Express Router", "Handles HTTP requests")
|
||||
Component(service, "Business Service", "Service Class", "Contains business logic")
|
||||
Component(repo, "Data Repository", "Data Access Layer", "Database queries")
|
||||
Component(auth, "Auth Component", "JWT/OAuth", "Handles authentication")
|
||||
Component(email, "Email Component", "Email Service", "Sends emails")
|
||||
}
|
||||
|
||||
ContainerDb(db, "Database", "PostgreSQL", "Persistence")
|
||||
System_Ext(email_service, "Email Service", "SendGrid/SMTP")
|
||||
|
||||
Rel(ctrl, service, "Uses")
|
||||
Rel(service, repo, "Uses")
|
||||
Rel(service, auth, "Uses")
|
||||
Rel(service, email, "Uses")
|
||||
Rel(repo, db, "Reads/Writes")
|
||||
Rel(email, email_service, "Sends via")
|
||||
```
|
||||
|
||||
**Key Elements to Include**:
|
||||
|
||||
- 5-8 main internal components
|
||||
- Component responsibilities clearly described
|
||||
- Dependencies between components
|
||||
- External dependencies (databases, services)
|
||||
- Focus on one container (usually API/backend service)
|
||||
|
||||
---
|
||||
|
||||
### Diagram 4: Data Flow Diagram (DFD)
|
||||
|
||||
**Purpose**: Show how data moves through the system - from sources, through processes and transformations, to storage and destinations.
|
||||
|
||||
**Output Format**: Use flowchart syntax with data process symbols
|
||||
|
||||
**Requirements**:
|
||||
|
||||
- Identify all data sources (users, external systems)
|
||||
- Show major data processing/transformation steps
|
||||
- Show all data storage locations (databases, caches, files)
|
||||
- Show data destinations (output systems, reports, notifications)
|
||||
- Label flows with data type descriptions
|
||||
- Use consistent formatting for similar element types
|
||||
|
||||
**Mermaid Syntax Template**:
|
||||
|
||||
```
|
||||
flowchart LR
|
||||
subgraph sources["📥 Data Sources"]
|
||||
user["👤 User Input"]
|
||||
external["🔗 External APIs"]
|
||||
end
|
||||
|
||||
subgraph processes["⚙️ Data Processing"]
|
||||
validation["Validate Data"]
|
||||
transform["Transform Data"]
|
||||
aggregate["Aggregate Data"]
|
||||
end
|
||||
|
||||
subgraph storage["💾 Data Storage"]
|
||||
db["Primary DB<br/>(PostgreSQL)"]
|
||||
cache["Cache<br/>(Redis)"]
|
||||
archive["Archive<br/>(S3)"]
|
||||
end
|
||||
|
||||
subgraph outputs["📤 Data Outputs"]
|
||||
api_out["API Response"]
|
||||
report["Reports"]
|
||||
notification["Notifications"]
|
||||
end
|
||||
|
||||
user -->|"raw input"| validation
|
||||
external -->|"API data"| validation
|
||||
validation -->|"valid data"| transform
|
||||
transform -->|"structured data"| aggregate
|
||||
aggregate -->|"final data"| db
|
||||
aggregate -->|"hot data"| cache
|
||||
db -->|"queries"| api_out
|
||||
cache -->|"session data"| api_out
|
||||
db -->|"historical"| report
|
||||
aggregate -->|"events"| notification
|
||||
db -->|"old data"| archive
|
||||
```
|
||||
|
||||
**Key Elements to Include**:
|
||||
|
||||
- Data sources (at least 2)
|
||||
- Data transformation steps (at least 3)
|
||||
- Data storage locations
|
||||
- Data destinations
|
||||
- Flow labels showing data types
|
||||
|
||||
---
|
||||
|
||||
### Diagram 5: Deployment Diagram (C4Deployment)
|
||||
|
||||
**Purpose**: Show how software components are deployed across physical/cloud infrastructure, environments, and how they're replicated/distributed.
|
||||
|
||||
**Output Format**: Use C4Deployment Mermaid syntax with Deployment_Node and Node elements
|
||||
|
||||
**Requirements**:
|
||||
|
||||
- Show deployment environments (production, staging)
|
||||
- Show cloud providers or infrastructure boundaries
|
||||
- Show servers/nodes/instances where containers run
|
||||
- Show load balancers, databases, and other infrastructure
|
||||
- Show internal connections between nodes
|
||||
- Indicate scaling and high availability configurations
|
||||
- Use proper C4Deployment syntax with Deployment_Node, Node, and Rel
|
||||
|
||||
**Mermaid Syntax Template**:
|
||||
|
||||
```mermaid
|
||||
C4Deployment
|
||||
title <Diagram Title>
|
||||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||||
Container(<id>, "<Name>", "<Technology>", "<Description>")
|
||||
}
|
||||
|
||||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||||
Deployment_Node(<id>, "<Name>", "<Technology>") {
|
||||
Container(<id>, "<Name>", "<Technology>", "<Description>")
|
||||
}
|
||||
}
|
||||
|
||||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||||
Deployment_Node(<id>, "<Name>", "<Technology>") {
|
||||
ContainerDb(<id>, "<Name>", "<Technology>", "<Description>")
|
||||
}
|
||||
}
|
||||
|
||||
Rel(<source_id>, <target_id>, "<Description>", "<Protocol>")
|
||||
Rel_U(<source_id>, <target_id>, "<Description>")
|
||||
Rel_R(<source_id>, <target_id>, "<Description>")
|
||||
|
||||
UpdateRelStyle(<source_id>, <target_id>, $offsetX="<value>", $offsetY="<value>")
|
||||
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Use Deployment_Node for devices, servers, or environments.
|
||||
- Use Container for applications or services.
|
||||
- Use ContainerDb for databases.
|
||||
- Use Rel, Rel_U, or Rel_R for relationships.
|
||||
- Use UpdateRelStyle to adjust label or arrow positions.
|
||||
|
||||
## Example: C4Deployment for Internet Banking System
|
||||
|
||||
```mermaid
|
||||
C4Deployment
|
||||
title Deployment Diagram for Internet Banking System - Live
|
||||
|
||||
Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){
|
||||
Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.")
|
||||
}
|
||||
|
||||
Deployment_Node(comp, "Customer's computer", "Microsoft Windows or Apple macOS"){
|
||||
Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox,<br/> Apple Safari or Microsoft Edge"){
|
||||
Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.")
|
||||
}
|
||||
}
|
||||
|
||||
Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){
|
||||
Deployment_Node(dn, "bigbank-api*** x8", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bb2, "bigbank-web*** x4", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){
|
||||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS") {
|
||||
Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c") {
|
||||
ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Rel(mobile, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel(spa, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel_U(web, spa, "Delivers to the customer's web browser")
|
||||
Rel(api, db, "Reads from and writes to", "JDBC")
|
||||
Rel(api, db2, "Reads from and writes to", "JDBC")
|
||||
Rel_R(db, db2, "Replicates data to")
|
||||
|
||||
UpdateRelStyle(spa, api, $offsetY="-40")
|
||||
UpdateRelStyle(web, spa, $offsetY="-40")
|
||||
UpdateRelStyle(api, db, $offsetY="-20", $offsetX="5")
|
||||
UpdateRelStyle(api, db2, $offsetX="-40", $offsetY="-20")
|
||||
UpdateRelStyle(db, db2, $offsetY="-10")
|
||||
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Key Elements to Include**:
|
||||
|
||||
- Cloud provider/infrastructure boundary
|
||||
- Production environment with load balancer
|
||||
- Multiple instances of compute nodes for high availability
|
||||
- Database with read replicas
|
||||
- Caching layer
|
||||
- External service connections
|
||||
- Message queues for async processing
|
||||
|
||||
---
|
||||
|
||||
## Input Information Required
|
||||
|
||||
Before generating the diagrams, gather or confirm the following information about the system:
|
||||
|
||||
### Project Overview
|
||||
|
||||
- System name and purpose
|
||||
- Primary users/actors
|
||||
- Main external systems it integrates with
|
||||
|
||||
### Technical Components (Containers)
|
||||
|
||||
- List all applications/services in the system
|
||||
- Technology stack for each container (language, framework)
|
||||
- Database systems and their purposes
|
||||
- Message queues, caches, or other data stores
|
||||
- Third-party services (payment, auth, notifications, etc.)
|
||||
|
||||
### Internal Components (for Level 3)
|
||||
|
||||
- Main controller/handler types
|
||||
- Key service/business logic components
|
||||
- Data access/repository layers
|
||||
- Utility/helper components
|
||||
- Authentication/authorization components
|
||||
|
||||
### Data Processing
|
||||
|
||||
- Main data types flowing through the system
|
||||
- How data enters the system (APIs, uploads, imports)
|
||||
- Major processing/transformation steps
|
||||
- How data is stored and how long
|
||||
- How data exits the system (exports, reports, APIs)
|
||||
|
||||
### Infrastructure & Deployment
|
||||
|
||||
- Cloud provider (AWS, GCP, Azure, on-premises)
|
||||
- Number of instances/replicas for high availability
|
||||
- Load balancing strategy
|
||||
- Database replication/backup strategy
|
||||
- CDN or content delivery strategy
|
||||
- Message queue setup
|
||||
|
||||
---
|
||||
|
||||
## Generation Steps
|
||||
|
||||
1. **Understand the context**: Read and understand the system description
|
||||
2. **Generate Diagram 1**: System Context (C4 Level 1) - showing external relationships
|
||||
3. **Generate Diagram 2**: Container (C4 Level 2) - showing internal components and technologies
|
||||
4. **Generate Diagram 3**: Component (C4 Level 3) - showing one container's internal structure
|
||||
5. **Generate Diagram 4**: Data Flow - showing how data moves through the system
|
||||
6. **Generate Diagram 5**: Deployment (C4Deployment) - showing infrastructure and deployment topology
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
For each diagram, output:
|
||||
|
||||
```markdown
|
||||
### Diagram [Number]: [Diagram Title]
|
||||
|
||||
**Description**: [One sentence about what this diagram shows]
|
||||
|
||||
**Focus**: [What this diagram emphasizes]
|
||||
|
||||
\`\`\`mermaid
|
||||
[Complete Mermaid diagram code]
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
For each diagram, verify:
|
||||
|
||||
- ✅ Syntax is valid Mermaid.js code
|
||||
- ✅ Diagram clearly shows the intended architectural layer
|
||||
- ✅ All relationships/connections are labeled
|
||||
- ✅ Component descriptions are concise and clear
|
||||
- ✅ Technology choices are explicitly shown (where applicable)
|
||||
- ✅ No syntax errors or unclosed elements
|
||||
- ✅ Diagram is readable and not overcrowded
|
||||
- ✅ Follows C4 model conventions for that level
|
||||
- ✅ For C4Deployment: Uses proper Deployment_Node, Node, and Rel syntax
|
||||
|
||||
---
|
||||
|
||||
## Why All 5 Diagrams?
|
||||
|
||||
| Diagram | Audience | Detail Level | Purpose |
|
||||
| ---------------------- | -------------------------------------- | ---------------- | ------------------------------------------ |
|
||||
| **Level 1: Context** | Everyone | Ultra-high level | System boundary and external relationships |
|
||||
| **Level 2: Container** | Tech leads, architects, devs | High level | Main technical components |
|
||||
| **Level 3: Component** | Senior devs, architects | Mid-level | How one container is built internally |
|
||||
| **Data Flow** | Data engineers, backend devs, security | Process level | Data movement and transformations |
|
||||
| **Deployment** | DevOps, SRE, ops team | Infrastructure | How it runs in production |
|
||||
|
||||
---
|
||||
|
||||
355
skills/references/microservices.md
Normal file
355
skills/references/microservices.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# Microservices Architecture Patterns
|
||||
|
||||
## Table of Contents
|
||||
- Core Principles
|
||||
- Service Design Patterns
|
||||
- Communication Patterns
|
||||
- Data Management
|
||||
- Deployment Patterns
|
||||
- Observability
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Single Responsibility
|
||||
Each service owns one business capability and does it well.
|
||||
|
||||
### Decentralized Data
|
||||
Each service has its own database (database-per-service pattern).
|
||||
|
||||
### Independence
|
||||
Services can be developed, deployed, and scaled independently.
|
||||
|
||||
### Resilience
|
||||
Services must handle failures gracefully (circuit breakers, retries).
|
||||
|
||||
## Service Design Patterns
|
||||
|
||||
### Service Boundaries
|
||||
Define services around business capabilities, not technical layers:
|
||||
- ✅ User Service, Order Service, Payment Service
|
||||
- ❌ Database Service, Email Service (too technical)
|
||||
|
||||
### Service Size
|
||||
Guideline: A service should be maintainable by a small team (2-pizza team).
|
||||
|
||||
### API Design
|
||||
- Use RESTful APIs for synchronous communication
|
||||
- Use gRPC for high-performance internal communication
|
||||
- Use message queues for asynchronous communication
|
||||
- Version APIs (v1, v2) to support backward compatibility
|
||||
|
||||
## Communication Patterns
|
||||
|
||||
### Synchronous (Request-Response)
|
||||
|
||||
**REST APIs:**
|
||||
```
|
||||
Service A --HTTP--> Service B
|
||||
<-JSON---
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Need immediate response
|
||||
- Simple request-response flow
|
||||
- External-facing APIs
|
||||
|
||||
**gRPC:**
|
||||
```
|
||||
Service A --Protocol Buffer--> Service B
|
||||
<--Binary Response---
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Internal service communication
|
||||
- Need high performance
|
||||
- Strong typing required
|
||||
|
||||
### Asynchronous (Event-Driven)
|
||||
|
||||
**Message Queue:**
|
||||
```
|
||||
Service A --publish--> Queue --consume--> Service B
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Don't need immediate response
|
||||
- Decouple services
|
||||
- Handle bursts of traffic
|
||||
- Background processing
|
||||
|
||||
**Event Bus/Broker:**
|
||||
```
|
||||
Service A --emit event--> Event Bus --subscribe--> Service B, C, D
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Multiple services need same event
|
||||
- Event sourcing patterns
|
||||
- Complex event processing
|
||||
|
||||
**Popular Tools:**
|
||||
- Kafka: High-throughput, event streaming
|
||||
- RabbitMQ: Traditional message broker
|
||||
- AWS SQS/SNS: Cloud-native messaging
|
||||
- NATS: Lightweight messaging
|
||||
|
||||
### API Gateway Pattern
|
||||
|
||||
Centralized entry point for all client requests.
|
||||
|
||||
**Responsibilities:**
|
||||
- Request routing
|
||||
- Authentication/Authorization
|
||||
- Rate limiting
|
||||
- Request/Response transformation
|
||||
- Caching
|
||||
- Load balancing
|
||||
|
||||
**Tools:**
|
||||
- Kong
|
||||
- AWS API Gateway
|
||||
- Nginx
|
||||
- Spring Cloud Gateway
|
||||
- Traefik
|
||||
|
||||
### Service Mesh Pattern
|
||||
|
||||
Infrastructure layer for service-to-service communication.
|
||||
|
||||
**Features:**
|
||||
- Traffic management
|
||||
- Security (mTLS)
|
||||
- Observability
|
||||
- Circuit breaking
|
||||
- Retry logic
|
||||
|
||||
**Tools:**
|
||||
- Istio
|
||||
- Linkerd
|
||||
- Consul Connect
|
||||
|
||||
## Data Management
|
||||
|
||||
### Database Per Service
|
||||
|
||||
Each service owns its database. No shared databases.
|
||||
|
||||
**Benefits:**
|
||||
- Service independence
|
||||
- Technology flexibility
|
||||
- Scalability
|
||||
|
||||
**Challenges:**
|
||||
- Data consistency
|
||||
- Joins across services
|
||||
- Transactions
|
||||
|
||||
### Saga Pattern
|
||||
|
||||
Manage transactions across multiple services.
|
||||
|
||||
**Choreography:**
|
||||
```
|
||||
Order Service --creates order-->
|
||||
|--event--> Payment Service --processes payment-->
|
||||
|--event--> Inventory Service --reserves items-->
|
||||
|--event--> Shipping Service --ships order-->
|
||||
```
|
||||
|
||||
Each service listens to events and publishes new events.
|
||||
|
||||
**Orchestration:**
|
||||
```
|
||||
Order Orchestrator
|
||||
|--call--> Payment Service
|
||||
|--call--> Inventory Service
|
||||
|--call--> Shipping Service
|
||||
```
|
||||
|
||||
Central orchestrator coordinates the saga.
|
||||
|
||||
### CQRS (Command Query Responsibility Segregation)
|
||||
|
||||
Separate read and write models.
|
||||
|
||||
**Pattern:**
|
||||
- Write: Command Model (normalized, transactional)
|
||||
- Read: Query Model (denormalized, optimized for reads)
|
||||
- Sync via events or batch processes
|
||||
|
||||
**When to use:**
|
||||
- Complex domains
|
||||
- Different read/write patterns
|
||||
- Need to scale reads separately
|
||||
|
||||
### Event Sourcing
|
||||
|
||||
Store state changes as events rather than current state.
|
||||
|
||||
**Benefits:**
|
||||
- Complete audit log
|
||||
- Temporal queries
|
||||
- Event replay for debugging
|
||||
- Derive new models from events
|
||||
|
||||
**Challenges:**
|
||||
- Complexity
|
||||
- Event versioning
|
||||
- Storage requirements
|
||||
|
||||
## Deployment Patterns
|
||||
|
||||
### Containerization
|
||||
|
||||
**Docker:**
|
||||
```
|
||||
Each service → Docker image → Container
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Consistency across environments
|
||||
- Isolation
|
||||
- Resource efficiency
|
||||
|
||||
### Container Orchestration
|
||||
|
||||
**Kubernetes:**
|
||||
```
|
||||
Cluster
|
||||
├── Namespace: production
|
||||
│ ├── Deployment: user-service
|
||||
│ ├── Deployment: order-service
|
||||
│ └── Deployment: payment-service
|
||||
└── Namespace: staging
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Automated deployment
|
||||
- Scaling
|
||||
- Self-healing
|
||||
- Service discovery
|
||||
- Load balancing
|
||||
- Rolling updates
|
||||
|
||||
### Service Discovery
|
||||
|
||||
**Pattern:**
|
||||
Services register themselves and discover other services dynamically.
|
||||
|
||||
**Client-side:**
|
||||
- Service queries registry
|
||||
- Service makes direct call
|
||||
- Tools: Eureka, Consul
|
||||
|
||||
**Server-side:**
|
||||
- Load balancer queries registry
|
||||
- Routes request to service
|
||||
- Tools: Kubernetes, AWS ELB
|
||||
|
||||
### Configuration Management
|
||||
|
||||
**External Configuration:**
|
||||
- Spring Cloud Config
|
||||
- Consul
|
||||
- etcd
|
||||
- Kubernetes ConfigMaps/Secrets
|
||||
|
||||
**Pattern:**
|
||||
- Store config separately from code
|
||||
- Environment-specific configs
|
||||
- Runtime configuration changes
|
||||
|
||||
## Observability
|
||||
|
||||
### Distributed Tracing
|
||||
|
||||
Track requests across multiple services.
|
||||
|
||||
**Tools:**
|
||||
- Jaeger
|
||||
- Zipkin
|
||||
- AWS X-Ray
|
||||
- Datadog APM
|
||||
|
||||
**Pattern:**
|
||||
```
|
||||
Request ID: abc123
|
||||
User Service (10ms) --> Order Service (50ms) --> Payment Service (100ms)
|
||||
Total: 160ms
|
||||
```
|
||||
|
||||
### Centralized Logging
|
||||
|
||||
Aggregate logs from all services.
|
||||
|
||||
**Tools:**
|
||||
- ELK Stack (Elasticsearch, Logstash, Kibana)
|
||||
- Splunk
|
||||
- CloudWatch Logs
|
||||
- Datadog
|
||||
|
||||
**Pattern:**
|
||||
- Structured logging (JSON)
|
||||
- Correlation IDs
|
||||
- Log levels
|
||||
- Searchable aggregation
|
||||
|
||||
### Metrics and Monitoring
|
||||
|
||||
**Metrics to track:**
|
||||
- Request rate
|
||||
- Error rate
|
||||
- Response time (latency)
|
||||
- Resource usage (CPU, memory)
|
||||
|
||||
**Tools:**
|
||||
- Prometheus + Grafana
|
||||
- CloudWatch
|
||||
- Datadog
|
||||
- New Relic
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Types:**
|
||||
- Liveness: Is service alive?
|
||||
- Readiness: Can service handle requests?
|
||||
- Startup: Has service started?
|
||||
|
||||
**Implementation:**
|
||||
```
|
||||
/health/live → 200 OK
|
||||
/health/ready → 200 OK (or 503 if not ready)
|
||||
```
|
||||
|
||||
## Common Challenges
|
||||
|
||||
### Network Latency
|
||||
**Solution:** Async communication, caching, service mesh
|
||||
|
||||
### Data Consistency
|
||||
**Solution:** Eventual consistency, saga pattern, CQRS
|
||||
|
||||
### Testing
|
||||
**Solution:** Contract testing, integration tests, chaos engineering
|
||||
|
||||
### Debugging
|
||||
**Solution:** Distributed tracing, centralized logging, correlation IDs
|
||||
|
||||
### Security
|
||||
**Solution:** API gateway, service mesh mTLS, OAuth2/JWT
|
||||
|
||||
### Service Proliferation
|
||||
**Solution:** Clear service boundaries, API standards, governance
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with a Monolith:** Don't start with microservices
|
||||
2. **Define Clear Boundaries:** Use Domain-Driven Design
|
||||
3. **Automate Everything:** CI/CD, testing, deployment
|
||||
4. **Monitor from Day One:** Logging, metrics, tracing
|
||||
5. **Design for Failure:** Circuit breakers, retries, timeouts
|
||||
6. **Version APIs:** Support backward compatibility
|
||||
7. **Document APIs:** OpenAPI/Swagger
|
||||
8. **Use Async for Non-Critical Paths:** Message queues
|
||||
9. **Implement Health Checks:** For orchestration
|
||||
10. **Security at Every Layer:** Gateway, service mesh, code
|
||||
244
skills/references/nodejs.md
Normal file
244
skills/references/nodejs.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Node.js Architecture Patterns
|
||||
|
||||
## Table of Contents
|
||||
- Common Frameworks and Patterns
|
||||
- Project Structure Conventions
|
||||
- Deployment Considerations
|
||||
- Best Practices
|
||||
|
||||
## Common Frameworks and Patterns
|
||||
|
||||
### Express.js
|
||||
**Typical Structure:**
|
||||
```
|
||||
src/
|
||||
├── routes/ # Route definitions
|
||||
├── controllers/ # Request handlers
|
||||
├── services/ # Business logic
|
||||
├── models/ # Data models
|
||||
├── middleware/ # Custom middleware
|
||||
└── config/ # Configuration
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- Minimalist, unopinionated framework
|
||||
- Middleware-based architecture
|
||||
- Common with REST APIs
|
||||
- Often paired with ORM (Sequelize, Prisma, TypeORM)
|
||||
|
||||
### NestJS
|
||||
**Typical Structure:**
|
||||
```
|
||||
src/
|
||||
├── modules/ # Feature modules
|
||||
│ └── user/
|
||||
│ ├── user.controller.ts
|
||||
│ ├── user.service.ts
|
||||
│ ├── user.module.ts
|
||||
│ └── dto/
|
||||
├── common/ # Shared utilities
|
||||
└── config/ # Configuration
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- Opinionated, TypeScript-first
|
||||
- Dependency injection
|
||||
- Modular architecture
|
||||
- Built-in support for microservices, GraphQL, WebSockets
|
||||
|
||||
### Fastify
|
||||
**Key Characteristics:**
|
||||
- Performance-focused
|
||||
- Schema-based validation
|
||||
- Plugin architecture
|
||||
- Similar patterns to Express but faster
|
||||
|
||||
### Koa
|
||||
**Key Characteristics:**
|
||||
- Lightweight, modern middleware
|
||||
- Async/await native
|
||||
- No bundled middleware
|
||||
- More control than Express
|
||||
|
||||
## Project Structure Conventions
|
||||
|
||||
### REST API (Express/Koa)
|
||||
```
|
||||
project/
|
||||
├── src/
|
||||
│ ├── api/
|
||||
│ │ ├── routes/
|
||||
│ │ └── controllers/
|
||||
│ ├── services/
|
||||
│ ├── models/
|
||||
│ ├── middleware/
|
||||
│ ├── utils/
|
||||
│ └── config/
|
||||
├── tests/
|
||||
├── .env
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Microservices (NestJS)
|
||||
```
|
||||
project/
|
||||
├── apps/ # Multiple services
|
||||
│ ├── api-gateway/
|
||||
│ ├── user-service/
|
||||
│ └── order-service/
|
||||
├── libs/ # Shared libraries
|
||||
│ ├── common/
|
||||
│ └── database/
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Serverless (Lambda)
|
||||
```
|
||||
project/
|
||||
├── functions/
|
||||
│ ├── handler1/
|
||||
│ │ └── index.js
|
||||
│ ├── handler2/
|
||||
│ │ └── index.js
|
||||
│ └── shared/
|
||||
├── layers/ # Lambda layers
|
||||
└── serverless.yml
|
||||
```
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### Containerization
|
||||
**Dockerfile patterns:**
|
||||
- Multi-stage builds for smaller images
|
||||
- Use Alpine for minimal size
|
||||
- Install only production dependencies
|
||||
- Set NODE_ENV=production
|
||||
|
||||
**Typical:**
|
||||
```dockerfile
|
||||
FROM node:18-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/dist ./dist
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
CMD ["node", "dist/index.js"]
|
||||
```
|
||||
|
||||
### Process Management
|
||||
- **PM2**: Production process manager, clustering
|
||||
- **nodemon**: Development auto-reload
|
||||
- **Docker**: Container orchestration handles process management
|
||||
|
||||
### Common Deployment Platforms
|
||||
- **AWS**: Lambda (serverless), ECS/Fargate (containers), EC2, Elastic Beanstalk
|
||||
- **Vercel/Netlify**: Serverless functions, Edge functions
|
||||
- **Heroku**: PaaS, simple deployment
|
||||
- **Google Cloud**: Cloud Run, App Engine, Cloud Functions
|
||||
- **Kubernetes**: Container orchestration
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Code Organization
|
||||
- Separate concerns: routes, controllers, services, models
|
||||
- Use dependency injection (especially with NestJS)
|
||||
- Keep controllers thin, services fat
|
||||
- Use environment variables for configuration
|
||||
|
||||
### Database Integration
|
||||
**Popular ORMs/ODMs:**
|
||||
- **Sequelize**: SQL ORM, supports multiple databases
|
||||
- **TypeORM**: TypeScript-first SQL ORM
|
||||
- **Prisma**: Modern ORM with great DX
|
||||
- **Mongoose**: MongoDB ODM
|
||||
- **Knex**: SQL query builder
|
||||
|
||||
### Error Handling
|
||||
- Use centralized error handler middleware
|
||||
- Create custom error classes
|
||||
- Log errors properly
|
||||
- Return appropriate HTTP status codes
|
||||
|
||||
### Security
|
||||
- Use helmet for security headers
|
||||
- Validate input with joi, yup, or class-validator
|
||||
- Rate limiting with express-rate-limit
|
||||
- CORS configuration
|
||||
- SQL injection prevention via ORM
|
||||
- Don't expose sensitive errors to clients
|
||||
|
||||
### Performance
|
||||
- Use compression middleware
|
||||
- Implement caching (Redis)
|
||||
- Database connection pooling
|
||||
- Optimize queries
|
||||
- Use clustering for CPU-intensive tasks
|
||||
|
||||
### Testing
|
||||
**Frameworks:**
|
||||
- Jest: Most popular, full-featured
|
||||
- Mocha + Chai: Flexible, modular
|
||||
- Supertest: HTTP endpoint testing
|
||||
|
||||
**Patterns:**
|
||||
- Unit tests for services
|
||||
- Integration tests for routes
|
||||
- Mock external dependencies
|
||||
- Use test databases
|
||||
|
||||
### Configuration
|
||||
- dotenv for environment variables
|
||||
- config package for multi-environment configs
|
||||
- Never commit secrets
|
||||
- Use secrets management in production
|
||||
|
||||
### Common Middleware Stack
|
||||
```javascript
|
||||
app.use(helmet()); // Security headers
|
||||
app.use(cors()); // CORS
|
||||
app.use(express.json()); // Parse JSON
|
||||
app.use(compression()); // Compress responses
|
||||
app.use(morgan('combined')); // Logging
|
||||
app.use(rateLimit({...})); // Rate limiting
|
||||
```
|
||||
|
||||
### Monitoring and Observability
|
||||
- **Application monitoring**: New Relic, Datadog, AppDynamics
|
||||
- **Error tracking**: Sentry, Rollbar
|
||||
- **Logging**: Winston, Pino, Bunyan
|
||||
- **APM**: OpenTelemetry, AWS X-Ray
|
||||
|
||||
### Package Management
|
||||
- Use npm or yarn consistently
|
||||
- Lock dependencies with package-lock.json or yarn.lock
|
||||
- Regular dependency updates
|
||||
- Check for vulnerabilities: npm audit
|
||||
|
||||
## Technology-Specific Patterns
|
||||
|
||||
### Real-time Applications
|
||||
- Socket.io for WebSockets
|
||||
- Server-Sent Events (SSE) for one-way updates
|
||||
- Redis pub/sub for scaling WebSockets
|
||||
|
||||
### GraphQL APIs
|
||||
- Apollo Server
|
||||
- Type-GraphQL with TypeScript
|
||||
- DataLoader for batching and caching
|
||||
|
||||
### Background Jobs
|
||||
- Bull (Redis-based queue)
|
||||
- Agenda (MongoDB-based)
|
||||
- BeeQueue (lightweight)
|
||||
- AWS SQS for serverless
|
||||
|
||||
### API Documentation
|
||||
- Swagger/OpenAPI with swagger-jsdoc
|
||||
- API Blueprint
|
||||
- Postman collections
|
||||
383
skills/references/python.md
Normal file
383
skills/references/python.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# Python Architecture Patterns
|
||||
|
||||
## Table of Contents
|
||||
- Common Frameworks and Patterns
|
||||
- Project Structure Conventions
|
||||
- Deployment Considerations
|
||||
- Best Practices
|
||||
|
||||
## Common Frameworks and Patterns
|
||||
|
||||
### Django
|
||||
**Typical Structure:**
|
||||
```
|
||||
project/
|
||||
├── manage.py
|
||||
├── project_name/ # Project config
|
||||
│ ├── settings.py
|
||||
│ ├── urls.py
|
||||
│ └── wsgi.py
|
||||
├── app_name/ # Django apps
|
||||
│ ├── models.py
|
||||
│ ├── views.py
|
||||
│ ├── serializers.py # If using DRF
|
||||
│ ├── urls.py
|
||||
│ └── admin.py
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- "Batteries included" framework
|
||||
- ORM built-in
|
||||
- Admin interface out of the box
|
||||
- Best for full-stack web applications
|
||||
- Django REST Framework for APIs
|
||||
|
||||
### Flask
|
||||
**Typical Structure:**
|
||||
```
|
||||
project/
|
||||
├── app/
|
||||
│ ├── __init__.py # Application factory
|
||||
│ ├── routes/
|
||||
│ ├── models/
|
||||
│ ├── services/
|
||||
│ └── utils/
|
||||
├── tests/
|
||||
├── config.py
|
||||
├── requirements.txt
|
||||
└── run.py
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- Microframework, minimal
|
||||
- Flexible and unopinionated
|
||||
- Extension-based (Flask-SQLAlchemy, Flask-JWT, etc.)
|
||||
- Good for APIs and smaller applications
|
||||
|
||||
### FastAPI
|
||||
**Typical Structure:**
|
||||
```
|
||||
project/
|
||||
├── app/
|
||||
│ ├── main.py
|
||||
│ ├── routers/
|
||||
│ ├── models/
|
||||
│ ├── schemas/ # Pydantic models
|
||||
│ ├── services/
|
||||
│ └── dependencies.py
|
||||
├── tests/
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
**Key Characteristics:**
|
||||
- Modern, high-performance
|
||||
- Type hints and validation (Pydantic)
|
||||
- Automatic API documentation (Swagger/ReDoc)
|
||||
- Async support built-in
|
||||
- Ideal for APIs and microservices
|
||||
|
||||
## Project Structure Conventions
|
||||
|
||||
### API Application (Flask/FastAPI)
|
||||
```
|
||||
project/
|
||||
├── app/
|
||||
│ ├── api/
|
||||
│ │ ├── v1/
|
||||
│ │ │ ├── endpoints/
|
||||
│ │ │ └── dependencies.py
|
||||
│ │ └── v2/
|
||||
│ ├── core/
|
||||
│ │ ├── config.py
|
||||
│ │ └── security.py
|
||||
│ ├── models/
|
||||
│ ├── schemas/
|
||||
│ ├── services/
|
||||
│ └── db/
|
||||
├── tests/
|
||||
├── alembic/ # Database migrations
|
||||
├── .env
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
### Django Monolith
|
||||
```
|
||||
project/
|
||||
├── manage.py
|
||||
├── project_name/
|
||||
│ ├── settings/
|
||||
│ │ ├── base.py
|
||||
│ │ ├── dev.py
|
||||
│ │ └── prod.py
|
||||
│ ├── urls.py
|
||||
│ └── wsgi.py
|
||||
├── apps/
|
||||
│ ├── users/
|
||||
│ ├── orders/
|
||||
│ └── products/
|
||||
├── static/
|
||||
├── templates/
|
||||
└── requirements/
|
||||
```
|
||||
|
||||
### Data Science/ML Application
|
||||
```
|
||||
project/
|
||||
├── data/
|
||||
│ ├── raw/
|
||||
│ ├── processed/
|
||||
│ └── models/
|
||||
├── notebooks/
|
||||
├── src/
|
||||
│ ├── data/
|
||||
│ ├── features/
|
||||
│ ├── models/
|
||||
│ └── visualization/
|
||||
├── tests/
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### WSGI/ASGI Servers
|
||||
**Production servers:**
|
||||
- **Gunicorn**: WSGI server for Django/Flask
|
||||
- **Uvicorn**: ASGI server for FastAPI
|
||||
- **uWSGI**: Full-featured application server
|
||||
- **Hypercorn**: ASGI server alternative
|
||||
|
||||
**Typical setup:**
|
||||
```bash
|
||||
gunicorn -w 4 -b 0.0.0.0:8000 app:app # Flask
|
||||
gunicorn -w 4 myproject.wsgi:application # Django
|
||||
uvicorn app.main:app --workers 4 # FastAPI
|
||||
```
|
||||
|
||||
### Containerization
|
||||
**Dockerfile patterns:**
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
# Copy application
|
||||
COPY . .
|
||||
|
||||
# Run as non-root user
|
||||
RUN useradd -m appuser && chown -R appuser /app
|
||||
USER appuser
|
||||
|
||||
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]
|
||||
```
|
||||
|
||||
### Common Deployment Platforms
|
||||
- **AWS**: Lambda (Zappa, Chalice), ECS, EC2, Elastic Beanstalk
|
||||
- **Google Cloud**: Cloud Run, App Engine, Compute Engine
|
||||
- **Azure**: App Service, Functions, Container Instances
|
||||
- **Heroku**: Simple deployment with Procfile
|
||||
- **PythonAnywhere**: Python-specific hosting
|
||||
- **Kubernetes**: Container orchestration
|
||||
|
||||
### Virtual Environments
|
||||
- **venv**: Built-in Python 3.3+
|
||||
- **virtualenv**: Cross-version compatibility
|
||||
- **conda**: Data science focused
|
||||
- **Poetry**: Modern dependency management
|
||||
- **pipenv**: Combines pip and virtualenv
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Code Organization
|
||||
- Follow PEP 8 style guide
|
||||
- Use blueprints (Flask) or apps (Django) for modularity
|
||||
- Separate business logic from views/routes
|
||||
- Keep models lean, use services for complex logic
|
||||
|
||||
### Database Integration
|
||||
|
||||
**Django ORM:**
|
||||
- Built-in, powerful ORM
|
||||
- Migrations with django-admin
|
||||
- QuerySet API
|
||||
|
||||
**SQLAlchemy (Flask/FastAPI):**
|
||||
- Most popular ORM
|
||||
- Core and ORM layers
|
||||
- Alembic for migrations
|
||||
|
||||
**Alternatives:**
|
||||
- **Tortoise ORM**: AsyncIO ORM for FastAPI
|
||||
- **Peewee**: Lightweight ORM
|
||||
- **asyncpg/psycopg3**: Direct database drivers
|
||||
|
||||
### Configuration Management
|
||||
```python
|
||||
# Use environment-specific configs
|
||||
import os
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
class Config:
|
||||
DEBUG = os.getenv('DEBUG', False)
|
||||
DATABASE_URL = os.getenv('DATABASE_URL')
|
||||
SECRET_KEY = os.getenv('SECRET_KEY')
|
||||
|
||||
class DevelopmentConfig(Config):
|
||||
DEBUG = True
|
||||
|
||||
class ProductionConfig(Config):
|
||||
DEBUG = False
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
**Django:**
|
||||
- CSRF protection built-in
|
||||
- XSS protection
|
||||
- SQL injection prevention via ORM
|
||||
- Security middleware enabled
|
||||
|
||||
**Flask/FastAPI:**
|
||||
- Use Flask-Security or FastAPI security utilities
|
||||
- Validate input with Pydantic (FastAPI) or marshmallow (Flask)
|
||||
- CORS: flask-cors or FastAPI CORSMiddleware
|
||||
- Rate limiting: Flask-Limiter
|
||||
|
||||
**General:**
|
||||
- Never commit secrets
|
||||
- Use environment variables
|
||||
- Validate and sanitize input
|
||||
- Use parameterized queries
|
||||
- Keep dependencies updated
|
||||
|
||||
### Error Handling
|
||||
```python
|
||||
# Centralized error handling
|
||||
from fastapi import HTTPException
|
||||
from flask import jsonify
|
||||
|
||||
@app.errorhandler(404)
|
||||
def not_found(error):
|
||||
return jsonify({"error": "Not found"}), 404
|
||||
|
||||
@app.exception_handler(ValueError)
|
||||
async def value_error_handler(request, exc):
|
||||
return JSONResponse(
|
||||
status_code=400,
|
||||
content={"message": str(exc)}
|
||||
)
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
**Frameworks:**
|
||||
- **pytest**: Most popular, full-featured
|
||||
- **unittest**: Built-in
|
||||
- **nose2**: Extension of unittest
|
||||
|
||||
**Tools:**
|
||||
- **pytest-cov**: Coverage reporting
|
||||
- **factory_boy**: Test fixtures
|
||||
- **faker**: Generate fake data
|
||||
- **responses/httpx**: Mock HTTP requests
|
||||
|
||||
**Patterns:**
|
||||
- Unit tests for business logic
|
||||
- Integration tests for endpoints
|
||||
- Use fixtures for test data
|
||||
- Mock external services
|
||||
|
||||
### Logging
|
||||
```python
|
||||
import logging
|
||||
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
```
|
||||
|
||||
**Production logging:**
|
||||
- Use structured logging (structlog)
|
||||
- Log to stdout/stderr for containers
|
||||
- Integrate with ELK, Datadog, CloudWatch
|
||||
|
||||
### Package Management
|
||||
```txt
|
||||
# requirements.txt
|
||||
Django==4.2.0
|
||||
psycopg2-binary==2.9.6
|
||||
gunicorn==20.1.0
|
||||
|
||||
# Or use Poetry
|
||||
# pyproject.toml
|
||||
[tool.poetry.dependencies]
|
||||
python = "^3.11"
|
||||
django = "^4.2"
|
||||
```
|
||||
|
||||
### Type Hints
|
||||
```python
|
||||
from typing import List, Optional
|
||||
|
||||
def get_users(limit: int = 10) -> List[User]:
|
||||
return User.objects.all()[:limit]
|
||||
|
||||
# Use mypy for static type checking
|
||||
```
|
||||
|
||||
### Async/Await (FastAPI, modern Python)
|
||||
```python
|
||||
async def get_data():
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get('https://api.example.com')
|
||||
return response.json()
|
||||
```
|
||||
|
||||
## Technology-Specific Patterns
|
||||
|
||||
### REST APIs
|
||||
- Django REST Framework: Full-featured, batteries included
|
||||
- Flask-RESTX: Flask extension for APIs
|
||||
- FastAPI: Modern, automatic docs, high performance
|
||||
|
||||
### Background Jobs
|
||||
- **Celery**: Distributed task queue (with Redis/RabbitMQ)
|
||||
- **RQ**: Simple Redis-based queue
|
||||
- **Dramatiq**: Alternative to Celery
|
||||
- **APScheduler**: Scheduler for periodic tasks
|
||||
|
||||
### Caching
|
||||
- **Redis**: Most common
|
||||
- **Memcached**: Simple key-value store
|
||||
- **Django cache framework**: Built-in abstraction
|
||||
- **Flask-Caching**: Flask extension
|
||||
|
||||
### GraphQL
|
||||
- **Graphene-Django**: Django integration
|
||||
- **Strawberry**: Modern, type-hint based
|
||||
- **Ariadne**: Schema-first approach
|
||||
|
||||
### WebSockets
|
||||
- **Django Channels**: Async Django
|
||||
- **Flask-SocketIO**: WebSocket support for Flask
|
||||
- **FastAPI WebSockets**: Built-in support
|
||||
|
||||
### API Documentation
|
||||
- FastAPI: Auto-generated (Swagger/ReDoc)
|
||||
- Django REST Framework: Browsable API + schema generation
|
||||
- Flask: flask-swagger or flasgger
|
||||
|
||||
### Monitoring
|
||||
- **Sentry**: Error tracking
|
||||
- **New Relic/Datadog**: APM
|
||||
- **Prometheus**: Metrics
|
||||
- **django-debug-toolbar**: Development profiling
|
||||
390
skills/references/serverless.md
Normal file
390
skills/references/serverless.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Serverless Architecture Patterns
|
||||
|
||||
## Table of Contents
|
||||
- Core Concepts
|
||||
- Function Patterns
|
||||
- Data Patterns
|
||||
- Integration Patterns
|
||||
- Best Practices
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Function as a Service (FaaS)
|
||||
Code runs in response to events without managing servers.
|
||||
|
||||
**Key Characteristics:**
|
||||
- Event-driven execution
|
||||
- Automatic scaling
|
||||
- Pay-per-execution pricing
|
||||
- Stateless functions
|
||||
- Short-lived execution
|
||||
|
||||
**Major Providers:**
|
||||
- AWS Lambda
|
||||
- Google Cloud Functions
|
||||
- Azure Functions
|
||||
- Cloudflare Workers
|
||||
|
||||
### Backend as a Service (BaaS)
|
||||
Managed services replace traditional backend components.
|
||||
|
||||
**Examples:**
|
||||
- Database: DynamoDB, Firestore, Fauna
|
||||
- Auth: Auth0, AWS Cognito, Firebase Auth
|
||||
- Storage: S3, Cloud Storage
|
||||
- APIs: API Gateway, AppSync
|
||||
|
||||
## Function Patterns
|
||||
|
||||
### API Endpoint Pattern
|
||||
```
|
||||
API Gateway --trigger--> Lambda Function --response--> API Gateway
|
||||
```
|
||||
|
||||
**Use case:** REST API, GraphQL API
|
||||
|
||||
**Example (AWS):**
|
||||
```
|
||||
API Gateway (POST /users)
|
||||
↓
|
||||
Lambda (createUser)
|
||||
↓
|
||||
DynamoDB
|
||||
```
|
||||
|
||||
### Event Processing Pattern
|
||||
```
|
||||
Event Source --event--> Lambda --process--> Output
|
||||
```
|
||||
|
||||
**Event Sources:**
|
||||
- S3: File uploads
|
||||
- DynamoDB Streams: Database changes
|
||||
- SQS: Message queue
|
||||
- SNS: Notifications
|
||||
- EventBridge: Custom events
|
||||
|
||||
**Use case:** Image processing, data transformation, ETL
|
||||
|
||||
### Scheduled Jobs Pattern
|
||||
```
|
||||
CloudWatch Events (cron) --trigger--> Lambda
|
||||
```
|
||||
|
||||
**Use case:** Batch processing, cleanup jobs, reports
|
||||
|
||||
**Example:**
|
||||
```
|
||||
EventBridge Rule (rate(1 day))
|
||||
↓
|
||||
Lambda (dailyReport)
|
||||
↓
|
||||
Send Email / Store Results
|
||||
```
|
||||
|
||||
### Stream Processing Pattern
|
||||
```
|
||||
Kinesis Stream --records--> Lambda --aggregate/transform--> Destination
|
||||
```
|
||||
|
||||
**Use case:** Real-time analytics, log processing
|
||||
|
||||
## Data Patterns
|
||||
|
||||
### DynamoDB Pattern (NoSQL)
|
||||
|
||||
**Access Patterns:**
|
||||
- Single table design
|
||||
- GSI for query flexibility
|
||||
- DynamoDB Streams for CDC
|
||||
|
||||
**Best practices:**
|
||||
- Design for access patterns first
|
||||
- Use partition keys for distribution
|
||||
- Batch operations when possible
|
||||
- Enable auto-scaling
|
||||
|
||||
### Aurora Serverless Pattern (SQL)
|
||||
|
||||
**Features:**
|
||||
- Auto-scaling SQL database
|
||||
- Pay per use
|
||||
- Data API for HTTP access
|
||||
|
||||
**Use case:** Variable workloads, development environments
|
||||
|
||||
### Multi-Database Pattern
|
||||
|
||||
**Polyglot persistence:**
|
||||
- DynamoDB for user profiles
|
||||
- S3 for files
|
||||
- ElastiCache for sessions
|
||||
- RDS for relational data
|
||||
|
||||
### API Composition Pattern
|
||||
|
||||
Function aggregates data from multiple sources:
|
||||
```
|
||||
Lambda
|
||||
├── Call Service A API
|
||||
├── Call Service B API
|
||||
├── Query DynamoDB
|
||||
└── Aggregate results
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### API Gateway Integration
|
||||
|
||||
**Types:**
|
||||
- Lambda Proxy: Full HTTP request to function
|
||||
- Lambda Integration: Custom request/response mapping
|
||||
- HTTP Proxy: Direct passthrough to backend
|
||||
- Mock: Return static response
|
||||
|
||||
**Features:**
|
||||
- Request validation
|
||||
- Authorization
|
||||
- Rate limiting
|
||||
- Caching
|
||||
- CORS
|
||||
|
||||
### EventBridge Pattern
|
||||
|
||||
Central event bus for service integration:
|
||||
```
|
||||
Service A --event--> EventBridge --route--> Lambda B
|
||||
--route--> Lambda C
|
||||
--route--> SQS Queue
|
||||
```
|
||||
|
||||
**Use case:** Event-driven architecture, decoupling services
|
||||
|
||||
### Step Functions Pattern
|
||||
|
||||
Orchestrate multiple Lambda functions:
|
||||
```
|
||||
Step Functions State Machine
|
||||
↓
|
||||
Step 1: Validate (Lambda)
|
||||
↓
|
||||
Step 2: Process (Lambda)
|
||||
↓
|
||||
Step 3: Notify (Lambda)
|
||||
```
|
||||
|
||||
**Use case:** Workflows, long-running processes, error handling
|
||||
|
||||
### SQS Queue Pattern
|
||||
|
||||
Decouple and buffer workloads:
|
||||
```
|
||||
Producer --message--> SQS Queue --poll--> Lambda Consumer
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Async processing
|
||||
- Rate limiting
|
||||
- Retry logic
|
||||
- Dead letter queue
|
||||
|
||||
### Fan-out Pattern
|
||||
|
||||
Single event triggers multiple functions:
|
||||
```
|
||||
S3 Upload Event
|
||||
↓
|
||||
SNS Topic
|
||||
├── Lambda: Create Thumbnail
|
||||
├── Lambda: Extract Metadata
|
||||
└── Lambda: Virus Scan
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Cold Start Optimization
|
||||
|
||||
**Strategies:**
|
||||
- Keep functions small
|
||||
- Minimize dependencies
|
||||
- Use provisioned concurrency (critical paths)
|
||||
- Reuse connections
|
||||
- Initialize outside handler
|
||||
|
||||
```javascript
|
||||
// Good: Initialize outside
|
||||
const db = new DynamoDB.DocumentClient();
|
||||
|
||||
exports.handler = async (event) => {
|
||||
// Use db here
|
||||
};
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Patterns:**
|
||||
- Return errors explicitly
|
||||
- Use Dead Letter Queues
|
||||
- Implement retry logic
|
||||
- Log errors with context
|
||||
|
||||
```javascript
|
||||
exports.handler = async (event) => {
|
||||
try {
|
||||
// Process event
|
||||
} catch (error) {
|
||||
console.error('Error:', error);
|
||||
// Send to DLQ or SNS
|
||||
throw error; // Trigger retry
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
**Best practices:**
|
||||
- Least privilege IAM roles
|
||||
- Encrypt environment variables
|
||||
- Use VPC for private resources
|
||||
- Validate input
|
||||
- Use AWS Secrets Manager
|
||||
|
||||
### Cost Optimization
|
||||
|
||||
**Strategies:**
|
||||
- Right-size memory (affects CPU)
|
||||
- Optimize execution time
|
||||
- Use SQS for buffering
|
||||
- Set appropriate timeouts
|
||||
- Monitor unused functions
|
||||
|
||||
### Observability
|
||||
|
||||
**Logging:**
|
||||
- Use structured logging (JSON)
|
||||
- Include correlation IDs
|
||||
- Log key metrics
|
||||
|
||||
**Monitoring:**
|
||||
- CloudWatch Metrics
|
||||
- X-Ray for tracing
|
||||
- Custom metrics
|
||||
|
||||
**Alerts:**
|
||||
- Error rates
|
||||
- Duration
|
||||
- Throttles
|
||||
- Dead letter queue depth
|
||||
|
||||
### State Management
|
||||
|
||||
**Stateless functions:**
|
||||
- No local state
|
||||
- Use external stores (DynamoDB, S3, ElastiCache)
|
||||
- Pass state in events
|
||||
|
||||
**Step Functions for stateful workflows:**
|
||||
- Maintain workflow state
|
||||
- Handle long-running processes
|
||||
|
||||
### Testing
|
||||
|
||||
**Levels:**
|
||||
- Unit: Test handler logic
|
||||
- Integration: Test with local services (LocalStack)
|
||||
- E2E: Test in AWS
|
||||
|
||||
**Tools:**
|
||||
- Jest/Mocha for unit tests
|
||||
- AWS SAM for local testing
|
||||
- LocalStack for local AWS
|
||||
|
||||
### Deployment
|
||||
|
||||
**IaC Tools:**
|
||||
- AWS SAM (Serverless Application Model)
|
||||
- Serverless Framework
|
||||
- AWS CDK
|
||||
- Terraform
|
||||
|
||||
**CI/CD:**
|
||||
- Automated testing
|
||||
- Canary deployments
|
||||
- Blue-green deployments
|
||||
- Rollback capability
|
||||
|
||||
## Architecture Examples
|
||||
|
||||
### REST API
|
||||
```
|
||||
API Gateway (REST)
|
||||
├── GET /items --> Lambda (listItems) --> DynamoDB
|
||||
├── POST /items --> Lambda (createItem) --> DynamoDB
|
||||
└── GET /items/{id} --> Lambda (getItem) --> DynamoDB
|
||||
```
|
||||
|
||||
### Event-Driven Processing
|
||||
```
|
||||
S3 Bucket (image upload)
|
||||
↓
|
||||
Lambda (processImage)
|
||||
├── Resize image
|
||||
├── Store in S3
|
||||
└── Update DynamoDB
|
||||
```
|
||||
|
||||
### Microservices
|
||||
```
|
||||
Service 1: API Gateway + Lambda + DynamoDB
|
||||
Service 2: API Gateway + Lambda + RDS Aurora
|
||||
Service 3: EventBridge + Lambda + SQS
|
||||
|
||||
Inter-service: HTTP APIs or EventBridge
|
||||
```
|
||||
|
||||
### Data Pipeline
|
||||
```
|
||||
S3 (raw data)
|
||||
↓
|
||||
Lambda (transform)
|
||||
↓
|
||||
Kinesis Firehose
|
||||
↓
|
||||
S3 (processed data)
|
||||
↓
|
||||
Athena (query)
|
||||
```
|
||||
|
||||
## Common Challenges
|
||||
|
||||
### Vendor Lock-in
|
||||
**Mitigation:** Use frameworks (Serverless Framework), abstract provider-specific code
|
||||
|
||||
### Cold Starts
|
||||
**Mitigation:** Provisioned concurrency, keep functions warm, optimize bundle size
|
||||
|
||||
### Debugging
|
||||
**Mitigation:** Structured logging, X-Ray tracing, local testing
|
||||
|
||||
### Testing
|
||||
**Mitigation:** Unit tests, integration tests with LocalStack, E2E tests in staging
|
||||
|
||||
### Distributed Tracing
|
||||
**Mitigation:** AWS X-Ray, correlation IDs, structured logs
|
||||
|
||||
## When to Use Serverless
|
||||
|
||||
**Good for:**
|
||||
- Variable workload
|
||||
- Event-driven applications
|
||||
- APIs with unpredictable traffic
|
||||
- Scheduled jobs
|
||||
- Rapid prototyping
|
||||
- Startups (reduce ops overhead)
|
||||
|
||||
**Not ideal for:**
|
||||
- Long-running processes (>15 min)
|
||||
- Consistent high-throughput
|
||||
- Applications requiring low latency
|
||||
- Complex state management
|
||||
- Heavy computation (cost)
|
||||
156
skills/references/workflows.md
Normal file
156
skills/references/workflows.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Architecture Documentation Workflows
|
||||
|
||||
## Table of Contents
|
||||
- Interview Workflow for New Projects
|
||||
- Interview Workflow for Existing Systems
|
||||
- Documentation Generation Process
|
||||
- Update and Maintenance Workflow
|
||||
|
||||
## Interview Workflow for New Projects
|
||||
|
||||
Gather information through these questions in order:
|
||||
|
||||
### Phase 1: Project Context (2-3 questions)
|
||||
1. **Project basics**: Name, purpose, target users
|
||||
2. **Timeline**: Launch date, current phase (planning/development/production)
|
||||
3. **Team**: Size, composition, experience level
|
||||
|
||||
### Phase 2: Technical Stack (2-4 questions)
|
||||
1. **Backend**: Primary language and framework (e.g., "Node.js with Express" or "Python with Django")
|
||||
2. **Frontend**: Framework or approach (e.g., "React SPA" or "Server-rendered with templates")
|
||||
3. **Database**: Type and name (e.g., "PostgreSQL" or "MongoDB")
|
||||
4. **Infrastructure**: Cloud provider or hosting (e.g., "AWS" or "On-premise")
|
||||
|
||||
### Phase 3: Architecture Pattern (1-2 questions)
|
||||
1. **Pattern**: Monolith, microservices, serverless, or hybrid
|
||||
2. **Rationale**: Why this pattern? (helps understand constraints)
|
||||
|
||||
### Phase 4: Components (2-4 questions based on pattern)
|
||||
|
||||
For Monolith:
|
||||
- Main modules or features
|
||||
- Background jobs or scheduled tasks
|
||||
- Static asset handling
|
||||
|
||||
For Microservices:
|
||||
- List of services (name and responsibility)
|
||||
- How services communicate (REST, gRPC, message queue)
|
||||
- Shared components (API gateway, service mesh)
|
||||
|
||||
For Serverless:
|
||||
- Functions and their triggers
|
||||
- State management approach
|
||||
- Event sources
|
||||
|
||||
### Phase 5: Data and Integrations (1-3 questions)
|
||||
1. **Additional data stores**: Cache, search engine, file storage
|
||||
2. **External services**: Payment, email, analytics, etc.
|
||||
3. **APIs**: Third-party APIs being consumed
|
||||
|
||||
### Phase 6: Operations (1-2 questions)
|
||||
1. **Deployment**: Manual, CI/CD, orchestration
|
||||
2. **Monitoring**: Logging, metrics, alerting setup
|
||||
|
||||
## Interview Workflow for Existing Systems
|
||||
|
||||
For systems already built, adjust approach:
|
||||
|
||||
### Quick Assessment
|
||||
1. **Documentation exists?** If yes, review it first
|
||||
2. **Codebase access?** If yes, analyze structure
|
||||
3. **Team knowledge?** Interview developers
|
||||
|
||||
### Targeted Questions
|
||||
1. What's changed since last documentation?
|
||||
2. What's causing confusion for new developers?
|
||||
3. What's undocumented or poorly documented?
|
||||
4. Are there any planned changes?
|
||||
|
||||
### Validation Approach
|
||||
- Cross-reference answers with code
|
||||
- Identify discrepancies between docs and reality
|
||||
- Highlight areas needing attention
|
||||
|
||||
## Documentation Generation Process
|
||||
|
||||
### Step 1: Select Template
|
||||
Choose based on architecture pattern:
|
||||
- `assets/ARCHITECTURE.md` for general/unknown
|
||||
- `assets/ARCHITECTURE-microservices.md` for microservices
|
||||
- `assets/ARCHITECTURE-monolith.md` for monoliths
|
||||
|
||||
### Step 2: Generate System Diagram
|
||||
Use `scripts/generate_diagram.py` based on pattern:
|
||||
- Monolith: Use "layered" type
|
||||
- Microservices: Use "flow" or "c4" type
|
||||
- Simple systems: Use "simple" type
|
||||
|
||||
### Step 3: Fill Template Sections
|
||||
Populate in this order:
|
||||
1. Project Identification (Section 10) - establishes context
|
||||
2. Project Structure (Section 1) - concrete foundation
|
||||
3. System Diagram (Section 2) - using generated diagram
|
||||
4. Core Components (Section 3) - from interview data
|
||||
5. Data Stores (Section 4) - databases and caches
|
||||
6. External Integrations (Section 5) - third-party services
|
||||
7. Deployment & Infrastructure (Section 6) - ops details
|
||||
8. Security Considerations (Section 7) - auth, encryption
|
||||
9. Development & Testing (Section 8) - dev environment
|
||||
10. Future Considerations (Section 9) - roadmap items
|
||||
11. Glossary (Section 11) - domain-specific terms
|
||||
|
||||
### Step 4: Enhance with Technology Specifics
|
||||
Load relevant reference and apply patterns:
|
||||
- Node.js: See references/nodejs.md
|
||||
- Python: See references/python.md
|
||||
- Java: See references/java.md
|
||||
|
||||
### Step 5: Validate
|
||||
Run validation script:
|
||||
```bash
|
||||
python scripts/validate_architecture.py ARCHITECTURE.md
|
||||
```
|
||||
|
||||
Address any issues or warnings.
|
||||
|
||||
## Update and Maintenance Workflow
|
||||
|
||||
### For Incremental Updates
|
||||
1. Identify changed components
|
||||
2. Update affected sections only
|
||||
3. Update "Date of Last Update" in Section 10
|
||||
4. Add brief note in Future Considerations if major change
|
||||
|
||||
### For Major Updates
|
||||
1. Re-interview on changed areas
|
||||
2. Regenerate system diagram if structure changed
|
||||
3. Update multiple sections as needed
|
||||
4. Consider adding version notes
|
||||
|
||||
### Best Practices
|
||||
- Keep updates small and frequent
|
||||
- Document changes when they happen
|
||||
- Review quarterly even if no changes
|
||||
- Archive old versions if major restructure
|
||||
|
||||
## Tips for Effective Interviews
|
||||
|
||||
### Keep Questions Focused
|
||||
- Ask one thing at a time
|
||||
- Avoid overwhelming with options
|
||||
- Build on previous answers
|
||||
|
||||
### Adapt Based on Responses
|
||||
- If user is technical, use technical terms
|
||||
- If user is non-technical, simplify language
|
||||
- Skip redundant questions
|
||||
|
||||
### Handle Uncertainty
|
||||
- If user unsure, offer to add placeholder
|
||||
- Suggest reasonable defaults
|
||||
- Mark uncertain items for review
|
||||
|
||||
### Validate Understanding
|
||||
- Summarize what you heard
|
||||
- Confirm critical details
|
||||
- Check for consistency
|
||||
308
skills/scripts/create_package.py
Normal file
308
skills/scripts/create_package.py
Normal file
@@ -0,0 +1,308 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Package architecture documentation into a comprehensive ZIP file.
|
||||
Includes: ARCHITECTURE.md, OpenAPI spec, PDF, and diagram images.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import json
|
||||
import subprocess
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
import zipfile
|
||||
|
||||
|
||||
def convert_markdown_to_pdf(md_file: str, output_pdf: str, work_dir: str) -> bool:
|
||||
"""Convert markdown to PDF using pandoc if available, else create placeholder."""
|
||||
try:
|
||||
# Try using pandoc
|
||||
result = subprocess.run(
|
||||
['pandoc', md_file, '-o', output_pdf, '--pdf-engine=pdflatex'],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=30
|
||||
)
|
||||
if result.returncode == 0:
|
||||
return True
|
||||
except (FileNotFoundError, subprocess.TimeoutExpired):
|
||||
pass
|
||||
|
||||
# Fallback: Try weasyprint
|
||||
try:
|
||||
import markdown
|
||||
from weasyprint import HTML, CSS
|
||||
|
||||
# Read markdown
|
||||
with open(md_file, 'r', encoding='utf-8') as f:
|
||||
md_content = f.read()
|
||||
|
||||
# Convert to HTML
|
||||
html_content = markdown.markdown(md_content, extensions=['tables', 'fenced_code'])
|
||||
|
||||
# Add styling
|
||||
styled_html = f"""
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<style>
|
||||
body {{
|
||||
font-family: Arial, sans-serif;
|
||||
line-height: 1.6;
|
||||
max-width: 800px;
|
||||
margin: 40px auto;
|
||||
padding: 0 20px;
|
||||
}}
|
||||
h1, h2, h3 {{ color: #333; }}
|
||||
h1 {{ border-bottom: 2px solid #333; padding-bottom: 10px; }}
|
||||
h2 {{ border-bottom: 1px solid #666; padding-bottom: 5px; margin-top: 30px; }}
|
||||
code {{
|
||||
background: #f4f4f4;
|
||||
padding: 2px 6px;
|
||||
border-radius: 3px;
|
||||
font-family: 'Courier New', monospace;
|
||||
}}
|
||||
pre {{
|
||||
background: #f4f4f4;
|
||||
padding: 15px;
|
||||
border-radius: 5px;
|
||||
overflow-x: auto;
|
||||
}}
|
||||
table {{
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 20px 0;
|
||||
}}
|
||||
th, td {{
|
||||
border: 1px solid #ddd;
|
||||
padding: 12px;
|
||||
text-align: left;
|
||||
}}
|
||||
th {{
|
||||
background-color: #f2f2f2;
|
||||
font-weight: bold;
|
||||
}}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
{html_content}
|
||||
</body>
|
||||
</html>
|
||||
"""
|
||||
|
||||
# Convert HTML to PDF
|
||||
HTML(string=styled_html).write_pdf(output_pdf)
|
||||
return True
|
||||
|
||||
except ImportError:
|
||||
pass
|
||||
|
||||
# Last resort: Create a simple text-based PDF notice
|
||||
notice = f"""PDF Generation Not Available
|
||||
|
||||
The required tools (pandoc or weasyprint) are not installed.
|
||||
Please refer to the ARCHITECTURE.md file for the full documentation.
|
||||
|
||||
To generate a PDF manually:
|
||||
1. Install pandoc: apt-get install pandoc texlive-latex-base
|
||||
OR
|
||||
2. Install weasyprint: pip install markdown weasyprint --break-system-packages
|
||||
|
||||
Then run:
|
||||
pandoc {md_file} -o {output_pdf}
|
||||
OR
|
||||
python {os.path.abspath(__file__)} <work_dir>
|
||||
"""
|
||||
|
||||
# Create a simple text file as placeholder
|
||||
with open(output_pdf + '.txt', 'w') as f:
|
||||
f.write(notice)
|
||||
|
||||
print(f"⚠️ PDF generation tools not available. Created notice file instead.")
|
||||
return False
|
||||
|
||||
|
||||
def render_mermaid_diagrams(work_dir: str, diagrams_dir: str) -> list:
|
||||
"""Render Mermaid diagrams to PNG images using mmdc if available."""
|
||||
|
||||
# Find all .mmd files in work directory
|
||||
mmd_files = list(Path(work_dir).glob('*.mmd'))
|
||||
|
||||
if not mmd_files:
|
||||
print("No .mmd files found to render")
|
||||
return []
|
||||
|
||||
os.makedirs(diagrams_dir, exist_ok=True)
|
||||
rendered_files = []
|
||||
|
||||
for mmd_file in mmd_files:
|
||||
output_file = os.path.join(diagrams_dir, mmd_file.stem + '.png')
|
||||
|
||||
try:
|
||||
# Try using mermaid-cli (mmdc)
|
||||
result = subprocess.run(
|
||||
['mmdc', '-i', str(mmd_file), '-o', output_file, '-b', 'transparent'],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=30
|
||||
)
|
||||
|
||||
if result.returncode == 0 and os.path.exists(output_file):
|
||||
rendered_files.append(output_file)
|
||||
print(f"✅ Rendered: {mmd_file.name} → {os.path.basename(output_file)}")
|
||||
else:
|
||||
print(f"⚠️ Could not render: {mmd_file.name}")
|
||||
|
||||
except (FileNotFoundError, subprocess.TimeoutExpired) as e:
|
||||
print(f"⚠️ mermaid-cli not available. Skipping diagram rendering.")
|
||||
print(f" Install with: npm install -g @mermaid-js/mermaid-cli")
|
||||
break
|
||||
|
||||
return rendered_files
|
||||
|
||||
|
||||
def create_package_zip(work_dir: str, output_zip: str) -> bool:
|
||||
"""Create a ZIP package with all documentation files in proper structure."""
|
||||
|
||||
work_path = Path(work_dir)
|
||||
|
||||
# Collect files to include
|
||||
files_to_include = []
|
||||
|
||||
# ARCHITECTURE.md (required)
|
||||
arch_file = work_path / 'ARCHITECTURE.md'
|
||||
if arch_file.exists():
|
||||
files_to_include.append(('ARCHITECTURE.md', arch_file))
|
||||
else:
|
||||
print("❌ ARCHITECTURE.md not found!")
|
||||
return False
|
||||
|
||||
# OpenAPI spec (if exists)
|
||||
openapi_file = work_path / 'openapi.json'
|
||||
if openapi_file.exists():
|
||||
files_to_include.append(('openapi.json', openapi_file))
|
||||
|
||||
# PDF (if exists)
|
||||
pdf_file = work_path / 'ARCHITECTURE.pdf'
|
||||
pdf_exists = False
|
||||
if pdf_file.exists():
|
||||
files_to_include.append(('ARCHITECTURE.pdf', pdf_file))
|
||||
pdf_exists = True
|
||||
else:
|
||||
# Check for the txt notice
|
||||
pdf_txt = work_path / 'ARCHITECTURE.pdf.txt'
|
||||
if pdf_txt.exists():
|
||||
files_to_include.append(('PDF_GENERATION_NOTICE.txt', pdf_txt))
|
||||
|
||||
# Find .mmd source files (should be in work_dir root)
|
||||
mmd_files = sorted(list(work_path.glob('*.mmd')))
|
||||
|
||||
# Find diagram images (PNG/SVG)
|
||||
diagrams_dir = work_path / 'diagrams'
|
||||
diagram_files = []
|
||||
if diagrams_dir.exists():
|
||||
diagram_files = sorted(list(diagrams_dir.glob('*.png')) + list(diagrams_dir.glob('*.svg')))
|
||||
|
||||
# Create ZIP with proper structure
|
||||
try:
|
||||
with zipfile.ZipFile(output_zip, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||
# Add main files at root
|
||||
for arc_name, file_path in files_to_include:
|
||||
zipf.write(file_path, arc_name)
|
||||
print(f"📦 Added: {arc_name}")
|
||||
|
||||
# Add .mmd source files to diagrams/source/
|
||||
if mmd_files:
|
||||
for mmd_file in mmd_files:
|
||||
arc_name = f"diagrams/source/{mmd_file.name}"
|
||||
zipf.write(mmd_file, arc_name)
|
||||
print(f"📦 Added: {arc_name}")
|
||||
|
||||
# Add rendered diagram images to diagrams/
|
||||
if diagram_files:
|
||||
for diagram_file in diagram_files:
|
||||
arc_name = f"diagrams/{diagram_file.name}"
|
||||
zipf.write(diagram_file, arc_name)
|
||||
print(f"📦 Added: {arc_name}")
|
||||
|
||||
# Print summary
|
||||
print(f"\n✅ Package created: {output_zip}")
|
||||
print(f"\n📦 Package contents:")
|
||||
print(f" ├── ARCHITECTURE.md")
|
||||
if pdf_exists:
|
||||
print(f" ├── ARCHITECTURE.pdf")
|
||||
if openapi_file.exists():
|
||||
print(f" ├── openapi.json")
|
||||
if mmd_files or diagram_files:
|
||||
print(f" └── diagrams/")
|
||||
if diagram_files:
|
||||
for df in diagram_files:
|
||||
print(f" ├── {df.name}")
|
||||
if mmd_files:
|
||||
print(f" └── source/")
|
||||
for mf in mmd_files:
|
||||
print(f" ├── {mf.name}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating ZIP: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
return False
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python create_package.py <work_directory> [output_zip]")
|
||||
print("\nThe work directory should contain:")
|
||||
print(" - ARCHITECTURE.md (required)")
|
||||
print(" - openapi.json (optional)")
|
||||
print(" - *.mmd files (optional, for diagram rendering)")
|
||||
sys.exit(1)
|
||||
|
||||
work_dir = sys.argv[1]
|
||||
output_zip = sys.argv[2] if len(sys.argv) > 2 else os.path.join(work_dir, 'architecture-package.zip')
|
||||
|
||||
if not os.path.exists(work_dir):
|
||||
print(f"❌ Work directory not found: {work_dir}")
|
||||
sys.exit(1)
|
||||
|
||||
print(f"📦 Creating architecture documentation package...\n")
|
||||
print(f"Work directory: {work_dir}")
|
||||
print(f"Output ZIP: {output_zip}\n")
|
||||
|
||||
# Step 1: Convert Markdown to PDF
|
||||
arch_md = os.path.join(work_dir, 'ARCHITECTURE.md')
|
||||
if os.path.exists(arch_md):
|
||||
print("📄 Converting ARCHITECTURE.md to PDF...")
|
||||
pdf_file = os.path.join(work_dir, 'ARCHITECTURE.pdf')
|
||||
convert_markdown_to_pdf(arch_md, pdf_file, work_dir)
|
||||
print()
|
||||
|
||||
# Step 2: Render Mermaid diagrams
|
||||
diagrams_dir = os.path.join(work_dir, 'diagrams')
|
||||
print("🎨 Rendering Mermaid diagrams...")
|
||||
rendered = render_mermaid_diagrams(work_dir, diagrams_dir)
|
||||
if rendered:
|
||||
print(f"✅ Rendered {len(rendered)} diagram(s)")
|
||||
print()
|
||||
|
||||
# Step 3: Create ZIP package
|
||||
print("📦 Creating ZIP package...")
|
||||
success = create_package_zip(work_dir, output_zip)
|
||||
|
||||
if success:
|
||||
# Get file size
|
||||
size_mb = os.path.getsize(output_zip) / (1024 * 1024)
|
||||
print(f"\n✅ Package complete! Size: {size_mb:.2f} MB")
|
||||
print(f"📦 {output_zip}")
|
||||
else:
|
||||
print("\n❌ Package creation failed")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
205
skills/scripts/generate_diagram.py
Normal file
205
skills/scripts/generate_diagram.py
Normal file
@@ -0,0 +1,205 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Generate ASCII/text-based system architecture diagrams.
|
||||
Supports simple component and data flow diagrams.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import json
|
||||
from typing import List, Dict, Tuple
|
||||
|
||||
|
||||
def generate_simple_diagram(components: List[str], connections: List[Tuple[str, str]]) -> str:
|
||||
"""
|
||||
Generate a simple left-to-right component diagram.
|
||||
|
||||
Args:
|
||||
components: List of component names
|
||||
connections: List of (from_component, to_component) tuples
|
||||
"""
|
||||
diagram_lines = []
|
||||
|
||||
# Create component boxes
|
||||
for i, component in enumerate(components):
|
||||
if i == 0:
|
||||
diagram_lines.append(f"[{component}]")
|
||||
else:
|
||||
# Add connection arrow
|
||||
prev = components[i-1]
|
||||
if (prev, component) in connections or (component, prev) in connections:
|
||||
diagram_lines.append(" |")
|
||||
diagram_lines.append(" v")
|
||||
else:
|
||||
diagram_lines.append("")
|
||||
diagram_lines.append(f"[{component}]")
|
||||
|
||||
return "\n".join(diagram_lines)
|
||||
|
||||
|
||||
def generate_layered_diagram(layers: Dict[str, List[str]]) -> str:
|
||||
"""
|
||||
Generate a layered architecture diagram.
|
||||
|
||||
Args:
|
||||
layers: Dict of layer_name -> [components]
|
||||
"""
|
||||
diagram_lines = []
|
||||
|
||||
for layer_name, components in layers.items():
|
||||
diagram_lines.append(f"\n{layer_name}:")
|
||||
diagram_lines.append("+" + "-" * 60 + "+")
|
||||
|
||||
for component in components:
|
||||
# Center the component name
|
||||
padding = (58 - len(component)) // 2
|
||||
diagram_lines.append(f"| {' ' * padding}{component}{' ' * (58 - len(component) - padding)} |")
|
||||
|
||||
diagram_lines.append("+" + "-" * 60 + "+")
|
||||
diagram_lines.append(" |")
|
||||
diagram_lines.append(" v")
|
||||
|
||||
# Remove last arrow
|
||||
if diagram_lines:
|
||||
diagram_lines = diagram_lines[:-2]
|
||||
|
||||
return "\n".join(diagram_lines)
|
||||
|
||||
|
||||
def generate_flow_diagram(flow: List[Dict[str, str]]) -> str:
|
||||
"""
|
||||
Generate a data flow diagram.
|
||||
|
||||
Args:
|
||||
flow: List of dicts with 'from', 'to', 'label' keys
|
||||
"""
|
||||
diagram_lines = []
|
||||
components_seen = set()
|
||||
|
||||
for step in flow:
|
||||
from_comp = step['from']
|
||||
to_comp = step['to']
|
||||
label = step.get('label', '')
|
||||
|
||||
if from_comp not in components_seen:
|
||||
diagram_lines.append(f"[{from_comp}]")
|
||||
components_seen.add(from_comp)
|
||||
|
||||
# Add arrow with label
|
||||
arrow = f" |--{label}-->" if label else " |---->"
|
||||
diagram_lines.append(arrow)
|
||||
diagram_lines.append(f"[{to_comp}]")
|
||||
components_seen.add(to_comp)
|
||||
|
||||
return "\n".join(diagram_lines)
|
||||
|
||||
|
||||
def generate_c4_context_diagram(system: str, actors: List[str], external_systems: List[str]) -> str:
|
||||
"""
|
||||
Generate a C4 Level 1 (System Context) diagram.
|
||||
|
||||
Args:
|
||||
system: Name of the system being documented
|
||||
actors: List of user types/actors
|
||||
external_systems: List of external systems
|
||||
"""
|
||||
diagram_lines = []
|
||||
|
||||
# Add actors
|
||||
for actor in actors:
|
||||
diagram_lines.append(f"[{actor}]")
|
||||
diagram_lines.append(" |")
|
||||
diagram_lines.append(" v")
|
||||
|
||||
# Add main system
|
||||
diagram_lines.append("+" + "=" * 40 + "+")
|
||||
diagram_lines.append(f"|{system.center(40)}|")
|
||||
diagram_lines.append("+" + "=" * 40 + "+")
|
||||
|
||||
# Add external systems
|
||||
if external_systems:
|
||||
diagram_lines.append(" |")
|
||||
diagram_lines.append(" v")
|
||||
for ext_sys in external_systems:
|
||||
diagram_lines.append(f"[{ext_sys}] (External)")
|
||||
if ext_sys != external_systems[-1]:
|
||||
diagram_lines.append(" |")
|
||||
|
||||
return "\n".join(diagram_lines)
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python generate_diagram.py <type> [json_config]")
|
||||
print("\nTypes:")
|
||||
print(" simple - Simple component flow")
|
||||
print(" layered - Layered architecture")
|
||||
print(" flow - Data flow diagram")
|
||||
print(" c4 - C4 context diagram")
|
||||
print("\nExamples:")
|
||||
print(' python generate_diagram.py simple \'{"components": ["User", "API", "DB"], "connections": [["User", "API"], ["API", "DB"]]}\'')
|
||||
print(' python generate_diagram.py layered \'{"Presentation": ["Web UI", "Mobile App"], "Business": ["API Service"], "Data": ["Database"]}\'')
|
||||
sys.exit(1)
|
||||
|
||||
diagram_type = sys.argv[1].lower()
|
||||
|
||||
if diagram_type == "simple":
|
||||
if len(sys.argv) < 3:
|
||||
# Default simple example
|
||||
components = ["User", "Frontend", "Backend", "Database"]
|
||||
connections = [("User", "Frontend"), ("Frontend", "Backend"), ("Backend", "Database")]
|
||||
else:
|
||||
config = json.loads(sys.argv[2])
|
||||
components = config.get('components', [])
|
||||
connections = [tuple(c) for c in config.get('connections', [])]
|
||||
|
||||
print(generate_simple_diagram(components, connections))
|
||||
|
||||
elif diagram_type == "layered":
|
||||
if len(sys.argv) < 3:
|
||||
# Default layered example
|
||||
layers = {
|
||||
"Presentation Layer": ["Web Interface", "Mobile App"],
|
||||
"Application Layer": ["Business Logic", "API Service"],
|
||||
"Data Layer": ["Database", "Cache"]
|
||||
}
|
||||
else:
|
||||
layers = json.loads(sys.argv[2])
|
||||
|
||||
print(generate_layered_diagram(layers))
|
||||
|
||||
elif diagram_type == "flow":
|
||||
if len(sys.argv) < 3:
|
||||
# Default flow example
|
||||
flow = [
|
||||
{"from": "User", "to": "API Gateway", "label": "request"},
|
||||
{"from": "API Gateway", "to": "Service", "label": "route"},
|
||||
{"from": "Service", "to": "Database", "label": "query"}
|
||||
]
|
||||
else:
|
||||
flow = json.loads(sys.argv[2])
|
||||
|
||||
print(generate_flow_diagram(flow))
|
||||
|
||||
elif diagram_type == "c4":
|
||||
if len(sys.argv) < 3:
|
||||
# Default C4 example
|
||||
system = "My Application"
|
||||
actors = ["End User", "Administrator"]
|
||||
external_systems = ["Payment Gateway", "Email Service"]
|
||||
else:
|
||||
config = json.loads(sys.argv[2])
|
||||
system = config.get('system', 'System')
|
||||
actors = config.get('actors', [])
|
||||
external_systems = config.get('external_systems', [])
|
||||
|
||||
print(generate_c4_context_diagram(system, actors, external_systems))
|
||||
|
||||
else:
|
||||
print(f"Unknown diagram type: {diagram_type}")
|
||||
print("Available types: simple, layered, flow, c4")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
345
skills/scripts/generate_mermaid.py
Normal file
345
skills/scripts/generate_mermaid.py
Normal file
@@ -0,0 +1,345 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Generate Mermaid.js diagrams for architecture documentation.
|
||||
Creates 5 essential diagrams: C4 Context, Container, Component, Data Flow, and Deployment.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import json
|
||||
from typing import Dict, List, Any
|
||||
|
||||
|
||||
def generate_c4_context(system_info: Dict[str, Any]) -> str:
|
||||
"""Generate C4 Level 1: System Context diagram."""
|
||||
system_name = system_info.get('system_name', 'System')
|
||||
users = system_info.get('users', [])
|
||||
external_systems = system_info.get('external_systems', [])
|
||||
|
||||
diagram = f"""```mermaid
|
||||
C4Context
|
||||
title System Context - {system_name}
|
||||
"""
|
||||
|
||||
# Add users
|
||||
for i, user in enumerate(users):
|
||||
user_id = user.get('id', f'user{i}')
|
||||
user_name = user.get('name', f'User {i}')
|
||||
user_desc = user.get('description', 'System user')
|
||||
diagram += f' Person({user_id}, "{user_name}", "{user_desc}")\n'
|
||||
|
||||
# Add main system
|
||||
system_desc = system_info.get('description', 'Core system functionality')
|
||||
diagram += f' System(system, "{system_name}", "{system_desc}")\n'
|
||||
|
||||
# Add external systems
|
||||
for i, ext_sys in enumerate(external_systems):
|
||||
ext_id = ext_sys.get('id', f'ext{i}')
|
||||
ext_name = ext_sys.get('name', f'External System {i}')
|
||||
ext_desc = ext_sys.get('description', 'Third-party service')
|
||||
diagram += f' System_Ext({ext_id}, "{ext_name}", "{ext_desc}")\n'
|
||||
|
||||
diagram += '\n'
|
||||
|
||||
# Add relationships
|
||||
for user in users:
|
||||
user_id = user.get('id', f'user{len(users)}')
|
||||
rel = user.get('relationship', 'uses')
|
||||
diagram += f' Rel({user_id}, system, "{rel}")\n'
|
||||
|
||||
for ext_sys in external_systems:
|
||||
ext_id = ext_sys.get('id', f'ext{len(external_systems)}')
|
||||
rel = ext_sys.get('relationship', 'integrates with')
|
||||
diagram += f' Rel(system, {ext_id}, "{rel}")\n'
|
||||
|
||||
diagram += '```'
|
||||
return diagram
|
||||
|
||||
|
||||
def generate_c4_container(system_info: Dict[str, Any]) -> str:
|
||||
"""Generate C4 Level 2: Container diagram."""
|
||||
system_name = system_info.get('system_name', 'System')
|
||||
containers = system_info.get('containers', [])
|
||||
external_systems = system_info.get('external_systems', [])
|
||||
|
||||
diagram = f"""```mermaid
|
||||
C4Container
|
||||
title Container Diagram - {system_name}
|
||||
|
||||
Person(user, "User", "System user")
|
||||
|
||||
System_Boundary(system, "{system_name}") {{
|
||||
"""
|
||||
|
||||
# Add containers
|
||||
for container in containers:
|
||||
cont_id = container.get('id', 'container')
|
||||
cont_name = container.get('name', 'Container')
|
||||
cont_tech = container.get('technology', 'Technology')
|
||||
cont_desc = container.get('description', 'Container description')
|
||||
diagram += f' Container({cont_id}, "{cont_name}", "{cont_tech}", "{cont_desc}")\n'
|
||||
|
||||
diagram += ' }\n\n'
|
||||
|
||||
# Add external systems (simplified)
|
||||
for ext_sys in external_systems[:2]: # Limit to 2 for clarity
|
||||
ext_id = ext_sys.get('id', 'ext')
|
||||
ext_name = ext_sys.get('name', 'External System')
|
||||
ext_desc = ext_sys.get('description', 'External service')
|
||||
diagram += f' System_Ext({ext_id}, "{ext_name}", "{ext_desc}")\n'
|
||||
|
||||
diagram += '\n'
|
||||
|
||||
# Add relationships
|
||||
relationships = system_info.get('container_relationships', [])
|
||||
for rel in relationships:
|
||||
from_id = rel.get('from', '')
|
||||
to_id = rel.get('to', '')
|
||||
desc = rel.get('description', 'interacts')
|
||||
protocol = rel.get('protocol', '')
|
||||
if protocol:
|
||||
diagram += f' Rel({from_id}, {to_id}, "{desc} [{protocol}]")\n'
|
||||
else:
|
||||
diagram += f' Rel({from_id}, {to_id}, "{desc}")\n'
|
||||
|
||||
diagram += '```'
|
||||
return diagram
|
||||
|
||||
|
||||
def generate_c4_component(system_info: Dict[str, Any]) -> str:
|
||||
"""Generate C4 Level 3: Component diagram for main container."""
|
||||
container_name = system_info.get('main_container_name', 'API Service')
|
||||
components = system_info.get('components', [])
|
||||
|
||||
diagram = f"""```mermaid
|
||||
C4Component
|
||||
title Component Diagram - {container_name}
|
||||
|
||||
Container_Boundary(container, "{container_name}") {{
|
||||
"""
|
||||
|
||||
# Add components
|
||||
for comp in components:
|
||||
comp_id = comp.get('id', 'component')
|
||||
comp_name = comp.get('name', 'Component')
|
||||
comp_tech = comp.get('technology', 'Technology')
|
||||
comp_desc = comp.get('description', 'Component description')
|
||||
diagram += f' Component({comp_id}, "{comp_name}", "{comp_tech}", "{comp_desc}")\n'
|
||||
|
||||
diagram += ' }\n\n'
|
||||
|
||||
# Add external dependencies
|
||||
ext_deps = system_info.get('component_dependencies', [])
|
||||
for dep in ext_deps:
|
||||
dep_id = dep.get('id', 'dep')
|
||||
dep_name = dep.get('name', 'Dependency')
|
||||
dep_type = dep.get('type', 'Database')
|
||||
dep_tech = dep.get('technology', 'Technology')
|
||||
|
||||
if 'db' in dep_type.lower() or 'database' in dep_type.lower():
|
||||
diagram += f' ContainerDb({dep_id}, "{dep_name}", "{dep_tech}", "{dep_type}")\n'
|
||||
else:
|
||||
diagram += f' System_Ext({dep_id}, "{dep_name}", "{dep_type}")\n'
|
||||
|
||||
diagram += '\n'
|
||||
|
||||
# Add component relationships
|
||||
comp_rels = system_info.get('component_relationships', [])
|
||||
for rel in comp_rels:
|
||||
from_id = rel.get('from', '')
|
||||
to_id = rel.get('to', '')
|
||||
desc = rel.get('description', 'uses')
|
||||
diagram += f' Rel({from_id}, {to_id}, "{desc}")\n'
|
||||
|
||||
diagram += '```'
|
||||
return diagram
|
||||
|
||||
|
||||
def generate_data_flow(system_info: Dict[str, Any]) -> str:
|
||||
"""Generate Data Flow Diagram."""
|
||||
diagram = """```mermaid
|
||||
flowchart LR
|
||||
subgraph sources["📥 Data Sources"]
|
||||
"""
|
||||
|
||||
# Data sources
|
||||
data_sources = system_info.get('data_sources', [])
|
||||
for source in data_sources:
|
||||
source_id = source.get('id', 'source')
|
||||
source_name = source.get('name', 'Source')
|
||||
diagram += f' {source_id}["{source_name}"]\n'
|
||||
|
||||
diagram += ' end\n\n'
|
||||
diagram += ' subgraph processes["⚙️ Data Processing"]\n'
|
||||
|
||||
# Processing steps
|
||||
processes = system_info.get('data_processes', [])
|
||||
for process in processes:
|
||||
proc_id = process.get('id', 'process')
|
||||
proc_name = process.get('name', 'Process')
|
||||
diagram += f' {proc_id}["{proc_name}"]\n'
|
||||
|
||||
diagram += ' end\n\n'
|
||||
diagram += ' subgraph storage["💾 Data Storage"]\n'
|
||||
|
||||
# Storage
|
||||
storages = system_info.get('data_storage', [])
|
||||
for store in storages:
|
||||
store_id = store.get('id', 'store')
|
||||
store_name = store.get('name', 'Storage')
|
||||
store_tech = store.get('technology', '')
|
||||
if store_tech:
|
||||
diagram += f' {store_id}["{store_name}<br/>({store_tech})"]\n'
|
||||
else:
|
||||
diagram += f' {store_id}["{store_name}"]\n'
|
||||
|
||||
diagram += ' end\n\n'
|
||||
diagram += ' subgraph outputs["📤 Data Outputs"]\n'
|
||||
|
||||
# Outputs
|
||||
outputs = system_info.get('data_outputs', [])
|
||||
for output in outputs:
|
||||
out_id = output.get('id', 'output')
|
||||
out_name = output.get('name', 'Output')
|
||||
diagram += f' {out_id}["{out_name}"]\n'
|
||||
|
||||
diagram += ' end\n\n'
|
||||
|
||||
# Add flows
|
||||
flows = system_info.get('data_flows', [])
|
||||
for flow in flows:
|
||||
from_id = flow.get('from', '')
|
||||
to_id = flow.get('to', '')
|
||||
label = flow.get('label', 'data')
|
||||
diagram += f' {from_id} -->|"{label}"| {to_id}\n'
|
||||
|
||||
diagram += '```'
|
||||
return diagram
|
||||
|
||||
|
||||
def generate_deployment(system_info: Dict[str, Any]) -> str:
|
||||
"""Generate C4 Deployment diagram."""
|
||||
system_name = system_info.get('system_name', 'System')
|
||||
cloud_provider = system_info.get('cloud_provider', 'Cloud Provider')
|
||||
|
||||
diagram = f"""```mermaid
|
||||
C4Deployment
|
||||
title Deployment Diagram - {system_name}
|
||||
|
||||
"""
|
||||
|
||||
# Generate deployment nodes
|
||||
deployment_nodes = system_info.get('deployment_nodes', [])
|
||||
|
||||
for node in deployment_nodes:
|
||||
node_id = node.get('id', 'node')
|
||||
node_name = node.get('name', 'Node')
|
||||
node_tech = node.get('technology', 'Technology')
|
||||
containers = node.get('containers', [])
|
||||
nested_nodes = node.get('nested_nodes', [])
|
||||
|
||||
diagram += f' Deployment_Node({node_id}, "{node_name}", "{node_tech}") {{\n'
|
||||
|
||||
# Add nested nodes if any
|
||||
for nested in nested_nodes:
|
||||
nested_id = nested.get('id', 'nested')
|
||||
nested_name = nested.get('name', 'Node')
|
||||
nested_tech = nested.get('technology', 'Tech')
|
||||
nested_containers = nested.get('containers', [])
|
||||
|
||||
diagram += f' Deployment_Node({nested_id}, "{nested_name}", "{nested_tech}") {{\n'
|
||||
|
||||
for cont in nested_containers:
|
||||
cont_id = cont.get('id', 'cont')
|
||||
cont_name = cont.get('name', 'Container')
|
||||
cont_tech = cont.get('technology', 'Tech')
|
||||
cont_desc = cont.get('description', 'Description')
|
||||
|
||||
if 'db' in cont_name.lower() or 'database' in cont_name.lower():
|
||||
diagram += f' ContainerDb({cont_id}, "{cont_name}", "{cont_tech}", "{cont_desc}")\n'
|
||||
else:
|
||||
diagram += f' Container({cont_id}, "{cont_name}", "{cont_tech}", "{cont_desc}")\n'
|
||||
|
||||
diagram += ' }\n'
|
||||
|
||||
# Add direct containers
|
||||
for cont in containers:
|
||||
cont_id = cont.get('id', 'cont')
|
||||
cont_name = cont.get('name', 'Container')
|
||||
cont_tech = cont.get('technology', 'Tech')
|
||||
cont_desc = cont.get('description', 'Description')
|
||||
|
||||
if 'db' in cont_name.lower() or 'database' in cont_name.lower():
|
||||
diagram += f' ContainerDb({cont_id}, "{cont_name}", "{cont_tech}", "{cont_desc}")\n'
|
||||
else:
|
||||
diagram += f' Container({cont_id}, "{cont_name}", "{cont_tech}", "{cont_desc}")\n'
|
||||
|
||||
diagram += ' }\n\n'
|
||||
|
||||
# Add relationships
|
||||
deployment_rels = system_info.get('deployment_relationships', [])
|
||||
for rel in deployment_rels:
|
||||
from_id = rel.get('from', '')
|
||||
to_id = rel.get('to', '')
|
||||
desc = rel.get('description', 'connects')
|
||||
protocol = rel.get('protocol', '')
|
||||
|
||||
if protocol:
|
||||
diagram += f' Rel({from_id}, {to_id}, "{desc}", "{protocol}")\n'
|
||||
else:
|
||||
diagram += f' Rel({from_id}, {to_id}, "{desc}")\n'
|
||||
|
||||
diagram += '```'
|
||||
return diagram
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python generate_mermaid.py <config_json>")
|
||||
print("\nConfig JSON should contain system architecture information")
|
||||
sys.exit(1)
|
||||
|
||||
# Load configuration
|
||||
try:
|
||||
config = json.loads(sys.argv[1])
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error parsing JSON: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
# Generate all 5 diagrams
|
||||
diagrams = {
|
||||
'c4_context': generate_c4_context(config),
|
||||
'c4_container': generate_c4_container(config),
|
||||
'c4_component': generate_c4_component(config),
|
||||
'data_flow': generate_data_flow(config),
|
||||
'deployment': generate_deployment(config)
|
||||
}
|
||||
|
||||
# Output diagrams
|
||||
print("### Diagram 1: System Context (C4 Level 1)\n")
|
||||
print("**Description**: Shows the system in context with external users and systems\n")
|
||||
print(diagrams['c4_context'])
|
||||
print("\n---\n")
|
||||
|
||||
print("### Diagram 2: Container Diagram (C4 Level 2)\n")
|
||||
print("**Description**: Shows the main technical components and their relationships\n")
|
||||
print(diagrams['c4_container'])
|
||||
print("\n---\n")
|
||||
|
||||
print("### Diagram 3: Component Diagram (C4 Level 3)\n")
|
||||
print("**Description**: Shows internal components of the main container\n")
|
||||
print(diagrams['c4_component'])
|
||||
print("\n---\n")
|
||||
|
||||
print("### Diagram 4: Data Flow Diagram\n")
|
||||
print("**Description**: Shows how data moves through the system\n")
|
||||
print(diagrams['data_flow'])
|
||||
print("\n---\n")
|
||||
|
||||
print("### Diagram 5: Deployment Diagram\n")
|
||||
print("**Description**: Shows infrastructure and deployment topology\n")
|
||||
print(diagrams['deployment'])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
423
skills/scripts/generate_openapi.py
Normal file
423
skills/scripts/generate_openapi.py
Normal file
@@ -0,0 +1,423 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Generate OpenAPI 3.0 specification from architecture information.
|
||||
Creates a comprehensive API specification for the designed endpoints.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import json
|
||||
from typing import Dict, List, Any
|
||||
|
||||
|
||||
def generate_openapi_spec(api_info: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Generate OpenAPI 3.0 specification."""
|
||||
|
||||
system_name = api_info.get('system_name', 'API')
|
||||
version = api_info.get('version', '1.0.0')
|
||||
description = api_info.get('description', 'API for ' + system_name)
|
||||
base_url = api_info.get('base_url', 'https://api.example.com')
|
||||
|
||||
spec = {
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"title": f"{system_name} API",
|
||||
"description": description,
|
||||
"version": version,
|
||||
"contact": {
|
||||
"name": api_info.get('contact_name', 'API Team'),
|
||||
"email": api_info.get('contact_email', 'api@example.com')
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": base_url,
|
||||
"description": api_info.get('server_description', 'Production server')
|
||||
}
|
||||
],
|
||||
"paths": {},
|
||||
"components": {
|
||||
"schemas": {},
|
||||
"securitySchemes": {},
|
||||
"responses": {}
|
||||
},
|
||||
"tags": []
|
||||
}
|
||||
|
||||
# Add security schemes
|
||||
auth_type = api_info.get('authentication', 'bearer')
|
||||
if auth_type == 'bearer' or auth_type == 'jwt':
|
||||
spec['components']['securitySchemes']['bearerAuth'] = {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT"
|
||||
}
|
||||
spec['security'] = [{"bearerAuth": []}]
|
||||
elif auth_type == 'apikey':
|
||||
spec['components']['securitySchemes']['apiKey'] = {
|
||||
"type": "apiKey",
|
||||
"in": "header",
|
||||
"name": "X-API-Key"
|
||||
}
|
||||
spec['security'] = [{"apiKey": []}]
|
||||
|
||||
# Add common schemas
|
||||
spec['components']['schemas']['Error'] = {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error": {
|
||||
"type": "string",
|
||||
"description": "Error message"
|
||||
},
|
||||
"code": {
|
||||
"type": "string",
|
||||
"description": "Error code"
|
||||
}
|
||||
},
|
||||
"required": ["error"]
|
||||
}
|
||||
|
||||
# Add common responses
|
||||
spec['components']['responses']['UnauthorizedError'] = {
|
||||
"description": "Authentication information is missing or invalid",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
spec['components']['responses']['NotFoundError'] = {
|
||||
"description": "The specified resource was not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Add tags
|
||||
tags = api_info.get('tags', [])
|
||||
for tag in tags:
|
||||
spec['tags'].append({
|
||||
"name": tag.get('name', 'default'),
|
||||
"description": tag.get('description', '')
|
||||
})
|
||||
|
||||
# Add schemas
|
||||
schemas = api_info.get('schemas', {})
|
||||
for schema_name, schema_def in schemas.items():
|
||||
spec['components']['schemas'][schema_name] = schema_def
|
||||
|
||||
# Add endpoints
|
||||
endpoints = api_info.get('endpoints', [])
|
||||
for endpoint in endpoints:
|
||||
path = endpoint.get('path', '/')
|
||||
method = endpoint.get('method', 'get').lower()
|
||||
|
||||
if path not in spec['paths']:
|
||||
spec['paths'][path] = {}
|
||||
|
||||
operation = {
|
||||
"summary": endpoint.get('summary', ''),
|
||||
"description": endpoint.get('description', ''),
|
||||
"operationId": endpoint.get('operation_id', method + path.replace('/', '_')),
|
||||
"tags": endpoint.get('tags', ['default']),
|
||||
"responses": {}
|
||||
}
|
||||
|
||||
# Add parameters
|
||||
parameters = endpoint.get('parameters', [])
|
||||
if parameters:
|
||||
operation['parameters'] = parameters
|
||||
|
||||
# Add request body
|
||||
request_body = endpoint.get('request_body', None)
|
||||
if request_body:
|
||||
operation['requestBody'] = request_body
|
||||
|
||||
# Add responses
|
||||
responses = endpoint.get('responses', {})
|
||||
if responses:
|
||||
operation['responses'] = responses
|
||||
else:
|
||||
# Default responses
|
||||
operation['responses'] = {
|
||||
"200": {
|
||||
"description": "Successful operation",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"$ref": "#/components/responses/UnauthorizedError"
|
||||
},
|
||||
"404": {
|
||||
"$ref": "#/components/responses/NotFoundError"
|
||||
}
|
||||
}
|
||||
|
||||
spec['paths'][path][method] = operation
|
||||
|
||||
return spec
|
||||
|
||||
|
||||
def generate_default_crud_api(resource_name: str) -> Dict[str, Any]:
|
||||
"""Generate a default CRUD API specification for a resource."""
|
||||
|
||||
resource_lower = resource_name.lower()
|
||||
resource_title = resource_name.title()
|
||||
|
||||
api_info = {
|
||||
"system_name": f"{resource_title} Management",
|
||||
"version": "1.0.0",
|
||||
"description": f"API for managing {resource_lower} resources",
|
||||
"base_url": "https://api.example.com/v1",
|
||||
"authentication": "bearer",
|
||||
"tags": [
|
||||
{
|
||||
"name": resource_lower,
|
||||
"description": f"{resource_title} operations"
|
||||
}
|
||||
],
|
||||
"schemas": {
|
||||
resource_title: {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"format": "uuid",
|
||||
"description": f"{resource_title} ID"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": f"{resource_title} name"
|
||||
},
|
||||
"createdAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Creation timestamp"
|
||||
},
|
||||
"updatedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Last update timestamp"
|
||||
}
|
||||
},
|
||||
"required": ["id", "name"]
|
||||
},
|
||||
f"{resource_title}Input": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": f"{resource_title} name"
|
||||
}
|
||||
},
|
||||
"required": ["name"]
|
||||
}
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"path": f"/{resource_lower}s",
|
||||
"method": "get",
|
||||
"summary": f"List all {resource_lower}s",
|
||||
"description": f"Retrieve a list of {resource_lower}s with pagination",
|
||||
"operation_id": f"list{resource_title}s",
|
||||
"tags": [resource_lower],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "page",
|
||||
"in": "query",
|
||||
"description": "Page number",
|
||||
"schema": {"type": "integer", "default": 1}
|
||||
},
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"description": "Items per page",
|
||||
"schema": {"type": "integer", "default": 20}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful operation",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": f"#/components/schemas/{resource_title}"
|
||||
}
|
||||
},
|
||||
"total": {"type": "integer"},
|
||||
"page": {"type": "integer"},
|
||||
"limit": {"type": "integer"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": f"/{resource_lower}s",
|
||||
"method": "post",
|
||||
"summary": f"Create a new {resource_lower}",
|
||||
"description": f"Create a new {resource_lower} resource",
|
||||
"operation_id": f"create{resource_title}",
|
||||
"tags": [resource_lower],
|
||||
"request_body": {
|
||||
"required": True,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": f"#/components/schemas/{resource_title}Input"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created successfully",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": f"#/components/schemas/{resource_title}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": f"/{resource_lower}s/{{id}}",
|
||||
"method": "get",
|
||||
"summary": f"Get a {resource_lower} by ID",
|
||||
"description": f"Retrieve a specific {resource_lower} by its ID",
|
||||
"operation_id": f"get{resource_title}",
|
||||
"tags": [resource_lower],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": True,
|
||||
"description": f"{resource_title} ID",
|
||||
"schema": {"type": "string", "format": "uuid"}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful operation",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": f"#/components/schemas/{resource_title}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": f"/{resource_lower}s/{{id}}",
|
||||
"method": "put",
|
||||
"summary": f"Update a {resource_lower}",
|
||||
"description": f"Update an existing {resource_lower} resource",
|
||||
"operation_id": f"update{resource_title}",
|
||||
"tags": [resource_lower],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": True,
|
||||
"description": f"{resource_title} ID",
|
||||
"schema": {"type": "string", "format": "uuid"}
|
||||
}
|
||||
],
|
||||
"request_body": {
|
||||
"required": True,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": f"#/components/schemas/{resource_title}Input"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Updated successfully",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": f"#/components/schemas/{resource_title}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": f"/{resource_lower}s/{{id}}",
|
||||
"method": "delete",
|
||||
"summary": f"Delete a {resource_lower}",
|
||||
"description": f"Delete a {resource_lower} resource",
|
||||
"operation_id": f"delete{resource_title}",
|
||||
"tags": [resource_lower],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": True,
|
||||
"description": f"{resource_title} ID",
|
||||
"schema": {"type": "string", "format": "uuid"}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "Deleted successfully"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
return generate_openapi_spec(api_info)
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python generate_openapi.py <config_json|resource_name>")
|
||||
print("\nExamples:")
|
||||
print(" python generate_openapi.py 'User' # Generate default CRUD API")
|
||||
print(" python generate_openapi.py '{...}' # Generate from JSON config")
|
||||
sys.exit(1)
|
||||
|
||||
input_data = sys.argv[1]
|
||||
|
||||
# Try to parse as JSON first
|
||||
try:
|
||||
config = json.loads(input_data)
|
||||
spec = generate_openapi_spec(config)
|
||||
except json.JSONDecodeError:
|
||||
# Treat as resource name for default CRUD API
|
||||
spec = generate_default_crud_api(input_data)
|
||||
|
||||
# Output OpenAPI spec
|
||||
print(json.dumps(spec, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
126
skills/scripts/validate_architecture.py
Normal file
126
skills/scripts/validate_architecture.py
Normal file
@@ -0,0 +1,126 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Validate ARCHITECTURE.md for completeness and consistency.
|
||||
Checks that all required sections are present and have content.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
# Required sections in ARCHITECTURE.md
|
||||
REQUIRED_SECTIONS = [
|
||||
"1. Project Structure",
|
||||
"2. High-Level System Diagram",
|
||||
"3. Core Components",
|
||||
"4. Data Stores",
|
||||
"5. External Integrations / APIs",
|
||||
"6. Deployment & Infrastructure",
|
||||
"7. Security Considerations",
|
||||
"8. Development & Testing Environment",
|
||||
"9. Future Considerations / Roadmap",
|
||||
"10. Project Identification",
|
||||
"11. Glossary / Acronyms"
|
||||
]
|
||||
|
||||
|
||||
def validate_architecture(file_path):
|
||||
"""Validate ARCHITECTURE.md file."""
|
||||
|
||||
if not Path(file_path).exists():
|
||||
return False, [f"File not found: {file_path}"]
|
||||
|
||||
with open(file_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
|
||||
issues = []
|
||||
warnings = []
|
||||
|
||||
# Check for required sections
|
||||
missing_sections = []
|
||||
for section in REQUIRED_SECTIONS:
|
||||
# Create regex pattern that matches section headings
|
||||
pattern = re.compile(rf'^##\s+{re.escape(section)}', re.MULTILINE)
|
||||
if not pattern.search(content):
|
||||
missing_sections.append(section)
|
||||
|
||||
if missing_sections:
|
||||
issues.append(f"Missing required sections: {', '.join(missing_sections)}")
|
||||
|
||||
# Check if sections have content (not just placeholders)
|
||||
empty_sections = []
|
||||
lines = content.split('\n')
|
||||
current_section = None
|
||||
section_content = []
|
||||
|
||||
for line in lines:
|
||||
if line.startswith('## '):
|
||||
# Save previous section
|
||||
if current_section and len(section_content) < 3:
|
||||
# Section has fewer than 3 lines of content
|
||||
if not any('[' in l or 'TODO' in l.upper() for l in section_content):
|
||||
empty_sections.append(current_section)
|
||||
# Start new section
|
||||
current_section = line.strip('# ').strip()
|
||||
section_content = []
|
||||
elif line.strip() and not line.startswith('#'):
|
||||
section_content.append(line)
|
||||
|
||||
# Check last section
|
||||
if current_section and len(section_content) < 3:
|
||||
if not any('[' in l or 'TODO' in l.upper() for l in section_content):
|
||||
empty_sections.append(current_section)
|
||||
|
||||
if empty_sections:
|
||||
warnings.append(f"Sections with minimal content: {', '.join(empty_sections[:3])}")
|
||||
|
||||
# Check for placeholder text
|
||||
placeholders = ['[TODO]', '[FILL IN]', '[INSERT', '[e.g.,']
|
||||
placeholder_count = sum(content.count(p) for p in placeholders)
|
||||
if placeholder_count > 10:
|
||||
warnings.append(f"Found {placeholder_count} placeholders - consider filling them in")
|
||||
|
||||
# Check for Project Identification fields
|
||||
required_fields = ['Project Name:', 'Repository URL:', 'Primary Contact', 'Date of Last Update:']
|
||||
missing_fields = []
|
||||
for field in required_fields:
|
||||
if field not in content:
|
||||
missing_fields.append(field)
|
||||
|
||||
if missing_fields:
|
||||
warnings.append(f"Missing project identification fields: {', '.join(missing_fields)}")
|
||||
|
||||
# Report results
|
||||
if issues:
|
||||
return False, issues
|
||||
|
||||
return True, warnings
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python validate_architecture.py <path-to-ARCHITECTURE.md>")
|
||||
sys.exit(1)
|
||||
|
||||
file_path = sys.argv[1]
|
||||
valid, messages = validate_architecture(file_path)
|
||||
|
||||
if valid:
|
||||
print("✅ ARCHITECTURE.md validation PASSED")
|
||||
if messages:
|
||||
print("\n⚠️ Warnings:")
|
||||
for msg in messages:
|
||||
print(f" - {msg}")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print("❌ ARCHITECTURE.md validation FAILED")
|
||||
print("\n❌ Issues:")
|
||||
for msg in messages:
|
||||
print(f" - {msg}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user