zhongwei/gh-cubical6-melly

Fork 0

Files

Zhongwei Li c0cd55ad8d Initial commit

2025-11-29 18:17:07 +08:00

23 KiB

Raw Blame History

name, description

name	description
c4model-c1	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.

name

description

c4model-c1

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:

How many repositories exist?
What type is each repository (monorepo, single, microservice)?
What package manifests exist (package.json, composer.json, etc.)?
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:

Independently deployable
- Can be built and deployed separately
- Has its own runtime environment
- Example: "Web Application", "REST API Service"
Self-contained with clear boundaries
- Has defined inputs and outputs
- Clear scope of responsibility
- Example: "Payment Processing System", "User Database"
Has a distinct purpose
- Solves a specific business problem
- Provides specific functionality
- Example: "Order Management System", "Notification Service"
External third-party services
- Services outside your control
- Third-party integrations
- Example: "Stripe Payment Gateway", "SendGrid Email Service"
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:

Technology/framework names
- ❌ "React Frontend" → ✅ "Customer Web Application"
- ❌ "Express Backend" → ✅ "E-Commerce API"
- ❌ "Django App" → ✅ "Content Management System"
Internal code modules (these are C3 components)
- ❌ "Authentication Module"
- ❌ "Payment Controller"
- ❌ "User Service Class"
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.
Vague names without clear purpose
- ❌ "Frontend"
- ❌ "Backend"
- ❌ "Service"

Step 3: Analyze Package Manifests

Package manifests reveal system purpose:

npm/package.json indicators:

{
  "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:

{
  "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
Relationships (how systems communicate) → See relationship-mapping.md
Observations (8 categories of findings) → See 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:

Simple Web Application - Frontend + Backend + Database
Microservices Architecture - Multiple services with API gateway
Event-Driven System - Async processing with message queue
Mobile + Backend - Mobile app with backend API

For complete pattern details, systems, actors, relationships, and indicators → See architecture-patterns.md

Integration with Melly Workflow

When This Skill is Used

This skill is activated during:

Phase 1: Initialization (/melly-init)
- Repository scanning
- Technology detection
Phase 2: C1 System Identification (/melly-c1-systems)
- Primary usage phase
- System identification
- Actor identification
- Boundary detection
- Relationship mapping
Phase 5: Documentation (/melly-doc-c4model)
- Markdown generation
- Observation documentation

Input Expectations

This skill expects data from init.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:

{
  "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:

Schema validation - Correct JSON structure
Timestamp ordering - metadata.timestamp > parent_timestamp
Referential integrity - All relation targets exist
Required fields - All required fields present
ID format - Kebab-case pattern

Validation script:

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

# Load init.json
cat init.json | jq '.repositories'

Step 2: Analyze Each Repository

For each repository:

Identify primary purpose
- What does this repository do?
- What is its main responsibility?
Detect technology stack
- What frameworks/languages are used?
- What does this tell us about system type?
Check for external dependencies
- What third-party services are used?
- What APIs are called?
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

Scan for user roles

grep -r "role\|Role\|USER_ROLE\|UserRole" src/

Find external integrations

cat .env.example | grep -E "API_KEY|API_URL|WEBHOOK"

Document each actor
- Name and type
- What systems they interact with
- Purpose/description

See actor-identification.md for complete methodology.

Step 4: Define Boundaries

For each system:

Determine scope - Internal (we own it) or external?
Determine deployment - Where does it run? (cloud, on-premise, SaaS)
Determine network - Who can access it? (public, private, DMZ)

Step 5: Map Relationships

For each system:

Find API calls
```
grep -r "axios\|fetch\|http" src/
```
Identify communication patterns - HTTP REST, GraphQL, WebSocket, message queue
Document each relationship - Source, target, type, direction, criticality

See 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 for complete guidance.

Step 7: Validate Output

Before finalizing:

Check system IDs - All kebab-case, all unique
Check relations - All targets exist, directions specified
Check timestamps - Child > parent

Run validation script

python ${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-c1-systems.py output.json

Best Practices Summary

✅ DO:

Start with repository boundaries - Repositories often map to systems
Focus on clear responsibilities - Each system has one clear purpose
Keep it high-level - Avoid implementation details
Document external dependencies - Mark external systems clearly
Use descriptive names - "Customer Web Application" not "Frontend"
Define all three boundary dimensions - Scope, deployment, network
Document relationships with direction - Prefer outbound/inbound over bidirectional
Provide evidence for observations - Code snippets, config files, patterns
Tag observations appropriately - Use lowercase kebab-case tags
Validate output before finalizing - Run validation scripts

❌ DON'T:

Don't use technology as system name - ❌ "React App" → ✅ "Web Application"
Don't over-granularize - ❌ "Login System" + "Register System" → ✅ "Auth System"
Don't identify components as systems - Components are C3, not C1
Don't use vague names - ❌ "Backend" → ✅ "E-Commerce API"
Don't mix abstraction levels - Keep C1, C2, C3 separate
Don't skip external actors - Third-party services are critical
Don't forget boundary definitions - Always specify scope/deployment/network
Don't use generic relationship types - ❌ "http" → ✅ "http-rest" or "http-graphql"
Don't ignore observations - Document findings with evidence
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

Investors/clients judge rigor - Technical stakeholders recognize proper C4 Model usage
Shortcuts compound - One wrong name becomes 10 wrong names becomes unmaintainable docs
Reputation is long-term - "Fixed it later" is remembered as "got it wrong initially"
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 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

Additional Resources

Supporting Documentation

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:

Analyze repositories from init.json
Identify systems using the rules above
Identify actors (users and external systems)
Define boundaries (scope, deployment, network)
Map relationships between systems
Document observations with evidence
Generate c1-systems.json following the schema
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+

23 KiB Raw Blame History