Initial commit
This commit is contained in:
Zhongwei Li
618
skills/c4model-c1/SKILL.md
Normal file
618
skills/c4model-c1/SKILL.md
Normal file
@@ -0,0 +1,618 @@
|
||||
---
|
||||
name: c4model-c1
|
||||
description: Use when performing C4 Model Level 1 (System Context) analysis to identify software systems, actors, and boundaries in a codebase. Invoke during architecture reverse engineering, system mapping, or when users mention "system context", "C1 level", "identify systems", "system boundaries", "architecture analysis", or "what systems exist". Essential for the /melly-c1-systems command workflow and understanding high-level architecture.
|
||||
---
|
||||
|
||||
# C4 Model - Level 1: System Context Analysis
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides C4 Model Level 1 (System Context) expertise for identifying and documenting software systems at the highest level of architectural abstraction.
|
||||
|
||||
**Mission:** Identify WHAT systems exist, WHO uses them, and HOW they relate—without diving into implementation details.
|
||||
|
||||
---
|
||||
|
||||
## C1 Level Definition
|
||||
|
||||
### What is System Context (C1)?
|
||||
|
||||
The System Context level shows the **big picture**—the systems and their environment:
|
||||
|
||||
- **Systems** - Self-contained software systems with clear boundaries
|
||||
- **Actors** - People and external systems that interact with your systems
|
||||
- **Relationships** - High-level communication between systems
|
||||
- **Boundaries** - Scope, ownership, and network boundaries
|
||||
|
||||
### Abstraction Level
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ C1: System Context │ ← THIS LEVEL
|
||||
│ "What systems exist?" │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ C2: Container Level │
|
||||
│ "What are the deployable units?" │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ C3: Component Level │
|
||||
│ "What are the code modules?" │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ C4: Code Level │
|
||||
│ "What are the classes/functions?" │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**At C1, focus on:**
|
||||
- ✅ System boundaries and scope
|
||||
- ✅ System purpose and responsibilities
|
||||
- ✅ User roles and actors
|
||||
- ✅ External integrations
|
||||
- ✅ High-level communication patterns
|
||||
|
||||
**At C1, do NOT focus on:**
|
||||
- ❌ Implementation technologies (that's C2)
|
||||
- ❌ Code structure (that's C3/C4)
|
||||
- ❌ Detailed APIs (that's C2/C3)
|
||||
- ❌ Internal components (that's C3)
|
||||
|
||||
---
|
||||
|
||||
## System Identification Methodology
|
||||
|
||||
### Step 1: Understand Repository Structure
|
||||
|
||||
Start by analyzing the repositories provided in `init.json`:
|
||||
|
||||
**Questions to ask:**
|
||||
1. How many repositories exist?
|
||||
2. What type is each repository (monorepo, single, microservice)?
|
||||
3. What package manifests exist (package.json, composer.json, etc.)?
|
||||
4. What is the directory structure?
|
||||
|
||||
**Repository-to-System Mapping:**
|
||||
- **Single repository** → Usually 1 system (sometimes 2 if frontend + backend)
|
||||
- **Monorepo** → One OR multiple systems (packages ≠ systems - see below)
|
||||
- **Microservices** → Each repository = 1 system
|
||||
- **Library** → Not a system itself, but used by systems
|
||||
|
||||
**Critical: Repository names are NOT system names.** Repository names like `nextjs-shop`, `react-frontend`, or `express-api` are developer shortcuts. C1 system names must describe business purpose, not technology.
|
||||
|
||||
**Critical: Monorepo packages are NOT automatically systems.** Multiple packages in a monorepo (e.g., `@platform/auth`, `@platform/users`) are often components (C3) of ONE system, not separate systems. Packages sharing the same npm scope (like `@platform/*`) are a strong signal they belong to one system. Test with: "Can Package A function independently without Package B?" and "Are they deployed separately?"
|
||||
|
||||
**Sanity check:** If you identify more than 5-8 systems from a single monorepo, you're likely over-granularizing. Re-evaluate with the diagnostic questions.
|
||||
|
||||
### Step 2: Apply System Identification Rules
|
||||
|
||||
A **system** at C1 level is:
|
||||
|
||||
#### ✅ A System IS:
|
||||
|
||||
1. **Independently deployable**
|
||||
- Can be built and deployed separately
|
||||
- Has its own runtime environment
|
||||
- Example: "Web Application", "REST API Service"
|
||||
|
||||
2. **Self-contained with clear boundaries**
|
||||
- Has defined inputs and outputs
|
||||
- Clear scope of responsibility
|
||||
- Example: "Payment Processing System", "User Database"
|
||||
|
||||
3. **Has a distinct purpose**
|
||||
- Solves a specific business problem
|
||||
- Provides specific functionality
|
||||
- Example: "Order Management System", "Notification Service"
|
||||
|
||||
4. **External third-party services**
|
||||
- Services outside your control
|
||||
- Third-party integrations
|
||||
- Example: "Stripe Payment Gateway", "SendGrid Email Service"
|
||||
|
||||
5. **Major infrastructure components** (ONLY if criteria below are met)
|
||||
- Databases, message queues, caches
|
||||
- **Include as C1 system ONLY when ALL of these apply:**
|
||||
- They are shared by multiple systems (3+ services; 2 is borderline - use judgment)
|
||||
- They have independent operational ownership (separate team manages it)
|
||||
- They are externally managed services (e.g., AWS RDS, CloudAMQP)
|
||||
- **Keep at C2 level when ANY of these apply:**
|
||||
- They are internal to a single system
|
||||
- They are implementation details of one application
|
||||
- They are defined in the same docker-compose.yml as the application
|
||||
- **Docker-compose test:** If infrastructure (db, cache, queue) is in the same docker-compose as your app, it's almost always C2, not C1
|
||||
- **Replacement test:** "Could we replace PostgreSQL with MySQL without changing what systems exist?" If YES → C2 detail
|
||||
- Example (C1): "Central Customer Database" (shared by all systems, separate DBA team)
|
||||
- Example (C2): PostgreSQL in order-service's docker-compose.yml
|
||||
|
||||
#### ❌ A System is NOT:
|
||||
|
||||
1. **Technology/framework names**
|
||||
- ❌ "React Frontend" → ✅ "Customer Web Application"
|
||||
- ❌ "Express Backend" → ✅ "E-Commerce API"
|
||||
- ❌ "Django App" → ✅ "Content Management System"
|
||||
|
||||
2. **Internal code modules** (these are C3 components)
|
||||
- ❌ "Authentication Module"
|
||||
- ❌ "Payment Controller"
|
||||
- ❌ "User Service Class"
|
||||
|
||||
3. **Over-granular responsibilities** (combine into one system)
|
||||
- ❌ "Login System" + "Registration System" → ✅ "User Management System"
|
||||
- ❌ "Product List System" + "Product Detail System" → ✅ "Product Catalog System"
|
||||
- **Team ownership does NOT define system boundaries.** Different team members maintaining different packages/modules is a code organization concern (C3), not system architecture (C1). One system can have multiple components maintained by different people.
|
||||
- **Diagnostic questions:** Do they share the same core domain entity? Are they deployed together? Do they have tight coupling? If YES to any → consolidate into one system.
|
||||
|
||||
4. **Vague names without clear purpose**
|
||||
- ❌ "Frontend"
|
||||
- ❌ "Backend"
|
||||
- ❌ "Service"
|
||||
|
||||
### Step 3: Analyze Package Manifests
|
||||
|
||||
Package manifests reveal system purpose:
|
||||
|
||||
**npm/package.json indicators:**
|
||||
```javascript
|
||||
{
|
||||
"name": "customer-portal", // System name hint
|
||||
"dependencies": {
|
||||
"react": "^18.0.0", // Frontend system
|
||||
"express": "^4.18.0" // Backend system (if same repo)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Common patterns:**
|
||||
- `react` / `vue` / `angular` → Web Application (frontend)
|
||||
- `express` / `fastify` / `koa` → API Service (backend)
|
||||
- `next` / `nuxt` → Full-stack Web Application
|
||||
- `@nestjs/core` → Backend API Service
|
||||
- `electron` → Desktop Application
|
||||
- `react-native` → Mobile Application
|
||||
|
||||
### Step 4: Detect System Type
|
||||
|
||||
Classify each system by type:
|
||||
|
||||
**Common System Types:**
|
||||
- `web-application` - User-facing web interfaces
|
||||
- `mobile-application` - iOS, Android apps
|
||||
- `api-service` - REST APIs, GraphQL APIs, backend services
|
||||
- `database` - Relational, NoSQL databases
|
||||
- `message-broker` - Event streaming, message queues
|
||||
- `cache` - In-memory caches
|
||||
- `external-service` - Third-party APIs and services
|
||||
- `internal-service` - Background workers, cron jobs
|
||||
- `data-store` - File storage, object storage
|
||||
|
||||
### Step 5: Define System Boundaries
|
||||
|
||||
For each system, define three boundary dimensions:
|
||||
|
||||
#### 1. Scope Boundary
|
||||
- **internal** - Your team owns and controls it
|
||||
- **external** - Third-party, outside your control
|
||||
- **hybrid** - Mix of internal and external
|
||||
|
||||
#### 2. Deployment Boundary
|
||||
- **on-premise** - Your own infrastructure
|
||||
- **cloud** - AWS, Azure, GCP
|
||||
- **hybrid** - Mix of on-premise and cloud
|
||||
- **saas** - Software as a Service (external)
|
||||
- **unknown** - Cannot determine
|
||||
|
||||
#### 3. Network Boundary
|
||||
- **public** - Accessible from internet
|
||||
- **private** - Internal network only
|
||||
- **dmz** - Demilitarized zone, limited external access
|
||||
- **unknown** - Cannot determine
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"id": "customer-portal",
|
||||
"name": "Customer Web Application",
|
||||
"boundaries": {
|
||||
"scope": "internal",
|
||||
"deployment": "cloud",
|
||||
"network": "public"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actor, Relationship & Observation Guidelines
|
||||
|
||||
For detailed methodology on identifying and documenting:
|
||||
|
||||
- **Actors** (users and external systems) → See [actor-identification.md](./actor-identification.md)
|
||||
- **Relationships** (how systems communicate) → See [relationship-mapping.md](./relationship-mapping.md)
|
||||
- **Observations** (8 categories of findings) → See [observation-categories.md](./observation-categories.md)
|
||||
|
||||
### Quick Overview
|
||||
|
||||
**Actors:**
|
||||
- User actors: Customer, Administrator, Support Agent, etc.
|
||||
- External system actors: Stripe, SendGrid, Auth0, etc.
|
||||
|
||||
**Relationships:**
|
||||
- Types: http-rest, http-graphql, grpc, websocket, message-queue, database-query, authentication
|
||||
- Direction: outbound, inbound, or bidirectional
|
||||
- Always prefer outbound/inbound over bidirectional for clarity
|
||||
|
||||
**Observations (8 categories):**
|
||||
- architecture, integration, boundaries, security
|
||||
- scalability, actors, deployment, technology-stack
|
||||
|
||||
---
|
||||
|
||||
## Common Architecture Patterns
|
||||
|
||||
Four common patterns with concrete examples:
|
||||
|
||||
1. **Simple Web Application** - Frontend + Backend + Database
|
||||
2. **Microservices Architecture** - Multiple services with API gateway
|
||||
3. **Event-Driven System** - Async processing with message queue
|
||||
4. **Mobile + Backend** - Mobile app with backend API
|
||||
|
||||
For complete pattern details, systems, actors, relationships, and indicators → See [architecture-patterns.md](./architecture-patterns.md)
|
||||
|
||||
---
|
||||
|
||||
## Integration with Melly Workflow
|
||||
|
||||
### When This Skill is Used
|
||||
|
||||
This skill is activated during:
|
||||
|
||||
1. **Phase 1: Initialization** (`/melly-init`)
|
||||
- Repository scanning
|
||||
- Technology detection
|
||||
|
||||
2. **Phase 2: C1 System Identification** (`/melly-c1-systems`)
|
||||
- Primary usage phase
|
||||
- System identification
|
||||
- Actor identification
|
||||
- Boundary detection
|
||||
- Relationship mapping
|
||||
|
||||
3. **Phase 5: Documentation** (`/melly-doc-c4model`)
|
||||
- Markdown generation
|
||||
- Observation documentation
|
||||
|
||||
### Input Expectations
|
||||
|
||||
This skill expects data from `init.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": { ... },
|
||||
"repositories": [
|
||||
{
|
||||
"id": "frontend-spa",
|
||||
"name": "Frontend SPA",
|
||||
"path": "/repos/frontend-spa",
|
||||
"type": "single",
|
||||
"manifests": [ ... ],
|
||||
"structure": { ... },
|
||||
"technology": { ... }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
This skill helps generate `c1-systems.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"schema_version": "1.0.0",
|
||||
"generator": "melly-workflow",
|
||||
"generated_by": "c1-abstractor",
|
||||
"timestamp": "2025-11-15T20:10:00.000Z",
|
||||
"melly_version": "1.0.0",
|
||||
"parent_timestamp": "2025-11-15T20:00:00.000Z"
|
||||
},
|
||||
"systems": [
|
||||
{
|
||||
"id": "web-frontend",
|
||||
"name": "Web Frontend",
|
||||
"type": "web-application",
|
||||
"description": "Customer-facing e-commerce web application",
|
||||
"repositories": ["/repos/frontend-spa"],
|
||||
"boundaries": { ... },
|
||||
"responsibilities": [ ... ],
|
||||
"observations": [ ... ],
|
||||
"relations": [ ... ]
|
||||
}
|
||||
],
|
||||
"actors": [ ... ],
|
||||
"summary": {
|
||||
"total_systems": 4,
|
||||
"total_actors": 3,
|
||||
"system_types": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Validation
|
||||
|
||||
Generated output must pass:
|
||||
|
||||
1. **Schema validation** - Correct JSON structure
|
||||
2. **Timestamp ordering** - metadata.timestamp > parent_timestamp
|
||||
3. **Referential integrity** - All relation targets exist
|
||||
4. **Required fields** - All required fields present
|
||||
5. **ID format** - Kebab-case pattern
|
||||
|
||||
Validation script:
|
||||
```bash
|
||||
python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c1-systems.py c1-systems.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Workflow
|
||||
|
||||
### When Invoked by c1-abstractor Agent
|
||||
|
||||
Follow this systematic approach:
|
||||
|
||||
#### Step 1: Load Input Data
|
||||
```bash
|
||||
# Load init.json
|
||||
cat init.json | jq '.repositories'
|
||||
```
|
||||
|
||||
#### Step 2: Analyze Each Repository
|
||||
|
||||
For each repository:
|
||||
|
||||
1. **Identify primary purpose**
|
||||
- What does this repository do?
|
||||
- What is its main responsibility?
|
||||
|
||||
2. **Detect technology stack**
|
||||
- What frameworks/languages are used?
|
||||
- What does this tell us about system type?
|
||||
|
||||
3. **Check for external dependencies**
|
||||
- What third-party services are used?
|
||||
- What APIs are called?
|
||||
|
||||
4. **Map repository to system(s)**
|
||||
- Is this one system or multiple?
|
||||
- What is the system name?
|
||||
- What is the system type?
|
||||
|
||||
#### Step 3: Identify Actors
|
||||
|
||||
1. **Scan for user roles**
|
||||
```bash
|
||||
grep -r "role\|Role\|USER_ROLE\|UserRole" src/
|
||||
```
|
||||
|
||||
2. **Find external integrations**
|
||||
```bash
|
||||
cat .env.example | grep -E "API_KEY|API_URL|WEBHOOK"
|
||||
```
|
||||
|
||||
3. **Document each actor**
|
||||
- Name and type
|
||||
- What systems they interact with
|
||||
- Purpose/description
|
||||
|
||||
See [actor-identification.md](./actor-identification.md) for complete methodology.
|
||||
|
||||
#### Step 4: Define Boundaries
|
||||
|
||||
For each system:
|
||||
|
||||
1. **Determine scope** - Internal (we own it) or external?
|
||||
2. **Determine deployment** - Where does it run? (cloud, on-premise, SaaS)
|
||||
3. **Determine network** - Who can access it? (public, private, DMZ)
|
||||
|
||||
#### Step 5: Map Relationships
|
||||
|
||||
For each system:
|
||||
|
||||
1. **Find API calls**
|
||||
```bash
|
||||
grep -r "axios\|fetch\|http" src/
|
||||
```
|
||||
|
||||
2. **Identify communication patterns** - HTTP REST, GraphQL, WebSocket, message queue
|
||||
|
||||
3. **Document each relationship** - Source, target, type, direction, criticality
|
||||
|
||||
See [relationship-mapping.md](./relationship-mapping.md) for complete methodology.
|
||||
|
||||
#### Step 6: Generate Observations
|
||||
|
||||
For each system, document findings across 8 categories:
|
||||
- Architecture, Integration, Boundaries, Security
|
||||
- Scalability, Actors, Deployment, Technology Stack
|
||||
|
||||
See [observation-categories.md](./observation-categories.md) for complete guidance.
|
||||
|
||||
#### Step 7: Validate Output
|
||||
|
||||
Before finalizing:
|
||||
|
||||
1. **Check system IDs** - All kebab-case, all unique
|
||||
2. **Check relations** - All targets exist, directions specified
|
||||
3. **Check timestamps** - Child > parent
|
||||
4. **Run validation script**
|
||||
```bash
|
||||
python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c1-systems.py output.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
1. **Start with repository boundaries** - Repositories often map to systems
|
||||
2. **Focus on clear responsibilities** - Each system has one clear purpose
|
||||
3. **Keep it high-level** - Avoid implementation details
|
||||
4. **Document external dependencies** - Mark external systems clearly
|
||||
5. **Use descriptive names** - "Customer Web Application" not "Frontend"
|
||||
6. **Define all three boundary dimensions** - Scope, deployment, network
|
||||
7. **Document relationships with direction** - Prefer outbound/inbound over bidirectional
|
||||
8. **Provide evidence for observations** - Code snippets, config files, patterns
|
||||
9. **Tag observations appropriately** - Use lowercase kebab-case tags
|
||||
10. **Validate output before finalizing** - Run validation scripts
|
||||
|
||||
### ❌ DON'T:
|
||||
|
||||
1. **Don't use technology as system name** - ❌ "React App" → ✅ "Web Application"
|
||||
2. **Don't over-granularize** - ❌ "Login System" + "Register System" → ✅ "Auth System"
|
||||
3. **Don't identify components as systems** - Components are C3, not C1
|
||||
4. **Don't use vague names** - ❌ "Backend" → ✅ "E-Commerce API"
|
||||
5. **Don't mix abstraction levels** - Keep C1, C2, C3 separate
|
||||
6. **Don't skip external actors** - Third-party services are critical
|
||||
7. **Don't forget boundary definitions** - Always specify scope/deployment/network
|
||||
8. **Don't use generic relationship types** - ❌ "http" → ✅ "http-rest" or "http-graphql"
|
||||
9. **Don't ignore observations** - Document findings with evidence
|
||||
10. **Don't skip validation** - Always validate generated JSON
|
||||
|
||||
---
|
||||
|
||||
## Handling External Pressure
|
||||
|
||||
C4 Model rules are technical standards, not suggestions. Follow them even under pressure.
|
||||
|
||||
### Common Pressure Scenarios
|
||||
|
||||
| Pressure | Wrong Response | Correct Response |
|
||||
|----------|---------------|------------------|
|
||||
| **Authority demands tech name** ("Call it 'Next.js Shop', that's a direct order") | Comply because "boss knows best" | Explain C1 naming rules; business names show rigor |
|
||||
| **Client prefers over-granularized** ("12 systems is exactly what we need") | Keep it because "client is paying" | Consolidate and explain why fewer = clearer architecture |
|
||||
| **Team ownership argument** ("Each package has different maintainer, make them separate systems") | Split because "respects team structure" | Team ownership is C3 concern; system boundaries are about deployment and domain, not code organization |
|
||||
| **Ops visibility request** ("Show PostgreSQL and Redis as separate C1 systems so ops knows what to maintain") | Add as C1 because "ops needs visibility" | Keep at C2; explain C2 provides the ops view while C1 shows system context |
|
||||
| **Team familiarity argument** ("Everyone calls it 'Next.js Shop', use familiar names") | Use tech name because "team knows it" | Use business name; add familiar name in description: "internally known as 'Next.js Shop'" |
|
||||
| **Time pressure** ("10 minutes to meeting") | Use shortcuts because "no time" | Rules exist specifically for time pressure; shortcuts compound |
|
||||
| **Social pressure** ("Don't look dogmatic") | Compromise to "seem reasonable" | Technical accuracy > social comfort |
|
||||
|
||||
### Why Rules Apply Under Pressure
|
||||
|
||||
1. **Investors/clients judge rigor** - Technical stakeholders recognize proper C4 Model usage
|
||||
2. **Shortcuts compound** - One wrong name becomes 10 wrong names becomes unmaintainable docs
|
||||
3. **Reputation is long-term** - "Fixed it later" is remembered as "got it wrong initially"
|
||||
4. **Model integrity matters** - Violating C1 rules undermines the entire C4 analysis
|
||||
|
||||
### What to Say
|
||||
|
||||
**To authority demanding incorrect naming:**
|
||||
> "I understand the time pressure. But 'Next.js Shop' is a technology name, not a business name. C4 Model requires us to separate what (system) from how (technology). Technical investors will respect that we're using the model correctly. 'E-Commerce Platform' is the right C1 name—we'll show Next.js at C2 level."
|
||||
|
||||
**To client preferring over-granularization:**
|
||||
> "I appreciate the positive feedback on the detail level. Looking at these 12 items, I'm seeing consolidation opportunities—for example, these 4 auth-related items are all one User Authentication System at C1. Let me regroup to 4-5 core systems. This makes the architecture clearer and easier to reason about."
|
||||
|
||||
**To ops team requesting infrastructure as C1:**
|
||||
> "I understand ops needs visibility into PostgreSQL, Redis, and RabbitMQ—that's a valid concern. The C4 Model addresses this at C2 (Container) level, not C1. C1 shows what systems exist; C2 shows the deployable units within each system. I recommend we proceed to C2 documentation right after C1—that will give ops exactly the infrastructure visibility they need."
|
||||
|
||||
**To team ownership argument:**
|
||||
> "I understand each package has a different maintainer—that's good code organization. However, team ownership is about code structure (C3), not system architecture (C1). These packages share the same domain (user identity), deploy together, and can't function independently. That makes them components of one system, not separate systems. We'll show the package breakdown at C3 level."
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For common issues and solutions:
|
||||
- Too many systems identified
|
||||
- Can't determine system boundaries
|
||||
- Technology names in system IDs
|
||||
- Missing external actors
|
||||
- Relations without direction
|
||||
- Components identified as systems
|
||||
- Validation failures
|
||||
|
||||
See [troubleshooting-guide.md](./troubleshooting-guide.md) for complete troubleshooting guidance with examples and solutions.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### System Type Checklist
|
||||
|
||||
- [ ] `web-application` - User-facing web UI
|
||||
- [ ] `mobile-application` - iOS/Android app
|
||||
- [ ] `desktop-application` - Desktop app
|
||||
- [ ] `api-service` - Backend API
|
||||
- [ ] `database` - Data store
|
||||
- [ ] `message-broker` - Event streaming
|
||||
- [ ] `cache` - In-memory cache
|
||||
- [ ] `external-service` - Third-party service
|
||||
- [ ] `internal-service` - Worker/background service
|
||||
|
||||
### Boundary Checklist
|
||||
|
||||
- [ ] Scope: `internal` / `external` / `hybrid`
|
||||
- [ ] Deployment: `on-premise` / `cloud` / `saas` / `hybrid`
|
||||
- [ ] Network: `public` / `private` / `dmz`
|
||||
|
||||
### Relationship Type Checklist
|
||||
|
||||
- [ ] `http-rest` - RESTful API
|
||||
- [ ] `http-graphql` - GraphQL API
|
||||
- [ ] `grpc` - gRPC RPC
|
||||
- [ ] `websocket` - WebSocket
|
||||
- [ ] `message-queue` - Async messaging
|
||||
- [ ] `database-query` - Database access
|
||||
- [ ] `authentication` - Auth flow
|
||||
|
||||
### Observation Category Checklist
|
||||
|
||||
- [ ] `architecture` - Patterns and decisions
|
||||
- [ ] `integration` - External integrations
|
||||
- [ ] `boundaries` - Scope and access
|
||||
- [ ] `security` - Auth and vulnerabilities
|
||||
- [ ] `scalability` - Scaling patterns
|
||||
- [ ] `actors` - Users and external actors
|
||||
- [ ] `deployment` - Hosting and infrastructure
|
||||
- [ ] `technology-stack` - Technologies used
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Supporting Documentation
|
||||
|
||||
- [Actor Identification Methodology](./actor-identification.md)
|
||||
- [Relationship Mapping Guide](./relationship-mapping.md)
|
||||
- [Observation Categories](./observation-categories.md)
|
||||
- [Architecture Patterns](./architecture-patterns.md)
|
||||
- [Troubleshooting Guide](./troubleshooting-guide.md)
|
||||
|
||||
### Templates and Examples
|
||||
|
||||
- **Template**: `${CLAUDE_PLUGIN_ROOT}/validation/templates/c1-systems-template.json`
|
||||
- **Schema**: `/docs/json-schemas-design.md`
|
||||
- **Methodology**: `/docs/c4model-methodology.md`
|
||||
- **Workflow**: `/docs/workflow-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
This skill provides comprehensive knowledge of C4 Model Level 1 (System Context) methodology. When invoked:
|
||||
|
||||
1. **Analyze repositories** from `init.json`
|
||||
2. **Identify systems** using the rules above
|
||||
3. **Identify actors** (users and external systems)
|
||||
4. **Define boundaries** (scope, deployment, network)
|
||||
5. **Map relationships** between systems
|
||||
6. **Document observations** with evidence
|
||||
7. **Generate `c1-systems.json`** following the schema
|
||||
8. **Validate output** before finalizing
|
||||
|
||||
Remember: **C1 is about the big picture.** Focus on WHAT systems exist, WHO uses them, and HOW they relate—not the implementation details.
|
||||
|
||||
---
|
||||
|
||||
**Skill Version**: 2.0.0
|
||||
**Last Updated**: 2025-11-17
|
||||
**Compatibility**: Melly 1.0.0+
|
||||
116
skills/c4model-c1/actor-identification.md
Normal file
116
skills/c4model-c1/actor-identification.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# Actor Identification Methodology
|
||||
|
||||
## Types of Actors
|
||||
|
||||
Actors are people or systems that interact with your systems.
|
||||
|
||||
### 1. User Actors (People)
|
||||
|
||||
**Questions to ask:**
|
||||
- Who uses this system?
|
||||
- What user roles exist?
|
||||
- What are the personas?
|
||||
- What permissions do they have?
|
||||
|
||||
**Common user actors:**
|
||||
- **End User / Customer** - Primary users of customer-facing systems
|
||||
- **Administrator** - System administrators, super users
|
||||
- **Support Agent** - Customer support representatives
|
||||
- **Developer** - Internal developers using APIs
|
||||
- **Manager** - Business users viewing reports
|
||||
- **Guest / Anonymous User** - Unauthenticated visitors
|
||||
|
||||
**How to identify:**
|
||||
- Look for authentication/authorization code
|
||||
- Check user role definitions in code
|
||||
- Review database user/role tables
|
||||
- Analyze permission systems
|
||||
|
||||
**Code indicators:**
|
||||
```typescript
|
||||
// User roles indicate actors
|
||||
enum UserRole {
|
||||
CUSTOMER, // → Customer actor
|
||||
ADMIN, // → Administrator actor
|
||||
SUPPORT, // → Support Agent actor
|
||||
GUEST // → Anonymous User actor
|
||||
}
|
||||
```
|
||||
|
||||
### 2. External System Actors
|
||||
|
||||
**Questions to ask:**
|
||||
- What external services are integrated?
|
||||
- What third-party APIs are called?
|
||||
- What systems are outside our control?
|
||||
- What services do we depend on?
|
||||
|
||||
**Common external system actors:**
|
||||
- **Payment Providers** - Stripe, PayPal, Square
|
||||
- **Email Services** - SendGrid, Mailgun, AWS SES
|
||||
- **SMS Services** - Twilio, Nexmo
|
||||
- **Authentication Providers** - Auth0, Okta, Firebase Auth
|
||||
- **Analytics Services** - Google Analytics, Mixpanel
|
||||
- **CDN Services** - CloudFront, Cloudflare
|
||||
- **Cloud Storage** - AWS S3, Google Cloud Storage
|
||||
- **Monitoring Services** - Datadog, New Relic, Sentry
|
||||
|
||||
**How to identify:**
|
||||
- Search for API keys in config files (.env.example)
|
||||
- Check package dependencies for SDK libraries
|
||||
- Review environment variables
|
||||
- Look for external API base URLs
|
||||
|
||||
**Example external actors:**
|
||||
```bash
|
||||
# .env.example reveals external actors:
|
||||
STRIPE_API_KEY=sk_test_... # → Stripe actor
|
||||
SENDGRID_API_KEY=SG... # → SendGrid actor
|
||||
TWILIO_ACCOUNT_SID=AC... # → Twilio actor
|
||||
GOOGLE_ANALYTICS_ID=UA-... # → Google Analytics actor
|
||||
```
|
||||
|
||||
## Actor Documentation Format
|
||||
|
||||
```json
|
||||
{
|
||||
"actors": [
|
||||
{
|
||||
"id": "customer",
|
||||
"name": "Customer",
|
||||
"type": "user",
|
||||
"description": "End user who browses products and makes purchases",
|
||||
"interacts_with": ["customer-web-app", "mobile-app"]
|
||||
},
|
||||
{
|
||||
"id": "stripe",
|
||||
"name": "Stripe Payment Gateway",
|
||||
"type": "external-actor",
|
||||
"description": "Third-party payment processing service",
|
||||
"interacts_with": ["payment-api"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Search Commands for Actors
|
||||
|
||||
**Find user roles:**
|
||||
```bash
|
||||
grep -r "role\|Role\|USER_ROLE\|UserRole" src/
|
||||
grep -r "permissions\|Permissions" src/
|
||||
grep -r "enum.*Role\|class.*Role" src/
|
||||
```
|
||||
|
||||
**Find external integrations:**
|
||||
```bash
|
||||
cat .env.example | grep -E "API_KEY|API_URL|WEBHOOK|TOKEN"
|
||||
grep -r "stripe\|sendgrid\|twilio\|auth0" package.json
|
||||
grep -r "import.*stripe\|from.*sendgrid" src/
|
||||
```
|
||||
|
||||
**Find authentication code:**
|
||||
```bash
|
||||
grep -r "auth\|Auth\|authentication\|login" src/
|
||||
grep -r "jwt\|JWT\|oauth\|OAuth" src/
|
||||
```
|
||||
250
skills/c4model-c1/architecture-patterns.md
Normal file
250
skills/c4model-c1/architecture-patterns.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# Common Architecture Patterns
|
||||
|
||||
## Pattern 1: Simple Web Application
|
||||
|
||||
**Scenario:** Small web app with frontend and backend
|
||||
|
||||
**Systems identified:**
|
||||
1. **Web Frontend** (web-application)
|
||||
- User-facing SPA
|
||||
- Repository: `/frontend/`
|
||||
|
||||
2. **Backend API** (api-service)
|
||||
- REST API
|
||||
- Repository: `/backend/`
|
||||
|
||||
3. **PostgreSQL Database** (database)
|
||||
- Data persistence
|
||||
- External infrastructure
|
||||
|
||||
**Actors:**
|
||||
- End User (uses Web Frontend)
|
||||
|
||||
**Relationships:**
|
||||
- Web Frontend → Backend API (http-rest)
|
||||
- Backend API → PostgreSQL Database (database-query)
|
||||
|
||||
**Typical indicators:**
|
||||
- Two repositories: frontend/ and backend/
|
||||
- package.json with react/vue/angular in frontend
|
||||
- package.json with express/fastify in backend
|
||||
- Database connection string in .env
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Microservices Architecture
|
||||
|
||||
**Scenario:** Multiple services with API gateway
|
||||
|
||||
**Systems identified:**
|
||||
1. **API Gateway** (api-service)
|
||||
- Request routing
|
||||
- Repository: `/gateway/`
|
||||
|
||||
2. **Auth Service** (api-service)
|
||||
- Authentication
|
||||
- Repository: `/auth-service/`
|
||||
|
||||
3. **User Service** (api-service)
|
||||
- User management
|
||||
- Repository: `/user-service/`
|
||||
|
||||
4. **Order Service** (api-service)
|
||||
- Order processing
|
||||
- Repository: `/order-service/`
|
||||
|
||||
5. **Message Queue** (message-broker)
|
||||
- Event bus
|
||||
- External (RabbitMQ/Kafka)
|
||||
|
||||
**Actors:**
|
||||
- Mobile App (external system actor)
|
||||
- Administrator (user actor)
|
||||
|
||||
**Relationships:**
|
||||
- API Gateway → Auth Service (grpc)
|
||||
- API Gateway → User Service (grpc)
|
||||
- API Gateway → Order Service (grpc)
|
||||
- Order Service → Message Queue (message-queue)
|
||||
|
||||
**Typical indicators:**
|
||||
- Multiple service repositories (auth-service/, user-service/, etc.)
|
||||
- API gateway with routing configuration
|
||||
- gRPC or REST between services
|
||||
- Message queue dependency (rabbitmq, kafka)
|
||||
- Service discovery (consul, etcd)
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Event-Driven System
|
||||
|
||||
**Scenario:** Async processing with message queue
|
||||
|
||||
**Systems identified:**
|
||||
1. **Web Application** (web-application)
|
||||
- User interface
|
||||
- Repository: `/webapp/`
|
||||
|
||||
2. **Backend API** (api-service)
|
||||
- API layer
|
||||
- Repository: `/api/`
|
||||
|
||||
3. **Message Queue** (message-broker)
|
||||
- Event streaming
|
||||
- External (Kafka)
|
||||
|
||||
4. **Worker Service** (internal-service)
|
||||
- Background processing
|
||||
- Repository: `/worker/`
|
||||
|
||||
5. **Notification Service** (internal-service)
|
||||
- Email/SMS sending
|
||||
- Repository: `/notifications/`
|
||||
|
||||
**External Actors:**
|
||||
- SendGrid (email delivery)
|
||||
- Twilio (SMS delivery)
|
||||
|
||||
**Relationships:**
|
||||
- Web Application → Backend API (http-rest)
|
||||
- Backend API → Message Queue (message-queue, publish)
|
||||
- Worker Service → Message Queue (message-queue, subscribe)
|
||||
- Notification Service → Message Queue (message-queue, subscribe)
|
||||
- Notification Service → SendGrid (http-rest)
|
||||
- Notification Service → Twilio (http-rest)
|
||||
|
||||
**Typical indicators:**
|
||||
- Message queue dependency (kafka, rabbitmq, redis)
|
||||
- Worker/consumer services subscribe to topics
|
||||
- Async/background processing
|
||||
- Event publishing in API code
|
||||
- Email/SMS service integrations
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Mobile + Backend
|
||||
|
||||
**Scenario:** Mobile app with backend API
|
||||
|
||||
**Systems identified:**
|
||||
1. **Mobile Application** (mobile-application)
|
||||
- iOS/Android app
|
||||
- Repository: `/mobile-app/`
|
||||
|
||||
2. **Backend API** (api-service)
|
||||
- REST API
|
||||
- Repository: `/backend/`
|
||||
|
||||
3. **PostgreSQL Database** (database)
|
||||
- Data store
|
||||
- External infrastructure
|
||||
|
||||
4. **Redis Cache** (cache)
|
||||
- Session/data cache
|
||||
- External infrastructure
|
||||
|
||||
5. **Auth0** (external-service)
|
||||
- Authentication provider
|
||||
- External SaaS
|
||||
|
||||
**Actors:**
|
||||
- Mobile User (user actor)
|
||||
- Auth0 (external system actor)
|
||||
|
||||
**Relationships:**
|
||||
- Mobile Application → Backend API (http-rest)
|
||||
- Mobile Application → Auth0 (authentication, OAuth)
|
||||
- Backend API → PostgreSQL Database (database-query)
|
||||
- Backend API → Redis Cache (database-query)
|
||||
- Backend API → Auth0 (authentication, token validation)
|
||||
|
||||
**Typical indicators:**
|
||||
- React Native, Flutter, or native mobile code
|
||||
- Backend API with mobile-specific endpoints
|
||||
- OAuth/Auth0 integration
|
||||
- Push notification service
|
||||
- Redis for session/token caching
|
||||
- Mobile-specific features (geolocation, camera, etc.)
|
||||
|
||||
---
|
||||
|
||||
## How to Identify Architecture Pattern
|
||||
|
||||
### Ask These Questions:
|
||||
|
||||
1. **How many repositories?**
|
||||
- 1-2 repos → Simple Web App or Mobile + Backend
|
||||
- 3-5 repos → Event-Driven System
|
||||
- 5+ repos → Microservices Architecture
|
||||
|
||||
2. **Is there an API gateway?**
|
||||
- Yes → Likely Microservices
|
||||
- No → Likely Simple Web App or Event-Driven
|
||||
|
||||
3. **Is there a message queue?**
|
||||
- Yes → Event-Driven System or Microservices
|
||||
- No → Simple Web App or Mobile + Backend
|
||||
|
||||
4. **Is there a mobile app?**
|
||||
- Yes → Mobile + Backend pattern
|
||||
- No → Other patterns
|
||||
|
||||
5. **How many services?**
|
||||
- 1-2 services → Simple Web App
|
||||
- 3-4 services → Event-Driven
|
||||
- 5+ services → Microservices
|
||||
|
||||
### Pattern Decision Tree
|
||||
|
||||
```
|
||||
Start
|
||||
↓
|
||||
Mobile app exists?
|
||||
├─ Yes → Pattern 4: Mobile + Backend
|
||||
└─ No → Continue
|
||||
↓
|
||||
Message queue exists?
|
||||
├─ Yes → Pattern 3: Event-Driven
|
||||
└─ No → Continue
|
||||
↓
|
||||
API Gateway exists?
|
||||
├─ Yes → Pattern 2: Microservices
|
||||
└─ No → Pattern 1: Simple Web App
|
||||
```
|
||||
|
||||
## Pattern-Specific Observations
|
||||
|
||||
### Simple Web Application
|
||||
|
||||
**Common observations:**
|
||||
- Monolithic architecture
|
||||
- Direct database access from API
|
||||
- Session-based or JWT authentication
|
||||
- Single deployment unit per tier (frontend, backend)
|
||||
|
||||
### Microservices Architecture
|
||||
|
||||
**Common observations:**
|
||||
- Service-oriented architecture
|
||||
- Service discovery and registration
|
||||
- API gateway as single entry point
|
||||
- Inter-service communication (gRPC, REST)
|
||||
- Distributed data management
|
||||
|
||||
### Event-Driven System
|
||||
|
||||
**Common observations:**
|
||||
- Asynchronous message passing
|
||||
- Loose coupling between services
|
||||
- Event sourcing or CQRS patterns
|
||||
- Eventually consistent data
|
||||
- Background job processing
|
||||
|
||||
### Mobile + Backend
|
||||
|
||||
**Common observations:**
|
||||
- Mobile-first API design
|
||||
- OAuth/token-based authentication
|
||||
- Push notification support
|
||||
- Offline-first considerations
|
||||
- API versioning for mobile clients
|
||||
169
skills/c4model-c1/observation-categories.md
Normal file
169
skills/c4model-c1/observation-categories.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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" .
|
||||
```
|
||||
142
skills/c4model-c1/relationship-mapping.md
Normal file
142
skills/c4model-c1/relationship-mapping.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Relationship Identification
|
||||
|
||||
## Relationship Types
|
||||
|
||||
Document how systems communicate:
|
||||
|
||||
### Common Relationship Types
|
||||
|
||||
1. **http-rest** - RESTful HTTP API
|
||||
- Most common web API pattern
|
||||
- Example: Frontend calls backend REST API
|
||||
|
||||
2. **http-graphql** - GraphQL API
|
||||
- Query-based API pattern
|
||||
- Example: React app queries GraphQL server
|
||||
|
||||
3. **grpc** - gRPC remote procedure calls
|
||||
- High-performance RPC
|
||||
- Example: Microservice-to-microservice communication
|
||||
|
||||
4. **websocket** - WebSocket bidirectional communication
|
||||
- Real-time communication
|
||||
- Example: Chat application, live updates
|
||||
|
||||
5. **message-queue** - Asynchronous message queue
|
||||
- Decoupled async communication
|
||||
- Example: Publishing events to RabbitMQ
|
||||
|
||||
6. **database-query** - Database read/write operations
|
||||
- Direct database access
|
||||
- Example: API querying PostgreSQL
|
||||
|
||||
7. **file-transfer** - File upload/download
|
||||
- File operations
|
||||
- Example: Uploading files to S3
|
||||
|
||||
8. **authentication** - Authentication/authorization
|
||||
- Identity verification
|
||||
- Example: OAuth flow with Auth0
|
||||
|
||||
## Relationship Direction
|
||||
|
||||
Specify the direction of communication:
|
||||
|
||||
- **outbound** - This system initiates communication to target
|
||||
- Example: "Web App calls API" (outbound from Web App)
|
||||
|
||||
- **inbound** - Target system initiates communication to this system
|
||||
- Example: "API receives requests from Web App" (inbound to API)
|
||||
|
||||
- **bidirectional** - Communication flows both ways
|
||||
- Example: WebSocket connection
|
||||
|
||||
**Prefer outbound/inbound over bidirectional** for clarity.
|
||||
|
||||
## Relationship Metadata
|
||||
|
||||
Document additional context:
|
||||
|
||||
```json
|
||||
{
|
||||
"target": "payment-api",
|
||||
"type": "http-rest",
|
||||
"direction": "outbound",
|
||||
"description": "Processes payments via REST API",
|
||||
"protocol": {
|
||||
"method": "POST",
|
||||
"endpoint": "/api/v1/payments",
|
||||
"format": "JSON",
|
||||
"authentication": "JWT Bearer Token"
|
||||
},
|
||||
"metadata": {
|
||||
"synchronous": true,
|
||||
"frequency": "medium",
|
||||
"critical": true
|
||||
},
|
||||
"tags": ["payment", "rest", "critical"]
|
||||
}
|
||||
```
|
||||
|
||||
## How to Identify Relationships
|
||||
|
||||
### 1. Search for API calls:
|
||||
|
||||
```bash
|
||||
# Look for HTTP client libraries
|
||||
grep -r "axios\|fetch\|http.get" src/
|
||||
grep -r "requests.get\|httpx" .
|
||||
grep -r "Http::get\|Guzzle" .
|
||||
```
|
||||
|
||||
### 2. Check environment variables:
|
||||
|
||||
```bash
|
||||
# .env.example reveals external integrations
|
||||
cat .env.example | grep -E "API_URL|BASE_URL|ENDPOINT"
|
||||
```
|
||||
|
||||
### 3. Review configuration files:
|
||||
|
||||
```javascript
|
||||
// config/api.js
|
||||
const API_BASE_URL = 'https://api.example.com'; // → Relationship to API
|
||||
const STRIPE_API = 'https://api.stripe.com'; // → Relationship to Stripe
|
||||
```
|
||||
|
||||
### 4. Analyze package dependencies:
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"axios": "^1.0.0", // → HTTP client (likely REST API calls)
|
||||
"@sendgrid/mail": "^7.0.0", // → SendGrid integration
|
||||
"stripe": "^10.0.0", // → Stripe integration
|
||||
"socket.io-client": "^4.0.0" // → WebSocket communication
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Technology-to-Relationship Mapping
|
||||
|
||||
| Package/Library | Relationship Type | Example |
|
||||
|----------------|-------------------|---------|
|
||||
| axios, fetch | http-rest | REST API calls |
|
||||
| @apollo/client | http-graphql | GraphQL queries |
|
||||
| @grpc/grpc-js | grpc | Microservice RPC |
|
||||
| socket.io-client | websocket | Real-time communication |
|
||||
| amqplib, kafka-node | message-queue | Async messaging |
|
||||
| pg, mysql2, mongoose | database-query | Database access |
|
||||
| @aws-sdk/client-s3 | file-transfer | S3 uploads/downloads |
|
||||
| @auth0/auth0-spa-js | authentication | OAuth flow |
|
||||
|
||||
## Relationship Discovery Checklist
|
||||
|
||||
- [ ] Search for HTTP client imports
|
||||
- [ ] Check .env.example for API endpoints
|
||||
- [ ] Review package.json dependencies
|
||||
- [ ] Analyze configuration files
|
||||
- [ ] Look for WebSocket connections
|
||||
- [ ] Find message queue publishers/subscribers
|
||||
- [ ] Identify database connections
|
||||
- [ ] Detect authentication flows
|
||||
305
skills/c4model-c1/troubleshooting-guide.md
Normal file
305
skills/c4model-c1/troubleshooting-guide.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Troubleshooting Guide for C1 Analysis
|
||||
|
||||
## Problem: Too Many Systems Identified
|
||||
|
||||
**Symptom:** 10+ systems for a small application
|
||||
|
||||
**Root cause:** Over-granularization - treating components as systems
|
||||
|
||||
**Solution:** Combine systems that share:
|
||||
- Same deployment unit
|
||||
- Same repository
|
||||
- Same business capability
|
||||
|
||||
**Examples:**
|
||||
- Login + Registration + Profile → **User Management System**
|
||||
- Product List + Product Detail + Product Search → **Product Catalog System**
|
||||
- Multiple APIs doing similar things → **One API System** with multiple containers (C2)
|
||||
|
||||
**Questions to ask:**
|
||||
- Can these be deployed independently?
|
||||
- Do they have separate repositories?
|
||||
- Do they solve different business problems?
|
||||
|
||||
If "no" to all three → combine into one system.
|
||||
|
||||
---
|
||||
|
||||
## Problem: Can't Determine System Boundaries
|
||||
|
||||
**Symptom:** Unclear where one system ends and another begins
|
||||
|
||||
**Root cause:** Mixed abstraction levels or unclear responsibilities
|
||||
|
||||
**Solution:** Ask the following questions in order:
|
||||
|
||||
1. **Can this be deployed independently?**
|
||||
- Yes → Likely separate systems
|
||||
- No → Likely one system
|
||||
|
||||
2. **Does it have a clear single purpose?**
|
||||
- Yes → Good system candidate
|
||||
- No → May need to split or combine
|
||||
|
||||
3. **Is it in a separate repository?**
|
||||
- Yes → Usually separate system
|
||||
- No → May be same system (unless monorepo)
|
||||
|
||||
4. **Does it have its own runtime?**
|
||||
- Yes → Separate system
|
||||
- No → Probably same system
|
||||
|
||||
**If still unclear:** Default to fewer systems. You can always split at C2 (Container) level.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Unclear: "Authentication" separate from "User Management"?
|
||||
|
||||
Ask:
|
||||
- Independent deployment? No (both part of same API)
|
||||
- Separate repos? No
|
||||
- Own runtime? No
|
||||
|
||||
→ Combine into "User Management System"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem: Technology Names in System IDs
|
||||
|
||||
**Symptom:** System IDs like `react-frontend`, `express-backend`, `django-app`
|
||||
|
||||
**Root cause:** Focusing on implementation instead of purpose
|
||||
|
||||
**Solution:** Rename to business purpose:
|
||||
|
||||
| ❌ Technology Name | ✅ Business Purpose |
|
||||
|-------------------|---------------------|
|
||||
| react-frontend | customer-web-app |
|
||||
| express-backend | ecommerce-api |
|
||||
| django-app | content-management-system |
|
||||
| postgres-db | user-database |
|
||||
| redis-cache | session-cache |
|
||||
|
||||
**Pattern:** Ask "What does this do for the business?" not "What tech is it built with?"
|
||||
|
||||
**Good naming formula:**
|
||||
```
|
||||
[Business Capability] + [System Type]
|
||||
|
||||
Examples:
|
||||
- Order Processing + API = order-processing-api
|
||||
- Customer Portal + Web App = customer-portal
|
||||
- Product Catalog + Service = product-catalog-service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem: Missing External Actors
|
||||
|
||||
**Symptom:** No `external-service` type systems, no external actors
|
||||
|
||||
**Root cause:** Not checking for third-party integrations
|
||||
|
||||
**Solution:** Systematically check for external services:
|
||||
|
||||
### 1. Check .env.example
|
||||
|
||||
```bash
|
||||
cat .env.example | grep -E "API_KEY|API_URL|WEBHOOK|SECRET"
|
||||
```
|
||||
|
||||
Look for:
|
||||
- `STRIPE_API_KEY` → Stripe payment gateway
|
||||
- `SENDGRID_API_KEY` → SendGrid email service
|
||||
- `TWILIO_*` → Twilio SMS service
|
||||
- `AUTH0_*` → Auth0 authentication
|
||||
- `GOOGLE_ANALYTICS_ID` → Google Analytics
|
||||
|
||||
### 2. Check package.json dependencies
|
||||
|
||||
```bash
|
||||
cat package.json | grep -E "stripe|sendgrid|twilio|auth0|analytics"
|
||||
```
|
||||
|
||||
Look for SDK packages:
|
||||
- `stripe` → Stripe integration
|
||||
- `@sendgrid/mail` → SendGrid integration
|
||||
- `twilio` → Twilio integration
|
||||
- `@auth0/*` → Auth0 integration
|
||||
|
||||
### 3. Search code for API calls
|
||||
|
||||
```bash
|
||||
grep -r "https://api\." src/
|
||||
grep -r "external.*api\|third.?party" src/
|
||||
```
|
||||
|
||||
### 4. Common external services:
|
||||
|
||||
**Almost every app uses:**
|
||||
- Payment provider (Stripe, PayPal)
|
||||
- Email service (SendGrid, Mailgun)
|
||||
- Authentication (Auth0, Firebase)
|
||||
- Analytics (Google Analytics, Mixpanel)
|
||||
- Monitoring (Datadog, Sentry)
|
||||
- Cloud storage (S3, GCS)
|
||||
|
||||
---
|
||||
|
||||
## Problem: Relations Without Direction
|
||||
|
||||
**Symptom:** All relationships marked "bidirectional"
|
||||
|
||||
**Root cause:** Not analyzing who initiates communication
|
||||
|
||||
**Solution:** Think about who calls whom:
|
||||
|
||||
### Decision Rules:
|
||||
|
||||
1. **Frontend → Backend** = outbound from frontend
|
||||
- Frontend makes HTTP requests
|
||||
- Backend responds
|
||||
- Direction: outbound (from frontend perspective)
|
||||
|
||||
2. **API → Database** = outbound from API
|
||||
- API initiates queries
|
||||
- Database responds
|
||||
- Direction: outbound (from API perspective)
|
||||
|
||||
3. **Service → Message Queue** = depends on action
|
||||
- Publishing event → outbound
|
||||
- Subscribing/consuming → inbound
|
||||
|
||||
4. **Only bidirectional when:**
|
||||
- WebSocket connections
|
||||
- True peer-to-peer communication
|
||||
- Both systems initiate equally
|
||||
|
||||
### Examples:
|
||||
|
||||
| Relationship | Direction | Reasoning |
|
||||
|--------------|-----------|-----------|
|
||||
| Web App → API | outbound | Web app calls API |
|
||||
| API → Database | outbound | API queries database |
|
||||
| Worker → Queue | inbound | Worker consumes from queue |
|
||||
| API → Queue (publish) | outbound | API publishes to queue |
|
||||
| Chat Client ↔ Chat Server | bidirectional | WebSocket, both send |
|
||||
|
||||
**Rule of thumb:** If one system "calls" another, it's outbound from caller.
|
||||
|
||||
---
|
||||
|
||||
## Problem: Components Identified as Systems
|
||||
|
||||
**Symptom:** System IDs like `authentication-module`, `payment-controller`, `user-service-class`
|
||||
|
||||
**Root cause:** Confusing C1 (System) with C3 (Component) level
|
||||
|
||||
**Solution:** Recognize component indicators:
|
||||
|
||||
### ❌ These are C3 Components (NOT C1 Systems):
|
||||
|
||||
- Authentication Module
|
||||
- Payment Controller
|
||||
- User Service Class
|
||||
- Shopping Cart Manager
|
||||
- Email Helper
|
||||
- Validation Utilities
|
||||
|
||||
### ✅ These are C1 Systems:
|
||||
|
||||
- User Management System (contains auth module)
|
||||
- E-commerce API (contains payment controller)
|
||||
- Web Application (contains shopping cart)
|
||||
- Email Service (contains email helpers)
|
||||
|
||||
### How to tell:
|
||||
|
||||
| If it's... | Then it's... |
|
||||
|-----------|--------------|
|
||||
| Part of codebase structure | C3 Component |
|
||||
| In a `/src/` directory | C3 Component |
|
||||
| A class, module, or package | C3 Component |
|
||||
| Independently deployable | C1 System |
|
||||
| Has own repository (in microservices) | C1 System |
|
||||
| Has own runtime/process | C1 System |
|
||||
|
||||
**When in doubt:** If you can't deploy it separately, it's not a C1 system.
|
||||
|
||||
---
|
||||
|
||||
## Problem: Validation Fails
|
||||
|
||||
**Symptom:** `validate-c1-systems.py` reports errors
|
||||
|
||||
**Common validation errors and fixes:**
|
||||
|
||||
### 1. Invalid ID format
|
||||
|
||||
```
|
||||
Error: System ID 'User Management' is not kebab-case
|
||||
Fix: Change to 'user-management-system'
|
||||
```
|
||||
|
||||
### 2. Missing timestamps
|
||||
|
||||
```
|
||||
Error: metadata.timestamp is missing
|
||||
Fix: Add current ISO timestamp to metadata
|
||||
```
|
||||
|
||||
### 3. Broken relationships
|
||||
|
||||
```
|
||||
Error: Relation target 'api-service' does not exist
|
||||
Fix: Ensure all relation targets reference existing system IDs
|
||||
```
|
||||
|
||||
### 4. Invalid system type
|
||||
|
||||
```
|
||||
Error: Unknown system type 'backend'
|
||||
Fix: Use valid types: web-application, api-service, database, etc.
|
||||
```
|
||||
|
||||
### 5. Timestamp ordering
|
||||
|
||||
```
|
||||
Error: Child timestamp <= parent timestamp
|
||||
Fix: Ensure c1-systems.json timestamp > init.json timestamp
|
||||
```
|
||||
|
||||
**Debugging validation:**
|
||||
|
||||
```bash
|
||||
# Run validation with verbose output
|
||||
python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c1-systems.py c1-systems.json -v
|
||||
|
||||
# Check JSON syntax
|
||||
cat c1-systems.json | jq .
|
||||
|
||||
# Validate schema
|
||||
cat c1-systems.json | jq '.metadata.schema_version'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Troubleshooting Checklist
|
||||
|
||||
Before finalizing C1 analysis:
|
||||
|
||||
- [ ] System count reasonable (3-8 systems for small app, 8-15 for medium)
|
||||
- [ ] All system IDs in kebab-case
|
||||
- [ ] No technology names in system IDs
|
||||
- [ ] All systems have clear business purpose
|
||||
- [ ] External services identified (payment, email, auth, etc.)
|
||||
- [ ] Actors documented (both users and external systems)
|
||||
- [ ] Relationships have direction (outbound/inbound)
|
||||
- [ ] All relation targets exist
|
||||
- [ ] Boundaries defined (scope, deployment, network)
|
||||
- [ ] Observations documented with evidence
|
||||
- [ ] Timestamps valid (child > parent)
|
||||
- [ ] Validation script passes
|
||||
|
||||
**If checklist fails:** Review this troubleshooting guide for specific issues.
|
||||
Reference in New Issue
Block a user