Taktflow OpenSOVD — Engineering Specification

1. Executive Summary

Taktflow OpenSOVD is a general-purpose SOVD diagnostic stack for multi-ECU zonal architectures. It implements the ASAM SOVD v1.1 OpenAPI (ISO 17978-3) wire contract so that every ECU — virtual or physical, regardless of role or zone — becomes addressable via standard HTTP tooling instead of proprietary diagnostic hardware and binary protocols.

The HIL test bench is a minimal 3-ECU setup (CVC central + SC safety + BCM virtual body, per ADR-0023) that covers every architectural code path in the stack. The stack itself is architecture-agnostic within automotive diagnostics and scales to arbitrary ECU counts without code change.

Current status (2026-04-23): Phase 5 live-hardware work advancing. Software path green end-to-end in Docker SIL; observer dashboard serving live /sovd/v1/components, /faults, /operations, /data, /health, /session, /audit, /gateway/backends plus ws-bridge relay on the bench LAN. STM32G474 CVC firmware flashed and smoke-proven on metal (commit bb5708e). TMS570LC4357 UDS ECU live on bench CAN, and as of 2026-04-23 the TMS570 OTA bulk-data path is HIL-proven end-to-end: session 0x10 02, manifest v1 write (0xF1A0), 0x34/0x36/0x37 download of a 256 B image, on-MCU SHA-256 verify, status transition to COMMITTED, monotonic witness-counter increment, and witness-id read-back all confirmed. CVC OTA feature documentation shipped at docs/firmware/cvc-ota/. Remaining: TMS570 F021 Flash API wiring so the staged image actually reaches flash; CMS / X.509 signature validation (scaffold shipped, chain validator not implemented). See MASTER-PLAN.md for hardening gates.

1.1 Progress Snapshot (2026-04-23)

1.2 Repository structure — internal monorepo (as of 2026-04-20)

opensovd-core/ is Taktflow-owned — a normal monorepo subdirectory under taktflow-opensovd, no nested .git/. The DFM, Gateway, Server, fault-sink, ws-bridge, observer API, and dashboard here are all originals. classic-diagnostic-adapter/ stays vendored verbatim from Eclipse classic-diagnostic-adapter as a read-only SOVD→UDS/DoIP bridge for legacy ECUs and is never edited inline. Any CDA fixes required for Taktflow behaviour land in separate crates or external patches, keeping CDA's byte-for-byte pins intact for reproducibility. Upstream contribution to Eclipse OpenSOVD was dropped from project scope on 2026-04-20 (decision D-01 of the v3.0 master plan); the tree stays internal.

1.3 Conformance scope

• What we verify: the ASAM SOVD v1.1 OpenAPI wire contract published for ISO 17978-3, locked by sovd-interfaces schema snapshots and cargo xtask openapi-dump --check.
• What we align with: public scope statements for ISO 17978 Parts 1 and 2 from ASAM/ISO public pages, AUTOSAR EXP_SOVD, the Eclipse OpenSOVD design.md and mvp.md, the public Eclipse OpenSOVD CDA code when behavior is ambiguous, and the local research notes under external/asam-public/iso-17978-research/.
• What we do not claim: full normative conformance to ISO 17978 Parts 1 and 2, or paywalled Part 3 prose that has not been acquired yet.

2. System Architecture

2.1 System context

graph TB
    T["<b>Off-board SOVD Tester</b><br/>(laptop / Postman / curl)"]
    F["<b>Fleet / Cloud Operator</b><br/>(future)"]

    T -->|"HTTPS (ASAM v1.1 / ISO 17978-3)"| Stack
    F -->|"HTTPS (future)"| Stack

    subgraph Stack ["Taktflow SOVD Stack -- Pi Gateway Host"]
        GW["sovd-gateway"]
        SRV["sovd-server"]
        DFM["sovd-dfm"]
        CDA["Classic Diagnostic<br/>Adapter (CDA)"]
        PROXY["CAN-to-DoIP<br/>Proxy"]
    end

    Stack -->|"DoIP / TCP"| VE
    Stack -->|"CAN / ISO-TP<br/>(via proxy)"| PE

    VE["<b>Virtual ECU</b><br/>BCM<br/>(POSIX + DoIP)"]
    PE["<b>Physical ECUs</b><br/>CVC + SC<br/>(STM32G4 + TMS570)"]

    style Stack fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px
    style T fill:#fff3e0,stroke:#e65100
    style F fill:#fff3e0,stroke:#e65100
    style VE fill:#e8f5e9,stroke:#2e7d32
    style PE fill:#fce4ec,stroke:#c62828

2.2 Component topology

graph TB
    TESTER["<b>Off-board SOVD Tester</b>"]
    TESTER -->|"HTTPS"| GW

    subgraph PI ["Raspberry Pi Gateway Host (Linux aarch64)"]
        GW["<b>sovd-gateway</b><br/>routing, fan-out,<br/>backend registry"]
        SRV["<b>sovd-server</b><br/>one per ECU view"]
        DFM["<b>sovd-dfm</b><br/>central fault mgr"]
        DB["<b>sovd-db</b><br/>SQLite + WAL"]
        CDA["<b>CDA</b><br/>(upstream)"]
        PROXY["<b>CAN-to-DoIP</b><br/>proxy (Rust)"]

        GW <-->|"in-process"| SRV
        GW -->|"SovdBackend"| DFM
        GW -->|"HTTP"| CDA
        DFM --> DB
        SRV --> DFM
        CDA -->|"UDS / DoIP"| PROXY
    end

    PROXY -->|"SocketCAN<br/>(can0 / vcan0)"| PE
    CDA -->|"DoIP TCP"| VE

    VE["<b>Virtual POSIX ECU</b><br/>BCM"]
    PE["<b>Physical ECUs</b><br/>CVC + SC"]

    style PI fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px
    style TESTER fill:#fff3e0,stroke:#e65100
    style VE fill:#e8f5e9,stroke:#2e7d32
    style PE fill:#fce4ec,stroke:#c62828
    style GW fill:#bbdefb,stroke:#1565c0
    style DFM fill:#bbdefb,stroke:#1565c0
    style DB fill:#c8e6c9,stroke:#2e7d32
    style CDA fill:#ffe0b2,stroke:#e65100

2.3 Crate dependency graph

graph BT
    IF["<b>sovd-interfaces</b><br/>types, traits, errors<br/><i>(leaf -- zero I/O)</i>"]

    DB["sovd-db (SQLite)"] --> IF
    DFM["sovd-dfm"] --> IF
    SRV["sovd-server (Axum)"] --> IF
    CLI["sovd-client"] --> IF
    GW["sovd-gateway"] --> IF
    TR["sovd-tracing"] --> IF

    DFM --> DB

    MAIN["<b>sovd-main</b><br/>binary assembly"] --> SRV
    MAIN --> CLI
    MAIN --> GW
    MAIN --> TR
    MAIN --> DFM

    style IF fill:#fff9c4,stroke:#f9a825,stroke-width:2px
    style MAIN fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px
    style DB fill:#c8e6c9,stroke:#2e7d32

2.4 Protocol hops

2.5 Two request paths — native-SOVD vs CDA-backed

The SOVD server surface supports two request paths side by side. The native-SOVD path speaks JSON/REST end-to-end — no ODX, no UDS, no DoIP — and is the first-class citizen of the stack. The CDA-backed path bridges the same SOVD surface to legacy UDS/DoIP ECUs through an ODX-compiled MDD database. Both paths exit through the same sovd-gateway REST endpoint; the tester cannot tell the difference at the wire level.

graph LR
    TESTER["<b>Tester</b><br/>(HTTP/JSON)"]
    GW["<b>sovd-gateway</b>"]
    SRV["<b>sovd-server</b>"]

    TESTER -->|"HTTPS SOVD"| GW
    GW --> SRV

    subgraph NATIVE ["Native-SOVD path (JSON-only, no ODX)"]
        DFM["sovd-dfm"]
        FL["fault-lib (apps)"]
        COVESA["sovd-covesa (VSS)"]
        XV["sovd-extended-vehicle"]
        ML["sovd-ml"]
        FL -->|IPC| DFM
        SRV --> DFM
        SRV --> COVESA
        SRV --> XV
        SRV --> ML
    end

    subgraph LEGACY ["CDA-backed path (UDS/DoIP via ODX/MDD)"]
        CDA["Classic Diagnostic Adapter"]
        MDD["MDD database<br/>(compiled from ODX)"]
        UDSECU["Legacy UDS ECU"]
        SRV -->|"HTTP"| CDA
        CDA --> MDD
        CDA -->|"UDS / DoIP"| UDSECU
    end

    style NATIVE fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style LEGACY fill:#ffe0b2,stroke:#e65100,stroke-width:2px
    style TESTER fill:#fff3e0,stroke:#e65100
    style GW fill:#bbdefb,stroke:#1565c0
    style SRV fill:#bbdefb,stroke:#1565c0

2.5.1 Comparison

2.5.2 When the JSON-only path is the answer

Stakeholders asking for a pure JSON / REST diagnostic surface — no ODX files, no offline authoring step, no UDS translation — are describing the native-SOVD path. It is already the architecture's first-class citizen: every sovd-server instance can serve the SOVD REST surface without a CDA or MDD in the picture, and the bench-fault-injection plane committed in d42cb2f exercises exactly that path end-to-end.

Two capabilities still have to ship before the "no more ODX" story is fully deliverable to a third-party tester:

• PROD-12 online capability description — every SOVD resource must self-describe its schema variant-exactly at runtime, so a tester can drive the server using only the schema endpoint. See MASTER-PLAN-PART-2-PRODUCTION-GRADE.md §II.6.12; benchmark: ACTIA IME ships this today.
• SEM-1 / SEM-2 semantic schema enforcement — every response envelope validates against a machine-readable semantic schema, and the schemas themselves are discoverable. See MASTER-PLAN §5.5; P7-SEM-03 / P7-SEM-04 in progress.

CDA is not the JSON-native story — it is the transitional bridge that keeps legacy UDS ECUs reachable while zonal architectures migrate to native SOVD. For an OEM fleet fully on a post-ODX HPC, CDA can be disabled at config time and every request goes through the native path.

3. Feature Matrix

3.1 Capability overview

graph LR
    subgraph FAULTS ["Fault Management"]
        F1["List DTCs<br/>(per-component + all)"]
        F2["DTC detail + status"]
        F3["Clear DTCs<br/>(all or by group)"]
        F4["Pagination"]
    end

    subgraph ROUTINES ["Diagnostic Routines"]
        R1["Start routine"]
        R2["Stop routine"]
        R3["Poll status"]
        R4["Routine registry"]
    end

    subgraph COMPONENTS ["Component Management"]
        C1["List components"]
        C2["HW/SW version"]
        C3["DID catalogue"]
        C4["Capability discovery"]
    end

    subgraph FAULT_PIPE ["Fault Pipeline"]
        P1["Fault API<br/>(C shim + Rust)"]
        P2["DFM ingest"]
        P3["Debounce +<br/>op-cycle gating"]
        P4["SQLite persistence"]
    end

    subgraph SECURITY ["Security"]
        S1["mTLS + HTTPS"]
        S2["OAuth2 / OIDC tokens"]
        S3["Audit log"]
        S4["Rate limiting"]
    end

    style FAULTS fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px
    style ROUTINES fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style COMPONENTS fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style FAULT_PIPE fill:#fff9c4,stroke:#f9a825,stroke-width:2px
    style SECURITY fill:#fce4ec,stroke:#c62828,stroke-width:2px

3.2 Feature status matrix

4. Requirements Summary

4.1 Requirement traceability map

graph LR
    subgraph SOURCES ["Standards + Upstream"]
        ISO17["ISO 17978<br/>(SOVD)"]
        ISO14["ISO 14229<br/>(UDS)"]
        ISO26["ISO 26262<br/>(Safety)"]
        UD["upstream<br/>design.md"]
        MVP["upstream<br/>mvp.md"]
        MP["MASTER-PLAN"]
    end

    subgraph REQS ["Requirements (this project)"]
        FR["FR-1..7<br/>Functional"]
        NFR["NFR-1..6<br/>Non-functional"]
        SR["SR-1..5<br/>Safety"]
        SEC["SEC-1..5<br/>Security"]
        COMP["COMP-1..5<br/>Compliance"]
    end

    subgraph IMPL ["Implementation"]
        CODE["opensovd-core<br/>(16 crates)"]
        CDA_I["CDA<br/>(14 crates)"]
        FL["fault-lib"]
    end

    subgraph VERIFY ["Verification"]
        UT["5,680 unit tests"]
        SNAP["36 snapshots"]
        INT["25 integration<br/>test files"]
        HIL["8 HIL scenarios"]
    end

    ISO17 --> FR
    ISO14 --> FR
    ISO26 --> SR
    UD --> FR
    MVP --> FR
    MP --> NFR

    FR --> CODE
    NFR --> CODE
    SR --> FL
    SEC --> CODE
    COMP --> CODE

    CODE --> UT
    CODE --> SNAP
    CODE --> INT
    CODE --> HIL

    style SOURCES fill:#f5f5f5,stroke:#616161
    style REQS fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px
    style IMPL fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style VERIFY fill:#fff9c4,stroke:#f9a825,stroke-width:2px

4.2 Non-functional requirements

4.3 Safety requirements

4.4 Security requirements

5. Safety Boundary

graph TB
    subgraph QM ["QM Domain (no ASIL allocation)"]
        direction TB
        GW["SOVD Gateway"]
        SRV["SOVD Server"]
        DFM["DFM"]
        DB[("Diagnostic DB")]
        FS["FaultSink (IPC)"]

        GW --> SRV --> DFM --> DB
        DFM --> FS
    end

    BOUNDARY["---- Safety Boundary ----<br/><i>Fault Library API is the ONLY crossing point.<br/>Data flows one direction: firmware -> SOVD. Never SOVD -> firmware.</i>"]

    subgraph SAFETY ["Safety-Critical Domain (ASIL-D)"]
        direction TB
        CDA_S["CDA (UDS/DoIP)"]
        FL["Fault Library API<br/>(FaultShim_Report)"]
        ECU_S["Physical ECU"]
        FW["Firmware (ASIL-D)"]

        CDA_S --> ECU_S
        FW --> FL
    end

    FS -->|"fault data<br/>(one-way)"| FL
    GW -->|"diagnostic request"| CDA_S

    style QM fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style SAFETY fill:#fce4ec,stroke:#c62828,stroke-width:2px
    style BOUNDARY fill:#fff9c4,stroke:#f9a825,stroke-width:3px,stroke-dasharray: 5 5
    style FL fill:#ffcdd2,stroke:#c62828,stroke-width:2px

Boundary rules:

1. No SOVD path modifies ASIL-D firmware without HARA delta (SR-1.1)
2. opensovd-core links against zero ASIL-rated libraries (SR-1.2)
3. Fault Library API is the single crossing point
4. Fault data flows one direction: firmware → SOVD, never reverse
5. Routine interlocks enforced in firmware, not SOVD (SR-3.x)

6. State Machines

6.1 DTC lifecycle

stateDiagram-v2
    [*] --> Pending : FaultShim_Report received

    Pending --> Confirmed : debounce threshold met
    Pending --> Suppressed : operation cycle excludes fault
    Pending --> [*] : aging timeout

    Confirmed --> Cleared : POST .../faults/clear or UDS 0x14
    Confirmed --> Confirmed : additional occurrence (count++)

    Suppressed --> Pending : operation cycle ends

    Cleared --> Pending : same fault re-reported
    Cleared --> [*] : no recurrence

    note right of Confirmed
        Visible to SOVD GET.
        Persisted in SQLite.
    end note

6.2 Operation cycle

stateDiagram-v2
    [*] --> Idle : system boot

    Idle --> Running : start_cycle (REST or IPC)
    Running --> Evaluating : stop_cycle
    Running --> Running : faults ingested

    Evaluating --> Idle : evaluation complete

7. Use Case Catalog (UC1–UC20)

This section mirrors the canonical catalog at docs/USE-CASES.md. The five MVP flows (UC1–UC5) have full sequence diagrams below; the extended capability-showcase set (UC6–UC20) is summarized in the traceability table in §7.5. Every UC ID is stable and referenced from requirements, tests, ADR-0024 dashboard widgets, and HIL scenarios.

7.1 UC1 — Read DTCs (FR-1.1, FR-1.5)

sequenceDiagram
    participant T as Tester
    participant GW as sovd-gateway
    participant CDA as CDA
    participant PX as Proxy
    participant ECU as CVC (STM32)

    T->>+GW: GET /sovd/v1/components/cvc/faults
    GW->>+CDA: route("cvc") -> CdaBackend
    CDA->>+PX: DoIP -> UDS 0x19
    PX->>+ECU: CAN ISO-TP
    ECU-->>-PX: UDS response 0x59
    PX-->>-CDA: DoIP response
    CDA-->>-GW: JSON DTC list
    GW-->>-T: 200 OK

7.2 UC2 — Report fault via Fault API (FR-4.1)

sequenceDiagram
    participant SWC as Firmware (ASIL-B)
    participant SHIM as FaultShim
    participant DFM as DFM Pipeline
    participant DB as SQLite

    SWC->>SHIM: FaultShim_Report(fid, severity, meta)
    Note over SWC,SHIM: Non-blocking, returns immediately
    SHIM->>DFM: Unix socket / NvM buffer
    DFM->>DFM: Debounce -> OpCycle -> DtcLifecycle
    DFM->>DB: persist DTC
    Note over DB: Visible via GET within 100 ms

7.3 UC3 — Clear DTCs (FR-1.3)

sequenceDiagram
    participant T as Tester
    participant AUTH as Auth + Audit
    participant GW as Gateway
    participant CDA as CDA
    participant ECU as ECU

    T->>+AUTH: POST .../faults/clear
    AUTH->>AUTH: mTLS + token + audit log
    AUTH->>+GW: authorized
    GW->>+CDA: CdaBackend
    CDA->>+ECU: UDS 0x14 (ClearDTC)
    ECU-->>-CDA: 0x54 (success)
    CDA-->>-GW: OK
    GW-->>-AUTH: OK
    AUTH-->>-T: 204 No Content

7.4 UC5 — Trigger routine with safety interlock (FR-2.1, SR-3.1)

sequenceDiagram
    participant T as Tester
    participant GW as Gateway
    participant CDA as CDA
    participant ECU as ECU

    T->>+GW: POST .../operations/motor_self_test/start
    GW->>+CDA: CdaBackend
    CDA->>+ECU: UDS 0x31 01 (RoutineControl)

    alt vehicle not stationary
        ECU-->>CDA: NRC 0x22 ConditionsNotCorrect
        CDA-->>GW: error
        GW-->>T: 409 Conflict (safety interlock)
    else preconditions met
        ECU-->>-CDA: 0x71 01 (accepted)
        CDA-->>-GW: accepted
        GW-->>-T: 202 Accepted
    end

7.5 Full traceability matrix (UC × REQ × Test × Dashboard)

One row per use case. UC1–UC5 are the MVP set diagrammed above; UC6–UC20 are the extended capability-showcase set exposed by the Phase 5 observer dashboard per ADR-0024. Complete traceability (UC × REQ × Test × Source × Widget) lives in tools/traceability/ per COMP-4.1; this table is a convenience index.

How to add a new use case: pick the next free UC ID (UC21+), write the entry in docs/USE-CASES.md, add the row here, and — if it's an MVP flow — add a sequence diagram to ARCHITECTURE.md §6 and mirror it above.

8. API Surface

8.1 REST endpoints (ASAM SOVD v1.1 OpenAPI / ISO 17978-3)

8.2 Middleware stack

flowchart TD
    REQ["Incoming HTTPS request"] --> M1
    M1["Tracing<br/><i>correlation id + OTLP span</i>"] --> M2
    M2["Authentication<br/><i>TLS cert + bearer token</i>"] --> M3
    M3["Rate limiting<br/><i>per-IP, 20 rps default</i>"] --> M4
    M4["Audit logging<br/><i>privileged ops only</i>"] --> M5
    M5["Body validation<br/><i>size + schema</i>"] --> HANDLER
    HANDLER["Route handler"] --> BACKEND["SovdBackend trait dispatch"]

    style REQ fill:#fff3e0,stroke:#e65100
    style HANDLER fill:#bbdefb,stroke:#1565c0
    style BACKEND fill:#bbdefb,stroke:#1565c0

8.3 OpenAPI contract

The API schema is snapshot-locked to ASAM SOVD v1.1 OpenAPI (ISO 17978-3). Any schema change is detected by cargo xtask openapi-dump --check and fails CI.

• 36 golden JSON snapshot files verify wire format stability
• Schema regeneration is a PR gate

9. Deployment Topologies

9.1 Topology comparison

9.2 HIL test bench

graph LR
    subgraph DEV ["Dev Host (Windows)"]
        STL["3x ST-LINK"]
        XDS["1x XDS110"]
        GS["GS_USB (CAN)"]
    end

    subgraph PI ["Raspberry Pi (gateway host)"]
        SM["sovd-main"]
        SIM["ecu-sim"]
        PX["can-to-doip proxy"]
    end

    subgraph HW ["Physical ECUs (2)"]
        CVC["CVC STM32G474RE
(central)"]
        SC["SC TMS570LC43x
(safety)"]
    end

    DEV -->|"SSH"| PI
    DEV -->|"ST-LINK / XDS110 (flash)"| HW
    PI -->|"can0 (500 kbps)"| HW

    style DEV fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style PI fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px
    style HW fill:#fce4ec,stroke:#c62828,stroke-width:2px

10. Test Strategy

10.1 Test pyramid

graph TB
    subgraph PYRAMID ["Test Pyramid"]
        direction TB
        HIL["<b>Level 5: HIL</b><br/>8 scenarios on physical bench"]
        INT["<b>Level 4: Integration</b><br/>25 test files, real backends"]
        OA["<b>Level 3: OpenAPI Contract</b><br/>schema locked to ASAM v1.1"]
        SNAP["<b>Level 2: Snapshot</b><br/>36 golden JSON files"]
        UNIT["<b>Level 1: Unit + Async</b><br/>5,680 tests"]
    end

    HIL ~~~ INT ~~~ OA ~~~ SNAP ~~~ UNIT

    style HIL fill:#fce4ec,stroke:#c62828,stroke-width:2px
    style INT fill:#fff3e0,stroke:#e65100
    style OA fill:#fff9c4,stroke:#f9a825
    style SNAP fill:#e8f5e9,stroke:#2e7d32
    style UNIT fill:#e8f4fd,stroke:#1a73e8,stroke-width:2px

10.2 HIL scenario matrix

10.3 CI pipeline

11. Component Catalogue

11.1 opensovd-core workspace (16 crates)

11.2 Supporting components

12. Design Principles

1. Rust-first. Async (Tokio), memory-safe, #![forbid(unsafe_code)] where possible. Clippy pedantic + deny enforced in CI.
2. Trait boundaries, not frameworks. sovd-interfaces defines all contracts with zero I/O. Implementations are swappable.
3. Spec-locked API surface. OpenAPI schema snapshot-tested against ASAM SOVD v1.1 OpenAPI (ISO 17978-3).
4. Internal engineering deliverable. Taktflow OpenSOVD is not contributed upstream; the tree is internal. Prior upstream-contribution plans archived under docs/contribution/archive/ per decision D-01 (2026-04-20). See ADR-0007 (archived) for historical context.
5. Owned core, vendored bridge. opensovd-core/ is Taktflow-owned; classic-diagnostic-adapter/ stays vendored verbatim from Eclipse and is never edited inline — CDA modifications land in separate Taktflow crates or external patches.
6. Isolation over integration on the safety axis. Fault Library is the ONLY boundary between QM and ASIL-D.

13. Standards Compliance

14. Professional Development Story

This section pulls the engineering narrative into the same browser document as the system specification so the product story, requirement flowdown, architecture, implementation seams, and verification model can be read end-to-end in one place.

14.1 Purpose and End-to-End Chain

This part explains the professional engineering story of the repo:

• why the use cases exist
• how use cases become formal requirements
• how the architecture realizes those requirements
• how ADRs constrain the design
• how code is split across crates and runtime components
• how tests and phase gates prove the system

It complements, but does not replace, the canonical source documents:

• USE-CASES.md for the capability catalog
• REQUIREMENTS.md for numbered contractual requirements
• ARCHITECTURE.md for arc42 design and runtime views
• DEVELOPMENT-STORY.md for the narrative bridge document
• MASTER-PLAN.md for delivery phases, gates, and risks

OpenSOVD is being built as a professional diagnostic product line, not just as a collection of services:

stakeholder need -> use case -> requirement -> architecture -> ADR -> implementation -> verification -> phase exit -> release evidence

14.2 Starting Point: Why the Product Exists

The project starts from a business and engineering problem:

• legacy diagnostics are expressed as UDS services over CAN, ISO-TP, and DoIP
• those flows are difficult to consume from modern tools, cloud workflows, and multi-ECU zonal platforms
• Taktflow wants the same underlying ECU diagnostics exposed through ASAM SOVD v1.1 OpenAPI / ISO 17978-3 without breaking the existing safety lifecycle

So the real problem is not "invent an API." The actual product obligation is to keep legacy UDS and existing firmware behavior intact, add a modern REST diagnostic surface, and preserve safety boundaries plus internal engineering discipline (ADR hygiene, ASPICE traceability, ISO 21434 cybersecurity case, conformance testing).

14.3 Development Flow

Implementation follows the architecture seams:

• sovd-interfaces owns pure contracts and shared types
• sovd-server owns the SOVD REST surface
• sovd-gateway owns routing and fan-out
• sovd-dfm owns fault ingest, debounce, operation-cycle gating, and DTC state
• sovd-db-sqlite owns persistence
• fault-sink-* owns transport from firmware-side fault reports into DFM
• CDA owns UDS and DoIP adaptation for legacy ECUs
• the Pi proxy owns CAN ISO-TP bridging for physical CAN-only ECUs

14.4 How Use Cases, Requirements, and Architecture Fit Together

The most useful professional reading path is to follow one use case through the full chain rather than reading each document in isolation.

14.4.1 UC1 -- Read DTCs via SOVD

14.4.2 UC2 -- Report Fault via Fault API

14.4.3 UC3 -- Clear DTCs

14.4.4 UC4 -- Reach a Legacy UDS ECU Through SOVD

14.4.5 UC5 -- Trigger a Diagnostic Routine

The professional mapping is consistent across all five MVP flows:

• the use case defines the externally meaningful story
• the requirement turns that story into a precise obligation
• the architecture assigns responsibility to the correct runtime elements
• the code follows those structural seams
• the test proves the story in the intended topology

14.5 The Phase Story: How the Product Is Built Professionally

14.6 Where Each Document Fits

14.7 How to Read One Feature End-to-End

1. Find the use case in USE-CASES.md.
2. Open the linked requirement IDs in REQUIREMENTS.md.
3. Open the linked runtime view in ARCHITECTURE.md.
4. Check the relevant ADRs that constrain the design.
5. Locate the implementation crate or service named in the architecture.
6. Open the referenced integration or HIL test that verifies the flow.
7. Check the phase and exit criteria in MASTER-PLAN.md.

14.8 What Makes This Story Professional

• it starts from stakeholder-visible use cases, not internal modules
• it expresses those use cases as numbered requirements
• it separates functional, non-functional, safety, security, and compliance demands
• it uses architecture as realization, not as marketing
• it records major decisions in ADRs before burying them in code
• it aligns implementation boundaries with architectural boundaries
• it verifies the system at unit, integration, SIL, and HIL levels
• it uses phase exits and milestones instead of declaring everything done at once
• it preserves the safety boundary instead of treating diagnostics as a free-for-all
• it keeps internal quality bars (ADR hygiene, ASPICE traceability, conformance suites) aligned with the same engineering-spec discipline an upstream contribution would have required

Bottom line: use cases define the meaningful stories, requirements turn them into obligations, architecture assigns those obligations to runtime elements, ADRs freeze the key choices, implementation follows those seams, verification proves the result, and phase gates make the maturity story explicit.

15. Related Documents

16. Revision History

17. Part II — Production Roadmap

Part I (sections 1–16 above, milestones M0–M10) covers the bench → conformance → docs-maturity path. Part II extends the plan to in-vehicle production release (M10 → M12) and lives in MASTER-PLAN-PART-2-PRODUCTION-GRADE.md (Draft 0.7 as of 2026-04-21). The summary below is a customer-facing index of that document — the plan file is authoritative.

17.1 Milestones

17.2 Production capabilities (PROD-1 … PROD-20)

17.3 Open questions pending OEM answers (Q-PROD-*)

17.4 Design-OSS posture (2026-04-21)

Per user direction 2026-04-21, all design artifacts (ADRs, trade studies, plan sections) are authored publish-safe from the first draft. Upstream code contribution to Eclipse OpenSOVD stays dropped (Decision D-01, retained from v3.0); the design itself is genuinely open. The sovd-client SDK (PROD-19) is the customer-facing Rust consumer API and is designed for external consumption from the start — the hyper+tower / entity-navigator / no-domain-trait shape matches what every mainstream production Rust SDK (AWS, Azure, GCP, Kubernetes, GitHub, sqlx) ships. Evidence and rationale: TS-19.

© 2026 The Contributors to Taktflow OpenSOVD (includes vendored Eclipse OpenSOVD CDA) — Apache-2.0