Capability Guide: System Definition and Design¶

Purpose¶

Model system structure and architecture in a way that remains consistent across data models, governance views, and diagrams.

Modules In Scope¶

• sysdef_mgmt
• sysarch_mgmt
• diagrams_mgmt

When To Use This Guide¶

• establishing or refactoring system decomposition
• aligning architecture model and diagram representation
• diagnosing structure/diagram divergence

Integration Workflow¶

flowchart TD
    Define["Define System Entities"] --> Structure["Establish Relationships"]
    Structure --> Arch["Create Architecture Views"]
    Arch --> Diagram["Author/Update Diagrams"]
    Diagram --> Sync["Synchronize Diagram and Model"]
    Sync --> Review["Architecture Review"]

Step-by-Step¶

1. Create/update core system entities in sysdef_mgmt.
2. Define structural relationships and decomposition boundaries.
3. Build architecture views/governance states in sysarch_mgmt.
4. Update diagram representations in diagrams_mgmt.
5. Run sync and verify geometry/model consistency.
6. Re-validate dependent interface and requirement contexts.

Artifacts Produced¶

• canonical system definition entities
• architecture node and governance views
• synchronized diagram records and geometry state

Downstream Consumers¶

• interface_mgmt: interface endpoints and structural context
• requirements_mgmt: requirement scoping and linkage targets
• safety_assurance: architecture context for assurance narratives

Validation Checklist¶

docker compose run --rm app sh -c "pytest sysdef_mgmt/tests sysarch_mgmt/tests diagrams_mgmt/tests -v"
./scripts/run_smoke_tests.sh

• architecture views resolve to valid system entities
• diagram sync preserves intended structure
• no orphan diagram nodes after model changes

Common Failure Modes¶

# representative route mounts
urlpatterns = [
    path('sysdef/', include('sysdef_mgmt.urls', namespace='sysdef_mgmt')),
    path('sysarch/', include('sysarch_mgmt.urls')),
    path('diagrams/', include('diagrams_mgmt.urls', namespace='diagrams_mgmt')),
]