architecture-design

---
name: architecture-design
description: Design business architecture and technical architecture for staged software projects, including Mermaid diagrams, module boundaries, data flows, deployment view, integration points, project structure, and architecture risks. Use when moving from business context to architecture, when documenting module/service boundaries, or when reviewing whether architecture is ready for API/database design and implementation.
license: MIT
---

# Architecture Design

<!-- 中文说明: 架构设计要优先用 Mermaid 表达，复杂图可以建议使用 fireworks-tech-graph 生成 SVG/PNG。 -->

## Purpose

Use this skill to turn business discovery into clear business and technical architecture. Prefer diagrams plus concise explanation.

## Artifact Paths

<!-- 中文说明: 新项目默认使用阶段子目录；旧项目的扁平 docs 路径仍可兼容，但不要混用两套默认路径。 -->

For new projects, use staged document folders:

- `docs/00-discovery/project-brief.md`
- `docs/00-discovery/business-architecture.md`
- `docs/01-architecture/technical-architecture.md`
- `docs/01-architecture/project-structure.md`

Existing projects may keep legacy flat files such as `docs/01-business-architecture.md` and `docs/04-project-structure.md`, but new Matrix Boot projects should default to the staged paths above.

## Business Architecture

Produce or refine `docs/00-discovery/business-architecture.md`:

- Business capabilities.
- User roles and external actors.
- Business workflow.
- Business entities and ownership.
- Upstream/downstream systems.
- Key business risks and assumptions.

Use Mermaid flowcharts or sequence diagrams when helpful.

## Technical Architecture

Produce or refine `docs/01-architecture/technical-architecture.md`:

- System context.
- Application/module boundaries.
- Backend/frontend boundary.
- Data flow.
- Integration points.
- Authentication and authorization flow.
- Deployment topology.
- Observability and operations view.
- Architecture risks and tradeoffs.

## Diagram Policy

- Use Mermaid by default because it is easy to version in Markdown.
- For more polished architecture diagrams, suggest the optional `fireworks-tech-graph` skill when installed.
- Do not require `fireworks-tech-graph` for basic usage. It is an enhancement path, not a hard dependency.
- If using `fireworks-tech-graph`, provide the Mermaid or structured diagram intent as input and ask it to export SVG/PNG.

## Project Structure Templates

Produce or refine `docs/01-architecture/project-structure.md` before detailed requirements, API/database design, or implementation.

V1 defaults to a backend + frontend monorepo. Android, iOS, mini program, and split-repository templates are future extensions unless the user explicitly asks for a custom structure.

Default monorepo structure:

```text
project-root/
  .project-guide/
    state.yaml

  docs/
    00-discovery/
      project-brief.md
      business-architecture.md
    01-architecture/
      technical-architecture.md
      project-structure.md
    02-tech-stack/
      tech-stack-decision.md
    03-frontend-design/
      frontend-ux-design.md
    04-requirements/
      requirements-detail.md
    05-api-db/
      api-design.md
      database-design.md
    06-verification/
      implementation-verification.md
    07-integration-test/
      integration-test-plan.md
      integration-test-cases.md
      integration-test-report.md
    08-performance-test/
      performance-test-plan.md
      performance-test-cases.md
      performance-test-report.md
    09-release/
      release-readiness.md

  backend/
    pom.xml
    src/main/java/<basePackage>/
    src/main/resources/
    src/test/java/<basePackage>/

  frontend/
    package.json
    src/
    tests/

  scripts/
    db/
      migration/
      seed/
    test/
      integration/
    perf/
    deploy/

  reports/
    verification/
    integration/
    performance/

  DESIGN.md
  README.md
  .gitignore
```

When confirming project structure, require the user to input or explicitly confirm:

- Repository mode: default `monorepo`.
- Backend path: default `backend/`.
- Frontend path: default `frontend/`.
- Java `groupId`: must be provided or confirmed by the user.
- Java `basePackage`: must be provided or confirmed by the user.
- Documentation path: default `docs/`.
- Database script path: default `scripts/db/`.
- Database migration path: default `scripts/db/migration/`.
- Seed data path: default `scripts/db/seed/`.
- Integration test script path: default `scripts/test/integration/`.
- Performance test script path: default `scripts/perf/`.
- Deployment script path: default `scripts/deploy/`.
- Verification report output path: default `reports/verification/`.
- Integration test raw output path: default `reports/integration/`.
- Performance test raw output path: default `reports/performance/`.
- Project design file: default `DESIGN.md`.
- Root project README: default `README.md`.
- Git ignore file: default `.gitignore`.

Do not silently generate Java package names. A suggested value is allowed, but the user must approve it before implementation.

`scripts/` must contain source scripts and executable test definitions only. Do not place generated JMeter HTML reports, Playwright traces, screenshots, logs, `target/`, `node_modules/`, or build outputs under `scripts/`. Store raw execution output under `reports/`, summarize reviewable results in `docs/`, and ignore heavyweight/generated output in `.gitignore`.

Ask the user to confirm these choices before generating code. Native choice widgets are client-dependent; if no structured UI is available, present numbered project structure options and ask the user to reply with the number or option name.

Fallback format:

```text
Choose a project structure:
1. Default monorepo - backend/, frontend/, docs/, scripts/
2. Monorepo with custom paths
3. Backend-only repository
4. Frontend-only repository
5. Custom structure

Reply with a number or option name.
```

After producing business architecture, technical architecture, diagrams, or project structure, stop and request explicit user review. Do not proceed to technology selection, detailed requirements, API/database design, or implementation until the relevant artifact is approved.

Project structure is not approved until `docs/01-architecture/project-structure.md` exists or is intentionally mapped to a legacy equivalent, and repository mode, key paths, Java `groupId`, and Java `basePackage` are explicitly confirmed.

## Gate Checks

Architecture is not ready until:

- Business and technical diagrams are present or intentionally skipped.
- Main modules and boundaries are clear.
- Key data flows are clear.
- External integrations are identified.
- Project structure is confirmed.
- Java `groupId` and `basePackage` are confirmed.
- Major risks are documented.