Initial commit

2025-11-29 18:17:07 +08:00
commit c0cd55ad8d
55 changed files with 15836 additions and 0 deletions
--- a/skills/c4model-c2/communication-patterns.md
+++ b/skills/c4model-c2/communication-patterns.md
@@ -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