Skill Claude

System Architecture

system-architecture/

2 views 0 downloads

Pick the architecture pattern and the technology on purpose, before framework details: pattern trade-offs, design workflows and decision guides for databases, queues and APIs.

System Architecture: Brain Lab skill for Claude Code

Technology-agnostic system design, pick the pattern and the tech BEFORE touching framework mechanics.

Why use it

Jumping straight to schemas and modules bakes in an architecture nobody chose.
"Which database / queue / API style?" answered by habit rather than by the actual constraints.
Migrations and scale limits discovered after the build, not before it.

What it does

Architecture-pattern selection with trade-offs, monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway.
System-design workflows: capacity planning, API design, schema design, scalability assessment, migration planning.
Technology-decision frameworks: database, cache, message queue, auth, frontend, cloud, API style.
A lean map over three references, read the map, open the one that matches the question.

Benefits

Make the expensive call once. Pattern and tech chosen deliberately, and written down.
No accidental architecture. You stop inheriting a shape nobody picked.
Scale problems surface on paper, while they still cost nothing to fix.
Stack-agnostic. Pairs with whatever framework skill you already run.

Install

Download this skill and copy the system-architecture folder to .claude/skills/system-architecture/ in your project, or to ~/.claude/skills/system-architecture/ to use it in every project. Claude Code finds it on its own; you can also call it with /system-architecture.

Part of the Agent Engineering bundle. To get the whole set as a Claude Code plugin: /plugin marketplace add endorphin-ai/hasbrains-agent-kit, then /plugin install agent-engineering@hasbrains-agent-kit.

Source: endorphin-ai/hasbrains-agent-kit. License: MIT.

Files (8)

---
name: system-architecture
description: "Use when designing a system, choosing an architecture pattern, making a technology decision, or doing capacity/scalability planning — BEFORE drilling into framework-specific mechanics. A lean MAP over three reference docs: pattern selection (monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway, with trade-offs), the how-to system-design workflows (system-design-interview approach, capacity planning, API design, DB schema design, scalability assessment, migration planning), and the technology-choice frameworks (database, caching, message queue, auth, frontend framework, cloud provider, API style). Trigger on: 'design the system', 'choose an architecture pattern', 'which pattern fits', 'tech decision', 'SQL or NoSQL', 'REST vs GraphQL vs gRPC', 'capacity/scalability planning', 'plan the migration'. This is general, technology-agnostic system-design knowledge — it informs the decisions that come BEFORE any framework-specific mechanics."
---

TASKLANG
TYPE SKILL

IDENTITY "System Architecture"
  > General-purpose system-design knowledge for the planning step that comes
  > BEFORE technology-specific mechanics: pick the right architecture PATTERN,
  > make the load-bearing TECHNOLOGY decisions, and run the system-design
  > WORKFLOWS (capacity, API, schema, scalability, migration). This skill is a
  > lean MAP — the substance lives in three reference docs under references/.
  > Read the map, then open the one reference that matches the question.

!!! References FIRST — this SKILL.md only routes; the answers live in references/.
!!! This is technology-AGNOSTIC system design. Framework-specific mechanics —
!!! this stack's module/context boundaries, its ORM schema and migration syntax,
!!! its background-job and authorization APIs — belong to a stack-specific skill.
!!! system-architecture supports the PLANNING that precedes those mechanics.

---

## When to use this skill

KNOWLEDGE
  USE_WHEN
    - "Choosing an architecture pattern for a new system or a milestone (and weighing its trade-offs)."
    - "Making a technology decision — database, cache, message queue, auth, frontend framework, cloud provider, API style."
    - "Running a system-design workflow — capacity planning, API design, schema design, scalability assessment, migration planning."
    - "Doing the PLAN-FIRST step of a design: settle pattern + data/access model + boundaries before drilling into framework mechanics."
  NOT_FOR
    - "Framework-specific module/schema/job/authorization mechanics — that belongs to a stack-specific architecture skill."
    - "Writing or verifying implementation code — this skill informs design decisions, it does not produce code."

---

## Core knowledge (the map)

KNOWLEDGE
  METHOD
    - "PLAN before mechanics: a design starts by choosing a PATTERN, settling the DATA + ACCESS model, and naming the BOUNDARIES — then drills into technology-specific implementation."
    - "Every pattern and technology choice is a TRADE-OFF, not a default. Start simple (a monolith / modular monolith) and adopt complexity (microservices, CQRS, event sourcing) only when a concrete force — scale, team autonomy, independent deploy, audit/replay — demands it."
    - "Right-size the decision to the requirements you actually have: estimate scale FIRST (capacity-planning workflow), then let the numbers drive the pattern and the technology choices."
    - "Make decisions with a framework, not a hunch: each technology choice in tech_decision_guide.md carries a decision matrix + a 'when to use each' so the choice is defensible."

---

## References (open the one that matches the question)

> Three reference docs. Read the map above, then open exactly one.

MAP references
  "references/architecture_patterns.md"     -> PATTERN SELECTION. Open when choosing/comparing an architecture pattern. Monolith, Modular Monolith, Microservices, Event-Driven, CQRS, Event Sourcing, Hexagonal, Clean Architecture, API Gateway — each with its forces, trade-offs, and a pattern-selection quick reference.
  "references/system_design_workflows.md"   -> HOW-TO WORKFLOWS. Open when you need a step-by-step design procedure: the system-design-interview approach, capacity planning, API design, database schema design, scalability assessment, and migration planning.
  "references/tech_decision_guide.md"        -> TECHNOLOGY CHOICE. Open when picking a specific technology: database (SQL vs NoSQL + type), caching strategy, message queue, authentication strategy (JWT vs sessions, OAuth flows), frontend framework (SSR vs SPA vs SSG), cloud provider, and API style (REST vs GraphQL vs gRPC).

---

## How it fits a build

KNOWLEDGE
  FITS
    - "Supporting knowledge for the architecture role's DESIGN pass: consulted during the PLAN-FIRST step (pattern selection + tech decisions + the system-design workflows) BEFORE any stack-specific technical sub-steps."
    - "Does NOT replace a stack-specific architecture skill: that one owns the framework mechanics and the verify gate; this one informs the architectural choices that feed them."

---

Made by **HasBrains** — https://hasbrains.com/