102 System Architecture

What this skill is for

102-system-architecture produces the system architecture document: the technology stack, major components, deployment topology, integration points, and testing strategy. It is the technical baseline that every downstream SpecFlow document — backend architecture, frontend architecture, data model — references rather than re-establishing.

Output path: .specflow/docs/D02-system-architecture.md

When to use it

• When the project needs a shared technical baseline before backend or frontend design begins
• When the team has technology decisions to make explicit and record
• On existing projects where the architecture has never been fully written down
• Before 103, 104, or 105, which all depend on understanding the system shape

When NOT to use it

• When a clear, current architecture document already exists and is trusted by the team
• For a tiny prototype where a full architecture document would be premature overhead

Optional but important

On projects where the technology choices are still being made, 102 is the right moment to make those decisions explicit and reviewable. Running feature design against an undocumented or misunderstood architecture is one of the more common sources of rework.

What it produces

• .specflow/docs/D02-system-architecture.md covering:
  • System overview and architectural style
  • Technology stack decisions with rationale
  • Major components and their responsibilities
  • Deployment topology and environment model
  • Key integration points and external dependencies
  • Testing strategy and tooling
  • Relevant constraints and architectural decisions

Required inputs

1. Frontend framework and rendering approach
2. Backend runtime and API style
3. Database and storage choices
4. Deployment target and hosting model
5. Testing approach and key tooling

Tech stack auto-detection

Before asking for any of the above, 102 will attempt to infer your stack automatically — first from installed skills (e.g. react, solid.js, astro.js, typescript-engineering), then from existing project documentation, then from the codebase itself. Detected choices are presented for confirmation rather than asked from scratch. If no skills are installed and no code exists yet, the skill will ask targeted questions for each unresolved concern instead of guessing.

Common prompts

Prompt

Run 102-system-architecture. We are building a React SPA with a Node.js REST API, PostgreSQL, and deploying to AWS.

Prompt

Run 102 for an Astro + SolidJS frontend with a Firebase backend.

What usually comes next

103-common-data-model — define the entities and relationships the system must manage, using the architecture as context.

Practical guidance

• Include the rationale for key technology choices. Downstream work benefits from knowing why decisions were made, not just what was decided.
• If the project already has code, tell it to run 102 on the exsisting code base and it will create the documenation for you.
• Reference D01 for user goals and business requirements — D02 should not re-state what D01 already captured.

Common mistakes

• Leaving the testing strategy section as “we will write tests” without specifying tooling or approach
• Describing the ideal architecture rather than the actual one on existing projects