---
name: SRS+Architecture Rollout
overview: Define a prioritized set of fixes and produce an ISO/IEC/IEEE 29148-style Software Requirements Specification for the full Sensor Hub scope, then derive static architecture views and component-level specifications with traceability back to features and system requirements.
todos:
  - id: fsm-normative
    content: "Define full FSM: states, transitions, guards, actions; add per-state feature permissions"
    status: pending
  - id: fault-model
    content: Define fault taxonomy + escalation/recovery rules; map DIAG severity to state transitions
    status: pending
    dependencies:
      - fsm-normative
  - id: srs-setup
    content: Create ISO/IEC/IEEE 29148 SRS structure and SWR ID scheme; decide where SWR traceability lives (CSV vs MD annex)
    status: pending
    dependencies:
      - fsm-normative
  - id: derive-swr
    content: Derive SWR-* from SR-* and features; ensure testability, state preconditions, and trace links
    status: pending
    dependencies:
      - srs-setup
      - fault-model
  - id: static-architecture
    content: Write static architecture views (context/component/data/concurrency) aligned to repo structure and constraints
    status: pending
    dependencies:
      - derive-swr
  - id: component-specs
    content: Write component specs/APIs per major component; include threading model, ownership, errors, state behavior
    status: pending
    dependencies:
      - static-architecture
  - id: vv-matrix
    content: Create verification matrix mapping SWR-* to unit/integration/HIL tests with acceptance criteria
    status: pending
    dependencies:
      - component-specs
---

# SRS + Static Architecture + Component Design Plan (Sensor Hub)

## Context and constraints

- **Scope**: Sensor Hub (Sub-Hub) only; Main Hub/Cloud out of scope except interfaces.
- **Source of truth**: Features in `[System Design/Features/](System Design/Features/)`, system requirements in `[System Design/system_requirementsand_and_traceability.csv](System Design/system_requirementsand_and_traceability.csv)`, review gate in `[System Design/System Review Checklist.md](System Design/System Review Checklist.md)`.
- **Standard**: **ISO/IEC/IEEE 29148-style SRS** (per your selection).
- **Non-negotiables**: reliability > convenience, security mandatory, OTA fail-safe, power loss expected, SD failure assumed.

## Phase 0 — Close the definition gaps (before writing SW requirements)

These are blockers because SW requirements must be testable and state-scoped.

- **Define the full system FSM (normative)**
  - Produce a complete state set (including missing ones like `BootFailure`, `SdDegraded`, `Service`, etc.) and a **transition table** with guards, actions, and allowed callers.
  - Tie back to `SR-SYS-001..006` in the CSV.
- **Define cross-feature execution rules per state (normative)**
  - For each feature group (DAQ/DQC/COM/DIAG/DATA/OTA/SEC/SYS), specify **allowed/forbidden actions per state**.
  - Must satisfy `[System Design/Features/Cross-Feature Constraints.md](System Design/Features/Cross-Feature Constraints.md) `(notably `CFC-ARCH-02`, `CFC-DATA-02`, `CFC-SEC-01/02`, `CFC-DBG-01`).
- **Define failure handling model (normative)**
  - Fault taxonomy (info/warn/error/fatal), escalation rules, latching rules, recovery behaviors.
  - Link to DIAG requirements `SR-DIAG-*` and SYS state transitions.

## Phase 1 — Create the SRS (ISO/IEC/IEEE 29148) for full Sensor Hub

Deliver a dedicated SRS document set that derives **software requirements** from the system requirements CSV.

- **Create SRS structure** (new docs under `System Design/SRS/`)
  - `SRS.md` (main), plus annexes for traceability, interfaces, and timing/resource budgets.
- **Derive Software Requirements (SWRS) from System Requirements (SR-*)**
  - For each `SR-*` (CSV), create one or more `SWR-*` that is:
    - atomic and testable
    - state-scoped (explicit state preconditions)
    - implementation-neutral (no “use mutex”, no “use FreeRTOS queue”)
  - Maintain **bidirectional traceability**: `Feature -> SR -> SWR -> Component -> Test`.
- **Mandatory SRS sections (tailored for embedded)**
  - **Operational states and modes** (normative)
  - **External interfaces** (Main Hub link, peer link, debug port) (normative)
  - **Data model** (sensor record, diagnostics record, MC dataset, persistence records) (normative)
  - **Quality requirements**: timing determinism, memory constraints, storage wear, power-loss behavior, security posture (normative)

## Phase 2 — Static architecture (architecture views + constraints)

This converts SRS into implementable structure while enforcing separation of concerns.

- **Create architecture views** in `[software design/components/ARCHITECTURE.md](software design/components/ARCHITECTURE.md) `(or extend existing `arch.md` but remove non-audited claims):
  - **Context view**: Sensor Hub and external actors (Main Hub, SD, sensors)
  - **Container/component view**: align to repo structure under `[software design/components/](software design/components/)`
  - **Data flow view**: sensor data path, diagnostic path, OTA path
  - **Concurrency view**: tasks, priorities, ownership of blocking I/O
- **Turn constraints into enforceable rules**
  - Explicitly map each cross-feature constraint to architecture mechanisms (e.g., “DP is sole persistence interface”).

## Phase 3 — Component specifications (design inputs, not code)

Produce component-level specs that implement SWRs without ambiguity.

- **For each major component** (`STM`, `event_system`, `persistence`, `diag_task`, `error_handler`, `sensor_manager`, `machine_constant_manager`, `fw_upgrader`, `main_hub_apis`, `network_stack`, `diag_protocol_stack`):
  - responsibilities and non-responsibilities
  - public APIs (C/C++ headers), threading model, owned resources
  - error model and diagnostics emitted
  - state dependencies (what each component does per FSM state)
  - acceptance tests per SWR

## Phase 4 — Verification planning (definition-level)

- Create a **V&V matrix** mapping `SWR-*` to:
  - unit tests, integration tests, HIL/system tests
  - measurable acceptance criteria (timing, memory, recovery)

## Initial ordering (what to do first)

1. FSM + transition table + per-state feature permissions (SYS backbone)
2. DP/persistence contract (data integrity backbone)
3. Diagnostics + error taxonomy + escalation rules
4. COM/OTA/SEC contracts (secure channels, OTA safety)
5. DAQ/DQC flow + timing budgets + data model
6. HMI/debug session restrictions and isolation

## Mermaid artifacts to include in the docs

```mermaid
stateDiagram-v2
    [*] --> Init
    Init --> Running: initOk
    Init --> BootFailure: secureBootFail
    Running --> Warning: nonFatalFault
    Warning --> Running: faultCleared
    Running --> OtaPrep: otaRequestAccepted
    OtaPrep --> Teardown: beginTeardown
    Teardown --> OtaUpdate: teardownComplete
    OtaUpdate --> Running: otaSuccess
    OtaUpdate --> Fault: otaFail
    Running --> Fault: fatalFault
    Fault --> Teardown: controlledRecovery
    Teardown --> Init: reboot
```
```mermaid
flowchart TD
    Sensors-->DriversSensors
    DriversSensors-->SensorManager
    SensorManager-->EventSystem
    EventSystem-->DataPool
    DataPool-->Persistence
    DataPool-->MainHubApis
    EventSystem-->DiagTask
    DiagTask-->ErrorHandler
    ErrorHandler-->StateManager
```

## Files that will be created/updated

- **Create**: `System Design/SRS/SRS.md` (+ annexes) and `System Design/SRS/Traceability_SWRS.csv`
- **Update/extend**: `[System Design/system_requirementsand_and_traceability.csv](System Design/system_requirementsand_and_traceability.csv)` to include SWR rows and links (or keep SWR in a dedicated CSV and link by IDs)
- **Update/extend**: `[software design/components/ARCHITECTURE.md](software design/components/ARCHITECTURE.md) `/ `arch.md` to reflect audited, testable architecture views
- **Create**: per-component specs under `software design/components/*/ARCHITECTURE.md` (or `SPEC.md`) for each major component

## Deliverables checklist

- ISO/IEC/IEEE 29148-style **SRS** with `SWR-*` requirements
- FSM + transition table + per-state execution rules
- Static architecture views (context/component/data/concurrency)
- Component specifications + API sketches (headers only, no implementation)
- Traceability matrix and initial V&V mapping