gh-cubical6-melly/skills/c4model-c2/SKILL.md

name, description

name	description
c4model-c2	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 - Step-by-step container identification process
• Output Format - JSON schema and validation commands

Reference Materials:

• Technology Detection Patterns - Comprehensive guide to detecting frameworks, languages, and tooling
• Container Types Reference - Complete reference for all 10 container types with examples
• Communication Patterns - How containers communicate (HTTP, gRPC, queues, databases)
• Common Container Patterns - Reusable architecture patterns (SPA+API+DB, microservices, serverless)
• Observation Categories - 8 observation categories with examples
• Troubleshooting Guide - 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 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 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 for complete patterns guide.

Detection Commands

# 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 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 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
• Container Types Reference
• Communication Patterns
• Common Container Patterns
• Observation Categories
• Troubleshooting Guide