127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"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"
|