Back to Details

architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture

架构

Outcome

预期成果

Create or update root 
ARCHITECTURE.md
so a new teammate can understand the system that exists in code today.
The document should reveal the few rules that give the system its shape: where truth lives, which way dependencies point, how important work moves through the system, and which boundaries a change must preserve.
创建或更新根目录下的
ARCHITECTURE.md
文档，使新成员能够理解当前代码中实际存在的系统。
该文档应揭示塑造系统形态的核心规则：数据真相的存储位置、依赖关系的指向、关键工作流在系统中的流转方式，以及变更必须遵守的边界。

Workflow

工作流程

  1. Read the request, repository instructions, and any existing 
    ARCHITECTURE.md
    .
  2. Inspect the implementation. Start with manifests, entry points, configuration, schemas, migrations, infrastructure, tests, and the code behind a few critical flows. Follow evidence rather than trying to read every file.
  3. Identify the load-bearing facts: the system boundary, trust boundaries, source of truth, main parts, dependency direction, important protocols or data, and the one rule a contributor must not break.
  4. Create or update root 
    ARCHITECTURE.md
    . Preserve useful verified content from an existing document, remove stale claims, and organize the body around the system rather than a generic template.
  5. Verify each concrete claim against code, configuration, schemas, infrastructure, or executable tests. Treat existing prose as a claim, not evidence.
  6. Run the review pass and stop with the document ready for human review. Do not propose future behavior, write a design, plan work, or change implementation.
  1. 阅读需求、代码仓库说明以及现有
    ARCHITECTURE.md
    文档（若存在）。
  2. 检查实现细节。从清单文件、入口点、配置、schema、迁移脚本、基础设施、测试用例，以及几个关键流程背后的代码入手。依据实际证据进行分析，无需逐文件通读。
  3. 识别核心关键信息：系统边界、信任边界、数据真相来源、主要组件、依赖方向、重要协议或数据，以及贡献者绝对不能违反的核心规则。
  4. 创建或更新根目录下的
    ARCHITECTURE.md
    文档。保留现有文档中经过验证的有用内容，移除过时表述，围绕系统实际情况组织文档结构，而非套用通用模板。
  5. 对照代码、配置、schema、基础设施或可执行测试，验证每一个具体表述。将现有文档中的文字视为待验证的主张，而非证据。
  6. 完成审核环节，使文档准备好供人工审核。请勿提出未来行为建议、撰写设计方案、规划工作或修改实现代码。

Document shape

文档结构

Start every document with this small common frame:
markdown
undefined
所有文档均以以下通用框架开头：
markdown
undefined

<System> Architecture

<System> Architecture

Executive summary

Executive summary

Explain what the system does, name its source of truth, show how its main parts work together, and state the most important architectural rule.
Explain what the system does, name its source of truth, show how its main parts work together, and state the most important architectural rule.

System architecture

System architecture

Show the users, outside systems, runtime parts, and data stores in one small diagram when this makes the boundary clearer.
Show the users, outside systems, runtime parts, and data stores in one small diagram when this makes the boundary clearer.

Dependency hierarchy

Dependency hierarchy

Show which way important dependencies point. State the rule in prose below the diagram.

Shape the remaining sections around the repository itself. Prefer names such as `Protocol`, `Request lifecycle`, `Event pipeline`, `Storage model`, or the real component names. Do not add sections that have nothing useful to say.

For each critical flow:

- walk the path in exact execution order;
- include authentication, authorization, validation of untrusted input, persistence, side effects, response timing, cleanup, and recovery when they matter;
- show where permissions are enforced and whether security-sensitive failures fail closed;
- put hard limits and failure behavior beside the step they affect.

For each important component, state:

- what it owns;
- its important inputs, outputs, interfaces, or stored data;
- what it depends on;
- the permissions it has and the trust boundaries it crosses, when relevant;
- what it does **not** own.

End with a small source map that links concepts to their authoritative files and a verification section that names the checks or tests supporting important claims. State genuine evidence gaps instead of guessing.
Show which way important dependencies point. State the rule in prose below the diagram.

根据代码仓库的实际情况构建剩余章节。优先使用`协议`、`请求生命周期`、`事件流水线`、`存储模型`或组件真实名称作为章节标题。请勿添加无实际内容的章节。

针对每个关键流程：

- 按实际执行顺序梳理流程路径；
- 若相关，需包含身份验证、授权、不可信输入验证、持久化、副作用、响应时序、清理和恢复机制；
- 说明权限执行的位置，以及安全敏感故障是否采用关闭式失败策略；
- 在相关步骤旁标注硬限制和故障行为。

针对每个重要组件，需说明：

- 它负责的内容；
- 重要的输入、输出、接口或存储的数据；
- 它依赖的对象；
- 相关的权限以及它跨越的信任边界；
- 它不负责的内容。

文档末尾添加小型源映射，将概念链接至其权威文件，并添加验证章节，列出支持重要表述的检查或测试用例。若存在证据缺口，请如实说明，切勿猜测。

Writing rules

写作规则

  • Describe implemented reality only. Use 
    /design
    to decide future architecture or behavior.
  • Write for a new teammate who needs to change the system safely.
  • Lead with the source of truth, dependency direction, and load-bearing rules. Put detail later.
  • For each architectural invariant, name the code, schema, runtime guard, or test that enforces it.
  • Organize around runtime concepts and flows, not the directory tree.
  • Prefer exact names and execution order over broad labels such as "service layer" or "robust".
  • Keep diagrams small and useful. Use them for topology, dependency direction, or a flow that is harder to understand in prose.
  • Keep the length proportional to the system. A small repository needs a small document. A large system may need detailed protocol, lifecycle, and component sections.
  • Link to detailed API, schema, operations, or test documentation instead of copying it.
  • Do not include proposals, roadmaps, possible redesigns, or speculative limitations.
  • Do not turn the document into an exhaustive API reference, file inventory, or generated code tour.
  • Use short sentences and everyday words. Define technical and project-specific terms when first used.
  • Do not use em dashes.
Update 
ARCHITECTURE.md
when implementation changes ownership, dependency direction, protocols, stored data, trust boundaries, deployment topology, or hard limits.
  • 仅描述已实现的实际情况。若需确定未来架构或行为，请使用
    /design
    流程。
  • 为需要安全修改系统的新成员撰写文档。
  • 优先说明数据真相来源、依赖方向和核心规则，细节内容后置。
  • 针对每个架构不变量，说明执行它的代码、schema、运行时守卫或测试用例。
  • 围绕运行时概念和流程组织内容，而非目录结构。
  • 优先使用精确名称和执行顺序，而非宽泛标签（如“服务层”或“健壮性”）。
  • 保持图表简洁实用。图表应用于展示拓扑结构、依赖方向或难以用文字描述的流程。
  • 文档长度与系统规模成正比。小型代码仓库只需简短文档，大型系统可能需要详细的协议、生命周期和组件章节。
  • 链接至详细的API、schema、操作或测试文档，而非复制内容。
  • 请勿包含提案、路线图、可能的重新设计或推测性限制。
  • 请勿将文档变成详尽的API参考、文件清单或自动生成的代码导览。
  • 使用短句和日常词汇。首次使用技术术语或项目特定术语时需定义。
  • 请勿使用破折号。
当实现内容在所有权、依赖方向、协议、存储数据、信任边界、部署拓扑或硬限制方面发生变更时，需更新
ARCHITECTURE.md
文档。

Review pass

审核环节

Reread the document and check:
  1. Truth. Does every current-state claim match the working tree?
  2. Shape. Can a new teammate find the source of truth, system boundary, dependency direction, and critical flows quickly?
  3. Boundaries. Does each important part say what it owns, does not own, may access, and must not trust?
  4. Mechanics. Are order, data movement, failure behavior, cleanup, and limits concrete where they matter?
  5. Maintenance. Does the document avoid volatile detail that adds upkeep without helping someone make a safe change?
  6. Separation. Are all proposed changes kept in design documents rather than presented as implemented architecture?
Correct every issue supported by repository evidence. Put anything that cannot be verified under 
Verification
with the evidence needed to resolve it.
重新阅读文档并检查：
  1. 真实性：每个关于当前状态的表述是否与工作区内容一致？
  2. 结构性：新成员能否快速找到数据真相来源、系统边界、依赖方向和关键流程？
  3. 边界清晰性：每个重要组件是否明确说明了其负责内容、不负责内容、可访问对象和必须不信任的对象？
  4. 机制明确性：在关键位置，流程顺序、数据流转、故障行为、清理机制和限制是否具体明确？
  5. 可维护性：文档是否避免了那些会增加维护成本却无助于安全变更的易变细节？
  6. 分离性：所有拟议变更是否都保留在设计文档中，而非作为已实现架构呈现？
根据代码仓库中的证据修正所有问题。对于无法验证的内容，将其置于「验证」章节下，并注明解决所需的证据。