Initial commit

2025-11-29 18:17:07 +08:00
commit c0cd55ad8d
55 changed files with 15836 additions and 0 deletions
--- a/skills/c4model-c2/SKILL.md
+++ b/skills/c4model-c2/SKILL.md
@@ -0,0 +1,409 @@
+---
+name: c4model-c2
+description: Use when identifying deployable units within C1-identified systems, detecting technology stacks with versions, or documenting container communication patterns - provides C4 Model Level 2 methodology for container identification, type classification (spa, api, database, cache, worker, etc.), and runtime environment analysis
+---
+
+# C4 Model - Level 2: Container Methodology
+
+## Navigation
+
+**Core Methodology:**
+- **[Methodology](./methodology.md)** - Step-by-step container identification process
+- **[Output Format](./output-format.md)** - JSON schema and validation commands
+
+**Reference Materials:**
+- **[Technology Detection Patterns](./technology-detection-patterns.md)** - Comprehensive guide to detecting frameworks, languages, and tooling
+- **[Container Types Reference](./container-types-reference.md)** - Complete reference for all 10 container types with examples
+- **[Communication Patterns](./communication-patterns.md)** - How containers communicate (HTTP, gRPC, queues, databases)
+- **[Common Container Patterns](./common-container-patterns.md)** - Reusable architecture patterns (SPA+API+DB, microservices, serverless)
+- **[Observation Categories](./observation-categories-c2.md)** - 8 observation categories with examples
+- **[Troubleshooting Guide](./troubleshooting-guide-c2.md)** - Solutions to common problems
+
+---
+
+## Overview
+
+You are an expert in the C4 Model's Level 2 (Container) methodology. This skill provides comprehensive knowledge for identifying and documenting containers (deployable/runnable units) at the second level of architectural abstraction.
+
+**Your Mission:** Help identify WHAT deployable units exist within each system, WHAT technologies they use, and HOW they communicate - focusing on the building blocks that get deployed to production.
+
+**C2 Container Level Definition:**
+A container represents an application or data store that executes code or stores data. It's something that needs to be running for the overall system to work. Think: web servers, application servers, standalone applications, databases, file systems, message brokers.
+
+**Relationship to Other Levels:**
+- **C1 (System Context)** - Identified high-level systems → Now we decompose each system into containers
+- **C2 (Container) - YOU ARE HERE** - Identify deployable/runnable units within each system
+- **C3 (Component)** - Will identify code modules within each container (next level)
+
+**Common Questions This Skill Answers:**
+- "What deployable units exist in this system?"
+- "What frameworks/technologies are used?"
+- "How does the frontend communicate with the backend?"
+- "Is this application containerized/dockerized?"
+- "What database does this system use?"
+
+**Error Symptoms That Indicate C2 Issues:**
+- "missing technology.framework" - Container definition incomplete
+- "version not specified" - Forgot to extract from manifest
+- "container not found" - Reference to undefined container
+- "too many containers" - Over-decomposed at C3 level
+- "validation failed: primary_language" - Missing required field
+
+---
+
+## C2 Level Definition
+
+### What is a Container (C2)?
+
+A **container** at C2 level is a deployable/runnable unit:
+
+- **Deployable Unit** - Can be deployed independently (even if part of a larger system)
+- **Runs Code or Stores Data** - Executes application logic or persists information
+- **Has Technology Stack** - Built with specific languages, frameworks, libraries
+- **Has Runtime Environment** - Runs in browser, server, cloud, mobile device
+- **Communicates via Protocols** - HTTP, gRPC, database connections, message queues
+
+**Important:** Container in C4 Model ≠ Docker container
+- C4 "container" = deployable/runnable unit (broader concept)
+- Docker container is one possible deployment technology
+
+### Abstraction Level
+
+```
+┌─────────────────────────────────────────────┐
+│ C1: System Context                          │
+│ "What systems exist?"                       │
+├─────────────────────────────────────────────┤
+│ C2: Container Level                         │ ← YOU ARE HERE
+│ "What are the deployable units?"            │
+├─────────────────────────────────────────────┤
+│ C3: Component Level                         │
+│ "What are the code modules?"                │
+├─────────────────────────────────────────────┤
+│ C4: Code Level                              │
+│ "What are the classes/functions?"           │
+└─────────────────────────────────────────────┘
+```
+
+**At C2, we focus on:**
+- ✅ Deployable/runnable units (what gets deployed)
+- ✅ Technology stack (languages, frameworks, versions)
+- ✅ Runtime environment (browser, server, cloud, mobile)
+- ✅ Communication protocols (HTTP, gRPC, database, messaging)
+- ✅ Deployment model (containerized, serverless, standalone)
+
+**At C2, we do NOT focus on:**
+- ❌ Code structure (that's C3 Component level)
+- ❌ Classes and functions (that's C4 Code level)
+- ❌ System boundaries (that was C1 System level)
+- ❌ Line-by-line code analysis
+
+---
+
+## Container Identification Methodology
+
+> **Full methodology details:** See [Methodology](./methodology.md) for complete step-by-step process.
+
+### Is This a Container? Decision Tree
+
+```
+                    ┌─────────────────────┐
+                    │ Can it be deployed  │
+                    │   independently?    │
+                    └─────────┬───────────┘
+                              │
+                    ┌─────────┴─────────┐
+                   YES                  NO
+                    │                    │
+        ┌───────────┴────────┐     ┌─────┴─────┐
+        │ Does it run code   │     │  NOT a    │
+        │  or store data?    │     │ Container │
+        └─────────┬──────────┘     │ (maybe C3)│
+                  │                └───────────┘
+        ┌─────────┴─────────┐
+       YES                  NO
+        │                    │
+  ┌─────┴──────┐       ┌─────┴─────┐
+  │ Has own    │       │  NOT a    │
+  │ tech stack │       │ Container │
+  │ w/version? │       └───────────┘
+  └─────┬──────┘
+        │
+  ┌─────┴─────────┐
+ YES              NO
+  │                │
+┌─┴──────────┐  ┌──┴───────────┐
+│ CONTAINER! │  │ Add version  │
+│ Document   │  │ from manifest│
+│ in C2      │  │ then continue│
+└────────────┘  └──────────────┘
+```
+
+### Quick Summary
+
+**5 Steps:**
+1. **Understand System Decomposition** - Review c1-systems.json
+2. **Apply Container Identification Rules** - IS vs is NOT
+3. **Analyze Repository Structure** - Find deployment indicators
+4. **Detect Technology Stack** - Language, framework, versions
+5. **Identify Runtime Environment** - browser/server/mobile/cloud
+
+### Critical Rules
+
+**A Container IS:**
+- Deployable independently
+- Executes code OR stores data
+- Has distinct technology stack with versions
+- Has runtime environment
+- Communicates via defined protocols
+
+**A Container is NOT:**
+- Code modules (that's C3)
+- Config files or dev tools
+- Generic names without versions ("React SPA" → "React 18.2.0 SPA")
+
+**MANDATORY:** Extract versions from manifest files (package.json, requirements.txt, pom.xml, etc.). This is NOT optional.
+
+---
+
+## Container Types Quick Reference
+
+**10 Container Types:**
+
+1. **spa** - Single-Page Application (browser)
+2. **mobile-app** - iOS/Android application
+3. **desktop-app** - Desktop application
+4. **api** / **app-server** - Backend API server
+5. **web-server** - Web server, reverse proxy
+6. **database** - Relational or NoSQL database
+7. **cache** - In-memory cache (Redis, Memcached)
+8. **message-broker** - Message queue/event streaming
+9. **worker** - Background job processor
+10. **file-storage** - Object storage, file system
+
+> **See [Container Types Reference](./container-types-reference.md) for detailed examples of all 10 types.**
+
+---
+
+## Communication Pattern Identification
+
+### Identify Relationships Between Containers
+
+Document how containers communicate using these patterns:
+
+**Synchronous:**
+- **http-rest** - RESTful HTTP API
+- **http-graphql** - GraphQL API
+- **grpc** - gRPC remote procedure calls
+- **websocket** - WebSocket bidirectional communication
+
+**Asynchronous:**
+- **message-publish** - Publish to queue/topic
+- **message-subscribe** - Subscribe to queue/topic
+
+**Data Access:**
+- **database-query** - Database read/write
+- **cache-read-write** - Cache read and write
+- **file-storage-access** - File upload/download
+
+> **See [Communication Patterns](./communication-patterns.md) for complete patterns guide.**
+
+### Detection Commands
+
+```bash
+# Find HTTP clients
+grep -r "axios\|fetch\|requests" src/
+
+# Find database connections
+grep -r "DATABASE_URL\|DB_HOST" .env
+
+# Find message brokers
+grep -r "amqplib\|kafkajs\|redis.*publish" src/
+```
+
+---
+
+## Observation Categories
+
+When documenting containers, capture these 8 observation categories:
+
+1. **technology** - Technology stack, frameworks, libraries, versions
+2. **runtime** - Runtime environment, platform, deployment model
+3. **communication** - How container communicates with others
+4. **data-storage** - Data persistence, caching, storage patterns
+5. **authentication** - Authentication and authorization mechanisms
+6. **configuration** - Configuration management, environment variables
+7. **monitoring** - Logging, monitoring, observability
+8. **dependencies** - External dependencies, third-party services
+
+**Severity Levels:**
+- **info** - Informational observation (neutral)
+- **warning** - Potential issue requiring attention
+- **critical** - Critical issue requiring immediate action
+
+> **See [Observation Categories](./observation-categories-c2.md) for detailed guidelines and examples.**
+
+---
+
+## Workflow Integration
+
+### When This Skill is Used
+
+This skill is activated during:
+
+1. **Phase 3: C2 Container Identification** (`/melly-c2-containers`)
+   - Primary usage phase
+   - Container identification per system
+   - Technology stack detection
+
+2. **Manual Container Analysis**
+   - User asks "what containers exist?"
+   - User asks "what is the technology stack?"
+   - User mentions keywords: "deployable units", "runtime environment", "containerization"
+
+### Input Requirements
+
+**Required Files:**
+- `c1-systems.json` - Must exist with identified systems
+- Repository access - Must be able to read system repositories
+
+**Required Information:**
+- System ID to analyze
+- Repository paths
+- System type and technologies (from C1)
+
+### Output Format
+
+> **See [Output Format](./output-format.md) for complete JSON schema and validation commands.**
+
+Generate `c2-containers.json` with container definitions including id, name, type, system_id, technology (with versions), runtime, relations, and observations.
+
+---
+
+## Best Practices
+
+### DO:
+
+1. **Start with C1 understanding** - Review c1-systems.json first
+2. **Focus on deployment boundary** - What can be deployed separately?
+3. **Be specific with technology** - Include versions (React 18, not just React)
+4. **Document runtime precisely** - Exact platform and containerization details
+5. **Capture all communication** - Document how containers interact
+6. **Use proper container types** - Choose from 10 defined types
+7. **Provide evidence** - Link observations to files/commands
+8. **Validate early** - Run validation scripts frequently
+
+### DON'T:
+
+1. **Don't confuse C2 with C3** - Components are code modules, not containers
+2. **Don't be too granular** - 20+ containers likely means you're at C3 level
+3. **Don't use generic names** - "Frontend" → "React SPA"
+4. **Don't skip infrastructure** - Document databases, caches, brokers
+5. **Don't guess** - Only document what you can verify
+6. **Don't ignore validation** - Always validate before proceeding
+
+### Common Rationalizations (Red Flags)
+
+If you catch yourself thinking these, STOP - you're about to make a mistake:
+
+| Rationalization | Reality |
+|-----------------|---------|
+| "This module deserves its own container" | Modules within an app are C3 Components, not C2 Containers. Can it be deployed separately? |
+| "I'll add the version later" | Versions are MANDATORY. Read package.json/requirements.txt NOW. No version = invalid container. |
+| "The exact version doesn't matter" | It does. "React 18" ≠ "React 18.2.0". Extract full semantic version from manifest. |
+| "Generic versions (18.x) show appropriate uncertainty" | WRONG. "18.x" is not a version - it's an excuse. Extract exact version from manifest. |
+| "Architecture matters more than versions" | Both matter equally. C2 requires technology stack WITH versions. No shortcuts. |
+| "Version precision is not the decision point" | WRONG. Version precision IS required for valid C2 documentation. It's not optional. |
+| "This is obviously a container" | Verify deployment boundary. If it can't be deployed independently, it's not a container. |
+| "I'll group these APIs into separate containers" | One API server with multiple endpoints = one container. Don't over-decompose. |
+| "Reading package.json is too detailed for C2" | WRONG. Technology detection from manifests IS C2. Line-by-line code analysis is C3. |
+| "Infrastructure doesn't need technology fields" | ALL containers need ALL fields. Use "N/A" for primary_language on databases/caches. |
+| "I can skip the runtime environment" | Runtime is essential. browser/server/mobile/cloud determines how container operates. |
+
+**All of these mean: Go back, verify your work, follow the methodology.**
+
+---
+
+## Quick Reference Checklist
+
+### Container Identification Checklist
+
+- [ ] Review C1 systems from c1-systems.json
+- [ ] Identify deployable units per system
+- [ ] Verify deployment boundary (can it be deployed separately?)
+- [ ] Detect primary language and framework
+- [ ] Identify runtime environment and platform
+- [ ] Document communication patterns
+- [ ] Capture observations (8 categories)
+- [ ] Validate with melly-validation scripts
+
+### Required Fields Checklist
+
+- [ ] `id` - Unique container identifier
+- [ ] `name` - Descriptive container name with technology and version
+- [ ] `type` - One of 10 container types
+- [ ] `system_id` - Reference to C1 system
+- [ ] `technology.primary_language` - JavaScript, Python, etc. (or "N/A" for infrastructure)
+- [ ] `technology.framework` - React 18.2.0, Express 4.18.2, etc. (with full version)
+- [ ] `runtime.environment` - browser, server, mobile, cloud
+- [ ] `runtime.platform` - Exact platform details
+- [ ] `runtime.containerized` - true/false
+- [ ] `relations[]` - Communication with other containers
+
+### Required Fields Matrix by Container Type
+
+**APPLICATION CONTAINERS** (spa, mobile-app, desktop-app, api, app-server, worker):
+
+| Field | Required | Format | Example |
+|-------|----------|--------|---------|
+| `technology.primary_language` | **REQUIRED** | Actual language | "TypeScript", "Python", "Java" |
+| `technology.framework` | **REQUIRED** | Name + Full Version | "React 18.2.0", "FastAPI 0.104.1" |
+| `technology.libraries` | **REQUIRED** | Array with versions | `[{"name": "Redux", "version": "4.2.1"}]` |
+
+**INFRASTRUCTURE CONTAINERS** (database, cache, message-broker, web-server, file-storage):
+
+| Field | Required | Format | Example |
+|-------|----------|--------|---------|
+| `technology.primary_language` | **REQUIRED** | Always "N/A" | "N/A" |
+| `technology.framework` | **REQUIRED** | Tool + Full Version | "PostgreSQL 15.4", "Redis 7.2.3" |
+| `technology.libraries` | OPTIONAL | Usually empty | `[]` |
+
+**RULE:** ALL containers MUST have ALL technology fields filled. Use "N/A" for infrastructure containers' primary_language, but NEVER leave fields empty or undefined.
+
+**Version Format:** Always use semantic versioning: `<Major>.<Minor>.<Patch>`
+- ✅ "React 18.2.0"
+- ✅ "PostgreSQL 15.4.0"
+- ❌ "React 18" (missing minor.patch)
+- ❌ "Express" (missing version entirely)
+
+---
+
+## Summary
+
+**C2 Container Level focuses on:**
+
+1. **WHAT deployable units exist** - Identify containers within each system
+2. **WHAT technologies are used** - Detect languages, frameworks, versions
+3. **WHERE containers run** - Identify runtime environments and platforms
+4. **HOW containers communicate** - Document protocols and patterns
+
+**Key Outputs:**
+- `c2-containers.json` - Complete container inventory
+- Observations per container (8 categories)
+- Communication patterns documented
+- Technology stack validated
+
+**Next Steps:**
+After completing C2 analysis:
+1. Validate with `validate-c2-containers.py`
+2. Review observations for warnings/critical issues
+3. Proceed to C3 (Component) level analysis
+4. Generate documentation with `/melly-doc-c4model`
+
+**For detailed guidance, see the supporting documentation:**
+- [Technology Detection Patterns](./technology-detection-patterns.md)
+- [Container Types Reference](./container-types-reference.md)
+- [Communication Patterns](./communication-patterns.md)
+- [Common Container Patterns](./common-container-patterns.md)
+- [Observation Categories](./observation-categories-c2.md)
+- [Troubleshooting Guide](./troubleshooting-guide-c2.md)