Docs/mg advisor feedback

docs/Design/SoftArchitecture/MG.tex

@@ -9,6 +9,7 @@
 \usepackage{float}
 \usepackage{hyperref}
 \usepackage{array}
+\usepackage{xr}
 
 \hypersetup{
     colorlinks,
@@ -21,6 +22,8 @@
 \input{../../Comments}
 \input{../../Common}
 
+\externaldocument{../../SRS-Volere/SRS}
+
 \newcounter{acnum}
 \newcommand{\actheacnum}{AC\theacnum}
 \newcommand{\acref}[1]{AC\ref{#1}}
@@ -33,6 +36,19 @@
 \newcommand{\mthemnum}{M\themnum}
 \newcommand{\mref}[1]{M\ref{#1}}
 
+% Functional Requirement counter and macro
+\newcounter{frnum}
+\newcommand{\frthefrnum}{FR\thefrnum}
+\newcommand{\frref}[1]{FR\ref{#1}}
+\newcommand{\lfref}[1]{LF\ref{#1}}
+\newcommand{\uhref}[1]{UH\ref{#1}}
+\newcommand{\pfref}[1]{PF\ref{#1}}
+\newcommand{\oerref}[1]{OER\ref{#1}}
+\newcommand{\msref}[1]{MS\ref{#1}}
+\newcommand{\secref}[1]{SEC\ref{#1}}
+\newcommand{\culref}[1]{CUL\ref{#1}}
+\newcommand{\cplref}[1]{CPL\ref{#1}}
+
 \begin{document}
 
 \title{
@@ -61,6 +77,7 @@ \section{Revision History}
 Jan 21, 2026 & 2.1 & Added communication protocol details\\
 Feb 10, 2026 & 2.2 & Implemented advisor feedback on structure, clarity and terminology \\
 Feb 16, 2026 & 2.3 & Updated module descriptions to resemble rev0 architecture \\
+Feb 23, 2026 & 2.4 & Implemented advisor feedback on module classification and command refinement \\
 \bottomrule
 \end{tabularx}
 
@@ -266,6 +283,11 @@ \subsection{Architectural Terminology}
 
 \textbf{Orchestrator:} An orchestrator is a specialized type of module whose primary responsibility is coordinating the interactions between other modules to accomplish complex workflows. Unlike standard modules that focus on a single domain-specific task, orchestrators manage sequencing, decision-making, and data flow across module boundaries. In this system, M5 (Command Orchestrator) exemplifies this pattern by synthesizing speech transcripts into browser commands through coordination with M4, M17 (Prompting Module), M7 (Browser Orchestrator), and M8 (Session Manager). Orchestrators represent when modules interact and why certain sequences occur.
 
+\subsubsection*{Module Classification}
+
+Modules are classified as either user-facing or internal,based on their role in the system. User-facing modules (M1: User Interface, M2: Accessibility Layer, M3: Feedback Display) directly interact with the user and must meet accessibility and availability requirements. All other modules are internal; their focus is on correctness, maintainability, and security.
+
+
 
 \subsection{Design Rationale}
 
@@ -301,7 +323,7 @@ \subsection{Module Listing}
   \item \textbf{Prompting Module} - Generates contextual, accessible, and confidence-based prompts for user clarification
   \item \textbf{Model Tuner} - Adapts speech and intent models to individual user patterns through personalized embeddings
 \end{itemize}
-\section{Connection Between Requirements and Design} \label{SecConnection} \label{SecConnection}
+\section{Connection Between Requirements and Design} \label{SecConnection}
 
 The design of the system is intended to satisfy the requirements developed in the 
 (\href{https://github.com/speech-buddies/VoiceBridge/blob/main/docs/SRS-Volere/SRS.pdf}{SRS}).
@@ -378,7 +400,7 @@ \section{Connection Between Requirements and Design} \label{SecConnection} \labe
 % =========================
 % Module Decomposition
 % =========================
-\section{Module Decomposition} \label{SecMD}  \label{SecMD}
+\section{Module Decomposition} \label{SecMD}
 % ---------- Presentation Layer ----------
 \subsection*{Presentation Layer Modules}
 
@@ -465,6 +487,7 @@ \subsubsection*{M5: Command Orchestrator} \refstepcounter{mnum}\mthemnum\label{m
   \item Process user input to determine if intent is clear or needs clarification, returning either a clarified browser command or a clarification question.
   \item Apply safety guardrails to prevent execution of harmful or ambiguous commands.
   \item Reset session context and clear conversation history.
+  \item Accept supplemental user input when the recognized intent is incomplete, process it with the original transcript and session context, and generate an updated command.
 \end{itemize}
 \textbf{Implemented By:} CommandOrchestrator module using an external LLM API, dynamic context injection, and a JSON schema validation layer.
 
@@ -696,11 +719,11 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-FR-1 10.1 & \mref{m15}, \mref{m16}, \mref{m4}, \mref{m8}\\
-FR-2 10.2& \mref{m4}, \mref{m16}, \mref{m18}, \mref{m9}\\
-FR-3 10.3& \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
-FR-4 10.4& \mref{m5}, \mref{m6}\\
-FR-5 10.5& \mref{m7}, \mref{m7}, \mref{m11}, \mref{m6}\\
+\hyperref[fr:FR1]{FR1} & \mref{m15}, \mref{m4}, \mref{m8}\\
+\hyperref[fr:FR2]{FR2} & \mref{m4}, \mref{m18}, \mref{m9}\\
+\hyperref[fr:FR3]{FR3} & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
+\hyperref[fr:FR4]{FR4} & \mref{m5}, \mref{m6}\\
+\hyperref[fr:FR5]{FR5} & \mref{m7}, \mref{m7}, \mref{m11}, \mref{m6}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Functional Requirements and Modules}
@@ -713,8 +736,8 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-LF-1 11.1& \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
-LF-2 11.2& \mref{m1}, \mref{m2}, \mref{m17}, \mref{m3}\\
+\hyperref[req:AR1]{LF1} & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
+\hyperref[req:SR1]{LF2} & \mref{m1}, \mref{m2}, \mref{m17}, \mref{m3}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Look \& Feel Requirements and Modules}
@@ -727,11 +750,11 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-UH-1 12.1 & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
-UH-2 12.2 & \mref{m10}, \mref{m9}, \mref{m5}, \mref{m6}\\
-UH-3 12.3& \mref{m1}, \mref{m2}, \mref{m17}, \mref{m8}\\
-UH-4 12.4& \mref{m6}, \mref{m3}, \mref{m2}, \mref{m17}\\
-UH-5 12.5& \mref{m2}, \mref{m1}, \mref{m3}, \mref{m6}\\
+\hyperref[req:EU1]{UH1} & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
+\hyperref[req:PI1]{UH2} & \mref{m10}, \mref{m9}, \mref{m5}, \mref{m6}\\
+\hyperref[req:LR1]{UH3} & \mref{m1}, \mref{m2}, \mref{m17}, \mref{m8}\\
+\hyperref[req:UP1]{UH4} & \mref{m6}, \mref{m3}, \mref{m2}, \mref{m17}\\
+\hyperref[req:AC1]{UH5} & \mref{m2}, \mref{m1}, \mref{m3}, \mref{m6}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Usability \& Humanity Requirements and Modules}
@@ -744,13 +767,13 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-PF-1 13.1 & \mref{m4}, \mref{m5}, \mref{m6}, \mref{m7}, \mref{m7}\\
-PF-2 13.2& \mref{m5}, \mref{m6}, \mref{m7}, \mref{m6}, \mref{m11}\\
-PF-3 13.3& \mref{m4}, \mref{m16}, \mref{m18}, \mref{m5}\\
-PF-4 13.4& \mref{m11}, \mref{m8}, \mref{m6}, \mref{m7}\\
-PF-5 13.5 & \mref{m8}, \mref{m9}, \mref{m10}\\
-PF-6 13.6& \mref{m8}, \mref{m9}, \mref{m7}\\
-PF-7 13.7& \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}\\
+\hyperref[req:PR1]{PF1} & \mref{m4}, \mref{m5}, \mref{m6}, \mref{m7}, \mref{m7}\\
+\hyperref[req:PR2]{PF2} & \mref{m5}, \mref{m6}, \mref{m7}, \mref{m6}, \mref{m11}\\
+\hyperref[req:PR3]{PF3} & \mref{m4}, \mref{m18}, \mref{m5}\\
+\hyperref[req:PR4]{PF4} & \mref{m11}, \mref{m8}, \mref{m6}, \mref{m7}\\
+\hyperref[req:PR5]{PF5} & \mref{m8}, \mref{m9}, \mref{m10}\\
+\hyperref[req:PR6]{PF6} & \mref{m8}, \mref{m9}, \mref{m7}\\
+\hyperref[req:PR7]{PF7} & \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Performance Requirements and Modules}
@@ -763,11 +786,11 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-OER-1 14.1& \mref{m15}, \mref{m16}, \mref{m4}, \mref{m11}\\
-OER-2 14.2& \mref{m1}, \mref{m2}, \mref{m7}, \mref{m8}\\
-OER-3 14.3& \mref{m5}, \mref{m6}, \mref{m7}\\
-OER-4 14.4& \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m8}\\
-OER-5 14.5& \mref{m8}, \mref{m9}, \mref{m11}, \mref{m12}\\
+\hyperref[req:OE1]{OER1} & \mref{m15}, \mref{m4}, \mref{m11}\\
+\hyperref[req:OE2]{OER2} & \mref{m1}, \mref{m2}, \mref{m7}, \mref{m8}\\
+\hyperref[req:OE3]{OER3} & \mref{m5}, \mref{m6}, \mref{m7}\\
+\hyperref[req:OE4]{OER4} & \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m8}\\
+\hyperref[req:OE5]{OER5} & \mref{m8}, \mref{m9}, \mref{m11}, \mref{m12}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Operational \& Environmental Requirements and Modules}
@@ -780,9 +803,9 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-MS-1 15.1& \mref{m8}, \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}\\
-MS-2 15.2& \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}, \mref{m17}\\
-MS-3 15.3& \mref{m1}, \mref{m2}, \mref{m7}, \mref{m8}, \mref{m11}\\
+\hyperref[req:MS1]{MS1} & \mref{m8}, \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}\\
+\hyperref[req:MS2]{MS2} & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}, \mref{m17}\\
+\hyperref[req:MS3]{MS3} & \mref{m1}, \mref{m2}, \mref{m7}, \mref{m8}, \mref{m11}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Maintainability \& Support Requirements and Modules}
@@ -795,11 +818,11 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-SEC-1 16.1 & \mref{m12}, \mref{m13}, \mref{m10}, \mref{m9}, \mref{m8}\\
-SEC-2 16.2& \mref{m5}, \mref{m6}, \mref{m7}, \mref{m6}, \mref{m11}\\
-SEC-3 16.3& \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m13}\\
-SEC-4 16.4& \mref{m11}, \mref{m9}, \mref{m8}, \mref{m12}\\
-SEC-5 16.5& \mref{m11}, \mref{m6}, \mref{m16}, \mref{m7}, \mref{m7}\\
+\hyperref[req:SEC1]{SEC1} & \mref{m12}, \mref{m13}, \mref{m10}, \mref{m9}, \mref{m8}\\
+\hyperref[req:SEC2]{SEC2} & \mref{m5}, \mref{m6}, \mref{m7}, \mref{m6}, \mref{m11}\\
+\hyperref[req:SEC3]{SEC3} & \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m13}\\
+\hyperref[req:SEC4]{SEC4} & \mref{m11}, \mref{m9}, \mref{m8}, \mref{m12}\\
+\hyperref[req:SEC5]{SEC5} & \mref{m11}, \mref{m6}, \mref{m7}, \mref{m7}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Security Requirements and Modules}
@@ -812,7 +835,7 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-CUL-1 17.1& \mref{m2}, \mref{m3}, \mref{m6}, \mref{m17}, \mref{m5}\\
+\hyperref[req:CR1]{CUL1} & \mref{m2}, \mref{m3}, \mref{m6}, \mref{m17}, \mref{m5}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Cultural Requirements and Modules}
@@ -825,8 +848,8 @@ \section{Traceability Matrix} \label{SecTM}
 \toprule
 \textbf{Req.} & \textbf{Modules}\\
 \midrule
-CPL-1 18.1& \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m13}\\
-CPL-2 18.2& \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
+\hyperref[req:CO1]{CPL1} & \mref{m9}, \mref{m10}, \mref{m11}, \mref{m12}, \mref{m13}\\
+\hyperref[req:CO2]{CPL2} & \mref{m1}, \mref{m2}, \mref{m3}, \mref{m6}\\
 \bottomrule
 \end{tabular}
 \caption{Trace Between Compliance Requirements and Modules}
@@ -927,6 +950,16 @@ \section{User Interfaces}
 Figure 7 shows the command detection interface that appears after a voice command has been successfully recognized. The detected intent (e.g., opening a new browser tab) is displayed, along with the interpreted spoken phrase. 
 
 
+\begin{figure}[H]
+  \centering
+  \includegraphics[width=0.85\textwidth]{../../imgs/mg-ui-command-verification.png} 
+  \caption{Confirmation screen with command refinement input}
+  \label{fig:command-verification}
+\end{figure}
+
+Figure 8 shows the confirmation screen that verifies recognized commands by recording the user’s spoken response or allowing them to click Confirm or Cancel buttons, enabling refinement of incomplete intents like “search for an iPhone on Google” before execution.
+
+
 
 \section{Design of Communication Protocols}
 

docs/SRS-Volere/SRS.tex

@@ -757,7 +757,7 @@ \section{Undesired Event Handling}
 \section{Functional Requirements}
 \subsection{Functional Requirements}
 
-\subsection{FR1: Accept Speech Audio via Microphone}
+\subsection{FR1: Accept Speech Audio via Microphone}\label{fr:FR1}
 \textbf{Description:} The system must capture live speech input from the user through a standard built-in or external microphone.\\
 \textbf{Rationale:} Speech audio contains frequency components up to approximately 8 kHz. To capture this audio accurately without distortion, the sampling rate must be at least 2× the maximum frequency, resulting in a minimum required rate of 16 kHz. This ensures reliable speech transcription and is supported by standard built-in and external microphone hardware.\\
 \textbf{Fit Criterion:} The system reliably detects and records audio from default OS microphone devices across Windows, macOS, iOS, and Android, with a minimum 16 kHz sampling rate.
@@ -929,15 +929,15 @@ \section{Security Requirements}
 The following security/safety requirements are derived from the project Hazard Analysis (see \href{https://github.com/speech-buddies/VoiceBridge/blob/main/docs/HazardAnalysis/HazardAnalysis.pdf}{Hazard Analysis Section 6}.) Each item is traceable to hazards in the FMEA table and is included here to ensure consistency.
 We group VoiceBridge’s security requirements into five categories—\textbf{Access (ACR)}, \textbf{Integrity (IR)}, \textbf{Privacy (PRR)}, \textbf{Audit (ADR)}, and \textbf{Immunity (IMR)}.
 
-\subsection{Access Requirements}
+\subsection{Access Requirements}\label{req:SEC1}
 
 \begin{description}
   \item[ACR1:] Important actions (like sending data or external messages) must use a clear, two-step confirmation to prevent mistakes. \emph{(links to IR5/IMR7 — unclear confirmation)}
   \item[ACR2:] Access to stored audio or transcripts is restricted by role-based permissions so only authorized users can view or edit sensitive data. \emph{(links to Storage — Private data leaked)}
   \item[ACR3:] Multi-factor authentication (MFA) is required for all administrator or privileged logins to prevent unauthorized entry. \emph{(links to Auth/Access — Unauthorized entry)}
 \end{description}
 
-\subsection{Integrity Requirements}
+\subsection{Integrity Requirements}\label{req:SEC2}
 
 \begin{description}
   \item[IR1:] VoiceBridge auto-detects microphone devices and alerts users if permissions are missing, offering a quick way to select a new device. \emph{(links to Input Devices — Wrong mic chosen)}
@@ -947,7 +947,7 @@ \subsection{Integrity Requirements}
   \item[IR5:] Confirmation screens and the overall user interface must be clear, accessible, and perceivable by text, audio, and assistive tools. \emph{(links to Front-end Interface — Confirmation not clear)}
 \end{description}
 
-\subsection{Privacy Requirements}
+\subsection{Privacy Requirements}\label{req:SEC3}
 
 \begin{description}
   \item[PRR1:] All stored data is encrypted with restricted access to protect privacy. \emph{(links to Storage — Private data leaked)}
@@ -956,7 +956,7 @@ \subsection{Privacy Requirements}
   \item[PRR4:] Users can request deletion of stored data; the system removes it after a defined time. \emph{(future privacy maintenance)}
 \end{description}
 
-\subsection{Audit Requirements}
+\subsection{Audit Requirements}\label{req:SEC4}
 
 \begin{description}
   \item[ADR1:] The system records recognition accuracy over time and flags when results decline. \emph{(links to ML Model — Accuracy drops)}
@@ -965,7 +965,7 @@ \subsection{Audit Requirements}
   \item[ADR4:] Provide regular privacy reports showing data deletion and retention. \emph{(future extension)}
 \end{description}
 
-\subsection{Immunity Requirements}
+\subsection{Immunity Requirements}\label{req:SEC5}
 
 \begin{description}
   \item[IMR1:] The app recovers smoothly from device or permission changes without restarting. \emph{(links to Input Devices — Wrong mic chosen)}