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.

Architecture Design

Purpose

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

Artifact Paths

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:

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:

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.