gh-cubical6-melly/skills/c4model-c3/observation-guide.md

Observation Guide for C3 Components

This guide provides comprehensive methodology for documenting observations at the C3 level.

---

Observation Categories for C3

Observation Categories

When documenting components, capture these observation categories:

1. code-structure

Code organization patterns and file structure

Examples:

• "Feature-based structure with users/, orders/, products/ directories"
• "Layered architecture with controllers/, services/, repositories/ separation"
• "Domain-driven design with domain/, application/, infrastructure/ layers"
• "Monolithic structure - all code in single src/ directory"

2. design-patterns

Design patterns identified in code

Examples:

• "Singleton pattern for DatabaseConnection ensures single instance"
• "Repository pattern abstracts data access across all entities"
• "Factory pattern used for creating different user types"
• "Dependency injection via NestJS @Injectable decorators"
• "Observer pattern for event-driven order processing"

3. dependencies

Component dependencies and coupling

Examples:

• "UserService depends on UserRepository, EmailService, and ValidationUtil"
• "High coupling between OrderService and PaymentService (7 method calls)"
• "Circular dependency detected: UserService ↔ OrderService"
• "Controllers depend only on Services (proper layering)"

4. complexity

Code complexity metrics

Examples:

• "OrderService has cyclomatic complexity of 24 (high risk)"
• "UserController is 450 LOC (consider splitting)"
• "PaymentService has 12 public methods (large interface)"
• "Average complexity across services: 8 (acceptable)"

5. coupling

Coupling and cohesion analysis

Examples:

• "Tight coupling: UserService directly instantiates EmailService (no DI)"
• "Loose coupling: All dependencies injected via constructor"
• "High afferent coupling: UserModel imported by 15 components"
• "Low cohesion: UtilityService has unrelated helper methods"

6. cohesion

Component cohesion and single responsibility

Examples:

• "UserService has high cohesion - all methods relate to user management"
• "UtilityService has low cohesion - contains unrelated helpers"
• "OrderController violates SRP - handles both orders and payments"
• "Each repository focused on single entity (good cohesion)"

7. testing

Test coverage and testability

Examples:

• "UserService has 95% test coverage with 24 unit tests"
• "PaymentGateway untestable - uses hardcoded external URLs"
• "All services use dependency injection for easy mocking"
• "Controllers have integration tests covering main flows"

8. documentation

Code documentation quality

Examples:

• "All public methods have JSDoc comments"
• "UserService missing documentation for complex methods"
• "README.md in authentication/ explains module architecture"
• "Inline comments explain business logic in PaymentService"

Observation Structure for C3

{
  "id": "obs-repo-pattern-all-entities",
  "title": "Repository pattern used for all entity data access",
  "category": "design-patterns",
  "severity": "info",
  "pattern": "repository",
  "description": "All entities (User, Order, Product, Payment) have dedicated repository classes that abstract database operations using the Repository pattern. Repositories provide methods like findById, findAll, save, delete.",
  "evidence": [
    {
      "type": "pattern",
      "location": "src/users/UserRepository.ts",
      "snippet": "export class UserRepository { async findById(id: string): Promise<User> { ... } }"
    },
    {
      "type": "pattern",
      "location": "src/orders/OrderRepository.ts",
      "snippet": "export class OrderRepository { async findById(id: string): Promise<Order> { ... } }"
    }
  ],
  "impact": {
    "maintainability": "high",
    "testability": "high",
    "scalability": "medium"
  },
  "tags": ["repository-pattern", "data-access", "abstraction"]
}

Observation Severity Levels

• info - Informational observation (neutral)
• warning - Potential issue requiring attention
• critical - Critical issue requiring immediate action

Examples:

• ℹ️ info: "Repository pattern used for data access abstraction"
• ⚠️ warning: "Circular dependency between UserService and OrderService"
• 🔴 critical: "No input validation in UserController endpoints"