Modeling Guide¶

GUIDE · OVERVIEW

This guide walks through building a Syscribe model from scratch — from a directory skeleton to a fully traced, validated system description.

Prerequisites¶

Rust toolchain (stable, 1.75+)
cargo available on $PATH
A text editor with YAML syntax highlighting

Directory skeleton¶

model/
  _index.md          # root namespace (type: Namespace or Package)
  Requirements/
    _index.md        # Requirements package
  Verification/
    _index.md
  Decisions/
    _index.md
  MySystem/
    _index.md

Each _index.md declares the package:

---
type: Package
name: Requirements
---

System requirements for the XYZ project.

Running the validator¶

cargo run --package syscribe -- -m model/

This prints a full Markdown report to stdout with all errors, warnings, and a traceability matrix. Pipe it to a file for review:

cargo run --package syscribe -- -m model/ > reports/validation.md

Running the web browser¶

cargo run --package syscribe-server -- -m model/
# Listening on http://127.0.0.1:3000

The server watches the model directory for changes and reloads automatically.

Typical workflow¶

Identify stakeholder goals — write parent Requirement elements with REQ-SYS-000 style IDs
Decompose requirements — create child requirements with derivedFrom: and breakdownAdr:
Write an ADR for each decomposition decision — the validator enforces this (E310)
Build the architecture — create PartDef, PortDef, InterfaceDef elements
Assign requirements — add satisfies: and domain: to architecture elements
Link implementation — add implementedBy: on Part/PartDef/Interface/InterfaceDef to point at the source artifact that realises each element (§12.8); the validator flags missing paths with W023
Write test cases — create TestCase elements with verifies: and Gherkin bodies
Draw diagrams — create Diagram elements; add layout: for SVG rendering
Validate — run the validator; fix all errors; review warnings

Going further: a product line¶

If the system ships in more than one configuration, model the whole family as one 150% model instead of copying it per product:

Declare a feature model — add FeatureDef elements under Features/ (XOR/or/optional groups, requires:/excludes:, typed parameters:)
Condition the variants — add appliesWhen: to the elements (parts, requirements, test cases) that belong only to some products
Name the products — add Configuration elements (CONF-*) selecting one variant per group
Analyse and certify — feature-check --deep proves the feature model is sound; validate --config <C> certifies one product; validate --all-configs gates the whole family in CI

See the Variability & Product Lines guide for the full treatment, and the worked example below.

Worked example — the UAV product line¶

The bundled model/ is a UAV product line you can run every command against:

syscribe -m model/ feature-check --deep                      # feature model is sound
syscribe -m model/ matrix                                    # Requirement × Configuration grid
syscribe -m model/ validate --all-configs                    # certify every product
syscribe -m model/ diff --config CONF-UAV-SURVEY-001 \
                        --config CONF-UAV-DELIVERY-001        # what differs between products
syscribe -m model/ links UAV::Avionics::FlightController     # see its implementedBy code link
syscribe -m model/ refs firmware/flight_control/             # which elements that code realises

Its shape:

Feature model (model/Features/) — three mandatory XOR groups (Propulsion = Quad ⊕ Hex, Payload = Survey ⊕ Mapping ⊕ Delivery, DataLink = LoRa ⊕ Cellular ⊕ Satcom), an optional DualFlightController, cross-tree constraints (Delivery/DualFlightController requires Hex), and a typed parameter (Delivery.payloadCapacityKg).
Configurations (model/Configurations/) — three products: CONF-UAV-SURVEY-001, CONF-UAV-MAPPING-001, CONF-UAV-DELIVERY-001.
Conditioned elements — variant parts (PropulsionChoices, PayloadChoices, DataLinkChoices, BackupFlightController) and variant requirements/tests (REQ-UAV-MAP-001, REQ-UAV-CARGO-001, REQ-UAV-REDUN-001) carry appliesWhen:, all derived under ADR-SYS-PLE-001.
Implementation trace — architecture elements point at repo:firmware/... via implementedBy:.