architecture-designer

Skill: Architecture Designer

在逐场景的技术实现之前，建立项目的技术全局视图——系统架构、技术选型、部署拓扑和非功能性约束。确保后续的时序图、API 和代码生成在一致的架构约束下进行。

触发条件

• 用户要求设计技术架构、做技术选型或规划系统架构
• 用户提到 "Phase 3 Step 0"、"架构设计"、"技术方案"
• Phase 2 产品设计文档已完成，需要开始 Phase 3
• 用户想要确定技术栈或部署方案

核心能力

1. 读取 Phase 1 需求文档和 Phase 2 产品设计文档，理解产品全貌
2. 基于产品复杂度和场景特征，推荐适合的系统架构
3. 为每项技术选型提供选型理由和替代方案对比
4. 绘制系统架构图（Mermaid）和部署拓扑图
5. 更新 logos-project.yaml 的 tech_stack 字段

与 Phase 1/2 的衔接

架构设计是 Phase 2（产品设计）到 Phase 3（技术实现）的桥梁。它的输入来自 Phase 1/2，输出影响 Phase 3 所有后续步骤：

输入（来自 Phase 1/2）	输出（影响 Phase 3 后续步骤）
场景清单和复杂度	系统边界划分 → 时序图的参与方
非功能性需求（性能、安全）	技术选型约束 → API 设计决策
产品交互方式（Web/Mobile/API）	前端技术栈 → 原型实现方式
数据量和访问模式	数据库选型 → DB 设计
第三方服务依赖（支付、邮件等）	集成方式 → 时序图中的外部参与方

执行步骤

Step 1: 理解产品全貌

读取以下文档，建立对项目的整体认知：

• 需求文档（Phase 1）：产品定位、核心场景、约束与边界
• 产品设计文档（Phase 2）：信息架构、页面结构、交互复杂度
• 已有的 logos-project.yaml：当前 tech_stack 中是否已有初始选型

重点提取：

• 核心场景数量和复杂度
• 是否有实时性需求（WebSocket、SSE）
• 是否有后台任务（定时任务、消息队列）
• 第三方服务依赖清单
• 用户规模预期

Step 2: 确定系统架构

根据产品复杂度选择架构模式：

简单项目（个人 SaaS、工具类产品）：

• 单体架构 + 单数据库
• 架构概要可以用一段文字 + 一张简图

中等项目（团队 SaaS、多角色系统）：

• 前后端分离 + 单体后端 + 单数据库
• 可能需要对象存储、缓存等辅助服务

复杂项目（多服务、高并发、多端）：

• 微服务 / 模块化单体
• 需要详细的架构决策记录（ADR）

用 Mermaid 绘制系统架构图：

graph TB
    subgraph Frontend
        Web[Web App - Next.js]
    end
    subgraph Backend
        API[API Server - Node.js]
        Worker[Background Worker]
    end
    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
        S3[Object Storage]
    end
    subgraph External
        Auth[Supabase Auth]
        Email[SendGrid]
    end

    Web -->|REST API| API
    API --> DB
    API --> Cache
    API --> S3
    API --> Auth
    Worker --> DB
    Worker --> Email

Step 3: 技术选型

为每个技术维度给出选型和理由：

| 维度 | 选型 | 理由 | 备选方案 |
|------|------|------|---------|
| 语言 | TypeScript | 前后端统一、类型安全 | Go（性能优先时） |
| 前端框架 | Next.js 15 | SSR + RSC、生态成熟 | Astro（内容站）、Nuxt（Vue 生态） |
| 后端框架 | Hono | 轻量、边缘优先、TS 原生 | Express（生态）、Fastify（性能） |
| 数据库 | PostgreSQL | 功能丰富、JSONB、RLS | MySQL（简单场景） |
| 认证 | Supabase Auth | 开箱即用、RLS 集成 | NextAuth（自托管） |
| 部署 | Vercel + Supabase | 零运维、自动扩容 | AWS（自主控制） |