Solution Architecture Layer — Derive, Store, Validate
Why
Architectural decisions live in separate ADRs or Confluence pages with zero programmatic links to requirements or code. This is the layer where the costliest misalignments occur — a wrong architectural choice invalidates entire implementation efforts regardless of code quality. No tool today systematically connects business requirements → architectural decisions → implementation. A solution architecture module that derives, stores, and validates architecture with explicit traceability to requirements closes the biggest blind spot in the end-to-end chain.
Module Package Structure
modules/architecture/
module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace
src/architecture/
__init__.py
main.py # typer.Typer app — architecture command group
engine/
deriver.py # Derive architecture from requirements (template + AI-assisted)
coverage_validator.py # Validate architecture covers all requirements
trace_builder.py # Build architecture ↔ requirements traceability links
models/
solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models
templates/
microservice.yaml # Microservice architecture template
monolith.yaml # Modular monolith template
event_driven.yaml # Event-driven architecture template
commands/
derive.py # specfact architecture derive
validate_coverage.py # specfact architecture validate-coverage
trace.py # specfact architecture trace
storage/
architecture_store.py # Read/write .specfact/architecture/*.arch.yaml
module-package.yaml declares:
name: architectureversion: 0.1.0commands: [architecture derive, architecture validate-coverage, architecture trace]dependencies: [requirements-01-data-model, requirements-02-module-commands]schema_extensions: — via arch-07publisher: + integrity: — arch-06 marketplace readiness
What Changes
- NEW: Pydantic domain models in
modules/architecture/src/architecture/models/:
SolutionArchitecture — architecture ID, requirement IDs (traceability links), components, data flows, ADRsComponentSpec — name, responsibility, business rule IDs (from requirements), integrationsDataFlow — source, target, data type, protocolADR — ADR ID, decision, rationale (links to architectural constraints from requirements), alternatives considered, tradeoff
- NEW:
specfact architecture derive --requirements .specfact/requirements/ --suggest-components --interactive — derive architecture from requirements using templates and optional AI assistance
- NEW:
specfact architecture validate-coverage — verify every business rule maps to a component, every architectural constraint has an ADR, every component has spec coverage
- NEW:
specfact architecture trace --format table|json|markdown — show traceability matrix: requirements ↔ components ↔ ADRs ↔ specs
- NEW: Storage convention:
.specfact/architecture/{architecture_id}.arch.yaml
- NEW: Architecture templates for common patterns (microservice, monolith, event-driven) — profile-aware complexity
- EXTEND:
ProjectBundle extended with optional architecture field via arch-07 schema extensions (namespace: architecture.solution_architecture)
Capabilities
New Capabilities
solution-architecture: Derive, store, and validate solution architecture with explicit traceability to business requirements. Includes component specs, data flows, ADRs, and coverage validation.
Modified Capabilities
data-models: ProjectBundle extended with architecture field via arch-07 schema extensions
OpenSpec Change Proposal: architecture-01-solution-layer
Solution Architecture Layer — Derive, Store, Validate
Why
Architectural decisions live in separate ADRs or Confluence pages with zero programmatic links to requirements or code. This is the layer where the costliest misalignments occur — a wrong architectural choice invalidates entire implementation efforts regardless of code quality. No tool today systematically connects business requirements → architectural decisions → implementation. A solution architecture module that derives, stores, and validates architecture with explicit traceability to requirements closes the biggest blind spot in the end-to-end chain.
Module Package Structure
module-package.yamldeclares:name: architectureversion: 0.1.0commands: [architecture derive, architecture validate-coverage, architecture trace]dependencies: [requirements-01-data-model, requirements-02-module-commands]schema_extensions:— via arch-07publisher:+integrity:— arch-06 marketplace readinessWhat Changes
modules/architecture/src/architecture/models/:SolutionArchitecture— architecture ID, requirement IDs (traceability links), components, data flows, ADRsComponentSpec— name, responsibility, business rule IDs (from requirements), integrationsDataFlow— source, target, data type, protocolADR— ADR ID, decision, rationale (links to architectural constraints from requirements), alternatives considered, tradeoffspecfact architecture derive --requirements .specfact/requirements/ --suggest-components --interactive— derive architecture from requirements using templates and optional AI assistancespecfact architecture validate-coverage— verify every business rule maps to a component, every architectural constraint has an ADR, every component has spec coveragespecfact architecture trace --format table|json|markdown— show traceability matrix: requirements ↔ components ↔ ADRs ↔ specs.specfact/architecture/{architecture_id}.arch.yamlProjectBundleextended with optionalarchitecturefield via arch-07 schema extensions (namespace:architecture.solution_architecture)Capabilities
New Capabilities
solution-architecture: Derive, store, and validate solution architecture with explicit traceability to business requirements. Includes component specs, data flows, ADRs, and coverage validation.Modified Capabilities
data-models: ProjectBundle extended with architecture field via arch-07 schema extensionsOpenSpec Change Proposal:
architecture-01-solution-layer