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:

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 → Multiple systems in one repository
Microservices → Each repository = 1 system
Library → Not a system itself, but used by systems

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
- Databases, message queues, caches
- Critical infrastructure pieces
- Example: "PostgreSQL Database", "Redis Cache", "RabbitMQ Message Broker"

❌ 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"
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 plugins/melly-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 plugins/melly-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

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: /plugins/melly-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+

Install Skill

SKILL.md