Initial commit

2025-11-29 18:17:07 +08:00
commit c0cd55ad8d
55 changed files with 15836 additions and 0 deletions
--- a/skills/c4model-observations/reference.md
+++ b/skills/c4model-observations/reference.md
@@ -0,0 +1,883 @@
+# Observation Documentation Reference
+
+**Complete guide for documenting architectural observations across C1, C2, and C3 levels.**
+
+---
+
+## Table of Contents
+
+1. [Category Definitions](#category-definitions)
+2. [Evidence Collection Guidelines](#evidence-collection-guidelines)
+3. [Severity Level Best Practices](#severity-level-best-practices)
+4. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+5. [Cross-Level Consistency](#cross-level-consistency)
+6. [Validation Requirements](#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:**
+```json
+{
+  "type": "file",
+  "location": "src/repositories/UserRepository.ts",
+  "note": "Repository pattern implementation"
+}
+```
+
+**Good code evidence:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "description": "The authentication approach is poorly designed and should be refactored."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "description": "JWT tokens stored in localStorage are vulnerable to XSS attacks.",
+  "recommendation": "Migrate to httpOnly cookies"
+}
+```
+
+---
+
+### 2. Vague Observations
+
+❌ **Bad:**
+```json
+{
+  "title": "Performance issues",
+  "description": "The system is slow."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "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:**
+```json
+{
+  "title": "Uses event-driven architecture",
+  "description": "The system has an event-driven design."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "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:**
+```json
+{
+  "severity": "critical",
+  "title": "Using older version of React",
+  "description": "React 17 instead of React 18"
+}
+```
+
+✅ **Good:**
+```json
+{
+  "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):**
+```json
+{
+  "category": "code-quality",
+  "title": "High cyclomatic complexity in AuthService"
+}
+```
+
+✅ **Good (C1 level):**
+```json
+{
+  "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](examples.md)** - 30+ complete examples
+- **[categories.md](categories.md)** - Category quick reference
+- **Validation scripts** - `${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-*.py`
+- **Type definitions** - `${CLAUDE_PLUGIN_ROOT}/validation/templates/types-observations.json`