Initial commit

skills/c4model-relations/types.md

@@ -0,0 +1,498 @@
+# C4 Model Relation Types - Complete Reference
+
+## Overview
+
+This document provides comprehensive definitions for all relation types across C1, C2, and C3 levels of the C4 Model.
+
+**Usage:** Reference this document when choosing the appropriate relation type for your architecture documentation.
+
+---
+
+## Table of Contents
+
+1. [C1 System Context Relation Types](#c1-system-context-relation-types)
+2. [C2 Container Relation Types](#c2-container-relation-types)
+3. [C3 Component Relation Types](#c3-component-relation-types)
+4. [Type Selection Guidelines](#type-selection-guidelines)
+
+---
+
+## C1 System Context Relation Types
+
+### Network Communication Types
+
+#### http / https / http-rest
+**Description:** HTTP/HTTPS communication, typically RESTful APIs
+**When to use:** REST APIs, web requests, standard HTTP communication
+**Protocols:** HTTP/1.1, HTTP/2, HTTP/3
+**Direction:** Usually outbound (client calls server)
+**Example:** Web application calls backend REST API for data
+
+#### http-graphql
+**Description:** GraphQL API communication over HTTP
+**When to use:** GraphQL queries and mutations
+**Protocols:** HTTP with GraphQL
+**Direction:** Usually outbound (client queries server)
+**Example:** Frontend queries GraphQL API for flexible data fetching
+
+#### grpc
+**Description:** gRPC remote procedure calls
+**When to use:** High-performance RPC, microservice communication
+**Protocols:** HTTP/2 with Protocol Buffers
+**Direction:** Usually outbound (client calls service)
+**Example:** Microservices communicate via gRPC for low latency
+
+#### graphql
+**Description:** GraphQL protocol (alternative to http-graphql)
+**When to use:** When emphasizing GraphQL over HTTP transport
+**Example:** Same as http-graphql
+
+#### websocket
+**Description:** Bidirectional real-time communication
+**When to use:** Live updates, chat, real-time notifications
+**Protocols:** WebSocket Protocol (RFC 6455)
+**Direction:** Bidirectional
+**Example:** Chat application maintains persistent WebSocket connection
+
+#### rpc
+**Description:** Generic remote procedure call
+**When to use:** Custom RPC protocols, legacy RPC systems
+**Example:** XML-RPC, JSON-RPC communication
+
+#### soap
+**Description:** SOAP web services
+**When to use:** Enterprise integrations, legacy systems
+**Protocols:** SOAP over HTTP
+**Example:** Integration with enterprise ERP system
+
+### Messaging Types
+
+#### message-queue
+**Description:** Asynchronous messaging via message broker
+**When to use:** Event-driven architectures, async processing, decoupled systems
+**Protocols:** AMQP, Kafka Protocol, SQS API
+**Direction:** Outbound (publish) or Inbound (consume)
+**Example:** Order service publishes events to RabbitMQ for async processing
+
+#### event-stream
+**Description:** Event streaming platforms
+**When to use:** Real-time data pipelines, event sourcing, log aggregation
+**Protocols:** Kafka, Amazon Kinesis, Azure Event Hubs
+**Example:** Analytics system consumes clickstream events from Kafka
+
+### Data Access Types
+
+#### database-connection
+**Description:** Direct database access at system level
+**When to use:** System-to-database communication, primary database
+**Protocols:** PostgreSQL, MySQL, MongoDB protocols
+**Direction:** Outbound (system queries database)
+**Example:** Application system connects to PostgreSQL database
+
+#### database-query
+**Description:** Read-only database access
+**When to use:** Read replicas, reporting systems, analytics
+**Protocols:** SQL protocols (SELECT only)
+**Direction:** Outbound
+**Example:** Analytics dashboard queries PostgreSQL read replica
+
+### Integration Types
+
+#### authentication
+**Description:** Authentication and authorization flows
+**When to use:** Login flows, SSO, OAuth integrations
+**Protocols:** OAuth 2.0, SAML, OpenID Connect
+**Direction:** Outbound (system authenticates with provider)
+**Example:** Web application authenticates users via Auth0
+
+#### external-api
+**Description:** Third-party API integration
+**When to use:** Payment gateways, SaaS services, external data providers
+**Protocols:** REST, SOAP, GraphQL, proprietary
+**Direction:** Outbound (your system calls external API)
+**Example:** E-commerce system processes payments via Stripe API
+
+### Other Types
+
+#### file-transfer
+**Description:** File transfer protocols
+**When to use:** File uploads, downloads, FTP, SFTP
+**Protocols:** FTP, SFTP, SCP, HTTP multipart
+**Example:** Backup system transfers files to remote storage via SFTP
+
+#### smtp
+**Description:** Email protocol
+**When to use:** Email sending
+**Protocols:** SMTP
+**Example:** System sends transactional emails via SMTP
+
+---
+
+## C2 Container Relation Types
+
+### API Communication Types
+
+#### http-rest
+**Description:** RESTful HTTP API calls between containers
+**When to use:** Frontend to backend, service-to-service REST communication
+**Methods:** GET, POST, PUT, DELETE, PATCH
+**Typical containers:** SPA → API, API → Microservice
+**Example:** React SPA calls Express API endpoints
+
+#### http-graphql
+**Description:** GraphQL queries between containers
+**When to use:** Frontend GraphQL queries, flexible data fetching
+**Methods:** Query, Mutation, Subscription
+**Typical containers:** Apollo Client → GraphQL Server
+**Example:** Next.js app queries GraphQL API
+
+#### grpc
+**Description:** gRPC calls between containers
+**When to use:** High-performance inter-service communication
+**Typical containers:** Microservice → Microservice
+**Example:** Order service calls Inventory service via gRPC
+
+#### websocket
+**Description:** Real-time bidirectional communication
+**When to use:** Live updates, real-time collaboration, push notifications
+**Typical containers:** Browser → WebSocket Server
+**Example:** Chat client maintains WebSocket connection to server
+
+### Database Access Types
+
+#### database-query
+**Description:** Read-only database operations
+**When to use:** SELECT queries, read replicas, reporting
+**Operations:** SELECT
+**Typical containers:** API → Read Replica, Analytics → Database
+**Example:** API container reads user data from PostgreSQL read replica
+
+#### database-write
+**Description:** Write-only database operations
+**When to use:** INSERT, UPDATE, DELETE operations, write-specific workers
+**Operations:** INSERT, UPDATE, DELETE
+**Typical containers:** Worker → Database
+**Example:** Log aggregator writes logs to database
+
+#### database-read-write
+**Description:** Full database access (read and write)
+**When to use:** Primary API servers, application logic containers
+**Operations:** SELECT, INSERT, UPDATE, DELETE
+**Typical containers:** API → Primary Database
+**Example:** Express API reads and writes to PostgreSQL primary
+
+#### database-connection
+**Description:** Generic database connection (use specific types above when possible)
+**When to use:** When access pattern is unclear or mixed
+**Example:** General database connectivity
+
+### Cache Access Types
+
+#### cache-read
+**Description:** Read-only cache access
+**When to use:** Cache lookups, GET operations
+**Operations:** GET, EXISTS, TTL
+**Typical containers:** API → Cache
+**Example:** API reads session data from Redis
+
+#### cache-write
+**Description:** Write-only cache operations
+**When to use:** Cache updates, background cache warmers
+**Operations:** SET, SETEX, DEL
+**Typical containers:** Worker → Cache
+**Example:** Cache warmer updates frequently accessed data in Redis
+
+#### cache-read-write
+**Description:** Full cache access
+**When to use:** Typical caching patterns, read-through/write-through
+**Operations:** GET, SET, DEL, INCR, DECR
+**Typical containers:** API → Redis
+**Example:** API caches database query results in Redis
+
+#### cache-access
+**Description:** Generic cache access (use specific types above when possible)
+**When to use:** When access pattern is unclear
+**Example:** General cache connectivity
+
+### Message Queue Types
+
+#### message-publish
+**Description:** Publishes messages to queue or topic
+**When to use:** Event producers, async job creators
+**Patterns:** Pub-sub, work queue
+**Typical containers:** API → Queue, Service → Event Bus
+**Example:** Order API publishes order-created events to RabbitMQ
+
+#### message-subscribe / message-consumer
+**Description:** Consumes messages from queue or topic
+**When to use:** Event consumers, background workers
+**Patterns:** Pub-sub, work queue
+**Typical containers:** Worker → Queue
+**Example:** Email worker consumes notification jobs from SQS
+**Note:** `message-consumer` is an alias for `message-subscribe`
+
+### Storage Types
+
+#### file-read
+**Description:** Reads files from storage system
+**When to use:** File processing, data import, asset loading
+**Typical containers:** Worker → S3, API → File Storage
+**Example:** Image processor reads uploaded files from S3
+
+#### file-write
+**Description:** Writes files to storage system
+**When to use:** File uploads, data export, log writing
+**Typical containers:** API → S3, Worker → File Storage
+**Example:** API uploads user profile images to S3
+
+#### cdn-fetch
+**Description:** Fetches static assets from CDN
+**When to use:** Asset delivery, static resource loading
+**Typical containers:** Browser → CDN
+**Example:** Web app fetches CSS/JS/images from CloudFront
+
+### Other Types
+
+#### stream
+**Description:** Streaming data transfer
+**When to use:** Video/audio streaming, large file transfers
+**Example:** Video player streams content from media server
+
+---
+
+## C3 Component Relation Types
+
+### Dependency Types
+
+#### dependency
+**Description:** General dependency relationship
+**When to use:** Component depends on another for functionality
+**Coupling:** Varies (document as loose or tight)
+**Typical usage:** Any component dependency
+**Example:** Controller depends on Service for business logic
+
+#### uses
+**Description:** Uses another component's functionality
+**When to use:** Component actively uses another's methods or features
+**Coupling:** Loose to moderate
+**Typical usage:** Service uses Repository, Controller uses Service
+**Example:** UserController uses UserService for user operations
+
+#### calls
+**Description:** Directly invokes methods on another component
+**When to use:** Direct method calls, function invocation
+**Coupling:** Tight
+**Typical usage:** Any direct method invocation
+**Example:** Service calls specific repository methods
+
+### Object-Oriented Types
+
+#### inherits / extends
+**Description:** Class inheritance (is-a relationship)
+**When to use:** OOP inheritance hierarchies
+**Coupling:** Tight
+**Typical usage:** Class extends base class
+**Example:** UserController extends BaseController
+**Note:** Both `inherits` and `extends` are valid
+
+#### implements / interface-implementation
+**Description:** Implements an interface or contract
+**When to use:** Interface implementation, polymorphism
+**Coupling:** Loose
+**Typical usage:** Class implements interface
+**Example:** UserRepository implements IUserRepository
+**Note:** Both `implements` and `interface-implementation` are valid
+
+#### composes
+**Description:** Composition relationship (has-a, strong)
+**When to use:** Component contains another as integral part
+**Coupling:** Tight
+**Typical usage:** Object composition
+**Example:** Order composes OrderItem instances
+
+#### aggregates
+**Description:** Aggregation relationship (has-a, weak)
+**When to use:** Component references another but doesn't own it
+**Coupling:** Moderate
+**Typical usage:** Object aggregation
+**Example:** ShoppingCart aggregates Product references
+
+### Dependency Injection Types
+
+#### injects
+**Description:** Dependency injection
+**When to use:** DI frameworks, constructor/setter injection
+**Coupling:** Loose
+**Typical usage:** Service receives dependencies via DI container
+**Example:** UserService receives UserRepository via constructor injection
+
+#### provides
+**Description:** Provides data or functionality to consumers
+**When to use:** Provider pattern, dependency providers
+**Coupling:** Loose
+**Typical usage:** DI providers, context providers
+**Example:** AuthProvider provides authenticated user context
+
+#### consumes
+**Description:** Consumes data or functionality from provider
+**When to use:** Consumer pattern, dependency consumers
+**Coupling:** Loose
+**Typical usage:** Component consumes from provider
+**Example:** UserProfile consumes auth context from AuthProvider
+
+### Event-Driven Types
+
+#### observes / event-subscriber
+**Description:** Observer pattern - listens to events
+**When to use:** Event listeners, subscribers, reactive patterns
+**Coupling:** Loose
+**Typical usage:** Event-driven architectures
+**Example:** Logger observes error events from ErrorHandler
+**Note:** Both `observes` and `event-subscriber` are valid
+
+#### notifies / event-publisher
+**Description:** Publishes events or notifications
+**When to use:** Event emitters, publishers, observable patterns
+**Coupling:** Loose
+**Typical usage:** Event-driven architectures
+**Example:** OrderService notifies subscribers when order is placed
+**Note:** Both `notifies` and `event-publisher` are valid
+
+### Other Types
+
+#### imports
+**Description:** Direct ES6/CommonJS module import
+**When to use:** JavaScript/TypeScript module imports
+**Coupling:** Tight
+**Typical usage:** Any module import
+**Example:** Component imports utility functions
+
+#### delegates
+**Description:** Delegates operations to another component
+**When to use:** Delegation pattern, facades
+**Coupling:** Moderate
+**Typical usage:** Facade pattern, delegation
+**Example:** UserFacade delegates operations to multiple subsystems
+
+---
+
+## Type Selection Guidelines
+
+### Choosing Between Similar Types
+
+#### http vs http-rest vs http-graphql
+- Use **`http-rest`** for RESTful APIs (preferred)
+- Use **`http-graphql`** for GraphQL APIs (preferred)
+- Use **`http`** only when protocol is unclear (avoid if possible)
+
+#### database-connection vs database-query vs database-read-write
+- Use **`database-query`** for read-only access (SELECT)
+- Use **`database-write`** for write-only access (INSERT/UPDATE/DELETE)
+- Use **`database-read-write`** for full access (most common)
+- Use **`database-connection`** only as fallback
+
+#### cache-access vs cache-read vs cache-write
+- Use **`cache-read`** for read-only (GET operations)
+- Use **`cache-write`** for write-only (SET operations)
+- Use **`cache-read-write`** for both (most common)
+- Use **`cache-access`** only as fallback
+
+#### message-subscribe vs message-consumer
+- Both are valid (aliases)
+- Use **`message-subscribe`** for clarity (preferred)
+- Use **`message-consumer`** if it reads better in your context
+
+#### implements vs interface-implementation
+- Both are valid
+- Use **`implements`** for brevity (preferred)
+- Use **`interface-implementation`** if you need to be explicit
+
+#### observes vs event-subscriber
+- Both are valid
+- Use **`observes`** for brevity (preferred)
+- Use **`event-subscriber`** if you need to be explicit
+
+#### notifies vs event-publisher
+- Both are valid
+- Use **`notifies`** for brevity (preferred)
+- Use **`event-publisher`** if you need to be explicit
+
+### Level-Specific Guidelines
+
+#### C1 System Context
+**Focus:** Communication protocols between systems
+**Prefer:** Specific types (`http-rest` over `http`)
+**Always include:** `direction` and `protocol` fields
+
+#### C2 Container
+**Focus:** Container-to-container interactions
+**Prefer:** Access-specific types (`database-read-write` over `database-connection`)
+**Always include:** `protocol` and `isAsync` fields
+
+#### C3 Component
+**Focus:** Code-level dependencies and patterns
+**Prefer:** Pattern-specific types (`injects` over `dependency`)
+**Always include:** `coupling` field
+
+---
+
+## Examples by Level
+
+### C1 Examples
+```json
+{ "type": "http-rest", "description": "Fetches data via REST API" }
+{ "type": "grpc", "description": "High-performance RPC calls" }
+{ "type": "message-queue", "description": "Publishes events to AMQP queue" }
+{ "type": "authentication", "description": "Authenticates via OAuth 2.0" }
+```
+
+### C2 Examples
+```json
+{ "type": "http-rest", "description": "REST API calls from SPA to backend" }
+{ "type": "database-read-write", "description": "Full database access via ORM" }
+{ "type": "cache-read-write", "description": "Caches query results in Redis" }
+{ "type": "message-publish", "description": "Publishes order events to queue" }
+```
+
+### C3 Examples
+```json
+{ "type": "uses", "description": "Uses service for business logic" }
+{ "type": "injects", "description": "Injects repository via DI" }
+{ "type": "implements", "description": "Implements repository interface" }
+{ "type": "observes", "description": "Listens to order completion events" }
+```
+
+---
+
+## Validation Rules
+
+### All Levels
+- Type must be from the appropriate level enum
+- Description must be in active voice
+- ID must match pattern: `^rel-[a-z0-9-]+$`
+
+### C1 Specific
+- Must include `direction` field
+- Should include `protocol` for network communication
+
+### C2 Specific
+- Should include `protocol` for network communication
+- Should include `isAsync` for messaging/async operations
+
+### C3 Specific
+- Must include `coupling` field
+- Focus on code-level patterns
+
+---
+
+## References
+
+- **Detailed Reference:** [reference.md](./reference.md)
+- **Examples:** [examples.md](./examples.md)
+- **Main Skill:** [SKILL.md](./SKILL.md)
+- **Type Schema:** `${CLAUDE_PLUGIN_ROOT}/validation/templates/types-relations.json`
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2025-11-17