gh-cubical6-melly/skills/c4model-c1/observation-categories.md

Observation Guidelines for C1 Level

Observation Categories

When documenting systems, capture these observation categories:

1. architecture

System-level architectural patterns and decisions.

Examples:

• "Microservices architecture with API gateway"
• "Monolithic architecture with single database"
• "Event-driven architecture using message queue"
• "Serverless architecture on AWS Lambda"

2. integration

External system integrations and communication patterns.

Examples:

• "Integrates with Stripe for payment processing"
• "Uses SendGrid for email notifications"
• "Connects to Auth0 for authentication"
• "Publishes events to Kafka message broker"

3. boundaries

System boundary definitions and scope.

Examples:

• "Public-facing web application accessible from internet"
• "Internal admin panel restricted to VPN access"
• "API gateway serves as single entry point for all services"
• "Database isolated in private subnet with no internet access"

4. security

Security posture, authentication, and authorization.

Examples:

• "JWT-based authentication with 1-hour token expiry"
• "OAuth 2.0 integration with Auth0"
• "API keys stored in environment variables"
• "HTTPS enforced for all communications"
• "No CSRF protection implemented" (warning)

5. scalability

Scalability patterns and constraints.

Examples:

• "Horizontally scalable API with load balancer"
• "CDN used for static asset delivery"
• "Database read replicas for scaling reads"
• "Stateless API design enables easy scaling"

6. actors

User types and external actors.

Examples:

• "Three primary user roles: customer, admin, support"
• "Anonymous users can browse products without login"
• "External payment provider (Stripe) integrated"
• "Third-party analytics service (Google Analytics) tracking users"

7. deployment

Deployment patterns, hosting, and infrastructure.

Examples:

• "Deployed on AWS using ECS containers"
• "Hosted on Vercel with automatic deployments"
• "On-premise deployment in company data center"
• "Serverless deployment using AWS Lambda"

8. technology-stack

Technologies, frameworks, and libraries used.

Examples:

• "React 18 with TypeScript for type safety"
• "Node.js runtime with Express framework"
• "PostgreSQL database with Prisma ORM"
• "Redis cache for session storage"

Observation Structure

{
  "id": "obs-arch-microservices",
  "title": "Microservices architecture with API gateway",
  "category": "architecture",
  "severity": "info",
  "description": "System follows microservices architecture with multiple independent services coordinated through an API gateway that handles routing, authentication, and rate limiting",
  "evidence": [
    {
      "type": "pattern",
      "location": "infrastructure/",
      "snippet": "Multiple service directories: auth-service/, user-service/, order-service/"
    }
  ],
  "tags": ["microservices", "api-gateway", "distributed"]
}

Observation Severity Levels

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

Examples:

• ℹ️ info: "Uses React 18 for frontend development"
• ⚠️ warning: "No rate limiting on API endpoints"
• 🔴 critical: "API keys hardcoded in source code"

Best Practices for Observations

DO:

1. Provide evidence - Include code snippets, file paths, or configuration examples
2. Be specific - "JWT auth with 1-hour expiry" not "uses JWT"
3. Tag appropriately - Use lowercase kebab-case tags
4. Set correct severity - Critical for security issues, info for informational
5. Link observations - Reference related systems or actors

DON'T:

1. Don't be vague - "Uses authentication" → "JWT-based auth with Auth0"
2. Don't skip evidence - Always include proof
3. Don't mix categories - One observation = one category
4. Don't ignore warnings - Document potential issues
5. Don't duplicate - Similar observations should be combined

Observation Discovery Commands

Find architectural patterns:

ls -la  # Check directory structure
grep -r "microservice\|monolith\|serverless" .

Find integrations:

cat .env.example | grep -E "API_KEY|WEBHOOK"
grep -r "stripe\|sendgrid\|twilio" package.json

Find security configurations:

grep -r "jwt\|JWT\|oauth\|OAuth" src/
grep -r "bcrypt\|crypto\|hash" src/
cat .env.example | grep -E "SECRET|KEY|TOKEN"

Find scalability indicators:

grep -r "load.?balance\|cluster\|replica" .
grep -r "cache\|Cache\|redis\|Redis" .

Find deployment info:

cat Dockerfile package.json docker-compose.yml
ls -la .github/workflows/ .gitlab-ci.yml
grep -r "aws\|AWS\|azure\|gcp" .