Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

architecture

Greenfield architecture design: map functionality flows, draw components, design APIs, classify dependencies, plan observability. For multi-component, API, schema, auth, or integration-heavy work. For retrofitting existing code, use codebase-hygiene instead.

romiluz13 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add romiluz13/cc10x --skill architecture

About this skill


name: architecture description: | Greenfield architecture design: map functionality flows, draw components, design APIs, classify dependencies, plan observability. For multi-component, API, schema, auth, or integration-heavy work. For retrofitting existing code, use codebase-hygiene instead. allowed-tools: Read Grep Glob LSP Bash user-invocable: false

Architecture

Design systems from scratch: map flows, then draw components. For retrofitting existing code, use codebase-hygiene instead.

Intake Routing

Request typeUse
New system/major feature (greenfield)This skill
Existing code with shallow modulescodebase-hygiene
Multi-component integrationThis skill
Single-component refactorplanning + building

Functionality-First Design Process

Phase 1: Map Functionality Flows

Map every user flow end-to-end before designing any component:

Flow: [name]
1. [step] → [what the system does] → [what the user sees]
2. [step] → [what the system does] → [what the user sees]
Error paths:
- [error] → [system response] → [user sees]

Every flow must have its error paths mapped. Unmapped error paths become unmapped components.

Phase 2: Map to Architecture

Translate flows into components:

  • Each flow step maps to one or more components
  • Each error path maps to a component's error handling
  • Data crossings between components become interfaces

Phase 3: Design Components

For each component:

  • Interface: what it receives and returns (the contract)
  • Responsibility: what it does (one sentence)
  • Dependencies: what it needs (other components, external services)
  • State: what it remembers (if anything)
  • Error handling: what can go wrong and what it does about it

Before finalizing any component boundary, apply the Deletion Test and Two-Adapter Rule as defined in cc10x:codebase-design. A component that fails the deletion test (complexity vanishes if deleted) or fails the two-adapter rule (it is a port with only one adapter — an ordinary caller or test exercising the interface is not an adapter) is not a real boundary yet — fold it into its caller or defer the split until a second concrete need appears.

Architecture Views

System Context (C4 Level 1)

Box diagram: your system + external systems it talks to. One paragraph per external system: what it provides, what you depend on.

Container View (C4 Level 2)

Internal boxes: web app, API, database, queue, worker. Arrows show data flow. One paragraph per container: technology choice, responsibility.

Component View (C4 Level 3)

Inside each container: the modules/classes. Arrows show call relationships. This is what the builder will implement.

LSP-Powered Architecture Analysis

Use LSP to understand existing architecture before designing new:

  • Go to Definition on key functions to trace the call graph
  • Find References to understand blast radius of existing interfaces
  • Go to Type Definition to understand data models
  • Incoming/Outgoing Calls to map the dependency graph

API Design (Functionality-Aligned)

Design APIs from the flow, not from the data model:

  1. What does the user need to do? (action, not resource)
  2. What's the minimal interface that enables it? (fewest endpoints/parameters)
  3. What's the error contract? (every error case from the flow mapping)
  4. What's the type contract? (input/output types, not just shapes)
// Good: functionality-aligned
POST /orders/{id}/cancel  →  { status, cancelledAt }

// Bad: data-model-aligned
PUT /orders/{id}  →  { ..., status: "cancelled", ... }

Integration Patterns

For each integration:

FieldValue
System[name]
Protocol[HTTP/gRPC/CLI/message queue]
Direction[we call them / they call us / both]
Contract[request/response schema or event schema]
Failure mode[what happens when it's down]
Retry policy[retries, backoff, circuit breaker]

Dependency Classification

ClassMeaningExample
OwnedWe control the code and deploy itInternal service
WrappedWe depend on it but wrap it in our interfaceThird-party SDK behind adapter
ConsumedWe depend on it directly, no wrapperExternal API called directly
InfraPlatform-level dependencyDatabase, message queue

Wrapped dependencies can be swapped. Consumed dependencies cannot. Track which is which — it determines your coupling risk.

Observability Design

For each component:

  • Logging: what to log (not "everything" — specific events)
  • Metrics: what to track (business-relevant, not infra noise)
  • Tracing: what to trace (cross-component flows, not every function call)
  • Alerting: when to alert (user-visible impact, not internal noise)

Architecture Vocabulary

The deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality, deletion test, two-adapter rule) is defined in cc10x:codebase-design. Use those terms exactly.

Three extra terms specific to greenfield architecture (not in codebase-design):

  • Concealed complexity — work done behind a simple interface. The goal of deep modules.
  • Temporal coupling — caller must know the order of operations. Design defect — remove or document explicitly.
  • Leaky abstraction — interface exposes internal details callers must know. Design defect — fix the interface.

Before finalizing any component boundary, apply the Deletion Test and Two-Adapter Rule as defined in cc10x:codebase-design. A component that fails the deletion test (complexity vanishes if deleted) or fails the two-adapter rule (it is a port with only one adapter — an ordinary caller or test exercising the interface is not an adapter) is not a real boundary yet — fold it into its caller or defer the split

Read the complete source ↗