Breaking Apart Systems

Breaking Apart Systems

Load designing-software before starting — it provides property discovery and C4 model context this skill builds on.

Overview

C4 decomposition turns vague system descriptions into concrete, buildable architectures. This skill guides interactive decomposition through three levels (System → Container → Component) with approval gates at each level. The output — diagrams and design decisions — integrates back into the design document's Plan section.

When to Use

• After design doc review, before milestone identification
• When a system's internal structure is unclear
• When preparing to identify milestones for implementation
• When the Plan section lacks container/component diagrams

Entry Point

When the user invokes /c4-the-design, follow this sequence:

1. Locate the source document. If the user provided a path, read it. If not, use AskUserQuestion:

   • Point to a design document with a Plan section
   • Point to an existing system/container diagram to decompose further
   • Describe a system interactively (no document)
   • Stop

2. Create a companion diagram file. Create <design-doc-name>-c4-diagrams.md next to the source document. This file will hold all Mermaid diagrams so users can view rendered output in their markdown viewer.

3. Level 1: System Context. Identify the system boundary, users, and external dependencies. Write to diagram file, then get user approval.

4. Level 2: Containers. Decompose the system into deployable units. Write to diagram file, then get user approval.

5. Level 3: Components. Decompose each container into internal modules. Write to diagram file, then get user approval for each container.

6. Integrate outputs. Ask the user how to integrate diagrams and decisions back into the design doc.

Diagram Output Process

Mermaid diagrams cannot be rendered in terminal environments. Follow this process for each level:

1. Write the diagram to the companion *-c4-diagrams.md file
2. Ask the user to review by opening the file in a markdown viewer
3. Accept feedback and iterate on the diagram as needed
4. Get explicit approval before proceeding to the next level

This ensures users can actually see the rendered diagrams before approving them.

Diagram Clarity Guidelines

Make C4 levels visually distinct in Mermaid diagrams:

Container diagrams should:

• Use explicit labels like "📦 CONTAINER:" in each box name
• Include technology and role in each container box
• Use color coding: blue (#438DD5) for system containers, gray (#999) for external systems
• Add a legend explaining the color scheme
• Use style directives to apply colors

Example container box:

CLI["📦 CONTAINER: CLI Application<br/>─────────────<br/>Technology: Python/typer<br/>Role: Command interface"]
style CLI fill:#438DD5,color:#fff

Component diagrams should:

• Use "🧩 COMPONENT:" labels to distinguish from containers
• Show which container each component belongs to via subgraph
• Include one-sentence responsibility for each component

Core Pattern: Level-by-Level Decomposition

Level 1: System Context

Goal: Define what's inside vs outside the system.

Questions to surface:

1. What is the system? (one sentence)
2. Who uses it? (personas)
3. What external systems does it depend on?
4. What external systems depend on it?

Output: System context diagram (Mermaid) showing:

• The system as a single box
• Users/personas
• External dependencies with relationship labels

Validation:

• System boundary is clear
• All users/personas identified
• External dependencies named and relationships labeled
• User approves before proceeding to Level 2

Level 2: Containers

Goal: Identify deployable units within the system.

Key question: "Could this become independently deployable?"

• If yes → Container
• If no → Component (handle at Level 3)

Questions to surface:

1. What are the major deployable units? (apps, services, databases)
2. What's the data flow pattern? (see Data Flow Patterns below)
3. Which containers talk to external systems?
4. What protocols/formats do containers use to communicate?

Heuristics:

• Databases are containers (even embedded ones like SQLite, DuckDB)
• Data Access Layers are components, not containers
• "Future flexibility" that crosses deployment boundaries → container
• Code organization without deployment boundary → component

Output: Container diagram (Mermaid) showing:

• Each container with technology choice (e.g., "Python/typer")
• Communication arrows with protocols
• External system connections

Validation:

• Each container is independently deployable
• Data flow pattern identified and documented
• No premature containers (code organization masquerading as deployment units)
• User approves before proceeding to Level 3

Level 3: Components

Goal: Decompose each container into internal modules.

Decompose one container at a time, getting user approval before moving to the next.

Questions to surface:

1. What's the organizing principle for this container? (see Container Taxonomy)
2. What components does it contain?
3. What are each component's responsibilities?
4. How do components depend on each other?

Output: Component diagram (Mermaid) for each container showing:

• Components with responsibilities
• Internal dependencies
• External connections (to other containers)

Validation:

• Components follow the organizing principle for this container type
• No "SharedUtilities" or "CommonHelpers" components
• Dependencies flow in one direction (no cycles)
• User approves before proceeding to next container

Data Flow Patterns

Identify the data flow pattern early — it affects container and component boundaries.

Question to ask: "Does one container coordinate all data flow, or does data flow through containers sequentially?"

Container Taxonomy

Different container types have different organizing principles. Ask the type-specific question to identify components.

User-Facing Containers (CLI, UI)

Organizing principle: User actions, not internal concerns.

Heuristic: "If a user would describe it as a feature, it's probably a component boundary."

Pattern: Separate command components from infrastructure components:

• Command components: Map to user actions (auth, activities, export)
• Infrastructure components: Internal concerns (data access, transformation, caching)

Command components depend on infrastructure, not the reverse.

External API Client Containers

Organizing principle: Operations, not endpoints.

Why: Endpoints are implementation details that change. Operations are stable domain abstractions.

Exception: If endpoints have fundamentally different auth/protocols, separate components may be warranted.

Example:

• Good: SessionManager, ActivityFetcher, ReportFetcher (operations)
• Bad: LoginEndpoint, GraphQLEndpoint, RESTEndpoint (endpoints)

Data Handler Containers

Organizing principle: Data lifecycle stages.

Question: "What's the data lifecycle?"

ELT vs ETL: If you need to preserve raw data for re-transformation, use ELT (Extract-Load-Transform). Each stage becomes a component.

Configuration vs Runtime State

Question to ask early: "Is this configuration (external to the system) or runtime state (managed by the system)?"

This distinction affects component responsibilities. A credentials component that just reads .env is simpler than one that manages credential lifecycle.

Identifying the Real UI

Question: "How will humans actually interact with this data?"

The answer affects where complexity lives:

• If UI is a rich app → display logic in that container
• If UI is raw queries/exports → transformation must produce query-ready output

Example: When the "UI" is DuckDB queries + spreadsheet exports, the Transformer component becomes the real presentation layer. It must produce human-friendly column names, converted units, and flat structures.

Output Integration

After completing all three levels, ask the user how to integrate outputs:

Options:

1. Update the Plan section — Add diagrams and design decisions inline
2. Create a separate architecture document — New *-c4-diagrams.md file
3. Both — Architecture doc with summary in Plan section

What to integrate:

• System context diagram
• Container diagram with responsibilities table
• Component diagrams for each container
• Data flow integration diagram (how containers/components work together)
• Design decisions with rationale
• Resolved questions

Use AskUserQuestion to determine placement if the Plan section structure is unclear.

Self-Consistency Check

After completing integration, verify the C4 architecture is consistent with the design document:

1. Containers match the Plan section's description — Every container should appear in or align with the system overview described in the Plan.

2. Components map to milestones — Each milestone should have corresponding component(s) that implement it. If a milestone doesn't map to any component, either the component decomposition missed something or the milestone is out of scope.

3. Data flows match the described workflow — The data flow diagram should align with any workflow or sequence described in the design doc.

4. Technology choices are consistent — Technologies mentioned in the design doc should match container/component technology annotations.

If inconsistencies are found, ask the user whether to:

• Update the C4 diagrams to match the design doc
• Update the design doc to match the C4 analysis
• Flag as an open question for later resolution

Anti-Patterns

Common Mistakes

Anti-Rationalizations

• "The system is too simple for C4" — Simple systems still have containers and components. Clarity helps even for small projects.
• "I'll figure out components during implementation" — You'll discover missing work too late. Decompose now.
• "This could become a service later" — Is it a deployment boundary today? If not, it's a component.
• "We need a shared utilities component" — You don't. Wait for duplication to actually cause pain.
• "The user provided a diagram, I'll just use it" — Validate it. User diagrams often mix levels or miss containers.

Quick Reference

Level 1: System Context
  → What's inside/outside? Users? External dependencies?
  → Output: System context diagram
  → Gate: User approval

Level 2: Containers
  → "Could this be independently deployed?"
  → Identify data flow pattern (orchestration/pipeline)
  → Output: Container diagram + responsibilities
  → Gate: User approval

Level 3: Components (per container)
  → Container type → organizing question:
    - User-facing: "What does the user do?"
    - API client: "What operations?"
    - Data handler: "What's the lifecycle?"
  → Output: Component diagram + responsibilities
  → Gate: User approval per container

Integration:
  → Update Plan section OR create architecture doc
  → Include: diagrams, decisions, resolved questions

Handoff

When C4 decomposition is complete:

1. Summarize the architecture (containers, components, data flow pattern)
2. Verify diagrams are integrated into the design document
3. Present the handoff instructions using the exact format below

Handoff Instructions (present verbatim, substituting the actual filename):

C4 decomposition complete.

Your system architecture is now defined with containers and components. The next step is refining your milestones to align with this architecture.

Next steps:

1. Copy this command now (before clearing):

   /start-milestone-review @path/to/your-design-doc.md
   

2. Clear context:

   /clear
   

3. Paste and run the command you copied in step 1

This hands off your architecture to milestone refinement, which will:

• Validate milestones cover all components
• Add job stories, descriptions, and acceptance criteria
• Ensure milestones are in correct dependency order

The full workflow:

/review-and-validate-design → /c4-the-design → /start-milestone-review → /build-work-plan → /execute-work-plan

Summary

1. Complete each level before proceeding. System → Container → Component, with user approval at each gate.
2. Containers are deployable; components are not. DALs are components; databases are containers.
3. Identify data flow pattern early. Orchestration vs pipeline affects all boundaries.
4. Use container-type-specific questions. User-facing = user actions; API client = operations; data handler = lifecycle.
5. No premature shared utilities. Each component owns its code; refactor after 3+ duplications.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.