410 lines
18 KiB
Markdown
410 lines
18 KiB
Markdown
---
|
|
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)
|