zhongwei/gh-cubical6-melly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c0cd55ad8dc90e611fab21d7c90fccfdecf4a524
gh-cubical6-melly/skills/c4model-observations/reference.md
Zhongwei Li c0cd55ad8d Initial commit
2025-11-29 18:17:07 +08:00

21 KiB
Raw Blame History

Observation Documentation Reference

Complete guide for documenting architectural observations across C1, C2, and C3 levels.

Table of Contents

  1. Category Definitions
  2. Evidence Collection Guidelines
  3. Severity Level Best Practices
  4. Anti-Patterns to Avoid
  5. Cross-Level Consistency
  6. Validation Requirements

Category Definitions

C1 System Context Categories

architecture

Definition: Overall system architecture patterns, styles, and strategic decisions.

What to document:

  • Architectural styles (monolith, microservices, event-driven, layered)
  • System decomposition approach
  • Major architectural patterns (CQRS, event sourcing, etc.)
  • High-level structural decisions

Examples:

  • "Event-driven architecture with message queues"
  • "Microservices architecture with API gateway"
  • "Monolithic layered architecture"

integration

Definition: How systems integrate and communicate with each other.

What to document:

  • Integration patterns (REST, GraphQL, gRPC, messaging)
  • API contracts and interfaces
  • Data exchange formats
  • Synchronous vs asynchronous communication

Examples:

  • "Systems communicate via REST APIs over HTTPS"
  • "Event-driven integration using RabbitMQ"
  • "GraphQL gateway for unified API access"

boundaries

Definition: System scope, ownership boundaries, and organizational limits.

What to document:

  • What's inside vs outside the system
  • Team ownership boundaries
  • Deployment boundaries
  • Network boundaries (public/private/DMZ)

Examples:

  • "System boundary includes web app and API, excludes database"
  • "Frontend team owns UI system, backend team owns API system"

security

Definition: System-level security concerns, authentication, and authorization.

What to document:

  • Authentication mechanisms (OAuth, JWT, SAML)
  • Authorization approaches (RBAC, ABAC)
  • Security vulnerabilities
  • Data protection strategies

Examples:

  • "JWT-based authentication with OAuth2"
  • "No rate limiting on public API endpoints"
  • "TLS encryption for all inter-system communication"

scalability

Definition: System's ability to scale and handle growth.

What to document:

  • Horizontal vs vertical scaling approaches
  • Scaling limitations
  • Load balancing strategies
  • Stateless vs stateful design

Examples:

  • "Horizontally scalable via container orchestration"
  • "Vertical scaling limited by database constraints"
  • "Stateless design enables cloud auto-scaling"

actors

Definition: User types and external actors interacting with the system.

What to document:

  • User personas and roles
  • External systems acting as users
  • Actor permissions and capabilities

Examples:

  • "Three user types: Customer, Admin, Support Agent"
  • "External audit system queries via API"

external-dependencies

Definition: Third-party systems, services, and critical external dependencies.

What to document:

  • SaaS services and APIs
  • Third-party integrations
  • Dependency criticality
  • Fallback mechanisms

Examples:

  • "Critical dependency on Stripe payment gateway"
  • "SendGrid for email, with fallback to AWS SES"
  • "No fallback for authentication via Auth0"

deployment

Definition: Infrastructure, hosting, and deployment approaches.

What to document:

  • Cloud vs on-premise
  • Deployment strategies (blue-green, canary)
  • Infrastructure as code
  • Container orchestration

Examples:

  • "Deployed on AWS using Kubernetes"
  • "Blue-green deployment strategy with Terraform"
  • "On-premise deployment with Docker Swarm"

data-flow

Definition: How data moves between systems and external actors.

What to document:

  • Data flow directions
  • Data transformations
  • Data formats
  • Real-time vs batch processing

Examples:

  • "User data flows from web app to API to database"
  • "Analytics data streamed to data warehouse via Kafka"

C2 Container Categories

technology

Definition: Technology stack, frameworks, libraries, and languages.

What to document:

  • Programming languages
  • Frameworks and libraries
  • Runtime environments
  • Major dependencies

Examples:

  • "React 18 SPA with Redux Toolkit"
  • "Node.js 18 with Express.js framework"
  • "Python 3.11 with FastAPI"

runtime

Definition: Runtime characteristics, environment, and execution context.

What to document:

  • Runtime environment (Node.js, JVM, .NET)
  • Process model (single-threaded, multi-threaded)
  • Memory and resource requirements
  • Environment variables

Examples:

  • "Single-threaded Node.js event loop"
  • "JVM with 4GB heap size"
  • "Requires 16 environment variables"

communication

Definition: Inter-container communication protocols and patterns.

What to document:

  • Communication protocols (HTTP, gRPC, WebSocket)
  • API styles (REST, GraphQL)
  • Message formats (JSON, Protobuf)
  • Communication patterns (request/response, pub/sub)

Examples:

  • "REST API with JSON payloads"
  • "gRPC with Protobuf serialization"
  • "WebSocket for real-time updates"

data-storage

Definition: Databases, caches, and storage mechanisms.

What to document:

  • Database types (relational, NoSQL, graph)
  • Caching strategies
  • Storage technologies
  • Data persistence approaches

Examples:

  • "PostgreSQL 14 for relational data"
  • "Redis for session caching"
  • "MongoDB for document storage"

authentication

Definition: Container-level authentication and authorization.

What to document:

  • Authentication mechanisms
  • Token management
  • Session handling
  • Authorization strategies

Examples:

  • "JWT bearer token authentication"
  • "Session cookies with Redis storage"
  • "API key authentication for service-to-service"

deployment

Definition: Container deployment strategies and configurations.

What to document:

  • Containerization (Docker, etc.)
  • Orchestration (Kubernetes, Docker Swarm)
  • Deployment pipelines
  • Health checks and readiness probes

Examples:

  • "Docker container deployed on Kubernetes"
  • "Health check endpoint at /health"
  • "Blue-green deployment via ArgoCD"

scalability

Definition: Container-level scaling capabilities.

What to document:

  • Horizontal pod autoscaling
  • Replica counts
  • Resource limits
  • Scaling triggers

Examples:

  • "Auto-scales 2-10 pods based on CPU"
  • "Stateless design enables horizontal scaling"
  • "Limited by database connection pool size"

performance

Definition: Container performance characteristics and optimizations.

What to document:

  • Response times
  • Throughput capacity
  • Resource utilization
  • Performance optimizations

Examples:

  • "Average response time: 50ms"
  • "Code splitting and lazy loading implemented"
  • "Database queries not optimized with indexes"

dependencies

Definition: Container dependencies on other containers or services.

What to document:

  • Direct dependencies
  • Dependency versions
  • Dependency criticality
  • Coupling strength

Examples:

  • "Depends on API container and Redis cache"
  • "Critical dependency on database"
  • "Loose coupling via message queue"

configuration

Definition: Configuration management approaches.

What to document:

  • Configuration sources (env vars, config files, config servers)
  • Secret management
  • Feature flags
  • Configuration validation

Examples:

  • "Configuration via environment variables"
  • "Secrets stored in Kubernetes secrets"
  • "Feature flags managed in LaunchDarkly"

monitoring

Definition: Observability, logging, and monitoring.

What to document:

  • Logging frameworks and formats
  • Metrics collection
  • Tracing and APM
  • Alerting

Examples:

  • "Winston logger with JSON format"
  • "Prometheus metrics exposed at /metrics"
  • "No distributed tracing implemented"

C3 Component Categories

design-patterns

Definition: Design patterns and architectural patterns in code.

What to document:

  • Creational patterns (Factory, Singleton, Builder)
  • Structural patterns (Adapter, Decorator, Facade)
  • Behavioral patterns (Observer, Strategy, Command)
  • Domain patterns (Repository, Service, Entity)

Examples:

  • "Repository pattern for data access"
  • "Factory pattern for creating services"
  • "Observer pattern for event handling"

code-structure

Definition: Code organization, modularity, and file structure.

What to document:

  • Directory structure
  • Module organization
  • File naming conventions
  • Code grouping strategies

Examples:

  • "Feature-based directory structure"
  • "Layered architecture: controllers/services/repositories"
  • "Modules organized by domain"

dependencies

Definition: Component-level imports and dependencies.

What to document:

  • Import patterns
  • Circular dependencies
  • Dependency injection
  • Module coupling

Examples:

  • "Dependency injection via constructor"
  • "Circular dependency between User and Order modules"
  • "Heavy reliance on utility modules"

error-handling

Definition: Error handling strategies and patterns.

What to document:

  • Try-catch usage
  • Error propagation
  • Error logging
  • Custom error types

Examples:

  • "No error handling in async operations"
  • "Custom error classes for domain errors"
  • "Global error handler middleware"

testing

Definition: Test coverage, quality, and strategies.

What to document:

  • Unit test coverage
  • Integration tests
  • Test frameworks
  • Test quality

Examples:

  • "85% unit test coverage with Jest"
  • "No integration tests"
  • "Tests use actual database instead of mocks"

performance

Definition: Algorithm efficiency and code-level optimizations.

What to document:

  • Algorithm complexity
  • Performance bottlenecks
  • Optimization techniques
  • Resource usage

Examples:

  • "O(n²) algorithm for data processing"
  • "Memoization used for expensive calculations"
  • "No caching of computed values"

security

Definition: Security implementation details in code.

What to document:

  • Input validation
  • Output encoding
  • Secret handling
  • Vulnerability patterns

Examples:

  • "SQL injection vulnerability in query builder"
  • "JWT tokens stored in localStorage"
  • "Input validation using Joi schema"

code-quality

Definition: Code quality metrics and standards.

What to document:

  • Code complexity
  • Code duplication
  • Naming conventions
  • Code style

Examples:

  • "High cyclomatic complexity (>20)"
  • "Consistent naming conventions followed"
  • "Significant code duplication in controllers"

documentation

Definition: Code documentation quality and coverage.

What to document:

  • JSDoc/TSDoc comments
  • README files
  • API documentation
  • Inline comments

Examples:

  • "Comprehensive JSDoc for all public APIs"
  • "No documentation for complex algorithms"
  • "README outdated, doesn't match implementation"

complexity

Definition: Code complexity measurements.

What to document:

  • Cyclomatic complexity
  • Cognitive complexity
  • Function length
  • Nesting depth

Examples:

  • "Function with cyclomatic complexity of 45"
  • "Deep nesting (6 levels) in conditional logic"
  • "Functions average 150 lines (too long)"

coupling

Definition: Degree of interdependence between components.

What to document:

  • Tight vs loose coupling
  • Coupling to external libraries
  • Coupling to infrastructure
  • Circular dependencies

Examples:

  • "Tight coupling to ORM throughout codebase"
  • "Components loosely coupled via interfaces"
  • "Direct database access in UI components"

cohesion

Definition: How closely related component responsibilities are.

What to document:

  • Single Responsibility Principle adherence
  • Component focus
  • Mixed concerns

Examples:

  • "High cohesion: each service has single responsibility"
  • "Low cohesion: AuthService handles auth, logging, and config"

maintainability

Definition: How easy it is to maintain and modify the code.

What to document:

  • Code readability
  • Modification complexity
  • Technical debt
  • Refactoring needs

Examples:

  • "High maintainability with clear separation of concerns"
  • "Technical debt: hardcoded values throughout"
  • "Difficult to modify due to tight coupling"

Evidence Collection Guidelines

Best Practices

  1. Always provide file paths

    • Use relative paths from repository root
    • Include line numbers for code snippets: src/auth.ts:45-52
    • For directories, use trailing slash: src/controllers/

  2. Keep snippets concise

    • 1-10 lines maximum
    • Focus on the relevant part
    • Use ... to indicate omitted code

  3. Match evidence type to content

    • file - For file/directory existence: package.json, src/config/
    • code - For actual code snippets
    • config - For configuration values: .env, docker-compose.yml
    • pattern - For architectural patterns without specific file
    • metric - For quantitative measurements
    • dependency - For package dependencies from manifests

  4. Add context with notes

    • Explain what the evidence shows
    • Clarify non-obvious connections
    • Provide additional context

Evidence Examples

Good file evidence:

{
  "type": "file",
  "location": "src/repositories/UserRepository.ts",
  "note": "Repository pattern implementation"
}

Good code evidence:

{
  "type": "code",
  "location": "src/auth/AuthService.ts:45-47",
  "snippet": "localStorage.setItem('token', jwt);\nconst decoded = jwtDecode(jwt);\nreturn decoded;",
  "note": "JWT stored in localStorage, vulnerable to XSS"
}

Good config evidence:

{
  "type": "config",
  "location": "docker-compose.yml:15-18",
  "snippet": "redis:\n  image: redis:7-alpine\n  ports:\n    - '6379:6379'",
  "note": "Redis configured for caching"
}

Good pattern evidence:

{
  "type": "pattern",
  "location": "src/services/",
  "note": "Service layer pattern with dependency injection throughout codebase"
}

Severity Level Best Practices

Critical Severity

Use for:

  • Security vulnerabilities: XSS, SQL injection, exposed secrets, insecure authentication
  • Data loss risks: No backups, data deletion without confirmation
  • System unavailability: Single points of failure, no failover
  • Critical bugs: Core functionality broken, data corruption

Checklist:

  • ✅ Does this pose immediate risk to security, data, or availability?
  • ✅ Could this result in data breach or data loss?
  • ✅ Would this cause system downtime or service outage?
  • ✅ Is immediate action required?

Example:

{
  "severity": "critical",
  "title": "SQL injection vulnerability in user query",
  "description": "User input directly concatenated into SQL query without sanitization.",
  "impact": "Attackers can execute arbitrary SQL commands, access/modify all data",
  "recommendation": "Use parameterized queries immediately"
}

Warning Severity

Use for:

  • Performance issues: N+1 queries, inefficient algorithms, resource leaks
  • Code quality: High complexity, duplication, poor naming
  • Missing best practices: No error handling, no tests, deprecated dependencies
  • Architectural concerns: Anti-patterns, tight coupling, violations of SOLID

Checklist:

  • ✅ Should this be fixed but isn't immediately critical?
  • ✅ Does this impact performance, maintainability, or scalability?
  • ✅ Is this a violation of best practices?
  • ✅ Could this become critical if left unaddressed?

Example:

{
  "severity": "warning",
  "title": "Database connections not pooled",
  "description": "New database connection created for each request.",
  "impact": "High latency and connection exhaustion under load",
  "recommendation": "Implement connection pooling"
}

Info Severity

Use for:

  • Design patterns: Documented architectural patterns
  • Technology stack: Frameworks and libraries in use
  • Good practices: Well-implemented features
  • Architectural decisions: Strategic technical choices
  • System capabilities: Features and functionality

Checklist:

  • ✅ Is this neutral or positive information?
  • ✅ Does this document "what is" without judgment?
  • ✅ Is this useful for understanding the system?
  • ✅ Is no action required?

Example:

{
  "severity": "info",
  "title": "Event-driven architecture with RabbitMQ",
  "description": "System uses message queues for async processing between services.",
  "impact": "Enables loose coupling and horizontal scaling"
}

Anti-Patterns to Avoid

1. Opinion Instead of Fact

❌ Bad:

{
  "description": "The authentication approach is poorly designed and should be refactored."
}

✅ Good:

{
  "description": "JWT tokens stored in localStorage are vulnerable to XSS attacks.",
  "recommendation": "Migrate to httpOnly cookies"
}

2. Vague Observations

❌ Bad:

{
  "title": "Performance issues",
  "description": "The system is slow."
}

✅ Good:

{
  "title": "N+1 query problem in user dashboard",
  "description": "Dashboard loads user posts in a loop, executing one query per post instead of batching.",
  "evidence": [{"type": "code", "location": "src/dashboard.ts:78"}]
}

3. Missing Evidence

❌ Bad:

{
  "title": "Uses event-driven architecture",
  "description": "The system has an event-driven design."
}

✅ Good:

{
  "title": "Event-driven architecture with RabbitMQ",
  "description": "System uses RabbitMQ message broker for async event processing.",
  "evidence": [
    {"type": "config", "location": "docker-compose.yml", "snippet": "rabbitmq:..."},
    {"type": "dependency", "location": "package.json", "snippet": "\"amqplib\": \"^0.10.3\""}
  ]
}

4. Wrong Severity

❌ Bad:

{
  "severity": "critical",
  "title": "Using older version of React",
  "description": "React 17 instead of React 18"
}

✅ Good:

{
  "severity": "warning",
  "title": "React version outdated",
  "description": "Using React 17.0.2, missing React 18 performance improvements",
  "recommendation": "Upgrade to React 18 for concurrent features"
}

5. Wrong Category Level

❌ Bad (C1 level):

{
  "category": "code-quality",
  "title": "High cyclomatic complexity in AuthService"
}

✅ Good (C1 level):

{
  "category": "architecture",
  "title": "Microservices architecture with API gateway"
}

Code quality is a C3 category; architecture is appropriate for C1

Cross-Level Consistency

Observation Granularity

C1 observations should be high-level:

  • System-wide patterns
  • External integrations
  • System boundaries
  • Actor interactions

C2 observations should be mid-level:

  • Container technologies
  • Inter-container communication
  • Container deployment
  • Container-level performance

C3 observations should be detailed:

  • Code patterns
  • Component structure
  • Implementation details
  • Code quality metrics

Avoid Duplication Across Levels

If the same observation applies to multiple levels, document it at the highest appropriate level and reference it at lower levels.

Example:

  • C1: "System uses PostgreSQL for data persistence"
  • C2: "API container connects to PostgreSQL database"
  • C3: Don't repeat—focus on component-specific details like query patterns

Validation Requirements

Required Field Validation

  1. ID format: Must match ^obs-[a-z0-9-]+$

    • ✅ obs-event-driven-arch
    • ❌ OBS-001, observation1

  2. Category: Must be valid for the C4 level

    • C1: 9 categories (architecture, integration, boundaries, ...)
    • C2: 12 categories (technology, runtime, communication, ...)
    • C3: 13 categories (design-patterns, code-structure, dependencies, ...)

  3. Severity: Must be critical, warning, or info

  4. Title: Max 100 characters, descriptive

  5. Description: Min 10 characters, detailed

Evidence Validation

  1. Type: Must be valid evidence type
  2. Location: Required, should be a valid path
  3. Snippet: Optional but recommended
  4. Note: Optional but helpful for context

Recommendation Validation

  • Critical observations MUST include recommendation
  • Warning observations SHOULD include recommendation
  • Info observations MAY include recommendation

Additional Resources

  • examples.md - 30+ complete examples
  • categories.md - Category quick reference
  • Validation scripts - ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-*.py
  • Type definitions - ${CLAUDE_PLUGIN_ROOT}/validation/templates/types-observations.json
Reference in New Issue View Git Blame Copy Permalink