zhongwei/gh-cubical6-melly

Fork 0

Files

Zhongwei Li c0cd55ad8d Initial commit

2025-11-29 18:17:07 +08:00

10 KiB

Raw Blame History

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:

{
  "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:

# 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:

{
  "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:

# 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:

{
  "target": "user-service",
  "type": "grpc",
  "direction": "outbound",
  "description": "Calls user authentication via gRPC",
  "protocol": {
    "service": "UserService",
    "methods": ["Authenticate", "GetProfile"]
  }
}

Detection Commands:

# 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):

{
  "target": "order-queue",
  "type": "message-publish",
  "direction": "outbound",
  "description": "Publishes order created events",
  "protocol": {
    "queue": "orders.created",
    "format": "JSON",
    "broker": "RabbitMQ"
  }
}

Example (Consumer):

{
  "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:

# 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:

{
  "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:

{
  "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:

# 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:

{
  "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:

# 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:

{
  "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:

# 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:

{
  "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:

# 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:

{
  "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:

# 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/