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.