Software Requirements Specification
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.
98b05f66e64fdd504ec9ab458d051d1bf7ac6ef1cc6703c83eec0bbfcfa52d83
@DougYoungberg
coverage-plan: ST-001 on clean install — fresh workstation, first launch, verify the local clinic is visible in the Patients menu.
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.
NIST SP 800-111; IEC 81001-5-1 §5.5
PHI exfiltration from a lost, stolen, or imaged Windows host
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.
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.
45 CFR §164.312(c)(1); GDPR Art. 5(1)(f)
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.
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.
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.
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.
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.
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.
dc7ca8a24c6e21afa7a978cbb02263cfeab63085a843e6e7432c25b610be934a
@DougYoungberg
coverage-plan: ST item (planned) — verify the main application window is maximized immediately after launch.
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.
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.
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.
a2bd1b9f841162a89db68d43b7a5e544d65872f6e094573158396d0f6e6f4943
@DougYoungberg
coverage-plan: ST item (planned) — verify activating the bottom-bar toggle switches the bar between signal-control mode and menu mode.
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.
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.
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.
8b339f513a68052b72a0dab34f0ebc46b778848c38b8552a70abe5c96c660985
@DougYoungberg
coverage-plan: ST-008 opens one overlay, then opens a second, and verifies only the second is shown.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.