Architecture Overview

The Traceability Report Framework separates evidence creation, packaging, validation, and consumption. This page explains how the pieces fit together.

High-level pipeline

Source tools  -->  Extractors  -->  Artifact store  -->  TWPack builder  -->  Validators / Viewers
              (requirements,       (JSONL + metadata)    (CLI, CI jobs)      (CLI, validator, viewer)
               tests, design)

1. Source tools – Requirements management, test management, CI systems, experiment trackers, suppliers.
2. Extractors – Scripts or connectors convert tool data into TRF artifact/link JSONL.
3. Artifact store – Git repository or evidence directory containing JSONL, attachments, and configuration.
4. TWPack builder – CLI assembles deterministic packages, applies profiles, signs archives.
5. Validators / viewers – Ensure package integrity and provide human-readable dashboards.

Components

• Profiles and extensions – Define available artifact kinds, validation rules, coverage expectations.
• Configuration (trf.yaml) – Maps repository directories to artifact kinds, declares link inference strategies, selects profiles.
• TWPack archive – Contains manifest, artifacts, links, signatures, attachments.
• Signer/validator – Applies cryptographic signatures, runs schema/hashing/timestamp checks.
• Viewer – Desktop app for interactive exploration.

Package lifecycle

Stage	What happens	Typical tooling
Collect data	Export from DOORS, Jira, Git, CI, ML platforms	Custom scripts, adapters
Normalize artifacts	Convert to JSONL, apply naming conventions	CLI helpers, ETL jobs
Link generation	Infer or import relationships	CLI inference, CSV imports, custom scripts
Build	Run tw build, attach files	CLI, CI pipeline
Sign & validate	tw sign, tw validate, trf-validator	PKI infrastructure, validator
Distribute	Share via git, artifact storage, regulator portals	Git LFS, S3, artifact registries
Monitor & update	Watch for source changes, rebuild as needed	tw build --watch, scheduled jobs

Environment patterns

Scenario	Characteristics	Recommended setup
Team workstations	Developers generate ad hoc packs while coding	CLI, viewer, local trf.yaml
CI pipelines	Automated builds per commit	CLI in container, validator, artifacts uploaded
Supplier integration	Multiple TWPack inputs merged	Signing keys per supplier, tw merge, validation gateways
Audit/assessment	Long-term storage and review	Signed TWPack, exported reports, viewer snapshots

Data stores

• Git – Version control for artifact JSONL, configuration, schemas.
• Object storage – Retain large attachments and archived TWPack releases.
• Secrets manager/HSM – Protect signing keys and certificates.
• Dashboards – Optional BI tools ingest exported CSV/JSON for leadership metrics.

Integration approach

1. Identify authoritative systems for each evidence type.
2. Build idempotent extractors that run during CI or nightly jobs.
3. Normalize data into artifacts/ and links/ directories.
4. Validate continuously; fail builds on schema or coverage regressions.
5. Deliver signed TWPack archives plus targeted reports to stakeholders.

Dive into data specifics in Data Model and version-management practices in Framework Versioning.