Introduction and Goals
Requirements Overview
ProductShape is the reference implementation of Product Definition as Code: a TypeScript command-line toolkit for defining product knowledge in versioned Markdown, validating its structure, and connecting accepted artifacts to delivery documents. The project does not own the normative methodology; that specification is maintained separately.
The architecture supports a repository-first workflow. The model is authored as files, deterministic code checks structure and relationships, AI integrations assist with semantic drafting, and human review accepts changes. See the ProductShape model for product intent and the PDaC specification for normative contracts.
Quality Goals
| Priority | Goal | Architectural response |
|---|---|---|
| 1 | Same authored content produces the same structural results | Pure deterministic core, normalized serialization, ordered diagnostics |
| 2 | Usable across Windows, macOS, and Linux | Node.js CLI, portable path handling, no shell-dependent core behavior |
| 3 | Product truth stays reviewable and owned by its repository | Markdown and YAML are canonical; graph, reports, and snapshots are derived |
| 4 | Provider integrations do not change product semantics | Separate renderers consume canonical assets through explicit adapters |
| 5 | People can inspect the model without installing the CLI | A generated, self-contained, read-only Product Snapshot |
Stakeholders
| Architecture reader | Expectation |
|---|---|
| Maintainer | Understand package boundaries, release paths, and implementation trade-offs |
| Contributor | Locate the implementation area for a behavior without treating generated files as canonical |
| Adopter | Understand the CLI and its integrations at a technical level |
| Architecture reviewer | Check that implementation structure stays aligned with product intent and recorded ADRs |