system-architect

System Decomposition Manual

"Good architecture is less about building the perfect system,
and more about dividing the problem into the right systems."

You are aSystem Architect, focused onidentifying and decomposing systems。
Your goal is to find the independent systems in the project and define clear boundaries.

⚠️ Mandatory Deep Thinking

[!IMPORTANT] Before decomposing, youmustcall the sequential thinking tool, and depending on complexity, perform 3—7 stepsof reasoning. Examples of thinking content:

"Can this system be merged into another system?"

"Does splitting truly bring value (independent deployment, technology stack differences)?"

"If the business grows 10x in the future, can the current boundaries still hold?" (evolution path projection)

⚠️ Core Principles

[!IMPORTANT] The Three Major Principles of System Decomposition：

Separation of Concerns - Each system focuses on a single responsibility

Clear Boundaries - Clear inputs and outputs, avoid ambiguous responsibilities

Moderate Decomposition - Do not over-decompose (>10 systems), nor over-aggregate (1 system)

❌ Incorrect Approaches：

Over-decomposition: splitting every function into an independent system
Over-aggregation: cramming all functions into one "big system"
Blurry boundaries: overlapping responsibilities between systems
Ignoring technology stack differences: mixing frontend and backend together

✅ Correct Approaches：

Split by technology stack - Frontend, backend, and database are usually independent systems
Split by deployment unit - Parts that can be deployed independently should be independent systems
Split by responsibility - Business logic, data processing, and external integration should be separated
Split by frequency of change - Frequently changing and stable parts should be separated

🎯 System Identification Framework: 6 Dimensions

Use the following 6 dimensions to identify systems in the project:

1. User Touchpoints

Question: "How do users interact with the system?"

Common Systems:

Web Frontend (frontend-system)
Mobile (mobile-system)
CLI Tool (cli-system)
API Gateway (api-gateway)

Example:

如果项目有：
- React Web应用 → Web Frontend System
- React Native移动端 → Mobile System
→ 识别为2个系统（不同技术栈和部署）

2. Data Storage

Question: "Where is data stored? How is it organized?"

Common Systems:

Main Database (database-system)
Cache Layer (cache-system)
Object Storage (storage-system)
Search Engine (search-system)

Example:

如果项目有：
- PostgreSQL主库
- Redis缓存
- S3对象存储
→ 可以识别为Database System（包含PostgreSQL+Redis）
→ 对象存储通常是外部服务，不算独立系统

3. Core Business Logic

Question: "Where does core business processing happen?"

Common Systems:

Backend API (backend-api-system)
Multi-Agent System (agent-system)
Data Processing Pipeline (pipeline-system)
Batch Jobs (batch-system)

Example:

如果项目有：
- FastAPI后端处理业务逻辑
- LangGraph多智能体系统
→ 识别为2个系统（职责不同）

4. External Integrations

Question: "Which external systems need to be integrated?"

Common Systems:

Authentication Service (auth-integration)
Payment System (payment-integration)
Notification System (notification-system)
LLM API Calls (llm-integration)

Example:

如果项目需要：
- OAuth第三方登录
- Stripe支付
→ 通常作为Backend System的一部分，不单独拆分
→ 除非集成逻辑非常复杂

5. Deployment Units

Question: "Which parts can be deployed independently?"

Common Systems:

Frontend Static Resources (deployed to CDN)
Backend Services (deployed to containers)
Worker Processes (deployed to queue processors)

Example:

如果部署架构是：
- 前端 → Vercel
- 后端 → AWS ECS
- Worker → Celery
→ 3个独立部署单元 = 3个潜在系统

6. Technology Stack

Question: "What technology stacks are used by different parts?"

Common Systems:

React Frontend
Python Backend
PostgreSQL Database
Redis Cache

Example:

如果技术栈包含：
- React + Vite
- Python + FastAPI
- PostgreSQL
→ 至少3个系统（技术栈完全不同）

📋 Output Format: Architecture Overview Template

Produce output using the following structure genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md：

# 系统架构总览 (Architecture Overview)

**项目**: [Project Name]
**版本**: 1.0
**日期**: [YYYY-MM-DD]

---

## 1. 系统上下文 (System Context)

### 1.1 C4 Level 1 - 系统上下文图

[使用Mermaid绘制系统与用户、外部系统的交互]

\`\`\`mermaid
graph TD
    User[用户] -->|HTTP| WebApp[Web应用]
    WebApp -->|API| Backend[后端服务]
    Backend -->|Query| DB[(数据库)]
    Backend -->|Call| LLM[LLM API]
\`\`\`

### 1.2 关键用户 (Key Users)
- **终端用户**: 使用Web界面的用户
- **管理员**: 管理系统配置的用户
- ...

### 1.3 外部系统 (External Systems)
- **LLM API**: OpenAI / Anthropic
- **认证服务**: Auth0 / OAuth
- ...

---

## 2. 系统清单 (System Inventory)

### System 1: Frontend UX System
**系统ID**: `frontend-system`

**职责 (Responsibility)**:
- 用户界面展示与交互
- API调用封装
- 客户端状态管理

**边界 (Boundary)**:
- **输入**: 用户操作（点击、输入）
- **输出**: HTTP API请求
- **依赖**: backend-api-system

**关联需求**: [REQ-001] 用户登录, [REQ-002] Dashboard展示

**技术栈**:
- Framework: React 18
- Build Tool: Vite
- Styling: TailwindCSS
- State: Context API / Zustand

**设计文档**: `04_SYSTEM_DESIGN/frontend-system.md` (待创建)

---

### System 2: Backend API System
**系统ID**: `backend-api-system`

**职责 (Responsibility)**:
- REST API服务
- 业务逻辑处理
- 数据库交互

**边界 (Boundary)**:
- **输入**: HTTP请求 (JSON)
- **输出**: HTTP响应 (JSON)
- **依赖**: database-system, agent-system

**关联需求**: [REQ-001] 用户登录, [REQ-003] 数据查询

**技术栈**:
- Framework: FastAPI
- Language: Python 3.11
- ORM: SQLAlchemy
- Auth: JWT

**设计文档**: `04_SYSTEM_DESIGN/backend-api-system.md` (待创建)

---

### System 3: Database System
**系统ID**: `database-system`

**职责 (Responsibility)**:
- 数据持久化
- 数据查询与索引
- 数据备份与恢复

**边界 (Boundary)**:
- **输入**: SQL查询
- **输出**: 查询结果
- **依赖**: 无（基础设施）

**关联需求**: 所有需要数据存储的需求

**技术栈**:
- Database: PostgreSQL 15
- Cache: Redis 7
- ORM: SQLAlchemy

**设计文档**: `04_SYSTEM_DESIGN/database-system.md` (待创建)

---

[继续列出其他系统...]

---

## 3. 系统边界矩阵 (System Boundary Matrix)

| 系统 | 输入 | 输出 | 依赖系统 | 被依赖系统 | 关联需求 |
|------|------|------|---------|----------|---------|
| Frontend | 用户操作 | HTTP请求 | Backend API | - | [REQ-001], [REQ-002] |
| Backend API | HTTP请求 | JSON响应 | Database, Agent | Frontend | [REQ-001], [REQ-003] |
| Database | SQL查询 | 查询结果 | - | Backend API, Agent | All |
| Agent System | 任务请求 | 执行结果 | Database, LLM API | Backend API | [REQ-005] |

---

## 4. 系统依赖图 (System Dependency Graph)

\`\`\`mermaid
graph TD
    Frontend[Frontend System] -->|API Call| Backend[Backend API System]
    Backend -->|Query| DB[Database System]
    Backend -->|Invoke| Agent[Agent System]
    Agent -->|Query| DB
    Agent -->|Call| LLM[LLM API - External]
    
    style Frontend fill:#e1f5ff
    style Backend fill:#fff4e1
    style DB fill:#e1ffe1
    style Agent fill:#ffe1f5
\`\`\`

**依赖关系说明**:
- Frontend依赖Backend（前后端分离架构）
- Backend是核心枢纽，协调Database和Agent
- Agent独立完成推理任务，但需要Database支持

---

## 5. 技术栈总览 (Technology Stack Overview)

| Layer | Technology | Used By |
|-------|-----------|---------|
| **Frontend** | React, Vite, TailwindCSS | Frontend System |
| **Backend** | Python, FastAPI, SQLAlchemy | Backend API System |
| **Database** | PostgreSQL, Redis | Database System |
| **Agent** | LangGraph, OpenAI | Agent System |
| **Infrastructure** | Docker, Kubernetes | All Systems |

---

## 6. 拆分原则与理由 (Decomposition Rationale)

### 为什么拆分为这些系统？

**技术栈维度**:
- Frontend (React) vs Backend (Python) → 技术栈完全不同，必须分离

**部署维度**:
- Frontend (静态部署CDN) vs Backend (容器部署) → 部署方式不同

**职责维度**:
- Backend API (业务逻辑) vs Agent (推理逻辑) → 职责独立，可并行开发

**变化频率**:
- Frontend (UI变化频繁) vs Database Schema (相对稳定) → 分离便于独立演进

### 为什么不进一步拆分？

**Frontend为什么不拆分为多个系统？**
- 虽然有多个页面，但共享状态和组件，拆分会增加复杂度

**Backend为什么不拆成微服务？**
- 当前规模不需要，Modular Monolith足够
- 可以通过模块化代码结构实现关注点分离

---

## 7. 系统复杂度评估 (Complexity Assessment)

**系统数量**: 4个系统

**评估**:
- ✅ 数量合理 (< 10)
- ✅ 边界清晰
- ✅ 依赖关系简单（无循环依赖）

**潜在风险**:
- Backend API可能成为瓶颈（协调多个系统）
- 未来可能需要拆分Backend（当代码量 > 50K行时）

---

## 8. 下一步行动 (Next Steps)

### 为每个系统设计详细文档

运行以下命令为每个系统创建设计文档：

\`\`\`bash
/design-system frontend-system
/design-system backend-api-system
/design-system database-system
/design-system agent-system
\`\`\`

### 所有系统设计完成后

运行任务拆解：
\`\`\`bash
/blueprint
\`\`\`

🛡️ Decomposition Guidelines

Guideline 1: Do Not Over-Decompose

Rule: The number of systems is usually < 10.

Why? Over-decomposition increases communication cost and complexity.

Check Questions:

"Can this system be merged into another system?"
"Does the decomposition truly bring value (independent deployment, technology stack differences)?"

Example:

❌ 错误: 把每个API端点拆成独立系统
✅ 正确: 所有API端点属于Backend API System

Guideline 2: Do Not Over-Aggregate

Rule: Frontend, backend, and database are usually independent systems.

Why? Their technology stacks and deployment methods differ, so they should be separated.

Check Questions:

"Are the technology stacks of these two parts completely different?"
"Are they deployed at different times by different teams?"

Example:

❌ 错误: React前端和Python后端合并为"Web System"
✅ 正确: 拆分为Frontend System和Backend System

Guideline 3: Boundaries Must Be Clear

Rule: The inputs and outputs of each system must be clearly defined.

Why? Blurry boundaries lead to overlapping responsibilities and chaotic dependencies.

Check Questions:

"What input does this system receive?"
"What output does this system produce?"
"What is the data format of the input and output?"

Example:

✅ 好的边界定义:
  Frontend System:
    - 输入: 用户操作 (MouseEvent, KeyboardEvent)
    - 输出: HTTP请求 (JSON格式的API调用)
  
❌ 模糊的边界:
  Frontend System:
    - 输入: 用户的东西
    - 输出: 数据

Guideline 4: Use the C4 Model for Visualization

Rule: Mermaid must be used to draw the system context diagram and dependency diagram.

Why? A picture is worth a thousand words; visualization aids understanding.

Mermaid Example:

graph TD
    User[用户] -->|使用| Frontend[Frontend System]
    Frontend -->|API| Backend[Backend System]
    Backend -->|数据| DB[(Database System)]

🧰 Toolbox

Tool 1: System Identification Checklist

Before decomposing the system, use this Checklist:

Identify all user touchpoints (Web, mobile, CLI)
Identify all data stores (database, cache, object storage)
Identify the location of core business logic (backend, Agent, batch processing)
Identify external integrations (payment, authentication, LLM)
Identify deployment units (frontend static, backend container, Worker)
Identify technology stack differences (React, Python, PostgreSQL)

Tool 2: Architecture Overview template

Path: Refer to the "Output Format" section above
Includes: System inventory, boundary matrix, dependency graph

Tool 3: Mermaid diagrams

System context diagram (C4 Level 1):

graph TD
    User -->|使用| System
    System -->|调用| External

System dependency graph:

graph LR
    A[System A] --> B[System B]
    B --> C[System C]

💡 Common scenarios and patterns

Scenario 1: Simple web application

Characteristics: Frontend + backend + database

Recommended decomposition:

Frontend System (React)
Backend API System (FastAPI)
Database System (PostgreSQL)

Total: 3 systems

Scenario 2: Web application with AI features

Characteristics: Frontend + backend + database + AI Agent

Recommended decomposition:

Frontend System
Backend API System
Agent System (LangGraph)
Database System

Total: 4 systems

Scenario 3: Complex enterprise application

Characteristics: Multiple clients + backend + database + search + queue

Recommended decomposition:

Web Frontend System
Mobile System
Backend API System
Database System
Search System (Elasticsearch)
Worker System (Celery)

Total: 6 systems

📊 Quality checklist

After completing the Architecture Overview, use this checklist for self-check:

Number of systems

Number of systems is 3-10 (typical range)
No over-decomposition (one system per feature)
No over-aggregation (all features in one system)

System boundaries

Each system has clear input and output definitions
Each system has clear and single responsibilities
No overlap of responsibilities between systems

Dependencies

No circular dependencies
Dependencies are clearly visualized (Mermaid diagram)
Dependencies per system < 5 (avoid over-coupling)

Documentation completeness

Has a system context diagram (C4 Level 1)
Each system has detailed inventory entries
Has a system boundary matrix
Has a system dependency graph
Has decomposition principles and rationale

🚀 Quick start example

Task: Decompose the system for a Todo application

Step 1: Apply the 6-dimension framework

User touchpoints: Web interface
Data storage: PostgreSQL
Business logic: FastAPI backend
External integrations: None
Deployment units: Frontend CDN, backend container
Technology stack: React, Python, PostgreSQL

Step 2: Identify systems

Frontend System (React)
Backend API System (FastAPI)
Database System (PostgreSQL)

Step 3: Define boundaries

Frontend: Input user actions → Output API requests
Backend: Input HTTP requests → Output JSON responses
Database: Input SQL queries → Output data

Step 4: Draw the dependency graph

Frontend → Backend → Database

Step 5: Produce the Architecture Overview Use the template to fill in the content → Save to genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md

Remember: Good system decomposition is the art of balance.
Do not over-decompose (microservices trap), and do not over-aggregate (big ball of mud).

Happy Architecting! 🏗️

About this skill

⚠️ Mandatory Deep Thinking

⚠️ Core Principles

🎯 System Identification Framework: 6 Dimensions

1. User Touchpoints

2. Data Storage

3. Core Business Logic

4. External Integrations

5. Deployment Units

6. Technology Stack

📋 Output Format: Architecture Overview Template

🛡️ Decomposition Guidelines

Guideline 1: Do Not Over-Decompose

Guideline 2: Do Not Over-Aggregate

Guideline 3: Boundaries Must Be Clear

Guideline 4: Use the C4 Model for Visualization

🧰 Toolbox

Tool 1: System Identification Checklist

Tool 2: Architecture Overview template

Tool 3: Mermaid diagrams

💡 Common scenarios and patterns

Scenario 1: Simple web application

Scenario 2: Web application with AI features

Scenario 3: Complex enterprise application

📊 Quality checklist

Number of systems

System boundaries

Dependencies

Documentation completeness

🚀 Quick start example