Initial commit
This commit is contained in:
Zhongwei Li
409
skills/c4model-c2/SKILL.md
Normal file
409
skills/c4model-c2/SKILL.md
Normal file
@@ -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)
|
||||
524
skills/c4model-c2/common-container-patterns.md
Normal file
524
skills/c4model-c2/common-container-patterns.md
Normal file
@@ -0,0 +1,524 @@
|
||||
# Common Container Patterns
|
||||
|
||||
This document provides reusable architecture patterns for C4 Model Level 2 (Container) analysis with detailed examples.
|
||||
|
||||
## Pattern 1: Simple SPA + API + Database
|
||||
|
||||
**Scenario:** Basic web application with frontend, backend, and database
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **Frontend SPA Container**
|
||||
- Type: `spa`
|
||||
- Technology: React 18 + TypeScript
|
||||
- Runtime: Browser
|
||||
- Communicates with API via HTTP REST
|
||||
|
||||
2. **Backend API Container**
|
||||
- Type: `api`
|
||||
- Technology: Express.js + Node.js 18
|
||||
- Runtime: Server (Node.js)
|
||||
- Communicates with database via PostgreSQL protocol
|
||||
|
||||
3. **PostgreSQL Database Container**
|
||||
- Type: `database`
|
||||
- Technology: PostgreSQL 15
|
||||
- Runtime: Server (Docker)
|
||||
- Stores application data
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ Browser │
|
||||
│ ┌────────────┐ │
|
||||
│ │ React SPA │ │
|
||||
│ └──────┬─────┘ │
|
||||
└─────────┼────────┘
|
||||
│ HTTP REST
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Server │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Express API│ │
|
||||
│ └──────┬─────┘ │
|
||||
└─────────┼───────┘
|
||||
│ SQL
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ ┌────────────┐ │
|
||||
│ │PostgreSQL │ │
|
||||
│ │ Database │ │
|
||||
│ └────────────┘ │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect pattern
|
||||
find . -name "package.json" | grep -E "(frontend|client|web)"
|
||||
find . -name "package.json" | grep -E "(backend|server|api)"
|
||||
find . -name "docker-compose.yml" | xargs grep postgres
|
||||
|
||||
# Verify frontend
|
||||
cat frontend/package.json | jq '.dependencies | keys | .[]' | grep -E "react|vue|angular"
|
||||
|
||||
# Verify backend
|
||||
cat backend/package.json | jq '.dependencies | keys | .[]' | grep -E "express|fastify|nestjs"
|
||||
|
||||
# Verify database
|
||||
docker-compose config | grep postgres
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Microservices with API Gateway
|
||||
|
||||
**Scenario:** Multiple microservices behind API gateway
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **API Gateway Container**
|
||||
- Type: `web-server`
|
||||
- Technology: Nginx or Kong
|
||||
- Runtime: Server
|
||||
- Routes requests to services
|
||||
|
||||
2. **Auth Service Container**
|
||||
- Type: `api`
|
||||
- Technology: NestJS
|
||||
- Runtime: Server (Node.js in Docker)
|
||||
- Handles authentication
|
||||
|
||||
3. **User Service Container**
|
||||
- Type: `api`
|
||||
- Technology: Spring Boot
|
||||
- Runtime: Server (JVM in Docker)
|
||||
- Manages user data
|
||||
|
||||
4. **Order Service Container**
|
||||
- Type: `api`
|
||||
- Technology: FastAPI
|
||||
- Runtime: Server (Python in Docker)
|
||||
- Processes orders
|
||||
|
||||
5. **Message Broker Container**
|
||||
- Type: `message-broker`
|
||||
- Technology: RabbitMQ
|
||||
- Runtime: Server (Docker)
|
||||
- Event bus
|
||||
|
||||
6. **Per-Service Databases**
|
||||
- Each service has its own database container
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌──────────────┐
|
||||
│ API Gateway │
|
||||
└──────┬───────┘
|
||||
│ HTTP
|
||||
┌───┴────┬────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────┐ ┌──────┐ ┌───────┐
|
||||
│Auth │ │User │ │Order │
|
||||
│Svc │ │Svc │ │Svc │
|
||||
└──┬──┘ └──┬───┘ └───┬───┘
|
||||
│ │ │
|
||||
└───────┴────┬────┘
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│RabbitMQ │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect microservices pattern
|
||||
find . -type d -name "*-service" -o -name "*-api"
|
||||
ls services/ | wc -l # Count service directories
|
||||
|
||||
# Find API gateway
|
||||
grep -r "nginx\|kong\|traefik" docker-compose.yml k8s/
|
||||
|
||||
# Find message broker
|
||||
grep -r "rabbitmq\|kafka" docker-compose.yml k8s/
|
||||
|
||||
# Count services
|
||||
find services/ -name "package.json" -o -name "pom.xml" -o -name "requirements.txt" | wc -l
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Serverless Architecture
|
||||
|
||||
**Scenario:** Serverless functions with managed services
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **Frontend SPA Container**
|
||||
- Type: `spa`
|
||||
- Deployed to: CloudFront + S3
|
||||
- Technology: React
|
||||
- Runtime: Browser
|
||||
|
||||
2. **API Lambda Functions Container(s)**
|
||||
- Type: `api`
|
||||
- Multiple functions or single function
|
||||
- Technology: Node.js Lambda handlers
|
||||
- Runtime: AWS Lambda (serverless)
|
||||
|
||||
3. **DynamoDB Database**
|
||||
- Type: `database`
|
||||
- Technology: AWS DynamoDB
|
||||
- Runtime: AWS managed
|
||||
- Fully serverless
|
||||
|
||||
4. **S3 Storage Container**
|
||||
- Type: `file-storage`
|
||||
- Technology: AWS S3
|
||||
- Runtime: AWS managed
|
||||
- Stores uploaded files
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌─────────────┐
|
||||
│ CloudFront │
|
||||
│ + S3 │
|
||||
│ (SPA) │
|
||||
└──────┬──────┘
|
||||
│ HTTP
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ API Gateway │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐ ┌──────────┐
|
||||
│ Lambda │──────▶ DynamoDB │
|
||||
│ Functions │ └──────────┘
|
||||
└─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ S3 Bucket │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect serverless pattern
|
||||
find . -name "serverless.yml" -o -name "serverless.yaml"
|
||||
find . -name "vercel.json" -o -name "netlify.toml"
|
||||
find . -name "template.yaml" | xargs grep "AWS::Serverless"
|
||||
|
||||
# Find Lambda functions
|
||||
grep -r "AWS::Serverless::Function\|handler:" serverless.yml
|
||||
|
||||
# Find DynamoDB tables
|
||||
grep -r "DynamoDB\|AWS::DynamoDB" template.yaml
|
||||
|
||||
# Find S3 usage
|
||||
grep -r "S3_BUCKET\|aws-sdk.*s3" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Full-Stack Framework (Next.js/Nuxt)
|
||||
|
||||
**Scenario:** Single full-stack application with SSR
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **Next.js Application Container**
|
||||
- Type: `app-server` (full-stack)
|
||||
- Technology: Next.js 13
|
||||
- Runtime: Server (Node.js)
|
||||
- Serves both frontend and API routes
|
||||
- **Note:** This is ONE container, not separate frontend/backend
|
||||
|
||||
2. **Database Container**
|
||||
- Type: `database`
|
||||
- Technology: PostgreSQL
|
||||
- Runtime: Server (Docker)
|
||||
|
||||
3. **Redis Cache Container**
|
||||
- Type: `cache`
|
||||
- Technology: Redis
|
||||
- Runtime: Server (Docker)
|
||||
- Caches SSR pages
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌────────────────────┐
|
||||
│ Next.js App │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ SSR + API │ │
|
||||
│ │ Routes │ │
|
||||
│ └──────┬───────┘ │
|
||||
└─────────┼──────────┘
|
||||
┌─┴──┐
|
||||
│ │
|
||||
┌───▼──┐ └──▼─────┐
|
||||
│ DB │ │ Redis │
|
||||
└──────┘ └───────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect Next.js/Nuxt pattern
|
||||
grep -r "\"next\":\|\"nuxt\":" package.json
|
||||
|
||||
# Check for API routes
|
||||
find . -type d -name "api" -path "*/pages/api" -o -path "*/app/api"
|
||||
|
||||
# Check for SSR
|
||||
grep -r "getServerSideProps\|getStaticProps" pages/ app/
|
||||
|
||||
# Verify single application
|
||||
[ $(find . -name "package.json" -not -path "*/node_modules/*" | wc -l) -eq 1 ] && echo "Single app"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Mobile App + Backend
|
||||
|
||||
**Scenario:** Mobile application with supporting backend
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **Mobile Application Container**
|
||||
- Type: `mobile-app`
|
||||
- Technology: React Native
|
||||
- Runtime: iOS/Android
|
||||
- Communicates with API
|
||||
|
||||
2. **Backend API Container**
|
||||
- Type: `api`
|
||||
- Technology: Django REST Framework
|
||||
- Runtime: Server (Python)
|
||||
- Provides mobile API
|
||||
|
||||
3. **PostgreSQL Database Container**
|
||||
- Type: `database`
|
||||
- Technology: PostgreSQL
|
||||
- Runtime: Server
|
||||
|
||||
4. **Redis Cache Container**
|
||||
- Type: `cache`
|
||||
- Technology: Redis
|
||||
- Runtime: Server
|
||||
- API response caching
|
||||
|
||||
5. **Push Notification Service Container**
|
||||
- Type: `worker`
|
||||
- Technology: Custom Python service
|
||||
- Runtime: Server
|
||||
- Sends push notifications via FCM/APNS
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Mobile Device │
|
||||
│ ┌─────────────┐ │
|
||||
│ │React Native │ │
|
||||
│ │ App │ │
|
||||
│ └──────┬──────┘ │
|
||||
└────────┼────────┘
|
||||
│ HTTPS
|
||||
▼
|
||||
┌────────────────┐ ┌────────┐
|
||||
│ Django API │──────▶ Postgres│
|
||||
└────────┬───────┘ └────────┘
|
||||
│
|
||||
┌────┴────┐
|
||||
▼ ▼
|
||||
┌──────┐ ┌────────┐
|
||||
│Redis │ │Push │
|
||||
│Cache │ │Service │
|
||||
└──────┘ └────────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect mobile app
|
||||
find . -name "package.json" | xargs grep "react-native\|@ionic\|flutter"
|
||||
find . -name "Podfile" -o -name "build.gradle"
|
||||
|
||||
# Detect backend API
|
||||
grep -r "djangorestframework\|flask\|fastapi" requirements.txt
|
||||
|
||||
# Find push notification service
|
||||
grep -r "fcm\|apns\|firebase-admin" . | grep -v node_modules
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 6: Event-Driven with Workers
|
||||
|
||||
**Scenario:** Async processing with message queue and workers
|
||||
|
||||
**Containers identified:**
|
||||
|
||||
1. **Web Application Container**
|
||||
- Type: `spa`
|
||||
- Technology: Vue 3
|
||||
- Runtime: Browser
|
||||
|
||||
2. **Backend API Container**
|
||||
- Type: `api`
|
||||
- Technology: FastAPI
|
||||
- Runtime: Server (Python)
|
||||
- Publishes events to queue
|
||||
|
||||
3. **Message Queue Container**
|
||||
- Type: `message-broker`
|
||||
- Technology: Kafka
|
||||
- Runtime: Server (Docker)
|
||||
- Event streaming
|
||||
|
||||
4. **Email Worker Container**
|
||||
- Type: `worker`
|
||||
- Technology: Celery
|
||||
- Runtime: Server (Python)
|
||||
- Consumes email events
|
||||
|
||||
5. **Report Worker Container**
|
||||
- Type: `worker`
|
||||
- Technology: Celery
|
||||
- Runtime: Server (Python)
|
||||
- Generates reports
|
||||
|
||||
6. **Database Container**
|
||||
- Type: `database`
|
||||
- Technology: PostgreSQL
|
||||
- Runtime: Server
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌──────┐ ┌─────┐
|
||||
│ Vue │───▶│ API │
|
||||
│ SPA │ └──┬──┘
|
||||
└──────┘ │
|
||||
│ publish
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Kafka │
|
||||
│ Queue │
|
||||
└─────┬────┘
|
||||
┌───┴───┐
|
||||
subscribe subscribe
|
||||
│ │
|
||||
┌────▼──┐ ┌─▼──────┐
|
||||
│Email │ │Report │
|
||||
│Worker │ │Worker │
|
||||
└───────┘ └────────┘
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Detect event-driven pattern
|
||||
grep -r "celery\|sidekiq\|bull\|bee-queue" requirements.txt package.json Gemfile
|
||||
|
||||
# Find message brokers
|
||||
grep -r "kafka\|rabbitmq\|redis.*pub.*sub" docker-compose.yml
|
||||
|
||||
# Find worker definitions
|
||||
find . -name "*worker*.py" -o -name "*job*.py"
|
||||
grep -r "celery.*worker\|worker.*start" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Selection Guide
|
||||
|
||||
### When to Use Each Pattern
|
||||
|
||||
| Pattern | Best For | Complexity | Scalability |
|
||||
|---------|----------|------------|-------------|
|
||||
| Pattern 1: SPA + API + DB | Simple web apps, MVPs | Low | Medium |
|
||||
| Pattern 2: Microservices | Large systems, independent teams | High | Very High |
|
||||
| Pattern 3: Serverless | Variable load, cost optimization | Medium | Auto-scale |
|
||||
| Pattern 4: Full-Stack Framework | Rapid development, SSR needs | Low-Medium | Medium |
|
||||
| Pattern 5: Mobile + Backend | Mobile-first apps | Medium | High |
|
||||
| Pattern 6: Event-Driven | Async processing, decoupling | Medium-High | Very High |
|
||||
|
||||
### Mixing Patterns
|
||||
|
||||
Real-world systems often combine patterns:
|
||||
|
||||
**Example: E-commerce Platform**
|
||||
- Pattern 1: Customer web portal (SPA + API + DB)
|
||||
- Pattern 5: Mobile shopping app (Mobile + Backend)
|
||||
- Pattern 6: Order processing (Event-driven workers)
|
||||
- Pattern 3: Static assets (Serverless CDN)
|
||||
|
||||
---
|
||||
|
||||
## Detection Best Practices
|
||||
|
||||
1. **Start with docker-compose.yml or K8s manifests** - Shows all containers
|
||||
2. **Check package manifests** - package.json, requirements.txt, pom.xml
|
||||
3. **Look for framework indicators** - next.config.js, serverless.yml
|
||||
4. **Examine folder structure** - services/, apps/, packages/
|
||||
5. **Review deployment configs** - Dockerfile, K8s deployments
|
||||
6. **Check environment variables** - .env files reveal connections
|
||||
|
||||
## Common Variations
|
||||
|
||||
### Pattern 1 Variations
|
||||
- Add Redis cache → Pattern 1 + Cache
|
||||
- Add Nginx proxy → Pattern 1 + Reverse Proxy
|
||||
- Add worker → Pattern 1 + Background Jobs
|
||||
|
||||
### Pattern 2 Variations
|
||||
- Per-service databases → Database-per-Service
|
||||
- Shared database → Shared-Database (anti-pattern)
|
||||
- Service mesh → Add Istio/Linkerd sidecar containers
|
||||
|
||||
### Pattern 3 Variations
|
||||
- Vercel deployment → Vercel Edge Functions
|
||||
- Netlify deployment → Netlify Functions
|
||||
- Azure → Azure Functions + Cosmos DB
|
||||
|
||||
### Pattern 4 Variations
|
||||
- Monorepo → Multiple Next.js apps
|
||||
- Standalone API → Next.js + Separate API
|
||||
- Edge runtime → Vercel Edge Runtime
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
1. **Shared Database Across Services**
|
||||
- Violates microservices principles
|
||||
- Creates tight coupling
|
||||
- Makes each service dependent
|
||||
|
||||
2. **Monolith in Disguise**
|
||||
- Multiple "microservices" that all call each other synchronously
|
||||
- Should be one container
|
||||
|
||||
3. **Over-Granular Containers**
|
||||
- Breaking down below deployment boundary
|
||||
- Example: Separating utility functions into "containers"
|
||||
|
||||
4. **Missing Infrastructure Containers**
|
||||
- Forgetting databases, caches, message brokers
|
||||
- Only documenting application containers
|
||||
|
||||
5. **Generic Container Types**
|
||||
- "Node.js App" instead of "Express API Server"
|
||||
- "Python Service" instead of "FastAPI API + Celery Worker"
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After identifying the pattern:
|
||||
|
||||
1. **Document each container** using container-types-reference.md
|
||||
2. **Map communication** using communication-patterns.md
|
||||
3. **Capture technology details** using technology-detection-patterns.md
|
||||
4. **Add observations** per observation-categories-c2.md
|
||||
5. **Validate** using melly-validation scripts
|
||||
474
skills/c4model-c2/communication-patterns.md
Normal file
474
skills/c4model-c2/communication-patterns.md
Normal file
@@ -0,0 +1,474 @@
|
||||
# Communication Patterns
|
||||
|
||||
This document provides comprehensive patterns for inter-container communication in C4 Model Level 2 analysis.
|
||||
|
||||
## Synchronous Communication
|
||||
|
||||
### HTTP REST API
|
||||
|
||||
**Pattern:** Client makes HTTP request, waits for response
|
||||
|
||||
**Indicators:**
|
||||
- axios, fetch, requests library
|
||||
- REST endpoints (`/api/v1/users`)
|
||||
- JSON request/response
|
||||
|
||||
**Relation Type:** `http-rest`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "ecommerce-api",
|
||||
"type": "http-rest",
|
||||
"direction": "outbound",
|
||||
"description": "Fetches product catalog data via REST API",
|
||||
"protocol": {
|
||||
"method": "GET, POST",
|
||||
"endpoint": "/api/v1/products",
|
||||
"format": "JSON",
|
||||
"authentication": "JWT Bearer Token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find HTTP client libraries
|
||||
grep -r "axios\|fetch\|requests\|http.client" src/
|
||||
|
||||
# Find API endpoint definitions
|
||||
grep -r "@Get\|@Post\|@app.route\|router.get" src/
|
||||
|
||||
# Find REST API calls
|
||||
grep -r "http://\|https://" .env config/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### HTTP GraphQL API
|
||||
|
||||
**Pattern:** Client sends GraphQL query, receives specific data
|
||||
|
||||
**Indicators:**
|
||||
- Apollo Client, graphql-request
|
||||
- Single `/graphql` endpoint
|
||||
- Query language
|
||||
|
||||
**Relation Type:** `http-graphql`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "graphql-api",
|
||||
"type": "http-graphql",
|
||||
"direction": "outbound",
|
||||
"description": "Queries user and order data via GraphQL",
|
||||
"protocol": {
|
||||
"endpoint": "/graphql",
|
||||
"format": "GraphQL",
|
||||
"authentication": "API Key header"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find GraphQL client libraries
|
||||
grep -r "@apollo/client\|graphql-request" package.json
|
||||
|
||||
# Find GraphQL schemas
|
||||
find . -name "*.graphql" -o -name "schema.gql"
|
||||
|
||||
# Find GraphQL operations
|
||||
grep -r "query\|mutation\|subscription" src/ | grep graphql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gRPC
|
||||
|
||||
**Pattern:** Remote procedure call with Protocol Buffers
|
||||
|
||||
**Indicators:**
|
||||
- @grpc/grpc-js, grpc-go
|
||||
- .proto files
|
||||
- Binary protocol
|
||||
|
||||
**Relation Type:** `grpc`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "user-service",
|
||||
"type": "grpc",
|
||||
"direction": "outbound",
|
||||
"description": "Calls user authentication via gRPC",
|
||||
"protocol": {
|
||||
"service": "UserService",
|
||||
"methods": ["Authenticate", "GetProfile"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find gRPC libraries
|
||||
grep -r "@grpc\|grpc-go\|grpc-java" package.json pom.xml
|
||||
|
||||
# Find proto files
|
||||
find . -name "*.proto"
|
||||
|
||||
# Find gRPC service definitions
|
||||
grep -r "service.*{" *.proto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Asynchronous Communication
|
||||
|
||||
### Message Queue (Publish/Subscribe)
|
||||
|
||||
**Pattern:** Publisher sends message to queue, consumer processes later
|
||||
|
||||
**Indicators:**
|
||||
- RabbitMQ, Kafka, AWS SQS
|
||||
- amqplib, kafkajs
|
||||
- Queue/topic names
|
||||
|
||||
**Relation Types:** `message-publish`, `message-subscribe`
|
||||
|
||||
**Example (Publisher):**
|
||||
```json
|
||||
{
|
||||
"target": "order-queue",
|
||||
"type": "message-publish",
|
||||
"direction": "outbound",
|
||||
"description": "Publishes order created events",
|
||||
"protocol": {
|
||||
"queue": "orders.created",
|
||||
"format": "JSON",
|
||||
"broker": "RabbitMQ"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example (Consumer):**
|
||||
```json
|
||||
{
|
||||
"target": "order-queue",
|
||||
"type": "message-subscribe",
|
||||
"direction": "inbound",
|
||||
"description": "Consumes order created events for processing",
|
||||
"protocol": {
|
||||
"queue": "orders.created",
|
||||
"format": "JSON",
|
||||
"broker": "RabbitMQ"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find message broker libraries
|
||||
grep -r "amqplib\|kafkajs\|aws-sdk.*sqs" package.json
|
||||
|
||||
# Find queue/topic names
|
||||
grep -r "queue\|topic\|exchange" config/ src/
|
||||
|
||||
# Find publish/subscribe operations
|
||||
grep -r "publish\|subscribe\|sendMessage\|consume" src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Event Streaming (Kafka)
|
||||
|
||||
**Pattern:** Continuous stream of events, multiple consumers
|
||||
|
||||
**Indicators:**
|
||||
- Apache Kafka
|
||||
- kafkajs, confluent-kafka
|
||||
- Topics and partitions
|
||||
|
||||
**Relation Types:** `event-publish`, `event-subscribe`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "kafka-broker",
|
||||
"type": "event-publish",
|
||||
"direction": "outbound",
|
||||
"description": "Streams order events to Kafka topic",
|
||||
"protocol": {
|
||||
"topic": "orders.events",
|
||||
"partitions": 3,
|
||||
"format": "Avro",
|
||||
"broker": "Kafka"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Communication
|
||||
|
||||
### Database Connection
|
||||
|
||||
**Pattern:** Application connects to database, executes queries
|
||||
|
||||
**Indicators:**
|
||||
- Connection strings in .env
|
||||
- ORM libraries (Prisma, SQLAlchemy, Hibernate)
|
||||
- Database drivers (pg, psycopg2, mysql2)
|
||||
|
||||
**Relation Type:** `database-query`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "main-database",
|
||||
"type": "database-query",
|
||||
"direction": "outbound",
|
||||
"description": "Reads and writes user and order data",
|
||||
"protocol": {
|
||||
"driver": "PostgreSQL wire protocol",
|
||||
"connection_pool": "Max 20 connections",
|
||||
"orm": "Prisma"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find database connection strings
|
||||
grep -r "DATABASE_URL\|DB_HOST\|POSTGRES\|MYSQL" .env config/
|
||||
|
||||
# Find ORM libraries
|
||||
grep -r "prisma\|typeorm\|sequelize\|sqlalchemy\|hibernate" package.json requirements.txt pom.xml
|
||||
|
||||
# Find database drivers
|
||||
grep -r "pg\|psycopg2\|mysql2\|mongodb" package.json requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cache Access
|
||||
|
||||
### Cache Read/Write
|
||||
|
||||
**Pattern:** Application reads/writes to in-memory cache
|
||||
|
||||
**Indicators:**
|
||||
- redis, ioredis, node-cache
|
||||
- Cache keys and TTL
|
||||
- GET/SET operations
|
||||
|
||||
**Relation Type:** `cache-read-write`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "session-cache",
|
||||
"type": "cache-read-write",
|
||||
"direction": "bidirectional",
|
||||
"description": "Stores and retrieves user session data",
|
||||
"protocol": {
|
||||
"driver": "Redis protocol",
|
||||
"operations": ["GET", "SET", "DEL", "EXPIRE"],
|
||||
"ttl": "1 hour"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find cache libraries
|
||||
grep -r "redis\|ioredis\|memcached\|node-cache" package.json
|
||||
|
||||
# Find cache configuration
|
||||
grep -r "REDIS_URL\|REDIS_HOST\|CACHE_" .env config/
|
||||
|
||||
# Find cache operations
|
||||
grep -r "\.get\|\.set\|\.del\|cache\." src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Storage Access
|
||||
|
||||
### Object Storage
|
||||
|
||||
**Pattern:** Application uploads/downloads files to/from object storage
|
||||
|
||||
**Indicators:**
|
||||
- AWS S3, MinIO, Azure Blob
|
||||
- aws-sdk, @aws-sdk/client-s3
|
||||
- Bucket names
|
||||
|
||||
**Relation Type:** `file-storage-access`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "media-storage",
|
||||
"type": "file-storage-access",
|
||||
"direction": "bidirectional",
|
||||
"description": "Uploads user-generated images and retrieves media files",
|
||||
"protocol": {
|
||||
"service": "AWS S3",
|
||||
"bucket": "user-media-prod",
|
||||
"operations": ["PutObject", "GetObject", "DeleteObject"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find storage SDKs
|
||||
grep -r "aws-sdk\|@aws-sdk\|minio\|azure-storage" package.json
|
||||
|
||||
# Find bucket/container names
|
||||
grep -r "S3_BUCKET\|STORAGE_BUCKET\|AZURE_CONTAINER" .env config/
|
||||
|
||||
# Find storage operations
|
||||
grep -r "putObject\|getObject\|upload\|download" src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## External API Calls
|
||||
|
||||
### Third-Party API Integration
|
||||
|
||||
**Pattern:** Container calls external third-party service
|
||||
|
||||
**Indicators:**
|
||||
- API keys in .env
|
||||
- External domain URLs
|
||||
- SDK libraries (Stripe, Twilio, SendGrid)
|
||||
|
||||
**Relation Type:** `external-api`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "stripe-api",
|
||||
"type": "external-api",
|
||||
"direction": "outbound",
|
||||
"description": "Processes payments via Stripe API",
|
||||
"protocol": {
|
||||
"service": "Stripe API v1",
|
||||
"authentication": "API Key",
|
||||
"endpoints": ["POST /v1/charges", "GET /v1/customers"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find external API libraries
|
||||
grep -r "stripe\|twilio\|sendgrid\|mailgun" package.json
|
||||
|
||||
# Find API keys
|
||||
grep -r "API_KEY\|SECRET_KEY" .env | grep -v "DATABASE\|JWT"
|
||||
|
||||
# Find external domains
|
||||
grep -r "https://api\." src/ config/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Communication
|
||||
|
||||
### Real-Time Bidirectional
|
||||
|
||||
**Pattern:** Persistent connection for real-time data exchange
|
||||
|
||||
**Indicators:**
|
||||
- socket.io, ws, websocket
|
||||
- WebSocket URLs (ws://, wss://)
|
||||
- Real-time events
|
||||
|
||||
**Relation Type:** `websocket`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"target": "realtime-server",
|
||||
"type": "websocket",
|
||||
"direction": "bidirectional",
|
||||
"description": "Real-time chat and notifications",
|
||||
"protocol": {
|
||||
"library": "Socket.IO 4.x",
|
||||
"events": ["message", "notification", "status_update"],
|
||||
"format": "JSON"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find WebSocket libraries
|
||||
grep -r "socket.io\|ws\|websocket" package.json
|
||||
|
||||
# Find WebSocket connections
|
||||
grep -r "ws://\|wss://\|io.connect\|new WebSocket" src/
|
||||
|
||||
# Find socket events
|
||||
grep -r "socket.emit\|socket.on" src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Communication Pattern Summary
|
||||
|
||||
| Pattern | Sync/Async | Use Case | Typical Protocol |
|
||||
|---------|-----------|----------|------------------|
|
||||
| HTTP REST | Sync | CRUD operations | JSON over HTTP |
|
||||
| GraphQL | Sync | Flexible data queries | GraphQL over HTTP |
|
||||
| gRPC | Sync | Service-to-service | Protobuf over HTTP/2 |
|
||||
| Message Queue | Async | Event-driven, decoupling | AMQP, SQS |
|
||||
| Event Stream | Async | Real-time data pipelines | Kafka protocol |
|
||||
| Database | Sync | Data persistence | SQL, MongoDB protocol |
|
||||
| Cache | Sync | Fast data access | Redis protocol |
|
||||
| Object Storage | Sync | File upload/download | S3 API |
|
||||
| WebSocket | Bidirectional | Real-time updates | WS protocol |
|
||||
|
||||
---
|
||||
|
||||
## Direction Guidelines
|
||||
|
||||
**Outbound:** Container initiates communication to another container
|
||||
- API calls from frontend to backend
|
||||
- Database queries from API server
|
||||
- Cache reads/writes from application
|
||||
|
||||
**Inbound:** Container receives communication from another container
|
||||
- API server receives HTTP requests
|
||||
- Worker consumes queue messages
|
||||
- Database accepts queries
|
||||
|
||||
**Bidirectional:** Two-way communication
|
||||
- WebSocket connections
|
||||
- Cache read/write operations
|
||||
- File storage upload/download
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be specific** - Document exact protocols, not just "HTTP"
|
||||
2. **Include authentication** - JWT, API keys, OAuth
|
||||
3. **Note data format** - JSON, Protobuf, Avro
|
||||
4. **Document endpoints** - Actual URLs or queue names
|
||||
5. **Capture direction** - Outbound, inbound, bidirectional
|
||||
6. **Version protocols** - REST API v1, gRPC v2
|
||||
7. **Performance characteristics** - Sync vs async, latency
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Missing intermediate containers** - Don't forget API gateways, proxies
|
||||
2. **Assuming HTTP** - Could be gRPC, WebSocket, etc.
|
||||
3. **Ignoring message brokers** - Async communication is indirect
|
||||
4. **Generic descriptions** - "Talks to API" → "Calls REST API GET /api/users"
|
||||
5. **Forgetting authentication** - Security mechanisms matter
|
||||
459
skills/c4model-c2/container-types-reference.md
Normal file
459
skills/c4model-c2/container-types-reference.md
Normal file
@@ -0,0 +1,459 @@
|
||||
# Container Types Reference
|
||||
|
||||
This document provides comprehensive reference for all C4 Model Level 2 (Container) types with detailed examples and runtime characteristics.
|
||||
|
||||
## Type 1: Single-Page Application (SPA)
|
||||
|
||||
**Type:** `spa`
|
||||
|
||||
**Description:** Client-side web application that runs entirely in the browser
|
||||
|
||||
**Technology Indicators:**
|
||||
- React, Vue, Angular, Svelte
|
||||
- Webpack, Vite, or similar bundler
|
||||
- Build output to static files (HTML/CSS/JS)
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `browser`
|
||||
- Platform: `Chrome, Firefox, Safari, Edge`
|
||||
- Containerized: `false` (static files)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "customer-portal-spa",
|
||||
"name": "Customer Portal SPA",
|
||||
"type": "spa",
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "React 18.2.0",
|
||||
"libraries": [
|
||||
{"name": "React Router", "version": "6.14.0", "purpose": "Client-side routing"},
|
||||
{"name": "Redux Toolkit", "version": "1.9.5", "purpose": "State management"},
|
||||
{"name": "Axios", "version": "1.4.0", "purpose": "HTTP client"}
|
||||
]
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "browser",
|
||||
"platform": "Modern browsers (Chrome 90+, Firefox 88+, Safari 14+)",
|
||||
"containerized": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 2: API Server / Application Server
|
||||
|
||||
**Type:** `app-server` or `api`
|
||||
|
||||
**Description:** Server-side application that exposes APIs or serves requests
|
||||
|
||||
**Technology Indicators:**
|
||||
- Express, NestJS, Fastify (Node.js)
|
||||
- Django, Flask, FastAPI (Python)
|
||||
- Spring Boot, Quarkus (Java)
|
||||
- Runs on server, listens on port
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server`
|
||||
- Platform: `Linux, Node.js 18, Python 3.11, JVM 17`
|
||||
- Containerized: `true` (usually)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "ecommerce-api",
|
||||
"name": "E-Commerce REST API",
|
||||
"type": "api",
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "NestJS 10.0.0",
|
||||
"libraries": [
|
||||
{"name": "Prisma", "version": "5.0.0", "purpose": "ORM"},
|
||||
{"name": "Passport", "version": "0.6.0", "purpose": "Authentication"},
|
||||
{"name": "class-validator", "version": "0.14.0", "purpose": "Validation"}
|
||||
]
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64, Node.js 18.16.0",
|
||||
"containerized": true,
|
||||
"container_technology": "Docker",
|
||||
"deployment_model": "Kubernetes (3 replicas)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 3: Database
|
||||
|
||||
**Type:** `database`
|
||||
|
||||
**Description:** Data persistence layer (relational or NoSQL)
|
||||
|
||||
**Technology Indicators:**
|
||||
- PostgreSQL, MySQL, MariaDB (relational)
|
||||
- MongoDB, Cassandra, DynamoDB (NoSQL)
|
||||
- Docker image or managed service
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server` or `cloud`
|
||||
- Platform: `Linux, Docker`
|
||||
- Containerized: `true` (often)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "main-database",
|
||||
"name": "Main PostgreSQL Database",
|
||||
"type": "database",
|
||||
"technology": {
|
||||
"primary_language": "SQL",
|
||||
"framework": "PostgreSQL 15.3",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64, Docker",
|
||||
"containerized": true,
|
||||
"container_technology": "Docker",
|
||||
"deployment_model": "Single instance with volume persistence"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 4: Cache
|
||||
|
||||
**Type:** `cache`
|
||||
|
||||
**Description:** In-memory data store for caching and session management
|
||||
|
||||
**Technology Indicators:**
|
||||
- Redis, Memcached
|
||||
- In-memory key-value store
|
||||
- TTL-based expiration
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server`
|
||||
- Platform: `Linux`
|
||||
- Containerized: `true` (usually)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "session-cache",
|
||||
"name": "Redis Session Cache",
|
||||
"type": "cache",
|
||||
"technology": {
|
||||
"primary_language": "N/A",
|
||||
"framework": "Redis 7.0",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64",
|
||||
"containerized": true,
|
||||
"container_technology": "Docker"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 5: Message Broker
|
||||
|
||||
**Type:** `message-broker`
|
||||
|
||||
**Description:** Message queue or event streaming platform
|
||||
|
||||
**Technology Indicators:**
|
||||
- RabbitMQ, Apache Kafka, AWS SQS, Redis Pub/Sub
|
||||
- Async message passing
|
||||
- Producers and consumers
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server` or `cloud`
|
||||
- Platform: `Linux, Docker, or managed cloud service`
|
||||
- Containerized: `true` (usually)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "event-broker",
|
||||
"name": "RabbitMQ Message Broker",
|
||||
"type": "message-broker",
|
||||
"technology": {
|
||||
"primary_language": "N/A",
|
||||
"framework": "RabbitMQ 3.12",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64",
|
||||
"containerized": true,
|
||||
"container_technology": "Kubernetes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 6: Web Server / Reverse Proxy
|
||||
|
||||
**Type:** `web-server`
|
||||
|
||||
**Description:** HTTP server, reverse proxy, or load balancer
|
||||
|
||||
**Technology Indicators:**
|
||||
- Nginx, Apache, Traefik
|
||||
- Serves static files
|
||||
- Reverse proxy to backend services
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server`
|
||||
- Platform: `Linux`
|
||||
- Containerized: `true` (usually)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "nginx-proxy",
|
||||
"name": "Nginx Reverse Proxy",
|
||||
"type": "web-server",
|
||||
"technology": {
|
||||
"primary_language": "N/A",
|
||||
"framework": "Nginx 1.25",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64",
|
||||
"containerized": true,
|
||||
"container_technology": "Kubernetes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 7: Worker / Background Service
|
||||
|
||||
**Type:** `worker`
|
||||
|
||||
**Description:** Background job processor, cron jobs, queue consumers
|
||||
|
||||
**Technology Indicators:**
|
||||
- Celery workers, Sidekiq, Bull queue
|
||||
- Processes background tasks
|
||||
- Often queue-based
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `server`
|
||||
- Platform: `Linux, Python, Ruby, Node.js`
|
||||
- Containerized: `true` (usually)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "email-worker",
|
||||
"name": "Email Processing Worker",
|
||||
"type": "worker",
|
||||
"technology": {
|
||||
"primary_language": "Python",
|
||||
"framework": "Celery 5.3.0",
|
||||
"libraries": [
|
||||
{"name": "sendgrid", "version": "6.10.0", "purpose": "Email sending"}
|
||||
]
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64, Python 3.11",
|
||||
"containerized": true,
|
||||
"container_technology": "Kubernetes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 8: Mobile Application
|
||||
|
||||
**Type:** `mobile-app`
|
||||
|
||||
**Description:** Native or hybrid mobile application
|
||||
|
||||
**Technology Indicators:**
|
||||
- React Native, Flutter, Swift, Kotlin
|
||||
- Runs on mobile devices
|
||||
- Platform-specific build outputs
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `mobile`
|
||||
- Platform: `iOS, Android`
|
||||
- Containerized: `false`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "shopping-mobile-app",
|
||||
"name": "Shopping Mobile App",
|
||||
"type": "mobile-app",
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "React Native 0.72.0",
|
||||
"libraries": [
|
||||
{"name": "React Navigation", "version": "6.1.0", "purpose": "Navigation"}
|
||||
]
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "mobile",
|
||||
"platform": "iOS 14+, Android 11+",
|
||||
"containerized": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 9: Desktop Application
|
||||
|
||||
**Type:** `desktop-app`
|
||||
|
||||
**Description:** Desktop application for Windows, macOS, or Linux
|
||||
|
||||
**Technology Indicators:**
|
||||
- Electron, Tauri, Qt
|
||||
- Native desktop frameworks
|
||||
- Installable applications
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `desktop`
|
||||
- Platform: `Windows, macOS, Linux`
|
||||
- Containerized: `false`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "admin-desktop-app",
|
||||
"name": "Admin Desktop Application",
|
||||
"type": "desktop-app",
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "Electron 25.0.0",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "desktop",
|
||||
"platform": "Windows 10+, macOS 11+, Linux",
|
||||
"containerized": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type 10: File Storage
|
||||
|
||||
**Type:** `file-storage`
|
||||
|
||||
**Description:** Object storage, file system, or CDN
|
||||
|
||||
**Technology Indicators:**
|
||||
- AWS S3, MinIO, Azure Blob Storage
|
||||
- File upload/download
|
||||
- Static asset storage
|
||||
|
||||
**Runtime:**
|
||||
- Environment: `cloud` or `server`
|
||||
- Platform: `Cloud provider or self-hosted`
|
||||
- Containerized: `varies`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "media-storage",
|
||||
"name": "S3 Media Storage",
|
||||
"type": "file-storage",
|
||||
"technology": {
|
||||
"primary_language": "N/A",
|
||||
"framework": "AWS S3",
|
||||
"libraries": []
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "cloud",
|
||||
"platform": "AWS",
|
||||
"containerized": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type Selection Guide
|
||||
|
||||
### Decision Tree
|
||||
|
||||
1. **Runs in browser?** → SPA (Type 1)
|
||||
2. **Exposes API/HTTP endpoints?** → API Server (Type 2)
|
||||
3. **Stores persistent data?** → Database (Type 3)
|
||||
4. **In-memory caching?** → Cache (Type 4)
|
||||
5. **Async messaging?** → Message Broker (Type 5)
|
||||
6. **Proxies/serves static files?** → Web Server (Type 6)
|
||||
7. **Background jobs?** → Worker (Type 7)
|
||||
8. **Mobile device?** → Mobile App (Type 8)
|
||||
9. **Desktop application?** → Desktop App (Type 9)
|
||||
10. **File/object storage?** → File Storage (Type 10)
|
||||
|
||||
### Common Combinations
|
||||
|
||||
**Typical Web App:**
|
||||
- SPA (frontend)
|
||||
- API Server (backend)
|
||||
- Database (persistence)
|
||||
- Cache (session/performance)
|
||||
|
||||
**Microservices:**
|
||||
- Multiple API Servers (services)
|
||||
- Message Broker (async communication)
|
||||
- Multiple Databases (per-service)
|
||||
- Web Server (gateway/proxy)
|
||||
|
||||
**Full-Stack Application:**
|
||||
- API Server with SSR (Next.js/Nuxt)
|
||||
- Database
|
||||
- Cache
|
||||
- File Storage (uploads)
|
||||
|
||||
**Enterprise System:**
|
||||
- SPA (admin portal)
|
||||
- Mobile App (customer app)
|
||||
- Multiple API Servers (microservices)
|
||||
- Worker (background jobs)
|
||||
- Message Broker (events)
|
||||
- Multiple Databases
|
||||
- Cache
|
||||
- File Storage
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One container = one deployable unit** - Don't split unnecessarily
|
||||
2. **Runtime matters** - Document where container actually runs
|
||||
3. **Technology precision** - Include versions (React 18, not just React)
|
||||
4. **Containerization awareness** - Note Docker/K8s deployment
|
||||
5. **Communication patterns** - Document how containers interact
|
||||
6. **Scaling characteristics** - Note replicas, stateful vs stateless
|
||||
7. **Dependencies** - Capture required infrastructure containers
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Confusing container with system** - Container is ONE deployable unit within a system
|
||||
2. **Too granular** - Don't break down below deployment boundary
|
||||
3. **Missing infrastructure** - Don't forget databases, caches, brokers
|
||||
4. **Generic types** - Be specific (FastAPI API, not "Python app")
|
||||
5. **Ignoring deployment** - Runtime and deployment model matter
|
||||
158
skills/c4model-c2/methodology.md
Normal file
158
skills/c4model-c2/methodology.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Container Identification Methodology
|
||||
|
||||
Detailed step-by-step process for identifying C2 containers within systems.
|
||||
|
||||
## Step 1: Understand System Decomposition
|
||||
|
||||
Start by reviewing the systems identified at C1 level in `c1-systems.json`:
|
||||
|
||||
**Questions to ask:**
|
||||
1. What systems were identified at C1?
|
||||
2. What repositories belong to each system?
|
||||
3. What is the system type (web-application, api-service, etc.)?
|
||||
4. What technologies were mentioned in system observations?
|
||||
|
||||
**System-to-Container Mapping Examples:**
|
||||
|
||||
**Simple Web Application System →**
|
||||
- Frontend SPA container (React/Vue/Angular in browser)
|
||||
- Backend API container (Express/Django/Spring on server)
|
||||
- Database container (PostgreSQL/MongoDB)
|
||||
- Cache container (Redis) - optional
|
||||
|
||||
**Microservice System →**
|
||||
- API Server container (main service logic)
|
||||
- Database container (service-specific database)
|
||||
- Worker container (background processing) - optional
|
||||
- Message broker container (RabbitMQ/Kafka) - if async
|
||||
|
||||
**Mobile App System →**
|
||||
- Mobile Application container (React Native/Flutter on mobile)
|
||||
- Backend API container (supporting backend)
|
||||
- Database container
|
||||
- Push notification service container - optional
|
||||
|
||||
> **See [Common Container Patterns](./common-container-patterns.md) for 6 reusable architecture patterns.**
|
||||
|
||||
## Step 2: Apply Container Identification Rules
|
||||
|
||||
### A Container IS:
|
||||
|
||||
1. **Deployable independently** - Has own build/deployment process and artifact
|
||||
2. **Executes code OR stores data** - Runs application logic or persists data
|
||||
3. **Has distinct technology stack** - Built with specific language/framework
|
||||
4. **Has runtime environment** - Runs in specific environment (browser, server, mobile, cloud)
|
||||
5. **Communicates via defined protocols** - HTTP, database connections, message queues
|
||||
6. **Infrastructure component** - Databases, caches, message brokers required for system operation
|
||||
|
||||
### A Container is NOT:
|
||||
|
||||
1. **Code modules within an application** (these are C3 components)
|
||||
- "Authentication Module" in React app → C3 Component
|
||||
- "Express API Application" → C2 Container
|
||||
|
||||
2. **Configuration files or static assets** - package.json, CSS files, images
|
||||
|
||||
3. **Development tools** - Webpack, Babel, ESLint, Jest test runner
|
||||
|
||||
4. **Generic names without technology and version**
|
||||
- "Frontend Container" → "React 18.2 SPA Container"
|
||||
- "Backend Container" → "Express 4.18 API Server Container"
|
||||
- "React SPA" (missing version) → "React 18.2 SPA"
|
||||
|
||||
5. **Names without versions** (versions MUST come from manifest files)
|
||||
- "React SPA" → "React 18.2.0 SPA"
|
||||
- "Express API Server" → "Express 4.18.2 API Server"
|
||||
|
||||
**RULE (Mandatory):** You MUST extract versions from manifest files:
|
||||
- package.json (JavaScript/TypeScript)
|
||||
- requirements.txt / pyproject.toml (Python)
|
||||
- pom.xml / build.gradle (Java)
|
||||
- Cargo.toml (Rust)
|
||||
- go.mod (Go)
|
||||
|
||||
This is NOT optional. Reading manifests is NOT "line-by-line code analysis" - it's standard C2 technology detection.
|
||||
|
||||
**Failure to include versions from manifests = VIOLATION of C2 methodology = Critical validation error.**
|
||||
|
||||
6. **Over-granular decomposition**
|
||||
- "Login API" + "Register API" → "User Management API"
|
||||
|
||||
> **See [Troubleshooting Guide](./troubleshooting-guide-c2.md#problem-too-many-containers-identified) for detailed guidance.**
|
||||
|
||||
## Step 3: Analyze Repository Structure
|
||||
|
||||
For each system, examine its repositories to identify containers:
|
||||
|
||||
**Look for deployment indicators:**
|
||||
|
||||
```bash
|
||||
# Check for containerization
|
||||
find . -name "Dockerfile" -o -name "docker-compose.yml"
|
||||
|
||||
# Check for build outputs
|
||||
ls -la dist/ build/ target/ out/
|
||||
|
||||
# Check for deployment configs
|
||||
ls -la .kubernetes/ .aws/ .azure/ vercel.json netlify.toml
|
||||
```
|
||||
|
||||
**Common patterns:**
|
||||
|
||||
- **Frontend SPA:** `public/index.html`, `src/App.tsx`, `package.json` with React/Vue/Angular
|
||||
- **Backend API:** `src/server.js`, `app.py`, `Main.java` with Express/Django/Spring
|
||||
- **Database:** `docker-compose.yml` defining database service, migration files
|
||||
- **Worker:** Queue consumer code, `worker.js`, `worker.py`
|
||||
|
||||
## Step 4: Detect Technology Stack
|
||||
|
||||
For each container, identify:
|
||||
|
||||
### Primary Language
|
||||
JavaScript, TypeScript, Python, Java, Go, Ruby, PHP, C#, Rust
|
||||
|
||||
**Detection methods:**
|
||||
```bash
|
||||
# Check package manifests
|
||||
cat package.json | jq '.dependencies'
|
||||
cat requirements.txt
|
||||
cat pom.xml
|
||||
|
||||
# Count file extensions
|
||||
find src -name "*.ts" | wc -l
|
||||
find src -name "*.py" | wc -l
|
||||
|
||||
# Check Dockerfile
|
||||
cat Dockerfile | grep "FROM"
|
||||
```
|
||||
|
||||
### Framework/Platform
|
||||
React, Vue, Angular (frontend) | Express, NestJS, FastAPI, Django, Spring Boot (backend)
|
||||
|
||||
**Detection methods:**
|
||||
- Check dependencies in package manifests
|
||||
- Look for framework-specific files (`angular.json`, `vue.config.js`)
|
||||
- Analyze import statements
|
||||
|
||||
> **See [Technology Detection Patterns](./technology-detection-patterns.md) for complete detection guide.**
|
||||
|
||||
## Step 5: Identify Runtime Environment
|
||||
|
||||
For each container, determine:
|
||||
|
||||
### Environment
|
||||
- **browser** - Runs in web browser (SPAs)
|
||||
- **server** - Runs on server (APIs, web servers)
|
||||
- **mobile** - Runs on mobile device (iOS/Android)
|
||||
- **cloud** - Runs in cloud (Lambda, Cloud Functions)
|
||||
- **edge** - Runs at edge (Cloudflare Workers)
|
||||
|
||||
### Platform
|
||||
- Browser: Chrome, Firefox, Safari, Edge
|
||||
- Server: Linux, Node.js 18, Python 3.11, JVM 17
|
||||
- Mobile: iOS 14+, Android 11+
|
||||
|
||||
### Containerization
|
||||
- **Containerized:** true/false
|
||||
- **Container Technology:** Docker, Kubernetes, ECS
|
||||
- **Container Image:** `node:18-alpine`, `python:3.11-slim`
|
||||
502
skills/c4model-c2/observation-categories-c2.md
Normal file
502
skills/c4model-c2/observation-categories-c2.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# Observation Categories for C2
|
||||
|
||||
This document provides comprehensive guidance on documenting observations for C4 Model Level 2 (Container) analysis.
|
||||
|
||||
## Observation Categories
|
||||
|
||||
When documenting containers, capture these observation categories:
|
||||
|
||||
### 1. technology
|
||||
|
||||
**Focus:** Technology stack, frameworks, libraries, and versions
|
||||
|
||||
**What to Document:**
|
||||
- Primary programming language and version
|
||||
- Framework name and version
|
||||
- Major libraries and their purposes
|
||||
- Build tools and bundlers
|
||||
- Package managers
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Uses React 18.2.0 with TypeScript for type safety"
|
||||
- ✅ "Built with NestJS 10.0 framework following modular architecture"
|
||||
- ✅ "Python 3.11 with FastAPI for high-performance async API"
|
||||
- ⚠️ "Outdated Express 3.x version (current is 4.x)" (warning)
|
||||
- ⚠️ "Mixed JavaScript and TypeScript files (inconsistent)" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# JavaScript/TypeScript
|
||||
cat package.json | jq '.dependencies'
|
||||
cat package.json | jq '.devDependencies'
|
||||
|
||||
# Python
|
||||
cat requirements.txt
|
||||
pip list
|
||||
|
||||
# Java
|
||||
cat pom.xml | grep "<dependency>"
|
||||
gradle dependencies
|
||||
|
||||
# Check versions
|
||||
node --version
|
||||
python --version
|
||||
java --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. runtime
|
||||
|
||||
**Focus:** Runtime environment, platform, and deployment model
|
||||
|
||||
**What to Document:**
|
||||
- Runtime environment (browser, Node.js, Python, JVM, etc.)
|
||||
- Platform details (OS, architecture, version)
|
||||
- Containerization (Docker, Kubernetes)
|
||||
- Deployment model (single instance, replicas, serverless)
|
||||
- Resource constraints (CPU, memory)
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Runs in browser (Chrome 90+, Firefox 88+, Safari 14+)"
|
||||
- ✅ "Node.js 18.16.0 runtime on Linux x64"
|
||||
- ✅ "Containerized with Docker, deployed to Kubernetes with 3 replicas"
|
||||
- ✅ "Serverless deployment on AWS Lambda with cold start ~500ms"
|
||||
- ⚠️ "No resource limits configured in Kubernetes" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Check Dockerfile
|
||||
cat Dockerfile | grep "FROM"
|
||||
|
||||
# Check K8s deployment
|
||||
kubectl get deployment <name> -o yaml | grep replicas
|
||||
|
||||
# Check docker-compose
|
||||
cat docker-compose.yml | grep "image:\|build:"
|
||||
|
||||
# Check runtime config
|
||||
cat .node-version
|
||||
cat runtime.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. communication
|
||||
|
||||
**Focus:** How the container communicates with other containers
|
||||
|
||||
**What to Document:**
|
||||
- Communication protocols (HTTP, gRPC, WebSocket, etc.)
|
||||
- API specifications (REST, GraphQL)
|
||||
- Message brokers (RabbitMQ, Kafka)
|
||||
- Synchronous vs asynchronous
|
||||
- Authentication mechanisms
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Communicates with API via HTTP REST over HTTPS"
|
||||
- ✅ "Publishes events to RabbitMQ message broker"
|
||||
- ✅ "Uses gRPC for inter-service communication"
|
||||
- ✅ "WebSocket connection for real-time updates"
|
||||
- ⚠️ "HTTP communication not encrypted (uses http://)" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find HTTP clients
|
||||
grep -r "axios\|fetch\|requests" src/
|
||||
|
||||
# Find gRPC
|
||||
grep -r "grpc\|proto" src/ | head -5
|
||||
|
||||
# Find WebSocket
|
||||
grep -r "socket.io\|ws\|websocket" src/
|
||||
|
||||
# Find message broker
|
||||
grep -r "amqp\|kafka\|redis.*publish" src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. data-storage
|
||||
|
||||
**Focus:** Data persistence, caching, and storage patterns
|
||||
|
||||
**What to Document:**
|
||||
- Database type and version (PostgreSQL, MongoDB, etc.)
|
||||
- Connection pooling configuration
|
||||
- Caching strategy (Redis, Memcached)
|
||||
- File storage (S3, local filesystem)
|
||||
- Stateful vs stateless
|
||||
|
||||
**Examples:**
|
||||
- ✅ "PostgreSQL 15 database with connection pooling (max 20)"
|
||||
- ✅ "Redis cache for session storage with 1-hour TTL"
|
||||
- ✅ "Stores uploaded files in AWS S3 bucket"
|
||||
- ✅ "No database connection (stateless API)"
|
||||
- ⚠️ "Database connection pool not configured (potential bottleneck)" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find database connections
|
||||
grep -r "DATABASE_URL\|DB_HOST" .env
|
||||
|
||||
# Find ORMs
|
||||
grep -r "prisma\|typeorm\|sequelize\|sqlalchemy" .
|
||||
|
||||
# Find cache usage
|
||||
grep -r "REDIS_URL\|redis.get\|redis.set" .
|
||||
|
||||
# Find file storage
|
||||
grep -r "S3_BUCKET\|aws-sdk.*s3\|multer" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. authentication
|
||||
|
||||
**Focus:** Authentication and authorization mechanisms
|
||||
|
||||
**What to Document:**
|
||||
- Authentication method (JWT, OAuth, API keys)
|
||||
- Token expiry and refresh
|
||||
- Authorization rules (RBAC, ABAC)
|
||||
- Session management
|
||||
- Security headers
|
||||
|
||||
**Examples:**
|
||||
- ✅ "JWT Bearer token authentication with 15-minute expiry"
|
||||
- ✅ "OAuth 2.0 integration with Auth0"
|
||||
- ✅ "API key authentication via x-api-key header"
|
||||
- ⚠️ "No authentication implemented" (warning)
|
||||
- 🔴 "JWT tokens never expire (security risk)" (critical)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find authentication libraries
|
||||
grep -r "passport\|jsonwebtoken\|auth0" package.json
|
||||
|
||||
# Find JWT usage
|
||||
grep -r "jwt\|bearer\|token" src/ | grep -i auth
|
||||
|
||||
# Find OAuth
|
||||
grep -r "oauth\|openid" .
|
||||
|
||||
# Check for API keys
|
||||
grep -r "API_KEY\|X-API-KEY" .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. configuration
|
||||
|
||||
**Focus:** Configuration management and environment variables
|
||||
|
||||
**What to Document:**
|
||||
- Configuration sources (.env, ConfigMap, Secrets)
|
||||
- Environment-specific configs (dev, staging, prod)
|
||||
- Secret management
|
||||
- Configuration validation
|
||||
- Default values
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Configuration via environment variables"
|
||||
- ✅ "Uses .env files for local development"
|
||||
- ✅ "ConfigMap and Secrets in Kubernetes"
|
||||
- ⚠️ "Hardcoded configuration values in source code" (warning)
|
||||
- 🔴 "Secrets committed to git repository" (critical)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find .env files
|
||||
find . -name ".env*" -not -path "*/node_modules/*"
|
||||
|
||||
# Check for ConfigMap usage
|
||||
grep -r "ConfigMap" k8s/
|
||||
|
||||
# Find hardcoded values
|
||||
grep -r "http://\|https://\|mongodb://\|postgres://" src/ | grep -v ".env"
|
||||
|
||||
# Check for secret management
|
||||
grep -r "vault\|doppler\|aws-secrets-manager" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. monitoring
|
||||
|
||||
**Focus:** Logging, monitoring, and observability
|
||||
|
||||
**What to Document:**
|
||||
- Logging framework and destination
|
||||
- Metrics collection (Prometheus, DataDog)
|
||||
- Tracing (OpenTelemetry, Jaeger)
|
||||
- Health checks and readiness probes
|
||||
- Error tracking (Sentry, Rollbar)
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Application logs to stdout, collected by Fluentd"
|
||||
- ✅ "Prometheus metrics exposed on /metrics endpoint"
|
||||
- ✅ "OpenTelemetry tracing enabled"
|
||||
- ⚠️ "No logging or monitoring configured" (warning)
|
||||
- ⚠️ "Logs contain sensitive data (PII, credentials)" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find logging libraries
|
||||
grep -r "winston\|pino\|bunyan\|logrus" package.json
|
||||
|
||||
# Find metrics
|
||||
grep -r "prometheus\|statsd\|datadog" .
|
||||
|
||||
# Find tracing
|
||||
grep -r "opentelemetry\|jaeger\|zipkin" .
|
||||
|
||||
# Check for health endpoints
|
||||
grep -r "/health\|/ready\|/alive" src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. dependencies
|
||||
|
||||
**Focus:** External dependencies and third-party services
|
||||
|
||||
**What to Document:**
|
||||
- Third-party API integrations (Stripe, SendGrid)
|
||||
- External service dependencies
|
||||
- SDK usage
|
||||
- Vendor lock-in risks
|
||||
- Availability dependencies
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Depends on Stripe API for payment processing"
|
||||
- ✅ "Uses SendGrid for transactional email"
|
||||
- ✅ "Integrates with Google Analytics for tracking"
|
||||
- ⚠️ "Heavy dependency on external APIs (availability risk)" (warning)
|
||||
- ⚠️ "No fallback for third-party service failures" (warning)
|
||||
|
||||
**Detection Commands:**
|
||||
```bash
|
||||
# Find third-party SDKs
|
||||
grep -r "stripe\|twilio\|sendgrid\|mailgun" package.json
|
||||
|
||||
# Find external API calls
|
||||
grep -r "https://api\." src/ .env
|
||||
|
||||
# Check for API keys
|
||||
grep -r "STRIPE_KEY\|TWILIO_\|SENDGRID_" .env
|
||||
|
||||
# Find vendor-specific code
|
||||
grep -r "aws-sdk\|google-cloud\|azure" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Observation Structure
|
||||
|
||||
### JSON Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obs-tech-react-18",
|
||||
"category": "technology",
|
||||
"severity": "info",
|
||||
"description": "React 18.2.0 with TypeScript 5.0 for type-safe component development",
|
||||
"evidence": {
|
||||
"type": "file",
|
||||
"location": "package.json",
|
||||
"snippet": "\"react\": \"^18.2.0\", \"typescript\": \"^5.0.0\""
|
||||
},
|
||||
"tags": ["react", "typescript", "frontend", "spa"],
|
||||
"discovered_at": "2025-01-15T10:30:00Z",
|
||||
"discovered_by": "c2-abstractor"
|
||||
}
|
||||
```
|
||||
|
||||
### Field Descriptions
|
||||
|
||||
- **id**: Unique identifier (format: `obs-<category>-<short-desc>`)
|
||||
- **category**: One of the 8 categories above
|
||||
- **severity**: `info`, `warning`, or `critical`
|
||||
- **description**: Human-readable observation
|
||||
- **evidence**: Proof of the observation
|
||||
- **type**: `file`, `command`, `inference`
|
||||
- **location**: File path, command, or reasoning
|
||||
- **snippet**: Code snippet, command output, or explanation
|
||||
- **tags**: Searchable keywords
|
||||
- **discovered_at**: ISO 8601 timestamp
|
||||
- **discovered_by**: Tool or agent name
|
||||
|
||||
---
|
||||
|
||||
## Observation Severity Levels
|
||||
|
||||
### info (Informational)
|
||||
|
||||
**Purpose:** Neutral findings documenting the system as it is
|
||||
|
||||
**Examples:**
|
||||
- ℹ️ "Uses Prisma ORM for database access"
|
||||
- ℹ️ "React 18.2.0 with functional components and hooks"
|
||||
- ℹ️ "Deployed with 3 replicas for high availability"
|
||||
|
||||
**When to Use:**
|
||||
- Technology choices (neutral)
|
||||
- Architecture patterns (no issues)
|
||||
- Configuration details (standard)
|
||||
|
||||
### warning (Needs Attention)
|
||||
|
||||
**Purpose:** Potential issues that should be addressed but aren't blocking
|
||||
|
||||
**Examples:**
|
||||
- ⚠️ "Redis cache has no password configured"
|
||||
- ⚠️ "Outdated Express 3.x version (current is 4.x)"
|
||||
- ⚠️ "No resource limits configured in Kubernetes"
|
||||
- ⚠️ "Logs contain timestamps but no correlation IDs"
|
||||
|
||||
**When to Use:**
|
||||
- Outdated dependencies
|
||||
- Missing best practices
|
||||
- Potential performance issues
|
||||
- Missing recommended features
|
||||
|
||||
### critical (Immediate Action)
|
||||
|
||||
**Purpose:** Critical issues requiring immediate action (security, stability)
|
||||
|
||||
**Examples:**
|
||||
- 🔴 "Database credentials hardcoded in source code"
|
||||
- 🔴 "JWT tokens never expire (security risk)"
|
||||
- 🔴 "API exposed without authentication"
|
||||
- 🔴 "Secrets committed to git repository"
|
||||
|
||||
**When to Use:**
|
||||
- Security vulnerabilities
|
||||
- Data exposure risks
|
||||
- Critical misconfigurations
|
||||
- Blocking production issues
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO:
|
||||
|
||||
1. **Be specific** - Include versions, exact technologies
|
||||
2. **Provide evidence** - Link to files, commands, or reasoning
|
||||
3. **Use consistent format** - Follow the JSON schema
|
||||
4. **Tag appropriately** - Use searchable, relevant tags
|
||||
5. **Document warnings** - Call out anti-patterns and risks
|
||||
6. **Cite sources** - Reference configuration files, code
|
||||
|
||||
### DON'T:
|
||||
|
||||
1. **Don't be vague** - "Uses React" → "Uses React 18.2.0"
|
||||
2. **Don't skip evidence** - Always provide proof
|
||||
3. **Don't over-categorize** - One observation = one category
|
||||
4. **Don't ignore security** - Flag security issues as critical
|
||||
5. **Don't duplicate** - Consolidate similar observations
|
||||
6. **Don't guess** - Only document what you can verify
|
||||
|
||||
---
|
||||
|
||||
## Common Observation Patterns
|
||||
|
||||
### Pattern: Outdated Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obs-tech-outdated-express",
|
||||
"category": "technology",
|
||||
"severity": "warning",
|
||||
"description": "Express 3.x is significantly outdated (current stable: 4.x). Consider upgrading for security patches and new features.",
|
||||
"evidence": {
|
||||
"type": "file",
|
||||
"location": "package.json",
|
||||
"snippet": "\"express\": \"^3.21.2\""
|
||||
},
|
||||
"tags": ["express", "outdated", "dependency", "security"]
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern: Missing Authentication
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obs-auth-missing",
|
||||
"category": "authentication",
|
||||
"severity": "critical",
|
||||
"description": "API endpoints exposed without authentication. All routes are publicly accessible.",
|
||||
"evidence": {
|
||||
"type": "command",
|
||||
"location": "grep -r 'app.get\\|app.post' src/",
|
||||
"snippet": "No authentication middleware found in route definitions"
|
||||
},
|
||||
"tags": ["authentication", "security", "api", "critical"]
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern: Performance Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obs-runtime-no-limits",
|
||||
"category": "runtime",
|
||||
"severity": "warning",
|
||||
"description": "Kubernetes deployment has no CPU or memory limits configured, which may lead to resource contention.",
|
||||
"evidence": {
|
||||
"type": "file",
|
||||
"location": "k8s/deployment.yaml",
|
||||
"snippet": "No 'resources.limits' section found in container spec"
|
||||
},
|
||||
"tags": ["kubernetes", "resources", "performance", "deployment"]
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern: Good Practice
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obs-monitor-prometheus",
|
||||
"category": "monitoring",
|
||||
"severity": "info",
|
||||
"description": "Prometheus metrics endpoint exposed at /metrics with custom application metrics",
|
||||
"evidence": {
|
||||
"type": "file",
|
||||
"location": "src/metrics.ts",
|
||||
"snippet": "app.get('/metrics', (req, res) => { res.set('Content-Type', register.contentType); res.end(register.metrics()); });"
|
||||
},
|
||||
"tags": ["prometheus", "monitoring", "metrics", "observability"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relationship to C1 Observations
|
||||
|
||||
C2 observations are **more detailed** than C1:
|
||||
|
||||
| Aspect | C1 (System) | C2 (Container) |
|
||||
|--------|-------------|----------------|
|
||||
| **Scope** | Entire system | Individual containers |
|
||||
| **Technology** | High-level tech stack | Specific frameworks & versions |
|
||||
| **Runtime** | General deployment | Exact runtime config |
|
||||
| **Communication** | External dependencies | Inter-container protocols |
|
||||
|
||||
**Example:**
|
||||
- **C1**: "E-Commerce System uses Node.js and React"
|
||||
- **C2 (Frontend)**: "React 18.2.0 SPA with TypeScript 5.0, deployed to Vercel"
|
||||
- **C2 (Backend)**: "NestJS 10.0 API on Node.js 18.16.0, containerized in Kubernetes with 3 replicas"
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After capturing observations:
|
||||
|
||||
1. **Validate** using melly-validation scripts
|
||||
2. **Store** in basic-memory MCP knowledge base
|
||||
3. **Reference** in container documentation
|
||||
4. **Track** warnings and critical issues
|
||||
5. **Update** as system evolves
|
||||
69
skills/c4model-c2/output-format.md
Normal file
69
skills/c4model-c2/output-format.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# C2 Output Format
|
||||
|
||||
JSON structure for `c2-containers.json` output file.
|
||||
|
||||
## Complete Example
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"version": "1.0.0",
|
||||
"timestamp": "2025-11-17T20:20:00.000Z",
|
||||
"generated_by": "c2-abstractor",
|
||||
"parent": {
|
||||
"file": "c1-systems.json",
|
||||
"timestamp": "2025-11-17T10:00:00.000Z"
|
||||
}
|
||||
},
|
||||
"containers": [
|
||||
{
|
||||
"id": "ecommerce-spa",
|
||||
"name": "E-Commerce Customer Portal",
|
||||
"type": "spa",
|
||||
"system_id": "ecommerce-system",
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "React 18.2.0",
|
||||
"libraries": [
|
||||
{"name": "React Router", "version": "6.14.0", "purpose": "Client-side routing"},
|
||||
{"name": "Redux Toolkit", "version": "1.9.5", "purpose": "State management"}
|
||||
]
|
||||
},
|
||||
"runtime": {
|
||||
"environment": "browser",
|
||||
"platform": "Modern browsers (Chrome 90+, Firefox 88+, Safari 14+)",
|
||||
"containerized": false
|
||||
},
|
||||
"relations": [
|
||||
{
|
||||
"target": "ecommerce-api",
|
||||
"type": "http-rest",
|
||||
"direction": "outbound",
|
||||
"description": "Fetches product data and submits orders"
|
||||
}
|
||||
],
|
||||
"observations": [],
|
||||
"metadata": {
|
||||
"repository": "frontend/",
|
||||
"discovered_at": "2025-11-17T20:15:00.000Z"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
After generating `c2-containers.json`:
|
||||
|
||||
```bash
|
||||
# Validate JSON structure
|
||||
python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c2-containers.py c2-containers.json
|
||||
|
||||
# Verify timestamps
|
||||
python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/check-timestamp.sh c2-containers.json c1-systems.json
|
||||
```
|
||||
|
||||
## Required Fields
|
||||
|
||||
See main [SKILL.md](./SKILL.md#required-fields-checklist) for complete required fields matrix.
|
||||
445
skills/c4model-c2/technology-detection-patterns.md
Normal file
445
skills/c4model-c2/technology-detection-patterns.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# Technology Detection Patterns
|
||||
|
||||
This document provides comprehensive patterns for detecting technologies and frameworks in C4 Model Level 2 (Container) analysis.
|
||||
|
||||
## Pattern 1: npm/package.json Detection
|
||||
|
||||
### Frontend Frameworks
|
||||
|
||||
**React:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"react": "^18.2.0", // → React 18 SPA
|
||||
"react-dom": "^18.2.0",
|
||||
"react-router-dom": "^6.14.0" // → Client-side routing
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** React SPA, runs in browser
|
||||
|
||||
**Vue:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"vue": "^3.3.0", // → Vue 3 SPA
|
||||
"@vue/runtime-core": "^3.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Vue SPA, runs in browser
|
||||
|
||||
**Angular:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@angular/core": "^16.0.0", // → Angular 16 SPA
|
||||
"@angular/platform-browser": "^16.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Angular SPA, runs in browser
|
||||
|
||||
### Backend Frameworks
|
||||
|
||||
**Express.js:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"express": "^4.18.2", // → Express API Server
|
||||
"cors": "^2.8.5",
|
||||
"helmet": "^7.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Express.js API Server, runs on Node.js
|
||||
|
||||
**NestJS:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@nestjs/core": "^10.0.0", // → NestJS API Server
|
||||
"@nestjs/platform-express": "^10.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** NestJS API Server, runs on Node.js
|
||||
|
||||
**Fastify:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"fastify": "^4.20.0", // → Fastify API Server
|
||||
"@fastify/cors": "^8.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Fastify API Server, runs on Node.js
|
||||
|
||||
### Full-Stack Frameworks
|
||||
|
||||
**Next.js:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"next": "^13.4.0", // → Next.js Full-Stack
|
||||
"react": "^18.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Next.js Application (SSR + API routes), runs on Node.js server
|
||||
|
||||
**Nuxt.js:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"nuxt": "^3.6.0", // → Nuxt.js Full-Stack
|
||||
"vue": "^3.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Nuxt.js Application, runs on Node.js server
|
||||
|
||||
### Mobile Frameworks
|
||||
|
||||
**React Native:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"react-native": "^0.72.0" // → React Native Mobile App
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** React Native Mobile Application, runs on iOS/Android
|
||||
|
||||
**Ionic:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@ionic/react": "^7.0.0", // → Ionic Mobile App
|
||||
"capacitor": "^5.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Ionic Mobile Application, runs on iOS/Android
|
||||
|
||||
### Desktop Frameworks
|
||||
|
||||
**Electron:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"electron": "^25.0.0" // → Electron Desktop App
|
||||
}
|
||||
}
|
||||
```
|
||||
→ **Container:** Electron Desktop Application, runs on Windows/macOS/Linux
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Python Detection
|
||||
|
||||
### Web Frameworks
|
||||
|
||||
**Django:**
|
||||
|
||||
```txt
|
||||
# requirements.txt
|
||||
Django==4.2.0 # → Django Web Application
|
||||
djangorestframework==3.14.0 # → Also has REST API
|
||||
psycopg2-binary==2.9.6 # → Uses PostgreSQL
|
||||
```
|
||||
→ **Container:** Django Web Application + API, runs on Python 3.x
|
||||
|
||||
**Flask:**
|
||||
|
||||
```txt
|
||||
# requirements.txt
|
||||
Flask==2.3.0 # → Flask API Server
|
||||
Flask-CORS==4.0.0
|
||||
gunicorn==21.0.0 # → WSGI server for production
|
||||
```
|
||||
→ **Container:** Flask API Server, runs on Python 3.x with Gunicorn
|
||||
|
||||
**FastAPI:**
|
||||
|
||||
```txt
|
||||
# requirements.txt
|
||||
fastapi==0.100.0 # → FastAPI API Server
|
||||
uvicorn[standard]==0.23.0 # → ASGI server
|
||||
pydantic==2.0.0 # → Data validation
|
||||
```
|
||||
→ **Container:** FastAPI API Server, runs on Python 3.x with Uvicorn
|
||||
|
||||
### Background Workers
|
||||
|
||||
**Celery:**
|
||||
|
||||
```txt
|
||||
# requirements.txt
|
||||
celery==5.3.0 # → Celery Worker
|
||||
redis==4.6.0 # → Uses Redis as broker
|
||||
```
|
||||
→ **Container:** Celery Worker, runs on Python 3.x
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Java Detection
|
||||
|
||||
### Maven (pom.xml)
|
||||
|
||||
**Spring Boot:**
|
||||
|
||||
```xml
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
<version>3.1.0</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
→ **Container:** Spring Boot API Server, runs on JVM 17+
|
||||
|
||||
### Gradle (build.gradle)
|
||||
|
||||
**Quarkus:**
|
||||
|
||||
```groovy
|
||||
dependencies {
|
||||
implementation 'io.quarkus:quarkus-resteasy-reactive'
|
||||
implementation 'io.quarkus:quarkus-jdbc-postgresql'
|
||||
}
|
||||
```
|
||||
→ **Container:** Quarkus API Server, runs on JVM or native
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Docker Detection
|
||||
|
||||
### Dockerfile Examples
|
||||
|
||||
**Node.js API Server:**
|
||||
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --omit=dev
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
CMD ["node", "server.js"]
|
||||
```
|
||||
→ **Container:** Node.js API Server, containerized with Docker, runs on Node.js 18
|
||||
|
||||
**Python FastAPI Server:**
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
WORKDIR /app
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
COPY . .
|
||||
EXPOSE 8000
|
||||
CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]
|
||||
```
|
||||
→ **Container:** Python FastAPI Server, containerized with Docker, runs on Python 3.11
|
||||
|
||||
### docker-compose.yml
|
||||
|
||||
**Multi-Container Application:**
|
||||
|
||||
```yaml
|
||||
services:
|
||||
api:
|
||||
build: ./api
|
||||
ports:
|
||||
- "3000:3000"
|
||||
depends_on:
|
||||
- db
|
||||
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
environment:
|
||||
POSTGRES_DB: myapp
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
```
|
||||
→ **Containers identified:**
|
||||
1. API Server (custom built from ./api)
|
||||
2. PostgreSQL Database (postgres:15-alpine)
|
||||
3. Redis Cache (redis:7-alpine)
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Kubernetes Detection
|
||||
|
||||
### Deployment YAML
|
||||
|
||||
**Frontend SPA with Nginx:**
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: frontend-spa
|
||||
spec:
|
||||
replicas: 3
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.25-alpine
|
||||
ports:
|
||||
- containerPort: 80
|
||||
```
|
||||
→ **Container:** Nginx Web Server, containerized with K8s, serves static SPA
|
||||
|
||||
**API Server:**
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: api-server
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: api
|
||||
image: myapp/api:1.0
|
||||
env:
|
||||
- name: DATABASE_URL
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: db-secret
|
||||
key: url
|
||||
```
|
||||
→ **Container:** Custom API Server, containerized with K8s
|
||||
|
||||
---
|
||||
|
||||
## Pattern 6: Serverless Detection
|
||||
|
||||
### Serverless Framework (serverless.yml)
|
||||
|
||||
**AWS Lambda:**
|
||||
|
||||
```yaml
|
||||
service: my-api
|
||||
provider:
|
||||
name: aws
|
||||
runtime: nodejs18.x
|
||||
functions:
|
||||
api:
|
||||
handler: handler.main
|
||||
events:
|
||||
- http:
|
||||
path: /api/{proxy+}
|
||||
method: ANY
|
||||
```
|
||||
→ **Container:** AWS Lambda Function, runs on Node.js 18, serverless
|
||||
|
||||
### Vercel (vercel.json)
|
||||
|
||||
**Next.js on Vercel:**
|
||||
|
||||
```json
|
||||
{
|
||||
"builds": [
|
||||
{
|
||||
"src": "package.json",
|
||||
"use": "@vercel/next"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
→ **Container:** Next.js Application, serverless deployment on Vercel
|
||||
|
||||
---
|
||||
|
||||
## Detection CLI Commands
|
||||
|
||||
### Find Package Manifests
|
||||
|
||||
```bash
|
||||
# Find npm package.json files
|
||||
find . -name "package.json" -not -path "*/node_modules/*"
|
||||
|
||||
# Find Python requirements files
|
||||
find . -name "requirements.txt" -o -name "Pipfile" -o -name "pyproject.toml"
|
||||
|
||||
# Find Java build files
|
||||
find . -name "pom.xml" -o -name "build.gradle"
|
||||
|
||||
# Find Docker files
|
||||
find . -name "Dockerfile" -o -name "docker-compose.yml"
|
||||
|
||||
# Find Kubernetes manifests
|
||||
find . -name "*.yaml" -path "*/k8s/*" -o -path "*/kubernetes/*"
|
||||
```
|
||||
|
||||
### Analyze Dependencies
|
||||
|
||||
```bash
|
||||
# Node.js: List dependencies
|
||||
cat package.json | jq '.dependencies'
|
||||
|
||||
# Python: List installed packages
|
||||
pip list
|
||||
|
||||
# Java Maven: Show dependency tree
|
||||
mvn dependency:tree
|
||||
|
||||
# Docker: Show image info
|
||||
docker inspect <image-name>
|
||||
```
|
||||
|
||||
### Grep for Framework Indicators
|
||||
|
||||
```bash
|
||||
# Search for web frameworks
|
||||
grep -r "express\|fastify\|nestjs" package.json
|
||||
|
||||
# Search for frontend frameworks
|
||||
grep -r "react\|vue\|angular" package.json
|
||||
|
||||
# Search for Python frameworks
|
||||
grep -r "django\|flask\|fastapi" requirements.txt
|
||||
|
||||
# Search for container orchestration
|
||||
grep -r "kubernetes\|docker-compose" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Check multiple indicators** - Don't rely on a single file
|
||||
2. **Verify versions** - Framework versions matter for capabilities
|
||||
3. **Look for actual usage** - Dependency presence doesn't guarantee usage
|
||||
4. **Consider build artifacts** - Check dist/, build/, target/ folders
|
||||
5. **Examine runtime configs** - .env files, config/*.json
|
||||
6. **Review deployment configs** - Dockerfile, K8s manifests, serverless.yml
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Monorepo confusion** - Multiple package.json files may exist
|
||||
2. **Dev vs prod dependencies** - Only production deps matter for runtime
|
||||
3. **Transitive dependencies** - Don't confuse direct vs indirect deps
|
||||
4. **Deprecated patterns** - Some frameworks have legacy detection patterns
|
||||
5. **Polyglot projects** - May have multiple technologies in different folders
|
||||
645
skills/c4model-c2/troubleshooting-guide-c2.md
Normal file
645
skills/c4model-c2/troubleshooting-guide-c2.md
Normal file
@@ -0,0 +1,645 @@
|
||||
# Troubleshooting Guide - C2 Container Analysis
|
||||
|
||||
This document provides solutions to common problems encountered during C4 Model Level 2 (Container) analysis.
|
||||
|
||||
## Problem: Too Many Containers Identified
|
||||
|
||||
**Symptom:** 15+ containers for a simple web application
|
||||
|
||||
**Root Cause:** Confusing C3 components with C2 containers
|
||||
|
||||
**Solution:** Remember the deployment boundary:
|
||||
- **Containers** are **deployable units** (can be deployed independently)
|
||||
- **Components** are **code modules** within containers (cannot be deployed alone)
|
||||
- If it can't be deployed independently, it's probably C3
|
||||
|
||||
**Decision Test:**
|
||||
```
|
||||
Can this be deployed separately?
|
||||
├─ ✅ Yes → C2 Container
|
||||
└─ ❌ No → C3 Component
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
| Item | Level | Reason |
|
||||
|------|-------|--------|
|
||||
| React SPA (builds to static files) | C2 Container | Deployed to CDN/web server |
|
||||
| Auth module within React app | C3 Component | Part of SPA bundle |
|
||||
| Express API server | C2 Container | Runs as separate process |
|
||||
| Payment controller in Express | C3 Component | Code within API server |
|
||||
| PostgreSQL database | C2 Container | Runs as separate process |
|
||||
| User table in database | C3 Component | Schema within database |
|
||||
|
||||
**HARD LIMITS (Mandatory Validation):**
|
||||
|
||||
| Count | Classification | Action Required |
|
||||
|-------|----------------|-----------------|
|
||||
| 3-10 | ✅ Standard | Correct C2 abstraction level |
|
||||
| 11-15 | ⚠️ Review Required | Each container MUST have explicit deployment boundary justification |
|
||||
| 16-20 | ⚠️ Microservices | Document why this is microservices architecture, not over-granular |
|
||||
| 20+ | 🛑 **STOP** | You are likely at C3 level. **Mandatory review of every container.** |
|
||||
|
||||
**RULE for 20+ Containers:**
|
||||
- STOP analysis immediately
|
||||
- Review EVERY identified "container" against the deployment boundary test
|
||||
- Each item must answer YES to: "Can this be deployed independently?"
|
||||
- If most answers are NO, you are at C3 level - consolidate to actual containers
|
||||
- This is NOT guidance - this is a mandatory validation checkpoint
|
||||
|
||||
---
|
||||
|
||||
## Problem: Can't Determine Technology Stack
|
||||
|
||||
**Symptom:** No clear framework or language indicators
|
||||
|
||||
**Solution Steps:**
|
||||
|
||||
### Step 1: Check All Package Manifests
|
||||
|
||||
```bash
|
||||
# Find all package files
|
||||
find . -name "package.json" -o -name "requirements.txt" -o -name "pom.xml" -o -name "Cargo.toml"
|
||||
|
||||
# Examine dependencies
|
||||
cat package.json | jq '.dependencies'
|
||||
cat requirements.txt
|
||||
```
|
||||
|
||||
### Step 2: Check Dockerfiles
|
||||
|
||||
```bash
|
||||
# Find Dockerfiles
|
||||
find . -name "Dockerfile*"
|
||||
|
||||
# Check base image
|
||||
cat Dockerfile | grep "FROM"
|
||||
```
|
||||
|
||||
**Common base images:**
|
||||
- `FROM node:18` → Node.js 18
|
||||
- `FROM python:3.11` → Python 3.11
|
||||
- `FROM openjdk:17` → Java 17
|
||||
- `FROM nginx:alpine` → Nginx web server
|
||||
|
||||
### Step 3: Count File Types
|
||||
|
||||
```bash
|
||||
# Count source files by extension
|
||||
find src -name "*.ts" | wc -l # TypeScript
|
||||
find src -name "*.js" | wc -l # JavaScript
|
||||
find src -name "*.py" | wc -l # Python
|
||||
find src -name "*.java" | wc -l # Java
|
||||
find src -name "*.go" | wc -l # Go
|
||||
find src -name "*.rs" | wc -l # Rust
|
||||
```
|
||||
|
||||
### Step 4: Check Build Configurations
|
||||
|
||||
```bash
|
||||
# Check for framework config files
|
||||
ls -la webpack.config.js tsconfig.json angular.json vue.config.js next.config.js
|
||||
|
||||
# Read framework configs
|
||||
cat tsconfig.json | jq '.compilerOptions.jsx' # React indicator
|
||||
cat angular.json | jq '.projects' # Angular indicator
|
||||
```
|
||||
|
||||
### Step 5: Search for Framework Imports
|
||||
|
||||
```bash
|
||||
# JavaScript/TypeScript frameworks
|
||||
grep -r "from 'react'\|from 'vue'\|from '@angular" src/ | head -5
|
||||
|
||||
# Python frameworks
|
||||
grep -r "from django\|from flask\|from fastapi" . | head -5
|
||||
|
||||
# Java frameworks
|
||||
grep -r "import.*springframework" src/ | head -5
|
||||
```
|
||||
|
||||
### Step 6: If Still Unclear - RESTRICTED USE ONLY
|
||||
|
||||
**"Unknown" is ONLY valid when ALL of these conditions are true:**
|
||||
- ❌ NO manifest files exist (no package.json, requirements.txt, pom.xml, Cargo.toml, go.mod, Gemfile)
|
||||
- ❌ NO Dockerfile exists OR Dockerfile does not specify version in FROM statement
|
||||
- ❌ NO build configuration files found (tsconfig.json, angular.json, etc.)
|
||||
- ❌ NO import statements reveal framework
|
||||
|
||||
**If ANY manifest file exists, you MUST extract the version. "Unknown" is NOT acceptable.**
|
||||
|
||||
When "Unknown" is legitimately required:
|
||||
- Mark technology as **"Unknown"** temporarily
|
||||
- Document **why** it's unclear with evidence of what you searched:
|
||||
```json
|
||||
{
|
||||
"id": "obs-tech-unknown",
|
||||
"category": "technology",
|
||||
"severity": "critical",
|
||||
"description": "Unable to determine primary framework. Searched for all standard manifest files - none found.",
|
||||
"evidence": {
|
||||
"type": "command",
|
||||
"location": "find . -name 'package.json' -o -name 'requirements.txt' -o -name 'pom.xml' -o -name 'Cargo.toml' -o -name 'go.mod'",
|
||||
"snippet": "No results found"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Ask user for clarification immediately
|
||||
- This triggers a CRITICAL observation, not a warning
|
||||
|
||||
**RULE:** If you mark something as "Unknown" when manifest files exist, this is a VIOLATION of C2 methodology.
|
||||
|
||||
---
|
||||
|
||||
## Problem: Container vs System Confusion
|
||||
|
||||
**Symptom:** Unclear if something is C1 System or C2 Container
|
||||
|
||||
**Remember the Levels:**
|
||||
|
||||
| Level | Abstraction | Example |
|
||||
|-------|-------------|---------|
|
||||
| **C1 System** | High-level logical system with business purpose | "E-Commerce System" |
|
||||
| **C2 Container** | Deployable/runnable unit within a system | "React SPA", "Express API", "PostgreSQL DB" |
|
||||
| **C3 Component** | Code module within a container | "ProductList.tsx", "PaymentController.ts" |
|
||||
|
||||
**Decision Tree:**
|
||||
|
||||
```
|
||||
Does it have a business purpose understood by non-technical stakeholders?
|
||||
├─ ✅ Yes → Could be C1 System
|
||||
│ └─ Does it consist of multiple deployable units?
|
||||
│ ├─ ✅ Yes → C1 System
|
||||
│ └─ ❌ No → C2 Container (simple system with one container)
|
||||
│
|
||||
└─ ❌ No → Not C1 System
|
||||
└─ Can it be deployed independently?
|
||||
├─ ✅ Yes → C2 Container
|
||||
└─ ❌ No → C3 Component
|
||||
```
|
||||
|
||||
**Real Examples:**
|
||||
|
||||
**Example 1: E-Commerce System**
|
||||
- "E-Commerce System" → **C1 System** (business purpose: sell products online)
|
||||
- "Customer Web Portal" → **C2 Container** (React SPA)
|
||||
- "Product API Server" → **C2 Container** (Express API)
|
||||
- "Order Database" → **C2 Container** (PostgreSQL)
|
||||
- "Product Catalog Component" → **C3 Component** (code in React SPA)
|
||||
|
||||
**Example 2: Payment Processing System**
|
||||
- "Payment Processing System" → **C1 System** (business purpose: process payments)
|
||||
- "Payment API Server" → **C2 Container** (NestJS API)
|
||||
- "Payment Database" → **C2 Container** (PostgreSQL)
|
||||
- "Stripe Integration Service" → **C2 Container** (Python worker)
|
||||
- "PaymentController" → **C3 Component** (code in NestJS API)
|
||||
|
||||
**Example 3: Monolith Application**
|
||||
- "Customer Portal System" → **C1 System**
|
||||
- "Next.js Full-Stack Application" → **C2 Container** (single deployable unit)
|
||||
- Frontend pages → **C3 Components**
|
||||
- API routes → **C3 Components**
|
||||
- "PostgreSQL Database" → **C2 Container**
|
||||
|
||||
---
|
||||
|
||||
## Problem: Missing Required Fields in Validation
|
||||
|
||||
**Symptom:** Validation script fails with "Missing required field"
|
||||
|
||||
### Common Missing Fields:
|
||||
|
||||
#### 1. `system_id`
|
||||
|
||||
**Error:** `Missing required field: system_id`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check c1-systems.json for valid system IDs
|
||||
cat c1-systems.json | jq '.systems[].id'
|
||||
|
||||
# Use exact ID (case-sensitive)
|
||||
# Example: "ecommerce-system" NOT "Ecommerce-System"
|
||||
```
|
||||
|
||||
#### 2. `technology.primary_language`
|
||||
|
||||
**Error:** `Missing required field: technology.primary_language`
|
||||
|
||||
**Solution:**
|
||||
- JavaScript, TypeScript, Python, Java, Go, Rust, etc.
|
||||
- Required for all containers except pure infrastructure
|
||||
- Use capitalized language name
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"technology": {
|
||||
"primary_language": "TypeScript",
|
||||
"framework": "React 18.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. `technology.framework`
|
||||
|
||||
**Error:** `Missing required field: technology.framework`
|
||||
|
||||
**Solution:**
|
||||
- React, Express, Django, Spring Boot, FastAPI, etc.
|
||||
- Required for all application containers
|
||||
- Include version number
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"technology": {
|
||||
"primary_language": "JavaScript",
|
||||
"framework": "Express.js 4.18.2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Exception:** Infrastructure containers (databases, caches) may use "N/A":
|
||||
```json
|
||||
{
|
||||
"technology": {
|
||||
"primary_language": "N/A",
|
||||
"framework": "PostgreSQL 15.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. `runtime.environment`
|
||||
|
||||
**Error:** `Missing required field: runtime.environment`
|
||||
|
||||
**Valid Values:**
|
||||
- `browser` - Client-side web application
|
||||
- `server` - Server-side application
|
||||
- `mobile` - iOS/Android application
|
||||
- `cloud` - Cloud-native/serverless
|
||||
- `edge` - Edge computing
|
||||
- `desktop` - Desktop application
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"runtime": {
|
||||
"environment": "server",
|
||||
"platform": "Linux x64, Node.js 18.16.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. `runtime.platform`
|
||||
|
||||
**Error:** `Missing required field: runtime.platform`
|
||||
|
||||
**Solution:**
|
||||
Describe the exact platform where the container runs.
|
||||
|
||||
**Examples:**
|
||||
```json
|
||||
// Browser
|
||||
"platform": "Modern browsers (Chrome 90+, Firefox 88+, Safari 14+)"
|
||||
|
||||
// Server
|
||||
"platform": "Linux x64, Node.js 18.16.0"
|
||||
"platform": "Linux x64, Python 3.11.4"
|
||||
"platform": "Linux x64, JVM 17"
|
||||
|
||||
// Mobile
|
||||
"platform": "iOS 14+, Android 11+"
|
||||
|
||||
// Cloud
|
||||
"platform": "AWS Lambda (Node.js 18 runtime)"
|
||||
```
|
||||
|
||||
#### 6. `runtime.containerized`
|
||||
|
||||
**Error:** `Missing required field: runtime.containerized`
|
||||
|
||||
**Solution:**
|
||||
- `true` - Runs in Docker/Kubernetes/container
|
||||
- `false` - Runs directly on OS or in browser
|
||||
|
||||
**Examples:**
|
||||
```json
|
||||
// Containerized API
|
||||
{
|
||||
"runtime": {
|
||||
"containerized": true,
|
||||
"container_technology": "Docker",
|
||||
"deployment_model": "Kubernetes with 3 replicas"
|
||||
}
|
||||
}
|
||||
|
||||
// Browser SPA
|
||||
{
|
||||
"runtime": {
|
||||
"containerized": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem: Timestamp Validation Fails
|
||||
|
||||
**Symptom:** "Timestamp must be newer than parent timestamp"
|
||||
|
||||
**Root Cause:** c2-containers.json timestamp must be > c1-systems.json timestamp
|
||||
|
||||
**Solution:**
|
||||
|
||||
### Step 1: Check Current Timestamps
|
||||
|
||||
```bash
|
||||
# Check C1 timestamp
|
||||
cat c1-systems.json | jq '.metadata.timestamp'
|
||||
# Example output: "2025-11-17T10:00:00.000Z"
|
||||
|
||||
# Check C2 timestamp
|
||||
cat c2-containers.json | jq '.metadata.timestamp'
|
||||
# Example output: "2025-11-17T09:00:00.000Z" # WRONG! Earlier than C1
|
||||
```
|
||||
|
||||
### Step 2: Regenerate with Current Timestamp
|
||||
|
||||
Ensure ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
|
||||
|
||||
```bash
|
||||
# Generate current timestamp
|
||||
date -u +"%Y-%m-%dT%H:%M:%S.000Z"
|
||||
# Example: 2025-11-17T20:20:00.000Z
|
||||
```
|
||||
|
||||
### Step 3: Update c2-containers.json
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"timestamp": "2025-11-17T20:20:00.000Z",
|
||||
"generated_by": "c2-abstractor",
|
||||
"parent": {
|
||||
"file": "c1-systems.json",
|
||||
"timestamp": "2025-11-17T10:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Rule:** Always ensure C2 timestamp > C1 timestamp
|
||||
|
||||
---
|
||||
|
||||
## Problem: Communication Pattern Unclear
|
||||
|
||||
**Symptom:** Don't know which relation type to use
|
||||
|
||||
**Solution: Decision Tree:**
|
||||
|
||||
```
|
||||
What protocol is used?
|
||||
├─ HTTP
|
||||
│ ├─ REST API → "http-rest"
|
||||
│ ├─ GraphQL → "http-graphql"
|
||||
│ └─ Generic → "http"
|
||||
│
|
||||
├─ gRPC → "grpc"
|
||||
│
|
||||
├─ WebSocket → "websocket"
|
||||
│
|
||||
├─ Database
|
||||
│ ├─ Read only → "database-read"
|
||||
│ ├─ Write only → "database-write"
|
||||
│ └─ Both → "database-query"
|
||||
│
|
||||
├─ Cache
|
||||
│ ├─ Read only → "cache-read"
|
||||
│ ├─ Write only → "cache-write"
|
||||
│ └─ Both → "cache-read-write"
|
||||
│
|
||||
├─ Message Queue
|
||||
│ ├─ Publish → "message-publish"
|
||||
│ └─ Subscribe → "message-subscribe"
|
||||
│
|
||||
└─ File Storage
|
||||
├─ Read → "file-read"
|
||||
├─ Write → "file-write"
|
||||
└─ Both → "file-read-write"
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- SPA calls API → `http-rest`
|
||||
- API reads database → `database-query`
|
||||
- API publishes to queue → `message-publish`
|
||||
- Worker consumes queue → `message-subscribe`
|
||||
- API caches responses → `cache-read-write`
|
||||
|
||||
---
|
||||
|
||||
## Problem: Monorepo vs Microservices Detection
|
||||
|
||||
**Symptom:** Unclear how many containers exist in a monorepo
|
||||
|
||||
**Solution:**
|
||||
|
||||
### Check for Multiple Package Files
|
||||
|
||||
```bash
|
||||
# Find all package.json files (excluding node_modules)
|
||||
find . -name "package.json" -not -path "*/node_modules/*"
|
||||
|
||||
# If multiple found, check structure
|
||||
ls -la packages/ apps/ services/
|
||||
```
|
||||
|
||||
### Check for Workspace Configuration
|
||||
|
||||
```bash
|
||||
# Check for monorepo tools
|
||||
cat package.json | jq '.workspaces' # npm/yarn workspaces
|
||||
cat lerna.json # Lerna
|
||||
cat nx.json # Nx
|
||||
cat pnpm-workspace.yaml # pnpm
|
||||
```
|
||||
|
||||
### Identify Deployable Units
|
||||
|
||||
**Rule:** Each independently deployable package = 1 container
|
||||
|
||||
**Example: Nx Monorepo**
|
||||
```
|
||||
monorepo/
|
||||
├── apps/
|
||||
│ ├── frontend/ → C2 Container (React SPA)
|
||||
│ ├── api/ → C2 Container (NestJS API)
|
||||
│ └── admin/ → C2 Container (Admin SPA)
|
||||
├── libs/
|
||||
│ ├── ui-components/ → C3 Component (shared library)
|
||||
│ ├── data-access/ → C3 Component (shared library)
|
||||
│ └── utils/ → C3 Component (shared library)
|
||||
```
|
||||
|
||||
**Result:** 3 containers, 3 shared libraries (C3)
|
||||
|
||||
---
|
||||
|
||||
## Problem: Serverless Function Granularity
|
||||
|
||||
**Symptom:** Unclear if each Lambda function is a container
|
||||
|
||||
**Solution:**
|
||||
|
||||
### Option 1: Single Container (Recommended)
|
||||
|
||||
Treat all Lambda functions as **one container** if:
|
||||
- Deployed together (single serverless.yml)
|
||||
- Share same codebase
|
||||
- Same runtime and dependencies
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
# serverless.yml
|
||||
functions:
|
||||
getUser: ...
|
||||
createUser: ...
|
||||
updateUser: ...
|
||||
deleteUser: ...
|
||||
```
|
||||
|
||||
→ **One Container:** "User API Lambda Functions"
|
||||
|
||||
### Option 2: Multiple Containers
|
||||
|
||||
Only split into multiple containers if:
|
||||
- Deployed independently (separate serverless.yml files)
|
||||
- Different runtimes or dependencies
|
||||
- Owned by different teams
|
||||
|
||||
**Example:**
|
||||
```
|
||||
services/
|
||||
├── user-service/serverless.yml → C2 Container
|
||||
├── order-service/serverless.yml → C2 Container
|
||||
└── payment-service/serverless.yml → C2 Container
|
||||
```
|
||||
|
||||
**Rule:** Deployment boundary = container boundary
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Checklists
|
||||
|
||||
### Container Type Checklist
|
||||
|
||||
- [ ] `spa` - Single-page application (browser)
|
||||
- [ ] `mobile-app` - iOS/Android application
|
||||
- [ ] `desktop-app` - Desktop application
|
||||
- [ ] `api` or `app-server` - Backend API server
|
||||
- [ ] `web-server` - Web server, reverse proxy
|
||||
- [ ] `database` - Relational or NoSQL database
|
||||
- [ ] `cache` - In-memory cache (Redis, Memcached)
|
||||
- [ ] `message-broker` - Message queue/event streaming
|
||||
- [ ] `worker` - Background job processor
|
||||
- [ ] `file-storage` - Object storage, file system
|
||||
|
||||
### Technology Detection Checklist
|
||||
|
||||
- [ ] **Primary Language** - JavaScript, TypeScript, Python, Java, etc.
|
||||
- [ ] **Framework** - React, Express, Django, Spring Boot, etc.
|
||||
- [ ] **Version** - Always include version numbers from manifests
|
||||
- [ ] **Key Libraries** - List important dependencies with purpose
|
||||
|
||||
### Runtime Environment Checklist
|
||||
|
||||
- [ ] **Environment** - browser / server / mobile / cloud / edge
|
||||
- [ ] **Platform** - OS, runtime version, supported browsers
|
||||
- [ ] **Containerized** - true / false
|
||||
- [ ] **Container Technology** - Docker, Kubernetes (if containerized)
|
||||
- [ ] **Deployment Model** - Standalone, replicated, serverless
|
||||
|
||||
### Communication Checklist
|
||||
|
||||
- [ ] **Protocol** - HTTP, gRPC, WebSocket, database, message queue
|
||||
- [ ] **Direction** - unidirectional / bidirectional
|
||||
- [ ] **Authentication** - JWT, OAuth, API key, none
|
||||
- [ ] **Format** - JSON, Protobuf, XML, binary
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- [ ] All required fields present (system_id, technology, runtime)
|
||||
- [ ] Timestamp newer than c1-systems.json
|
||||
- [ ] Valid container types used
|
||||
- [ ] Communication patterns documented
|
||||
- [ ] Observations categorized (8 categories)
|
||||
- [ ] Evidence provided for observations
|
||||
|
||||
---
|
||||
|
||||
## FORBIDDEN Rationalizations (Automatic Validation Failures)
|
||||
|
||||
When under pressure, you may be tempted to skip C2 methodology rules. These rationalizations are **always wrong** and trigger **automatic validation failures**:
|
||||
|
||||
**RULE:** If your thinking matches ANY of these rationalizations, STOP immediately. You are about to violate C2 methodology. Do not proceed without addressing the actual requirement.
|
||||
|
||||
**Consequences:**
|
||||
- Each rationalization triggers a CRITICAL severity observation
|
||||
- Validation scripts will fail with explicit error messages
|
||||
- Work containing these violations will be rejected
|
||||
|
||||
| Rationalization | Why It's Wrong |
|
||||
|-----------------|----------------|
|
||||
| "Versions can be refined later" | Creates technical debt, violates methodology. Do it right now. |
|
||||
| "Reading package.json is line-by-line analysis" | Manifest files are metadata, not code. Version detection is standard C2. |
|
||||
| "Version numbers get outdated anyway" | So does all documentation - not an excuse to skip standards. |
|
||||
| "Generic names are honest about current state" | Generic names violate C2 standards. Period. |
|
||||
| "Tech lead/senior approved it" | Authority doesn't override methodology. Push back professionally. |
|
||||
| "Each module is important" | Important ≠ C2 container. Many important things are C3 components. |
|
||||
| "Team needs granularity" | Then do C3 analysis. Don't pollute C2. |
|
||||
| "Good enough for now" | Standards exist for consistency across all analysis. |
|
||||
| "Being pragmatic not dogmatic" | Pragmatism ≠ violating definitions. The methodology IS pragmatic. |
|
||||
| "We can add more detail later" | "Later" never comes. Do it correctly now. |
|
||||
| "The spirit of the rule allows this" | Violating the letter IS violating the spirit. |
|
||||
| "This case is different" | No it isn't. Apply the same standards uniformly. |
|
||||
|
||||
**If you catch yourself thinking any of these - STOP. Follow the methodology.**
|
||||
|
||||
---
|
||||
|
||||
## Still Having Issues?
|
||||
|
||||
### Enable Debug Mode
|
||||
|
||||
```bash
|
||||
# Run validation with verbose output
|
||||
python scripts/validate-c2-containers.py --verbose c2-containers.json
|
||||
|
||||
# Check for specific issues
|
||||
python scripts/validate-c2-containers.py --check-timestamps c2-containers.json
|
||||
```
|
||||
|
||||
### Common Debug Commands
|
||||
|
||||
```bash
|
||||
# Validate JSON syntax
|
||||
cat c2-containers.json | jq . > /dev/null && echo "Valid JSON" || echo "Invalid JSON"
|
||||
|
||||
# Check required fields
|
||||
cat c2-containers.json | jq '.containers[] | select(.technology.primary_language == null)'
|
||||
|
||||
# Verify timestamps
|
||||
cat c2-containers.json | jq '.metadata.timestamp, .metadata.parent.timestamp'
|
||||
|
||||
# List all container IDs
|
||||
cat c2-containers.json | jq '.containers[].id'
|
||||
```
|
||||
|
||||
### Get Help
|
||||
|
||||
1. Review CLAUDE.md workflow guide
|
||||
2. Check ${CLAUDE_PLUGIN_ROOT}/validation/templates/ for examples
|
||||
3. Compare with c4model-c1 successful pattern
|
||||
4. Ask user for clarification on unclear cases
|
||||
Reference in New Issue
Block a user