BioFlow Requirements
Software Requirements Specification

Software Requirements Specification

UID: DOC-SRS
Type LevelMIDUIDREFS Title Statement Rationale CommentTYPERISK_CONTROL_REFHARM_IF_ABSENTSTANDARD_REFTHREAT_REFSTATUSREVIEWED_HASHREVIEWED_BYQMS_REVIEW_DATENOTES
REQUIREMENT 1 SRS-001 Parents: Children:
SRS-001
change in progress
First-launch database initialisation

On first launch, when no database file exists at the configured application data path, the software shall create the local database, apply the current schema version, and create a default local clinic record that serves as the container for locally-created patient records.

Refines SYS-001: the software-level mechanism that realises the device's first-launch readiness commitment. Establishes the minimum persistent state required for any subsequent clinical operation — without it, patient records cannot be stored and recording sessions cannot be attached to a patient.

 functional Approved 98b05f66e64fdd504ec9ab458d051d1bf7ac6ef1cc6703c83eec0bbfcfa52d83 @DougYoungberg coverage-plan: ST-001 on clean install — fresh workstation, first launch, verify the local clinic is visible in the Patients menu.
REQUIREMENT 2 SRS-002 Parents: Children:
SRS-002
change in progress
Local database confidentiality at rest

The software shall keep the local database file unreadable to any process that opens it without supplying the database credential, and shall reject database read and write operations when the credential is missing or incorrect.

Refines SYS-002. A workstation that is lost, stolen, imaged, or backed up off-site shall not yield PHI from the local database file alone. Tying readability to a credential held outside the database file ensures offline copies of the file cannot be opened independently of the BioFlow application's credential pathway.

 security NIST SP 800-111; IEC 81001-5-1 §5.5 PHI exfiltration from a lost, stolen, or imaged Windows host Approved bbce0aa8a344b16781b9aa4fd86855e614b296b31d614039b4a2221e7e5bda23 @DougYoungberg coverage-plan: IT-002 attempts to read the on-disk file without a credential and confirms the read does not yield plaintext records, then opens it through the application's pathway and confirms the records are readable.
REQUIREMENT 3 SRS-003 Parents: Children:
SRS-003
change in progress
Local database integrity enforcement

The software shall enforce referential integrity between clinic, patient, and recording records through database foreign-key constraints; shall wrap any multi-row or cross-table mutation in a single transaction such that a crash or process termination during the mutation leaves the database in either the pre-mutation state or the post-mutation state and never a partial state; and shall reject — rather than silently truncate or drop — any write that would violate a NOT NULL, FOREIGN KEY, or CHECK constraint declared in the schema.

Refines SYS-003. Three independent failure modes can corrupt the local store: (1) concurrent or crashing writes that complete only part of a multi-row update; (2) referential drift where a child row outlives its parent or never had one; (3) constraint-violating inserts that older code paths or migrations may attempt. Each is addressed by a specific software mechanism — schema-declared constraints applied by the persistence layer, transactional wrappers around use-case writes, and the underlying database engine's constraint enforcement — and each is observable through a failed write or a post-condition query. The requirement names the three mechanisms together so that removing any one of them (for example, disabling foreign-key enforcement for a performance change) is a visible regression against SRS-003 rather than a silent loosening of guarantees relied on by the rest of the application.

 data 45 CFR §164.312(c)(1); GDPR Art. 5(1)(f) Approved 0de558744d983b3d37d5f67856e20552eba80bae3e3f3fb4a235b12bbb886ee3 @DougYoungberg coverage-plan: IT-003 exercises each rejection category named in this requirement against the production encrypted-connection pathway: (a) FK violation — attempt to insert a patient with a non-existent clinic_id; (b) transactional atomicity — perform two writes inside a transaction, throw, and assert no partial state remains visible on re-open; (c) CHECK violation — attempt to insert a clinics row with an out-of-set origin value; (d) NOT NULL violation — issue a raw SQL INSERT (bypassing the typed API which guards NOT NULL at compile time) that supplies NULL for a non-nullable column. Test file location: test/integration/database_integrity_integration_test.dart.
REQUIREMENT 4 SRS-004 Parents: Children:
SRS-004
change in progress
Audit logging of clinical record operations

The software shall write one audit-log entry for each of the following operations on local clinical records: creation, modification, and deletion of a patient; start, stop, and deletion of a recording; and successful upload of a recording to the cloud. Each entry shall carry the action, the identifier of the affected record, and a system-generated UTC timestamp. After an entry is written, the software shall not modify it in a way that obscures previously recorded information, and shall not delete audit entries.

Refines SYS-004. The list of audited operations corresponds to the operator-initiated mutations and exports of patient or recording data that the application currently exposes. Clinic and clinical-user mutations are not in scope because the application does not permit those operations on the local workstation — clinics are read-only mirrors of an external cloud directory the device is configured to sync with; clinical users are authenticated rather than created in-app. The required content per entry (action, target, time) is the minimum that lets an audit reviewer reconstruct what happened: which clinical record was affected, what action was performed, and when. The immutability clause expresses the underlying invariant that an audit entry must remain a faithful record of the operation it describes; an application-layer path that overwrites the details of a prior entry would functionally be a record change that obscures original information, and is therefore prohibited.

 functional Approved 8670efd17561286bd5396fe9d81ff480539400a00719b06c3f4619af3242feb4 @DougYoungberg coverage-plan: IT-004 exercises the audit chain end-to-end by invoking each of the audited operations through the application's use-case pathway (or the corresponding production caller when no use case exists) and asserting that the audit-log entry is written with the correct action, target identifier, and system-generated timestamp. IT-005 verifies the data-shape and immutability commitments — entries have the required fields and an existing entry's content cannot be changed after write.
REQUIREMENT 5 SRS-005 Parents: Children:
SRS-005
change in progress
Audit-trail review and export

The software shall present the local audit trail to an authorised operator in a form that lists each entry's action, affected record, and system timestamp, ordered by time. The software shall additionally provide a means to export the current audit trail to a file in a portable, human-readable format that preserves the same fields as the on-screen presentation, so that the exported file can be examined off the device by an auditor or by the clinical organisation's own information-security review.

Refines SYS-004. Capturing audit entries in the local database is necessary but not sufficient: the entries live inside the encrypted application database, which an internal reviewer or external auditor is not expected to access directly. The device therefore surfaces the trail to an authorised operator inside the application and provides an exportable copy that can be examined off the device. Without a viewer-and-export surface, the audit trail is opaque to the clinical organisation's own review duties — the entries exist but cannot be examined without direct access to the encrypted database file. The "human-readable" wording is deliberate: a binary or schema-coupled export defeats the off-device review use case, which is conducted by people reading entries on a workstation other than the device. The "ordered by time" presentation rule keeps the on-screen view faithful to the chronology of operations; the export preserves the same fields so that the exported copy is a copy of the on-screen trail rather than a transformation of it.

 functional Approved 3da5c78892fc7f563c2fd96cb6b7e93ad305672d437b12b2a59dd039044ad207 @DougYoungberg coverage-plan: IT-006 verifies the export round-trip — written audit entries appear in the exported file with the same fields and content. ST-002 (planned, to be authored once the viewer surface ships) verifies an operator can locate the audit trail in the application, see the expected entries, and invoke the export from the workstation.
REQUIREMENT 6 SRS-006 Parents: Children:
SRS-006
reviewed
Maximized main window on launch

On application launch, the software shall display the main application window in a maximized state.

Refines SYS-005. Maximising the main window on launch gives the EEG signal display the full available screen area from the start of a session, so the operator can monitor the live signal without first resizing the window manually.

 ui Approved dc7ca8a24c6e21afa7a978cbb02263cfeab63085a843e6e7432c25b610be934a @DougYoungberg coverage-plan: ST item (planned) — verify the main application window is maximized immediately after launch.
REQUIREMENT 7 SRS-007 Parents: Children:
SRS-007
reviewed
Always-visible recording control widget

The software shall display a recording control widget anchored to the top of the main window, and shall keep that widget visible in all interaction states, including signal-control mode, menu mode, and while any overlay is open.

Refines SYS-005. The recording controls govern the active session — its start, its stop, and its running status. Keeping the widget visible in every interaction state ensures the operator can always see and reach the recording controls without first dismissing a menu or overlay.

 ui Approved bccb9886c2528cb600bccee06daef365798ce97ad2887816160909f6270bd10f @DougYoungberg coverage-plan: ST item (planned) — verify the recording control widget remains visible in signal-control mode, menu mode, and while an overlay is open.
REQUIREMENT 8 SRS-008 Parents: Children:
SRS-008
reviewed
Bottom-bar signal and menu mode toggle

The software shall provide a bottom bar that switches between a signal-control mode and a menu mode when the operator activates the bottom-bar mode toggle.

Refines SYS-005. A single bottom bar that switches between signal-control functions and menu functions keeps both sets of controls reachable from one fixed location, without permanently consuming screen area that would otherwise reduce the live signal display.

 ui Approved a2bd1b9f841162a89db68d43b7a5e544d65872f6e094573158396d0f6e6f4943 @DougYoungberg coverage-plan: ST item (planned) — verify activating the bottom-bar toggle switches the bar between signal-control mode and menu mode.
REQUIREMENT 9 SRS-009 Parents: Children:
SRS-009
reviewed
Dismiss overlay on ESC or click-outside

The software shall dismiss the active navigation overlay when the operator either presses the ESC key or clicks outside the overlay's content area.

Refines SYS-005. Navigation overlays float above the live EEG signal; providing the conventional dismissal gestures — ESC and click-away — lets the operator return to the unobstructed signal view quickly. An overlay with in-progress edits is guarded against accidental dismissal (see ARCH-010), so the dismissal applies to overlays that permit it.

 ui Approved b262c063b65c057df8f8d5f2d6aaaa0541cee3f7eb9887b695ffdbca7577e649 @DougYoungberg coverage-plan: ST-007 opens a navigation overlay and verifies it is dismissed both by pressing ESC and by clicking outside the overlay content.
REQUIREMENT 10 SRS-010 Parents: Children:
SRS-010
reviewed
At most one overlay open at a time

The software shall display at most one navigation overlay at a time; opening an overlay shall replace any overlay that is currently open.

Refines SYS-005. Limiting the interface to a single open overlay keeps the operator's focus clear and preserves the maximum visible area of the underlying signal display. The constraint is realised structurally by a single selected-overlay index rather than a navigation stack (see ARCH-010), so a second overlay cannot be layered over the first.

 functional Approved 8b339f513a68052b72a0dab34f0ebc46b778848c38b8552a70abe5c96c660985 @DougYoungberg coverage-plan: ST-008 opens one overlay, then opens a second, and verifies only the second is shown.
REQUIREMENT 11 SRS-011 Parents: Children:
SRS-011
reviewed
Signal-mode bottom-bar controls

In signal mode, the bottom bar shall present the signal-parameter controls: a high-pass filter, a low-pass filter, a notch filter, a sensitivity control, a timebase control, and a montage selector.

Refines SYS-005. These are the per-recording signal adjustments the operator reaches without leaving the signal view; presenting them on the bottom bar in signal mode keeps them one interaction away while the live signal remains visible.

 ui Approved 87a993af0ca2801932f9df334a3860d5e9de62d699450987430e7dd994b65a07 @DougYoungberg coverage-plan: IT-011 asserts the six controls render in signal mode; ST-006 confirms the signal-parameter controls are shown at the operator-facing tier.
REQUIREMENT 12 SRS-012 Parents: Children:
SRS-012
reviewed
Menu-mode bottom-bar navigation buttons

In menu mode, the bottom bar shall present the navigation buttons: Patients, Montages, Settings, and Activities.

Refines SYS-005. Menu mode replaces the signal-parameter controls with the four primary navigation destinations, each of which opens its overlay, so the operator reaches patients, montages, settings, and activities from the same fixed bar.

 ui Approved 68a5f126aba7210ab6bfdf3c3998fa61d7efa723f3b4cd42215e59a1f7fd2099 @DougYoungberg coverage-plan: IT-011 asserts the four navigation buttons render in menu mode; ST-006 confirms the four items are shown at the operator-facing tier.
REQUIREMENT 13 SRS-013 Parents: Children:
SRS-013
reviewed
Recorded-duration readout format

While a recording session is active, the software shall display the recorded duration in HH:MM:SS format.

Refines SYS-005. A recorded-duration readout in a fixed HH:MM:SS format lets the operator see how much signal has been captured so far while keeping the live signal in view.

 ui Approved 44a71204c417957885ee30f52c99c5b19e8e51c0e3da1d1cda7243ae850f84c6 @DougYoungberg coverage-plan: UT-001 verifies the duration-to-HH:MM:SS formatting at the unit tier; ST-009 observes the readout shown in HH:MM:SS format in the running application during an active recording.
REQUIREMENT 14 SRS-014 Parents: Children:
SRS-014
reviewed
Patient name in recording widget

While a patient is selected, the software shall display the selected patient's name in the recording control widget.

Refines SYS-005. Showing the selected patient's name in the always-visible recording widget lets the operator confirm at a glance which patient the session is being recorded for while keeping the live signal in view.

 ui Approved 3e52266db5d5faf9cfd839c7b4b8808bea0f43f535ef0af241b4cb0e72ffe88f @DougYoungberg coverage-plan: ST-010 observes the selected patient's name shown in the recording widget in the running application; IT-008 confirms the widget renders the patient name from seeded state.
REQUIREMENT 15 SRS-015 Parents: Children:
SRS-015
reviewed
Bottom bar default and resting mode

The bottom bar shall be in signal mode when the application launches, and shall return to signal mode whenever the open navigation overlay is dismissed.

Refines SYS-005. Signal mode is the operator's working view, so the bottom bar opens there and falls back to it once a navigation overlay is closed, keeping the signal-parameter controls available by default.

 ui Approved 9c6b9513d6834a87fc4441c8cea891e78a3add74b32609de21884fb0a816ea9e @DougYoungberg coverage-plan: IT-009 asserts signal mode at launch and IT-010 asserts the return to signal mode after the overlay is dismissed; ST-011 observes the launch-to-menu-to-signal cycle at the operator-facing tier.
REQUIREMENT 16 SRS-016 Parents: Children:
SRS-016
reviewed
Minimum main window size

The software shall prevent the main application window from being resized smaller than 1024 by 768 pixels.

Refines SYS-005. 1024 by 768 is the minimum size at which the operator workstation remains usable; preventing the window from shrinking below it keeps the live signal display and recording controls legible on lower-resolution laptops.

 ui Approved 4200fb2d0be3aee20b1455b9e0faba8eab18e82f2097544c2a0921230dd51767 @DougYoungberg coverage-plan: ST-012 (planned) resizes the window below the minimum and asserts the reported window bounds are clamped to at least 1024 by 768 at the operator-facing tier. No flutter_test integration test is feasible — the minimum is enforced natively by the window_manager package, not in a widget tree.
REQUIREMENT 17 SRS-017 Parents: Children:
SRS-017
reviewed
Selectable application themes

The software shall provide three selectable visual themes — Light, Dark, and Dark Glass — and shall apply the operator's selected theme across the application.

Refines SYS-005. Offering Light, Dark, and Dark Glass themes lets the operator pick the appearance that suits the room's lighting and their preference, while the selection applies consistently across the workstation.

 ui Approved 5e1badbc2e307e77ef9e1d06d69e677c0706f21a32b6a1d144b64768213b4160 @DougYoungberg coverage-plan: ST-013 observes the three themes offered and a theme change taking effect in the running application; IT-012 verifies that each theme type drives its application theme at the integration tier.
REQUIREMENT 18 SRS-018 Parents:
SRS-018
inactive
Live signal display frame rate

The software shall render the live EEG signal display at a sustained rate of at least 60 frames per second.

Refines SYS-005. A high, steady frame rate keeps the live signal readable without perceptible stutter during a recording session.

 performance Draft d6a0927e9b4a133f3ce35546a3661e34bc5f317ae66ba6df63ec5749b1393146 @DougYoungberg Pending: deferred per product decision (not required for now). Activating it needs a frame-timing measurement harness to verify the on-screen refresh rate, which does not yet exist. Revisit when that tooling is available.
REQUIREMENT 19 SRS-019 Parents:
SRS-019
inactive
Multi-monitor window position restore

The software shall remember the main window's position and restore it on the next launch, including when the window was placed on a secondary monitor.

Refines SYS-005. Restoring the window where the operator last placed it, across a multi-monitor workstation, avoids re-positioning the interface at the start of every session.

 ui Draft 3cabfa2067b9f2552e762aa3cde45becd92844962e52f522e0c302304e7a402b @DougYoungberg Pending: deferred per product decision (not required for now). Verification needs a multi-monitor test environment; the current CI/VisionTrace rig has a single virtual display. Revisit when that environment is available.
REQUIREMENT 20 SRS-020 Parents:
SRS-020
inactive
Display-scaling layout integrity

The software shall present the main interface without clipped or overlapping controls under Windows display-scaling settings of 100%, 125%, 150%, and 200%.

Refines SYS-005. Clinicians run BioFlow on laptops set to various display scales; the interface shall stay legible and fully laid out at each.

 ui Draft 64012965b01b94657d7d12839d019de4def916e9e0282d8e6ac706380021a6bd @DougYoungberg Pending: deferred per product decision (not required for now). End-to-end verification needs the ability to launch the app under different OS display- scaling levels, which is not set up. Revisit when that environment is available.