Skip to main content

Architecture Traceability

Architecture Traceability

Overview​

Architecture traceability in Pidima connects your architecture diagrams with requirements and test cases, creating a complete documentation chain. This is essential for regulated industries where you must demonstrate how requirements are implemented in the architecture and verified by tests.

Why Traceability Matters​

Regulatory Compliance​

Demonstrate to auditors that:

  • Every requirement has architectural representation
  • Architecture decisions align with requirements
  • Test cases verify architectural components
  • Changes are tracked across the system

Impact Analysis​

Understand the effect of changes:

  • Which diagrams are affected by a requirement change?
  • Which requirements depend on an architectural component?
  • What tests need updating when architecture changes?

Documentation Completeness​

Ensure comprehensive documentation:

  • No orphaned diagrams (not linked to requirements)
  • No requirements without architectural representation
  • Complete coverage across the development lifecycle

Team Communication​

Facilitate collaboration:

  • Developers see architecture for requirements they implement
  • Testers understand architecture they're verifying
  • Architects see which requirements drive design decisions

Traceability Relationships​

Requirements → Architecture​

Link Type: "Described By" or "Implements"

A requirement is described by architecture diagrams that show how it's implemented.

Example:

  • Requirement: "User shall authenticate with username and password"
  • Architecture: User authentication sequence diagram

Architecture → Requirements​

Link Type: "Describes" or "Implements"

An architecture diagram describes one or more requirements.

Example:

  • Architecture: API Gateway component diagram
  • Requirements: All requirements related to API routing, authentication, and service integration

Architecture → Test Cases​

Link Type: "Verified By"

Architecture components are verified by test cases.

Example:

  • Architecture: Payment processing sequence diagram
  • Test Cases: Payment flow tests, error handling tests, security tests

Viewing Traceability​

From Architecture Details Page​

View Linked Requirements​

  1. Navigate to Architecture page
  2. Click on an architecture diagram
  3. Scroll to Linked Requirements section
  4. See all requirements linked to this diagram

Information shown:

  • Requirement ID and name
  • Requirement type
  • Priority and status
  • Quick link to requirement details

View Linked Test Cases (Indirect)​

Test cases linked to the requirements are indirectly linked to the architecture.

  1. View linked requirements
  2. Click on a requirement
  3. See test cases linked to that requirement

From Requirements Details Page​

View Linked Architecture​

  1. Navigate to Requirements page
  2. Click on a requirement
  3. Scroll to Architecture section
  4. See all diagrams linked to this requirement

Information shown:

  • Diagram name
  • Diagram type (Use Case, Component, etc.)
  • Created date
  • Quick preview/link to diagram

From Traceability Matrix​

The traceability matrix provides a comprehensive view:

Requirements-Architecture Matrix​

  1. Navigate to Traceability page
  2. Select Architecture tab
  3. View matrix showing:
    • Rows: Requirements
    • Columns: Architecture diagrams
    • Cells: Links between them

Features:

  • Filter by level, status, priority
  • Search requirements and diagrams
  • Export to Excel
  • Identify coverage gaps

Coverage Indicators​

  • ✅ Green — Requirement has architecture links
  • ⚠️ Yellow — Partial coverage
  • ❌ Red — No architecture for requirement

Method 1: From Architecture Diagram​

  1. Open architecture diagram details
  2. Click Link Requirements button
  3. Select requirements from the list:
    • Use checkboxes for selection
    • Search to find specific requirements
    • Filter by level, type, status
  4. Click Save Links

Tips:

  • Link 3-10 requirements per diagram typically
  • Link requirements that the diagram illustrates
  • Don't over-link unrelated requirements
  1. Open architecture diagram details
  2. In Linked Requirements section
  3. Click X or Unlink next to requirement
  4. Confirm unlinking

Method 2: From Requirement​

  1. Open requirement details
  2. Scroll to Architecture section
  3. Click Link Architecture button
  4. Select diagrams from the list:
    • Choose relevant diagram types
    • View diagram previews
    • Select multiple diagrams
  5. Click Save Links

Tips:

  • Link diagrams that show this requirement's implementation
  • Include multiple diagram types for complete view
  • Use sequence diagrams for functional requirements
  • Use component diagrams for structural requirements

Method 3: During Generation​

When generating architecture with AI:

  1. Select requirements for generation
  2. Generate diagram
  3. Links are created automatically to selected requirements

Automatic linking:

  • ✅ Links created when diagram generated
  • ✅ Saves time on manual linking
  • ✅ Ensures generated diagrams are traceable
  • ⚠️ Review and adjust links if needed

Method 4: Bulk Linking (API)​

For large-scale linking, use the API:

curl -X POST https://pidima.ai/api/v1.0/architecture/{id}/requirements \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requirementIds": [
      "uuid1", "uuid2", "uuid3"
    ]
  }'

Traceability Best Practices​

Best Practice: Create links when creating or generating diagrams

Why:

  • Context is fresh in your mind
  • Prevents orphaned diagrams
  • Maintains traceability from the start
  • Reduces backlog of unlinking work

How:

  • Link during diagram creation
  • AI generation links automatically
  • Review and adjust immediately

Best Practice: Link from both requirements and architecture

Why:

  • Some users navigate from requirements
  • Others navigate from architecture
  • Bidirectional links ensure discoverability
  • Traceability matrix requires both directions

How:

  • Pidima automatically maintains bidirectional links
  • Link from either side updates both
  • No manual work needed for reverse links

Best Practice: Periodically review traceability links

Questions to ask:

  • Are all requirements represented in architecture?
  • Are all diagrams linked to requirements?
  • Are links still accurate after changes?
  • Are there irrelevant links to remove?

Schedule:

  • After major requirement changes
  • Before compliance audits
  • During architecture reviews
  • Quarterly reviews for active projects

Use Traceability Reports​

Best Practice: Generate reports to identify gaps

Reports to run:

  1. Requirements without architecture — Find gaps
  2. Architecture without requirements — Find orphans
  3. Coverage by level — Ensure each level complete
  4. Coverage by type — Check functional vs. non-functional

Action on results:

  • Create missing diagrams
  • Link orphaned diagrams
  • Remove obsolete diagrams

Best Practice: Add comments explaining why items are linked

Example assumptions on diagram:

Links:
- REQ-001: Defines user authentication requirement
- REQ-002: Specifies session management behavior
- REQ-015: Security constraints for authentication

Why:

  • Future maintainers understand relationships
  • Auditors see justification
  • Prevents accidental unlinking

Traceability in Practice​

Use Case: Medical Device Software​

Regulatory Requirement: IEC 62304 requires traceability from requirements through architecture to tests.

Pidima Implementation:

  1. System Requirements (Level 1) → High-level component diagrams
  2. Software Requirements (Level 2) → Detailed sequence diagrams
  3. Detailed Design (Level 3) → Class diagrams and state machines

Traceability Chain:

System Req → Software Req → Architecture → Test Case
   REQ-SYS-001 → REQ-SW-015 → ComponentDiagram-003 → TC-045

Audit Process:

  1. Auditor selects requirement
  2. Views linked architecture diagrams
  3. Verifies diagrams show implementation
  4. Follows links to test cases
  5. Confirms tests verify the architecture

Result: ✅ Complete traceability demonstrated

Use Case: Automotive Software (ISO 26262)​

Regulatory Requirement: ISO 26262 requires architecture traceability for safety-critical systems.

Pidima Implementation:

  1. Safety Goals → Architectural safety mechanisms shown in diagrams
  2. Safety Requirements → Component diagrams showing fault handling
  3. Technical Requirements → Sequence diagrams showing safety protocols

Traceability Chain:

Safety Goal → Safety Req → Architecture → Test Case
   SG-001 → FSR-042 → SafetyArchitecture-007 → TC-SafetyTest-102

Safety Analysis:

  • Identify all safety requirements
  • View architecture diagrams showing safety mechanisms
  • Verify test coverage of safety architecture
  • Demonstrate ASIL compliance

Result: ✅ Safety traceability maintained

Use Case: Aerospace Software (DO-178C)​

Regulatory Requirement: DO-178C requires bidirectional traceability.

Pidima Implementation:

  1. High-Level Requirements → System architecture diagrams
  2. Low-Level Requirements → Detailed design diagrams
  3. Architecture → Source code (external) → Tests

Traceability Chain:

HLR → LLR → Architecture → Code → Test
  HLR-025 → LLR-163 → ArchDiagram-042 → [Code] → TC-089

Certification Process:

  1. DER reviews requirement
  2. Follows link to architecture diagram
  3. Verifies architectural representation
  4. Follows to test cases
  5. Confirms coverage objectives met

Result: ✅ DO-178C traceability satisfied

Traceability Reports and Exports​

Coverage Report​

Shows:

  • Total requirements vs. requirements with architecture
  • Coverage percentage by level
  • List of requirements without architecture
  • List of orphaned architecture diagrams

Use for:

  • Identifying documentation gaps
  • Planning architecture work
  • Compliance readiness checks

Access:

  1. Navigate to Reports page
  2. Select Architecture Coverage
  3. Choose project and level
  4. Generate report

Traceability Matrix Export​

Exports:

  • Excel spreadsheet with requirements vs. architecture
  • Requirement details
  • Architecture diagram details
  • Link status

Use for:

  • External reviews
  • Compliance audits
  • Offline analysis
  • Stakeholder reports

Access:

  1. Navigate to Traceability page
  2. Select Architecture tab
  3. Apply desired filters
  4. Click Export to Excel

Shows:

  • When links were created
  • Who created links
  • When links were removed
  • Changes to linked items

Use for:

  • Audit trail
  • Understanding traceability evolution
  • Identifying when gaps were introduced

Access:

  1. Open architecture diagram or requirement
  2. View History or Audit Log section
  3. Filter for link-related events

Managing Traceability at Scale​

For Large Projects (1000+ Requirements)​

Solutions:

  1. Use AI generation — Automatically links on generation
  2. Bulk import with mapping — Import diagrams pre-linked
  3. API-based linking — Script large-scale linking operations
  4. Hierarchical approach — Link at appropriate levels only

Solutions:

  1. Version control — Track changes to requirements and architecture
  2. Change notifications — Alert when linked items change
  3. Periodic reviews — Schedule quarterly link validation
  4. Automated reports — Weekly coverage reports

Solutions:

  1. Search and filter — Use filters to narrow scope
  2. Smart suggestions — Pidima suggests relevant items
  3. Batch linking — Link multiple items at once
  4. Templates — Reuse linking patterns

For Distributed Teams​

Challenge: Coordination across teams​

Solutions:

  1. Role-based access — Architects manage architecture, link to requirements
  2. Notifications — Team notified when links added/removed
  3. Comments — Explain link rationale for team
  4. Regular sync — Weekly traceability reviews

Challenge: Consistency across teams​

Solutions:

  1. Linking guidelines — Establish team standards
  2. Review process — Peer review of links
  3. Training — Onboard new team members on traceability
  4. Quality metrics — Track coverage per team/module

Troubleshooting​

Problem: Architecture diagram doesn't appear in link dialog

Possible causes:

  • Diagram in different level (filter adjusted)
  • Diagram in different project
  • Insufficient permissions
  • Diagram recently created (refresh needed)

Solutions:

  • Clear filters in link dialog
  • Verify project and level selection
  • Check user permissions
  • Refresh page

Problem: Linked item shows as unavailable

Possible causes:

  • Item deleted
  • Permissions changed
  • Item moved to different level
  • Database sync issue

Solutions:

  • Verify item still exists
  • Check permissions for linked item
  • Re-link if item was moved
  • Contact support if persistent

Problem: Diagram has dozens of linked requirements

Issue: Over-linking reduces traceability value

Solutions:

  • Review links for relevance
  • Remove tangentially related requirements
  • Split diagram into focused sub-diagrams
  • Link only directly described requirements

Problem: Compliance audit identifies traceability gaps

Solutions:

  1. Run coverage report — Identify all gaps
  2. Prioritize — Focus on high-priority requirements
  3. Batch linking — Link systematically by level
  4. Verify — Run report again to confirm closure

Next Steps​