Migrate

2026-05-23 18:37:02 +07:00
parent f15d91ee29
commit 76d75c753b
3993 changed files with 403 additions and 0 deletions
--- a/microservices/.agent/skills/documentation/references/DIAGRAMS.md
+++ b/microservices/.agent/skills/documentation/references/DIAGRAMS.md
@@ -0,0 +1,109 @@
+# Diagrams & Visuals / Sơ Đồ & Hình Ảnh
+
+This reference provides detailed guidelines for creating and managing visual content in documentation.
+
+## When to Use Diagrams
+
+| Diagram Type | Use Case | Mermaid Type |
+|--------------|----------|--------------|
+| **Architecture** | High-level system overview, service dependencies | `graph TB` |
+| **Sequence** | Request/response flows, async processes, integrations | `sequenceDiagram` |
+| **ER Diagram** | Database schema, table relationships | `erDiagram` |
+| **State** | Status transitions (Order, Campaign, Payment) | `stateDiagram-v2` |
+| **Class** | Domain model, entity relationships | `classDiagram` |
+| **Flowchart** | Decision trees, business logic flows | `flowchart TD` |
+
+## Mermaid Dark Palette (MANDATORY)
+
+**CRITICAL**: Always use the dark color palette from [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md).
+
+**Standard Colors:**
+- **Primary (Blue)**: `#3498DB` - Main components, API layer
+- **Secondary (Purple)**: `#8E44AD` - Application layer, handlers
+- **Accent (Orange)**: `#E67E22` - Domain layer, business logic
+- **Neutral (Dark Gray)**: `#34495E` - Databases, infrastructure
+- **Success (Green)**: `#27AE60` - Success states
+- **Warning (Yellow)**: `#F39C12` - Warning states
+- **Danger (Red)**: `#E74C3C` - Error states
+
+**Example:**
+```mermaid
+graph TB
+    API[API Layer]
+    APP[Application]
+    DOMAIN[Domain]
+    DB[(Database)]
+    
+    API --> APP
+    APP --> DOMAIN
+    APP --> DB
+    
+    style API fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98
+    style APP fill:#3498DB,color:#ECF0F1,stroke:#2980B9
+    style DOMAIN fill:#E67E22,color:#ECF0F1,stroke:#D35400
+    style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50
+```
+
+## Screenshot Guidelines
+
+### File Naming
+
+- ✅ Descriptive: `auth-flow-login-screen.png`
+- ❌ Generic: `screenshot1.png`, `image.png`
+
+### File Organization
+
+```
+docs/
+├── en/
+│   ├── images/
+│   │   ├── architecture/
+│   │   ├── screenshots/
+│   │   └── diagrams/
+│   └── README.md
+└── vi/
+    ├── images/          # Mirror EN structure
+    └── README.md
+```
+
+### File Format
+
+- **PNG**: UI screenshots, diagrams with transparency
+- **JPG**: Photos, images without transparency
+- **SVG**: Vector graphics, logos (when possible)
+- **WebP**: Modern format for smaller file sizes
+
+### Optimization
+
+```bash
+# Optimize PNG files
+pngquant --quality 65-80 docs/en/images/*.png
+
+# Optimize JPG files
+jpegoptim --max=85 docs/en/images/*.jpg
+
+# Convert to WebP
+cwebp -q 80 input.png -o output.webp
+```
+
+### Embedding in Markdown
+
+```markdown
+# ✅ GOOD: With descriptive caption and alt text
+![Login flow showing email input, password field, and social login options](images/auth-flow-login.png)
+
+# ❌ BAD: No context
+![Screenshot](screenshot.png)
+```
+
+### Responsive Images
+
+```markdown
+<img src="images/large-diagram.png" alt="System Architecture" width="800">
+```
+
+## Resources
+
+- [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md) - MANDATORY for all diagrams
+- [Mermaid Live Editor](https://mermaid.live/) - Test Mermaid diagrams
+- [Back to Documentation Skill](../SKILL.md)