19 KiB
C4 Model Relations - Comprehensive Examples
Overview
This document provides comprehensive examples of relations across all three C4 Model levels, covering all major relation types.
Usage: Reference these examples when documenting your own architecture relations.
Table of Contents
C1 System Context Examples
Example 1: REST API Communication
{
"id": "rel-webapp-to-api",
"target": "backend-api",
"type": "http-rest",
"description": "Sends HTTP requests to fetch and update customer data",
"protocol": "HTTP/REST",
"direction": "outbound",
"isAsync": true,
"tags": ["api", "rest", "critical"]
}
Context: Web application calls backend API for all data operations Direction: Outbound (web app initiates requests) Protocol: RESTful HTTP
Example 2: External Payment Gateway
{
"id": "rel-api-to-payment",
"target": "stripe-payment-gateway",
"type": "external-api",
"description": "Processes payments via Stripe API for customer transactions",
"protocol": "HTTPS/REST",
"direction": "bidirectional",
"isAsync": true,
"tags": ["payment", "external", "stripe", "critical"]
}
Context: E-commerce system integrates with Stripe for payments Direction: Bidirectional (API calls Stripe, Stripe sends webhooks) Protocol: HTTPS with REST and webhook callbacks
Example 3: Message Queue Processing
{
"id": "rel-worker-to-queue",
"target": "rabbitmq",
"type": "message-queue",
"description": "Consumes background job messages for email notifications and data processing",
"protocol": "AMQP",
"direction": "inbound",
"isAsync": true,
"tags": ["async", "queue", "rabbitmq", "worker"]
}
Context: Worker service consumes messages from queue Direction: Inbound (queue pushes messages to worker) Protocol: AMQP (RabbitMQ)
Example 4: OAuth Authentication
{
"id": "rel-app-to-auth",
"target": "auth0",
"type": "authentication",
"description": "Authenticates users via OAuth 2.0 with social login support",
"protocol": "OAuth 2.0",
"direction": "outbound",
"isAsync": false,
"tags": ["auth", "oauth", "security", "auth0"]
}
Context: Application uses Auth0 for user authentication Direction: Outbound (app redirects to Auth0) Protocol: OAuth 2.0
Example 5: GraphQL API
{
"id": "rel-mobile-to-graphql",
"target": "graphql-api",
"type": "http-graphql",
"description": "Queries GraphQL API for flexible data fetching with nested relations",
"protocol": "HTTP/GraphQL",
"direction": "outbound",
"isAsync": true,
"tags": ["graphql", "api", "mobile"]
}
Context: Mobile app uses GraphQL for efficient data queries Direction: Outbound (mobile queries API) Protocol: GraphQL over HTTP
Example 6: WebSocket Real-Time Communication
{
"id": "rel-chat-to-websocket",
"target": "websocket-server",
"type": "websocket",
"description": "Maintains persistent WebSocket connection for real-time chat messages",
"protocol": "WebSocket (RFC 6455)",
"direction": "bidirectional",
"isAsync": true,
"tags": ["websocket", "realtime", "chat"]
}
Context: Chat application uses WebSocket for real-time messaging Direction: Bidirectional (messages flow both ways) Protocol: WebSocket
Example 7: gRPC Microservices
{
"id": "rel-gateway-to-services",
"target": "microservices-cluster",
"type": "grpc",
"description": "Communicates with microservices via gRPC for high-performance RPC calls",
"protocol": "HTTP/2 gRPC",
"direction": "outbound",
"isAsync": false,
"tags": ["grpc", "microservices", "rpc"]
}
Context: API gateway calls microservices via gRPC Direction: Outbound (gateway calls services) Protocol: gRPC over HTTP/2
Example 8: Event Stream Processing
{
"id": "rel-analytics-to-kafka",
"target": "kafka-cluster",
"type": "event-stream",
"description": "Consumes real-time clickstream events for analytics processing",
"protocol": "Kafka Protocol",
"direction": "inbound",
"isAsync": true,
"tags": ["kafka", "streaming", "analytics"]
}
Context: Analytics system processes events from Kafka Direction: Inbound (Kafka streams events to analytics) Protocol: Kafka streaming protocol
Example 9: Database Connection
{
"id": "rel-app-to-database",
"target": "postgres-cluster",
"type": "database-connection",
"description": "Connects to PostgreSQL cluster for persistent data storage",
"protocol": "PostgreSQL Wire Protocol",
"direction": "outbound",
"isAsync": false,
"tags": ["database", "postgres", "storage"]
}
Context: Application system connects to database system Direction: Outbound (app queries database) Protocol: PostgreSQL protocol
Example 10: Email Service Integration
{
"id": "rel-notif-to-sendgrid",
"target": "sendgrid",
"type": "external-api",
"description": "Sends transactional emails via SendGrid API",
"protocol": "HTTPS/REST",
"direction": "outbound",
"isAsync": true,
"tags": ["email", "sendgrid", "notifications"]
}
Context: Notification system sends emails via SendGrid Direction: Outbound (system calls SendGrid API) Protocol: HTTPS REST API
Example 11: File Transfer
{
"id": "rel-backup-to-s3",
"target": "aws-s3",
"type": "file-transfer",
"description": "Transfers backup files to S3 for long-term storage",
"protocol": "HTTPS S3 API",
"direction": "outbound",
"isAsync": true,
"tags": ["backup", "s3", "storage"]
}
Context: Backup system uploads files to S3 Direction: Outbound (backup pushes to S3) Protocol: S3 API over HTTPS
Example 12: Read Replica Access
{
"id": "rel-reporting-to-replica",
"target": "postgres-read-replica",
"type": "database-query",
"description": "Queries read replica for reporting without impacting primary database",
"protocol": "PostgreSQL Wire Protocol",
"direction": "outbound",
"isAsync": false,
"tags": ["database", "reporting", "read-replica"]
}
Context: Reporting system queries read-only replica Direction: Outbound (reporting queries replica) Protocol: PostgreSQL (read-only)
C2 Container Examples
Example 1: SPA to API
{
"id": "rel-spa-to-api",
"target": "express-api",
"type": "http-rest",
"description": "Fetches user data and submits forms via REST API endpoints",
"protocol": "HTTP/REST",
"isAsync": true,
"tags": ["rest", "ajax", "fetch", "spa"]
}
Context: React SPA calls Express backend Container Flow: Browser (SPA) → Server (API) Operations: GET, POST, PUT, DELETE
Example 2: API to PostgreSQL
{
"id": "rel-api-to-postgres",
"target": "postgres-container",
"type": "database-read-write",
"description": "Reads and writes application data using Sequelize ORM",
"protocol": "PostgreSQL Wire Protocol",
"isAsync": false,
"tags": ["database", "postgres", "sql", "sequelize"]
}
Context: Express API accesses PostgreSQL database Container Flow: API Server → Database Container Operations: Full CRUD via ORM
Example 3: API to Redis Cache
{
"id": "rel-api-to-redis",
"target": "redis-container",
"type": "cache-read-write",
"description": "Caches frequently accessed data to improve response times",
"protocol": "Redis Protocol (RESP)",
"isAsync": false,
"tags": ["cache", "redis", "performance"]
}
Context: API caches query results in Redis Container Flow: API Server → Cache Container Operations: GET, SET, DEL
Example 4: Worker to Message Queue
{
"id": "rel-worker-to-queue",
"target": "rabbitmq-container",
"type": "message-subscribe",
"description": "Consumes email notification jobs from RabbitMQ queue",
"protocol": "AMQP",
"isAsync": true,
"tags": ["queue", "worker", "email", "rabbitmq"]
}
Context: Worker consumes messages from RabbitMQ Container Flow: Worker Container ← Message Queue Container Pattern: Consumer (pull model)
Example 5: API to Message Queue
{
"id": "rel-api-to-queue",
"target": "rabbitmq-container",
"type": "message-publish",
"description": "Publishes order completion events for async processing",
"protocol": "AMQP",
"isAsync": true,
"tags": ["queue", "publisher", "async"]
}
Context: API publishes events to queue Container Flow: API Server → Message Queue Container Pattern: Publisher (push model)
Example 6: Frontend to GraphQL
{
"id": "rel-frontend-to-graphql",
"target": "graphql-server",
"type": "http-graphql",
"description": "Queries GraphQL API with Apollo Client for nested data fetching",
"protocol": "HTTP/GraphQL",
"isAsync": true,
"tags": ["graphql", "apollo", "queries"]
}
Context: Next.js frontend uses GraphQL API Container Flow: Frontend Container → GraphQL Server Container Operations: Query, Mutation
Example 7: API to S3 Storage
{
"id": "rel-api-to-s3",
"target": "aws-s3",
"type": "file-write",
"description": "Uploads user-generated images to S3 bucket",
"protocol": "HTTPS S3 API",
"isAsync": true,
"tags": ["s3", "upload", "images"]
}
Context: API uploads files to S3 Container Flow: API Server → S3 Storage Operations: PutObject, DeleteObject
Example 8: Worker Reading Files
{
"id": "rel-worker-to-s3",
"target": "aws-s3",
"type": "file-read",
"description": "Reads CSV files from S3 for batch processing",
"protocol": "HTTPS S3 API",
"isAsync": true,
"tags": ["s3", "batch", "csv"]
}
Context: Background worker processes files from S3 Container Flow: Worker Container → S3 Storage Operations: GetObject, ListObjects
Example 9: Browser to CDN
{
"id": "rel-browser-to-cdn",
"target": "cloudfront-cdn",
"type": "cdn-fetch",
"description": "Fetches static assets (JS, CSS, images) from CDN",
"protocol": "HTTPS",
"isAsync": true,
"tags": ["cdn", "static", "assets"]
}
Context: Browser loads assets from CloudFront Container Flow: Browser → CDN Operations: GET (cached assets)
Example 10: WebSocket Server
{
"id": "rel-client-to-websocket",
"target": "websocket-server",
"type": "websocket",
"description": "Maintains WebSocket connection for real-time notifications",
"protocol": "WebSocket Protocol",
"isAsync": true,
"tags": ["websocket", "realtime", "notifications"]
}
Context: Web client connects to WebSocket server Container Flow: Browser ↔ WebSocket Server (bidirectional) Operations: Send, Receive messages
Example 11: Service to MySQL
{
"id": "rel-service-to-mysql",
"target": "mysql-container",
"type": "database-connection",
"description": "Connects to MySQL database for general data operations",
"protocol": "MySQL Wire Protocol",
"isAsync": false,
"tags": ["database", "mysql", "generic"]
}
Context: Service container accesses MySQL Container Flow: Service Container → MySQL Container Operations: Mixed read/write
Example 12: Auth Service to Session Cache
{
"id": "rel-auth-to-cache",
"target": "redis-container",
"type": "cache-access",
"description": "Accesses session cache for user authentication state",
"protocol": "Redis Protocol",
"isAsync": false,
"tags": ["cache", "session", "auth"]
}
Context: Auth service stores sessions in Redis Container Flow: Auth Container → Redis Container Operations: Session management
C3 Component Examples
Example 1: Controller Uses Service
{
"id": "rel-controller-to-service",
"target": "user-service",
"type": "uses",
"description": "Delegates business logic operations to UserService",
"coupling": "loose",
"tags": ["service-layer", "delegation"]
}
Context: Layered architecture pattern Component Flow: UserController → UserService Pattern: Service layer delegation
Example 2: Service Injects Repository
{
"id": "rel-service-to-repo",
"target": "user-repository",
"type": "injects",
"description": "Injects UserRepository via dependency injection for data access",
"coupling": "loose",
"tags": ["di", "repository-pattern"]
}
Context: Dependency injection pattern Component Flow: UserService ← UserRepository (injected) Pattern: Constructor injection
Example 3: Auth Provides Context
{
"id": "rel-auth-to-user",
"target": "user-component",
"type": "provides",
"description": "Provides authenticated user information to consuming components",
"coupling": "loose",
"tags": ["auth", "context", "provider"]
}
Context: React context provider pattern Component Flow: AuthProvider → Consumers Pattern: Provider/Consumer
Example 4: Validator Extends Base
{
"id": "rel-validator-extends-base",
"target": "base-validator",
"type": "inherits",
"description": "Extends base validation logic with custom rules",
"coupling": "tight",
"tags": ["inheritance", "validation"]
}
Context: OOP inheritance hierarchy Component Flow: CustomValidator extends BaseValidator Pattern: Classical inheritance
Example 5: Payment Observes Order Events
{
"id": "rel-payment-observes-order",
"target": "order-component",
"type": "observes",
"description": "Listens to order completion events to trigger payment processing",
"coupling": "loose",
"tags": ["event", "observer-pattern", "payment"]
}
Context: Observer/subscriber pattern Component Flow: PaymentService ← OrderService (events) Pattern: Event-driven
Example 6: Order Notifies Subscribers
{
"id": "rel-order-notifies-payment",
"target": "payment-component",
"type": "notifies",
"description": "Emits order completion events to registered subscribers",
"coupling": "loose",
"tags": ["event", "publisher", "orders"]
}
Context: Publisher pattern Component Flow: OrderService → Subscribers Pattern: Event emitter
Example 7: Service Implements Interface
{
"id": "rel-service-implements-interface",
"target": "repository-interface",
"type": "implements",
"description": "Implements IUserRepository contract for data access abstraction",
"coupling": "loose",
"tags": ["interface", "contract", "di"]
}
Context: Interface-based programming Component Flow: UserRepository implements IUserRepository Pattern: Dependency inversion
Example 8: Logger Subscribes to Errors
{
"id": "rel-logger-subscribes-errors",
"target": "error-handler",
"type": "event-subscriber",
"description": "Subscribes to error events for centralized logging",
"coupling": "loose",
"tags": ["event", "logging", "observer"]
}
Context: Error handling with observers Component Flow: Logger ← ErrorHandler (events) Pattern: Event subscription
Example 9: Controller Calls Service Methods
{
"id": "rel-controller-calls-service",
"target": "order-service",
"type": "calls",
"description": "Invokes createOrder and getOrderById methods directly",
"coupling": "tight",
"tags": ["method-call", "direct-call"]
}
Context: Direct method invocation Component Flow: OrderController → OrderService.createOrder() Pattern: Direct coupling
Example 10: Component Composes Others
{
"id": "rel-order-composes-items",
"target": "order-item",
"type": "composes",
"description": "Composes OrderItem instances as integral parts of Order",
"coupling": "tight",
"tags": ["composition", "has-a"]
}
Context: Object composition Component Flow: Order has OrderItem[] Pattern: Composition (strong has-a)
Example 11: Component Aggregates References
{
"id": "rel-cart-aggregates-products",
"target": "product",
"type": "aggregates",
"description": "Aggregates Product references without owning them",
"coupling": "moderate",
"tags": ["aggregation", "reference"]
}
Context: Object aggregation Component Flow: ShoppingCart has Product[] (references) Pattern: Aggregation (weak has-a)
Example 12: Component Imports Utilities
{
"id": "rel-service-imports-utils",
"target": "date-utils",
"type": "imports",
"description": "Imports date formatting utilities via ES6 import",
"coupling": "tight",
"tags": ["import", "utilities"]
}
Context: Module imports Component Flow: OrderService imports { formatDate } from './utils' Pattern: ES6 modules
Example 13: Facade Delegates to Subsystems
{
"id": "rel-facade-delegates",
"target": "subsystems",
"type": "delegates",
"description": "Delegates complex operations to multiple subsystems",
"coupling": "moderate",
"tags": ["facade", "delegation"]
}
Context: Facade pattern Component Flow: OrderFacade → [PaymentService, InventoryService, ShippingService] Pattern: Facade
Example 14: Component Extends Functionality
{
"id": "rel-advanced-extends-basic",
"target": "basic-search",
"type": "extends",
"description": "Extends basic search with advanced filtering and sorting",
"coupling": "tight",
"tags": ["inheritance", "extension"]
}
Context: Feature extension via inheritance Component Flow: AdvancedSearch extends BasicSearch Pattern: Extension
Example 15: Consumer Uses Context
{
"id": "rel-profile-consumes-auth",
"target": "auth-context",
"type": "consumes",
"description": "Consumes authenticated user data from AuthContext",
"coupling": "loose",
"tags": ["context", "react", "consumer"]
}
Context: React context consumer Component Flow: UserProfile consumes AuthContext Pattern: Context API
Cross-Level Examples
Example: Full Stack Feature
C1 Level:
{
"source": "mobile-app",
"target": "backend-api",
"type": "http-rest",
"direction": "outbound"
}
C2 Level:
{
"source": "react-native-app",
"target": "express-api",
"type": "http-rest"
},
{
"source": "express-api",
"target": "postgres-db",
"type": "database-read-write"
}
C3 Level:
{
"source": "user-controller",
"target": "user-service",
"type": "uses",
"coupling": "loose"
},
{
"source": "user-service",
"target": "user-repository",
"type": "injects",
"coupling": "loose"
}
Summary
These examples demonstrate:
- C1 Relations: System-to-system communication patterns
- C2 Relations: Container-to-container interactions
- C3 Relations: Component-level dependencies and design patterns
Each example includes:
- Unique ID
- Target entity
- Relation type
- Clear description
- Appropriate metadata (direction, protocol, coupling)
- Tags for categorization
Use these as templates for documenting your own architecture relations.
Version: 1.0.0 Last Updated: 2025-11-17