170 lines
4.7 KiB
Markdown
170 lines
4.7 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
```bash
|
||
ls -la # Check directory structure
|
||
grep -r "microservice\|monolith\|serverless" .
|
||
```
|
||
|
||
**Find integrations:**
|
||
```bash
|
||
cat .env.example | grep -E "API_KEY|WEBHOOK"
|
||
grep -r "stripe\|sendgrid\|twilio" package.json
|
||
```
|
||
|
||
**Find security configurations:**
|
||
```bash
|
||
grep -r "jwt\|JWT\|oauth\|OAuth" src/
|
||
grep -r "bcrypt\|crypto\|hash" src/
|
||
cat .env.example | grep -E "SECRET|KEY|TOKEN"
|
||
```
|
||
|
||
**Find scalability indicators:**
|
||
```bash
|
||
grep -r "load.?balance\|cluster\|replica" .
|
||
grep -r "cache\|Cache\|redis\|Redis" .
|
||
```
|
||
|
||
**Find deployment info:**
|
||
```bash
|
||
cat Dockerfile package.json docker-compose.yml
|
||
ls -la .github/workflows/ .gitlab-ci.yml
|
||
grep -r "aws\|AWS\|azure\|gcp" .
|
||
```
|