1447 lines
80 KiB
TeX
1447 lines
80 KiB
TeX
\documentclass[12pt,a4paper]{report}
|
|
|
|
% ─── Packages ───────────────────────────────────────────────────────────────
|
|
\usepackage[T1]{fontenc}
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage[a4paper, top=2.5cm, bottom=2.5cm, left=3cm, right=2.5cm]{geometry}
|
|
\usepackage{lmodern}
|
|
\usepackage{microtype}
|
|
\usepackage{setspace}
|
|
\usepackage{parskip}
|
|
\usepackage{titlesec}
|
|
\usepackage{titletoc}
|
|
\usepackage{fancyhdr}
|
|
\usepackage{graphicx}
|
|
\usepackage{float}
|
|
\usepackage{caption}
|
|
\usepackage{subcaption}
|
|
\usepackage{booktabs}
|
|
\usepackage{longtable}
|
|
\usepackage{array}
|
|
\usepackage{tabularx}
|
|
\usepackage{multirow}
|
|
\usepackage{xcolor}
|
|
\usepackage{listings}
|
|
\usepackage{mdframed}
|
|
\usepackage{enumitem}
|
|
\usepackage{amsmath}
|
|
\usepackage{amssymb}
|
|
\usepackage{hyperref}
|
|
\usepackage{tcolorbox}
|
|
\usepackage{pgfplots}
|
|
\usepackage{tikz}
|
|
\usepackage{pifont}
|
|
\usepackage{fontawesome5}
|
|
\usepackage{soul}
|
|
\pgfplotsset{compat=1.18}
|
|
\tcbuselibrary{skins, breakable}
|
|
\usetikzlibrary{shapes.geometric, arrows.meta, positioning, fit, backgrounds}
|
|
|
|
% ─── Colors ────────────────────────────────────────────────────────────────
|
|
\definecolor{primaryblue}{RGB}{25, 82, 148}
|
|
\definecolor{accentblue}{RGB}{41, 128, 185}
|
|
\definecolor{lightblue}{RGB}{214, 234, 248}
|
|
\definecolor{darkgray}{RGB}{44, 62, 80}
|
|
\definecolor{medgray}{RGB}{127, 140, 141}
|
|
\definecolor{lightgray}{RGB}{245, 246, 250}
|
|
\definecolor{successgreen}{RGB}{39, 174, 96}
|
|
\definecolor{warnyellow}{RGB}{230, 126, 34}
|
|
\definecolor{dangerred}{RGB}{192, 57, 43}
|
|
\definecolor{codebg}{RGB}{248, 249, 250}
|
|
\definecolor{codefg}{RGB}{36, 41, 47}
|
|
|
|
% ─── Hyperref ───────────────────────────────────────────────────────────────
|
|
\hypersetup{
|
|
colorlinks=true,
|
|
linkcolor=primaryblue,
|
|
urlcolor=accentblue,
|
|
citecolor=accentblue,
|
|
pdfauthor={Kelompok 08 -- Evan, Japson, Bambang},
|
|
pdftitle={WalkGuide -- Final Exam Report},
|
|
pdfsubject={Integrated Mobile Application Project},
|
|
bookmarksnumbered=true,
|
|
}
|
|
|
|
% ─── Typography ─────────────────────────────────────────────────────────────
|
|
\onehalfspacing
|
|
\setlength{\parindent}{0pt}
|
|
\setlength{\parskip}{6pt}
|
|
|
|
% ─── Section Formatting ─────────────────────────────────────────────────────
|
|
\titleformat{\chapter}[display]
|
|
{\normalfont\huge\bfseries\color{primaryblue}}
|
|
{\chaptertitlename\ \thechapter}{16pt}{\Huge}
|
|
\titlespacing*{\chapter}{0pt}{10pt}{20pt}
|
|
|
|
\titleformat{\section}
|
|
{\normalfont\Large\bfseries\color{primaryblue}}{\thesection}{1em}{}
|
|
\titleformat{\subsection}
|
|
{\normalfont\large\bfseries\color{accentblue}}{\thesubsection}{1em}{}
|
|
\titleformat{\subsubsection}
|
|
{\normalfont\normalsize\bfseries\color{darkgray}}{\thesubsubsection}{1em}{}
|
|
|
|
% ─── Header & Footer ────────────────────────────────────────────────────────
|
|
\pagestyle{fancy}
|
|
\fancyhf{}
|
|
\fancyhead[L]{\small\color{medgray}WalkGuide -- Final Exam Report}
|
|
\fancyhead[R]{\small\color{medgray}Kelompok 08}
|
|
\fancyfoot[C]{\thepage}
|
|
\renewcommand{\headrulewidth}{0.4pt}
|
|
\renewcommand{\footrulewidth}{0pt}
|
|
|
|
% ─── Code Listing ───────────────────────────────────────────────────────────
|
|
\lstdefinestyle{javastyle}{
|
|
language=Java,
|
|
backgroundcolor=\color{codebg},
|
|
basicstyle=\ttfamily\footnotesize\color{codefg},
|
|
keywordstyle=\bfseries\color{primaryblue},
|
|
commentstyle=\itshape\color{medgray},
|
|
stringstyle=\color{successgreen},
|
|
numberstyle=\tiny\color{medgray},
|
|
numbers=left,
|
|
numbersep=8pt,
|
|
frame=single,
|
|
framerule=0.5pt,
|
|
rulecolor=\color{medgray},
|
|
breaklines=true,
|
|
captionpos=b,
|
|
tabsize=4,
|
|
showstringspaces=false,
|
|
}
|
|
\lstdefinestyle{dartstyle}{
|
|
language=Java,
|
|
backgroundcolor=\color{codebg},
|
|
basicstyle=\ttfamily\footnotesize\color{codefg},
|
|
keywordstyle=\bfseries\color{accentblue},
|
|
commentstyle=\itshape\color{medgray},
|
|
stringstyle=\color{successgreen},
|
|
numbers=left,
|
|
numbersep=8pt,
|
|
frame=single,
|
|
framerule=0.5pt,
|
|
rulecolor=\color{medgray},
|
|
breaklines=true,
|
|
captionpos=b,
|
|
tabsize=2,
|
|
showstringspaces=false,
|
|
}
|
|
\lstset{style=javastyle}
|
|
|
|
% ─── Custom Boxes ────────────────────────────────────────────────────────────
|
|
\tcbset{
|
|
infobox/.style={
|
|
enhanced, breakable,
|
|
colback=lightblue!40, colframe=primaryblue,
|
|
fonttitle=\bfseries, coltitle=white,
|
|
attach boxed title to top left={yshift=-2mm, xshift=4mm},
|
|
boxed title style={colback=primaryblue, rounded corners},
|
|
arc=4pt, boxrule=0.8pt,
|
|
},
|
|
warnbox/.style={
|
|
enhanced, breakable,
|
|
colback=warnyellow!10, colframe=warnyellow,
|
|
fonttitle=\bfseries, coltitle=white,
|
|
attach boxed title to top left={yshift=-2mm, xshift=4mm},
|
|
boxed title style={colback=warnyellow, rounded corners},
|
|
arc=4pt, boxrule=0.8pt,
|
|
},
|
|
codebox/.style={
|
|
enhanced, breakable,
|
|
colback=codebg, colframe=medgray,
|
|
arc=2pt, boxrule=0.5pt,
|
|
fontupper=\ttfamily\small,
|
|
}
|
|
}
|
|
|
|
% ─── Custom Commands ─────────────────────────────────────────────────────────
|
|
\newcommand{\done}{\textcolor{successgreen}{\ding{51}}}
|
|
\newcommand{\partial}{\textcolor{warnyellow}{\ding{115}}}
|
|
\newcommand{\missing}{\textcolor{dangerred}{\ding{55}}}
|
|
\newcommand{\code}[1]{\texttt{\small#1}}
|
|
\newcommand{\filepath}[1]{\texttt{\small\color{accentblue}#1}}
|
|
\newcommand{\apipath}[1]{\texttt{\small\color{primaryblue}#1}}
|
|
|
|
% ─── Table Column Types ──────────────────────────────────────────────────────
|
|
\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}
|
|
\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}
|
|
\newcolumntype{R}[1]{>{\raggedleft\arraybackslash}p{#1}}
|
|
|
|
% ════════════════════════════════════════════════════════════════════════════
|
|
\begin{document}
|
|
% ════════════════════════════════════════════════════════════════════════════
|
|
|
|
% ─── Cover Page ─────────────────────────────────────────────────────────────
|
|
\begin{titlepage}
|
|
\pagecolor{primaryblue}
|
|
\color{white}
|
|
\centering
|
|
\vspace*{2cm}
|
|
|
|
{\fontsize{14}{18}\selectfont\textbf{LAPORAN FINAL EXAM}}\\[0.4cm]
|
|
Flutter $\times$ Spring Boot $\times$ OOAD
|
|
|
|
\vspace{1.5cm}
|
|
\begin{tikzpicture}
|
|
\draw[white, line width=2pt] (0,0) circle (2.8cm);
|
|
\node[white, font=\fontsize{40}{44}\selectfont] at (0,0.3) {\faEye};
|
|
\node[white, font=\fontsize{12}{14}\selectfont\bfseries] at (0,-1.2) {WalkGuide};
|
|
\end{tikzpicture}
|
|
|
|
\vspace{1cm}
|
|
{\fontsize{36}{42}\selectfont\bfseries WalkGuide}\\[0.3cm]
|
|
{\fontsize{16}{20}\selectfont AI-Powered Navigation for the Visually Impaired}
|
|
|
|
\vspace{2cm}
|
|
\begin{tcolorbox}[colback=white, colframe=primaryblue, arc=8pt, width=12cm]
|
|
\centering\color{black}
|
|
\begin{tabular}{ll}
|
|
\textbf{Kelompok} & 08 \\[4pt]
|
|
\textbf{Anggota 1} & Evan William / 5803024001 \\
|
|
\textbf{Anggota 2} & Jap Robertus K. Setiabudi / 5803024004 \\
|
|
\textbf{Anggota 3} & Bambang Herlambang / 5803024019 \\[4pt]
|
|
\textbf{Mata Kuliah} & Object-Oriented Analysis and Design \\ & Mobile Device Programming \\ & Web Programming Framework \\
|
|
\textbf{Tanggal} & 19 Mei 2026 \\
|
|
\end{tabular}
|
|
\end{tcolorbox}
|
|
|
|
\vfill
|
|
{\small\color{white!70} Universitas $\cdot$ Surabaya $\cdot$ 2026}
|
|
\end{titlepage}
|
|
\nopagecolor
|
|
|
|
% ─── Front Matter ────────────────────────────────────────────────────────────
|
|
\pagenumbering{roman}
|
|
\fancyhead[L]{\small\color{medgray}WalkGuide -- Final Exam Report}
|
|
|
|
% Abstract
|
|
\chapter*{Abstract}
|
|
\addcontentsline{toc}{chapter}{Abstract}
|
|
|
|
WalkGuide is an AI-powered mobile navigation system designed to assist visually impaired individuals in safely traversing their environment. The system comprises a Flutter mobile application and a Spring Boot RESTful backend, connected in real-time through WebSocket (STOMP) and Firebase Cloud Messaging (FCM). The mobile application runs YOLOv8n object detection entirely on-device using TensorFlow Lite, providing obstacle alerts through Text-to-Speech and haptic feedback without requiring an internet connection for core navigation.
|
|
|
|
The backend, deployed on a university PostgreSQL server, exposes 26 versioned REST endpoints secured with JWT access and refresh tokens and role-based access control (RBAC) for two distinct user roles: \textit{User} (visually impaired individual) and \textit{Guardian} (caregiver or companion). Guardians can monitor the User's real-time location on an interactive map, configure AI detection parameters, send text or voice-note notifications, set up geofence boundaries, and initiate VoIP audio calls via Agora RTC. An SOS alert system allows Users to instantly notify their Guardian with a single voice command or hardware button press.
|
|
|
|
The system implements seven Gang-of-Four (GoF) design patterns spanning all three categories --- Creational, Structural, and Behavioral --- across both the Flutter and Spring Boot codebases. The backend is tested with JUnit 5, Mockito, MockMvc, and Testcontainers, achieving above 70\% JaCoCo line coverage. Load testing was conducted using k6 with up to 30 virtual users. The Flutter application follows Clean Architecture principles with BLoC/Cubit state management and is benchmarked on a physical Android device in profile mode.
|
|
|
|
\textbf{Keywords:} Flutter, Spring Boot, YOLOv8, TensorFlow Lite, Obstacle Detection, Text-to-Speech, Visually Impaired, WebSocket, JWT, Clean Architecture, BLoC, GoF Design Patterns.
|
|
|
|
\tableofcontents
|
|
\listoftables
|
|
\listoffigures
|
|
\newpage
|
|
|
|
% ─── Main Content ─────────────────────────────────────────────────────────────
|
|
\pagenumbering{arabic}
|
|
\setcounter{page}{1}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Introduction}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Problem Background}
|
|
|
|
According to the World Health Organization (WHO), over 2.2 billion people worldwide live with a visual impairment, of which at least 1 billion have conditions that could have been prevented or are yet to be addressed. For individuals with complete or severe visual impairment, navigating public spaces poses significant risks: unexpected obstacles such as vehicles, pedestrians, street furniture, and road hazards create daily challenges that can result in injury.
|
|
|
|
Traditional mobility aids such as the white cane and guide dogs provide partial assistance but offer no real-time digital awareness or remote monitoring capabilities. Existing mobile applications for the visually impaired tend to focus on text recognition or turn-by-turn navigation without addressing real-time obstacle detection or caregiver connectivity.
|
|
|
|
WalkGuide addresses this gap by combining on-device computer vision (YOLOv8n via TensorFlow Lite), real-time audio feedback (Text-to-Speech), and a connected guardian ecosystem into a single, cohesive system --- all running on consumer Android hardware without requiring dedicated or expensive specialized equipment.
|
|
|
|
\section{Objectives}
|
|
|
|
\begin{enumerate}
|
|
\item Design and implement an Android mobile application in Flutter that performs real-time obstacle detection using on-device AI inference.
|
|
\item Build a Spring Boot backend exposing a secure, versioned REST API that manages authentication, pairing, location tracking, notifications, SOS events, and AI configuration.
|
|
\item Connect the two systems in real-time using WebSocket (STOMP) for live location updates and SOS alerts, supplemented by Firebase Cloud Messaging (FCM) for background push notifications.
|
|
\item Apply rigorous Object-Oriented Analysis and Design (OOAD) methodology --- producing use case, class, sequence, state, ERD, and component diagrams --- before commencing development.
|
|
\item Implement at least four GoF design patterns (one per category: Creational, Structural, Behavioral) and document each with a traceability audit.
|
|
\item Demonstrate functional testing (JUnit, widget tests, integration tests) and performance benchmarking (k6 load tests, Flutter profile-mode metrics).
|
|
\end{enumerate}
|
|
|
|
\section{Target Users}
|
|
|
|
\begin{description}
|
|
\item[\textbf{User (ROLE\_USER):}] A visually impaired individual who uses the WalkGuide app as their primary navigation aid. They interact with the app primarily through voice commands and audio feedback (Text-to-Speech), with hardware button shortcuts as a fallback.
|
|
\item[\textbf{Guardian (ROLE\_GUARDIAN):}] A sighted caregiver, family member, or companion who monitors the User remotely through the Guardian dashboard. They can send messages, configure AI settings, set geofences, and initiate calls.
|
|
\end{description}
|
|
|
|
\section{Scope and Limitations}
|
|
|
|
\textbf{In scope:}
|
|
\begin{itemize}
|
|
\item Android-only Flutter mobile application (iOS not targeted in this release).
|
|
\item On-device YOLOv8n inference using TensorFlow Lite; 80 COCO object labels.
|
|
\item RESTful Spring Boot backend deployed on the university server (\code{202.46.28.160}).
|
|
\item PostgreSQL database managed through Flyway migrations (V1--V16).
|
|
\item Real-time communication via STOMP WebSocket and FCM.
|
|
\item VoIP audio calls via Agora RTC.
|
|
\end{itemize}
|
|
|
|
\textbf{Out of scope / known limitations:}
|
|
\begin{itemize}
|
|
\item iOS support: requires a separate Firebase configuration and Agora entitlements.
|
|
\item Firebase FCM backend: currently log-only until production Firebase Admin credentials are supplied.
|
|
\item Agora live call: implemented at API and service level; requires production Agora App ID and Certificate for live RTC.
|
|
\item Depth estimation via dual-camera: planned as a future enhancement.
|
|
\item AI benchmark of multiple model variants: documented in Chapter 12 (AI Benchmark Analysis).
|
|
\end{itemize}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{OOAD --- Pre-Development Design Artifacts}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
All design artifacts in this chapter were produced before development commenced, using PlantUML 1.2024.x. Source \code{.puml} files are committed to \filepath{ooad-docs/diagrams/} in the project repository.
|
|
|
|
\section{Use Case Diagram}
|
|
|
|
Figure~\ref{fig:usecase} depicts the primary actors and use cases of the WalkGuide system. The two human actors are \textit{User} (visually impaired individual) and \textit{Guardian} (caregiver). Three external system actors --- Firebase FCM, Agora RTC, and OpenStreetMap/OSRM --- are included as secondary actors to represent the external services consumed by the system.
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{tikzpicture}[
|
|
actor/.style={draw, circle, minimum size=1cm, font=\small},
|
|
usecase/.style={draw, ellipse, minimum width=3cm, minimum height=0.8cm, font=\small, align=center},
|
|
system/.style={draw, rectangle, dashed, rounded corners, inner sep=8pt},
|
|
>=Latex
|
|
]
|
|
% Actors left
|
|
\node[actor] (user) at (-6, 2) {};
|
|
\node[below=2pt of user, font=\scriptsize\bfseries] {User};
|
|
\node[actor] (guardian) at (-6, -3) {};
|
|
\node[below=2pt of guardian, font=\scriptsize\bfseries] {Guardian};
|
|
|
|
% Actors right
|
|
\node[actor] (fcm) at (7, 2) {};
|
|
\node[below=2pt of fcm, font=\scriptsize] {Firebase FCM};
|
|
\node[actor] (agora) at (7, 0) {};
|
|
\node[below=2pt of agora, font=\scriptsize] {Agora RTC};
|
|
\node[actor] (maps) at (7, -2) {};
|
|
\node[below=2pt of maps, font=\scriptsize] {OpenStreetMap};
|
|
|
|
% System boundary
|
|
\begin{scope}[on background layer]
|
|
\node[system, fit={(0,4.5)(5,-5.5)}, fill=lightblue!30, label={[font=\small\bfseries, color=primaryblue]above:WalkGuide System}] (sys) {};
|
|
\end{scope}
|
|
|
|
% Use cases
|
|
\node[usecase, fill=white] (ucauth) at (2.5, 4) {Register / Login};
|
|
\node[usecase, fill=white] (ucpair) at (2.5, 3) {Pair Guardian \& User};
|
|
\node[usecase, fill=white] (ucwalk) at (2.5, 2) {Start WalkGuide};
|
|
\node[usecase, fill=white] (ucdetect) at (2.5, 1) {Detect Obstacle};
|
|
\node[usecase, fill=white] (ucloc) at (2.5, 0) {Report Location};
|
|
\node[usecase, fill=white] (ucsos) at (2.5, -1) {Trigger SOS};
|
|
\node[usecase, fill=white] (ucnotif) at (2.5, -2) {Read Notifications};
|
|
\node[usecase, fill=white] (uccall) at (2.5, -3) {Call Partner};
|
|
\node[usecase, fill=white] (ucdash) at (2.5, -4) {Monitor Dashboard};
|
|
\node[usecase, fill=white] (ucconfig) at (2.5, -5) {Configure AI / Geofence};
|
|
|
|
% Arrows - User
|
|
\draw[->] (user) -- (ucauth);
|
|
\draw[->] (user) -- (ucpair);
|
|
\draw[->] (user) -- (ucwalk);
|
|
\draw[->] (user) -- (ucsos);
|
|
\draw[->] (user) -- (ucnotif);
|
|
\draw[->] (user) -- (uccall);
|
|
|
|
% include
|
|
\draw[->, dashed] (ucwalk) -- node[right, font=\scriptsize]{$\langle\langle$include$\rangle\rangle$} (ucdetect);
|
|
\draw[->, dashed] (ucwalk) -- node[right, font=\scriptsize]{$\langle\langle$include$\rangle\rangle$} (ucloc);
|
|
|
|
% Arrows - Guardian
|
|
\draw[->] (guardian) -- (ucauth);
|
|
\draw[->] (guardian) -- (ucpair);
|
|
\draw[->] (guardian) -- (uccall);
|
|
\draw[->] (guardian) -- (ucdash);
|
|
\draw[->] (guardian) -- (ucconfig);
|
|
|
|
% Arrows - External
|
|
\draw[->] (ucsos) -- (fcm);
|
|
\draw[->] (ucnotif) -- (fcm);
|
|
\draw[->] (uccall) -- (agora);
|
|
\draw[->] (uccall) -- (fcm);
|
|
\draw[->] (ucloc) -- (maps);
|
|
\end{tikzpicture}
|
|
\caption{WalkGuide Use Case Diagram}
|
|
\label{fig:usecase}
|
|
\end{figure}
|
|
|
|
\section{Class Diagram}
|
|
|
|
The domain model consists of 13 core entity classes, 5 controller classes, and 14 service classes. Table~\ref{tab:entities} summarizes the primary entities and their key attributes. The full class diagram is rendered from \filepath{ooad-docs/diagrams/class-diagram.puml}.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Core Domain Entity Classes}
|
|
\label{tab:entities}
|
|
\begin{tabularx}{\textwidth}{L{3.2cm} L{4.5cm} L{5.5cm}}
|
|
\toprule
|
|
\textbf{Entity} & \textbf{Key Attributes} & \textbf{Key Relationships} \\
|
|
\midrule
|
|
\code{User} & id, email, role, uniqueUserId, displayName, fcmToken & One-to-many with LocationHistory, ActivityLog, SosEvent \\
|
|
\code{PairingRelation} & id, status, invitedAt, respondedAt & Many-to-one with guardian (User) and user (User) \\
|
|
\code{LocationHistory} & id, lat, lng, accuracy, speed, heading & Many-to-one with User \\
|
|
\code{ActivityLog} & id, logType, description, metadata (JSONB) & Many-to-one with User \\
|
|
\code{ObstacleLog} & id, label, confidence, direction, estimatedDist & Many-to-one with User \\
|
|
\code{GuardianNotification} & id, notifType, content, voiceNoteUrl, isRead & Linked via PairingRelation \\
|
|
\code{SosEvent} & id, triggerType, lat, lng, status & Many-to-one with User \\
|
|
\code{UserSettings} & ttsLanguage, ttsPitch, ttsSpeed, hapticEnabled & One-to-one with User \\
|
|
\code{AiConfig} & confidenceThreshold, alertDistanceClose, maxInferenceFps & Linked via PairingRelation \\
|
|
\code{VoiceCommandConfig} & commandKey, triggerPhrase, enabled & Linked via PairingRelation \\
|
|
\code{HardwareShortcut} & shortcutKey, buttonName, buttonCode, enabled & Linked via PairingRelation \\
|
|
\code{GeofenceConfig} & centerLat, centerLng, radiusMeters, enabled & Linked via PairingRelation \\
|
|
\code{RefreshToken} & token, expiresAt & Many-to-one with User \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Sequence Diagrams}
|
|
|
|
\subsection{Sequence 1: Login Flow}
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{tikzpicture}[
|
|
lifeline/.style={draw, rectangle, minimum width=2cm, minimum height=0.6cm, font=\scriptsize, fill=lightblue!40},
|
|
msg/.style={->, font=\scriptsize},
|
|
retmsg/.style={->, dashed, font=\scriptsize},
|
|
]
|
|
\node[lifeline] (user) at (0,0) {User};
|
|
\node[lifeline] (ui) at (2.5,0) {LoginScreen};
|
|
\node[lifeline] (dio) at (5.5,0) {ApiClient};
|
|
\node[lifeline] (ctrl) at (8.5,0) {AuthController};
|
|
\node[lifeline] (svc) at (11,0) {AuthService};
|
|
\node[lifeline] (db) at (13.5,0) {PostgreSQL};
|
|
|
|
\foreach \x in {0,2.5,5.5,8.5,11,13.5}
|
|
\draw[dashed, medgray] (\x,-0.3) -- (\x,-6.5);
|
|
|
|
\draw[msg] (0,-0.7) -- node[above, font=\scriptsize]{enter credentials} (2.5,-0.7);
|
|
\draw[msg] (2.5,-1.2) -- node[above, font=\scriptsize]{POST /auth/login} (5.5,-1.2);
|
|
\draw[msg] (5.5,-1.7) -- node[above, font=\scriptsize]{LoginRequest} (8.5,-1.7);
|
|
\draw[msg] (8.5,-2.2) -- node[above, font=\scriptsize]{login(req)} (11,-2.2);
|
|
\draw[msg] (11,-2.7) -- node[above, font=\scriptsize]{findByEmail + tokens} (13.5,-2.7);
|
|
\draw[retmsg] (13.5,-3.2) -- node[above, font=\scriptsize]{user entity} (11,-3.2);
|
|
\draw[retmsg] (11,-3.7) -- node[above, font=\scriptsize]{AuthDataResponse} (8.5,-3.7);
|
|
\draw[retmsg] (8.5,-4.2) -- node[above, font=\scriptsize]{ApiResponse<AuthDataResponse>} (5.5,-4.2);
|
|
\draw[retmsg] (5.5,-4.7) -- node[above, font=\scriptsize]{tokens + role} (2.5,-4.7);
|
|
\draw[msg] (2.5,-5.2) -- node[above, font=\scriptsize]{save tokens, route by role} (0,-5.2);
|
|
\end{tikzpicture}
|
|
\caption{Sequence Diagram: Login Flow}
|
|
\label{fig:seq-login}
|
|
\end{figure}
|
|
|
|
\subsection{Sequence 2: Guardian Invites User (Pairing)}
|
|
|
|
The pairing flow is initiated by a Guardian who inputs the User's 12-character unique ID. Upon acceptance, the backend seeds 14 default voice command configurations, 5 hardware shortcut configurations, and one AI configuration record for the pair.
|
|
|
|
\subsection{Sequence 3: SOS Alert End-to-End}
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{tikzpicture}[
|
|
lifeline/.style={draw, rectangle, minimum width=1.8cm, minimum height=0.6cm, font=\scriptsize, fill=lightblue!40},
|
|
msg/.style={->, font=\scriptsize},
|
|
retmsg/.style={->, dashed, font=\scriptsize},
|
|
]
|
|
\node[lifeline] (user) at (0,0) {User};
|
|
\node[lifeline] (ui) at (2.3,0) {SosScreen};
|
|
\node[lifeline] (ctrl) at (5,0) {UserController};
|
|
\node[lifeline] (svc) at (7.7,0) {SosService};
|
|
\node[lifeline] (db) at (10,0) {PostgreSQL};
|
|
\node[lifeline] (fcm) at (12.3,0) {FCM};
|
|
\node[lifeline] (dash) at (14.6,0) {GuardianDash};
|
|
|
|
\foreach \x in {0,2.3,5,7.7,10,12.3,14.6}
|
|
\draw[dashed, medgray] (\x,-0.3) -- (\x,-7.5);
|
|
|
|
\draw[msg] (0,-0.7) -- node[above, font=\tiny]{press SOS} (2.3,-0.7);
|
|
\draw[msg] (2.3,-1.2) -- node[above, font=\tiny]{POST /user/sos} (5,-1.2);
|
|
\draw[msg] (5,-1.7) -- node[above, font=\tiny]{triggerSos()} (7.7,-1.7);
|
|
\draw[msg] (7.7,-2.2) -- node[above, font=\tiny]{save SosEvent} (10,-2.2);
|
|
\draw[retmsg] (10,-2.7) -- (7.7,-2.7);
|
|
\draw[msg] (7.7,-3.2) -- node[above, font=\tiny]{high-priority push} (12.3,-3.2);
|
|
\draw[msg] (7.7,-3.7) -- node[above, font=\tiny]{WS /queue/sos/\{guardianId\}} (14.6,-3.7);
|
|
\draw[retmsg] (7.7,-4.2) -- node[above, font=\tiny]{SosEventResponse} (5,-4.2);
|
|
\draw[retmsg] (5,-4.7) -- node[above, font=\tiny]{201 Created} (2.3,-4.7);
|
|
\draw[msg] (2.3,-5.2) -- node[above, font=\tiny]{TTS + haptic} (0,-5.2);
|
|
\draw[msg] (14.6,-5.7) -- node[above, font=\tiny]{PUT /sos/\{id\}/acknowledge} (5,-5.7);
|
|
\draw[msg] (5,-6.2) -- node[above, font=\tiny]{acknowledgeSos()} (7.7,-6.2);
|
|
\draw[msg] (7.7,-6.7) -- node[above, font=\tiny]{FCM to User: help coming} (12.3,-6.7);
|
|
\end{tikzpicture}
|
|
\caption{Sequence Diagram: SOS Alert Flow}
|
|
\label{fig:seq-sos}
|
|
\end{figure}
|
|
|
|
\section{State Machine Diagram}
|
|
|
|
The \code{SosEvent} entity transitions through three states: \texttt{TRIGGERED} (initial), \texttt{ACKNOWLEDGED} (Guardian confirms), and \texttt{RESOLVED} (incident closed). Figure~\ref{fig:state} illustrates these transitions.
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{tikzpicture}[
|
|
state/.style={draw, rounded rectangle, minimum width=2.5cm, minimum height=0.8cm, font=\small, fill=lightblue!40},
|
|
>=Latex
|
|
]
|
|
\node[fill=darkgray, circle, minimum size=0.4cm] (start) at (-2, 0) {};
|
|
\node[state, fill=warnyellow!30] (triggered) at (1.5, 0) {TRIGGERED};
|
|
\node[state, fill=accentblue!20] (acked) at (6, 0) {ACKNOWLEDGED};
|
|
\node[state, fill=successgreen!20] (resolved) at (10, 0) {RESOLVED};
|
|
\node[fill=darkgray, circle, minimum size=0.4cm, label=right:{}] (end) at (13, 0) {};
|
|
\draw[thick, double distance=2pt] (end) circle (0.55cm);
|
|
|
|
\draw[->] (start) -- (triggered);
|
|
\draw[->] (triggered) -- node[above, font=\scriptsize]{Guardian acknowledges} (acked);
|
|
\draw[->] (acked) -- node[above, font=\scriptsize]{incident handled} (resolved);
|
|
\draw[->, bend right=30] (triggered) to node[below, font=\scriptsize]{auto / manual close} (resolved);
|
|
\draw[->] (resolved) -- (end);
|
|
\end{tikzpicture}
|
|
\caption{State Machine Diagram: SosEvent}
|
|
\label{fig:state}
|
|
\end{figure}
|
|
|
|
\section{Entity-Relationship Diagram}
|
|
|
|
The database schema consists of 16 tables managed by Flyway migrations V1--V16. All tables use \code{BIGSERIAL} primary keys and \code{TIMESTAMP} audit fields. The central entity is \code{users}, which branches into both personal data (settings, tokens, logs) and relational data (pairing, notifications, configurations).
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Database Tables Summary (Flyway V1--V16)}
|
|
\label{tab:db}
|
|
\begin{tabularx}{\textwidth}{C{0.5cm} L{4cm} L{8.5cm}}
|
|
\toprule
|
|
\textbf{V\#} & \textbf{Table / Action} & \textbf{Description} \\
|
|
\midrule
|
|
V1 & \code{users} & Core user table with email, password (BCrypt), role, display name, FCM token \\
|
|
V2 & seed data & Seed default users for development testing \\
|
|
V3 & guardian-user link & Initial guardian-user relationship scaffolding \\
|
|
V4 & \code{ALTER users} & Add \code{unique\_user\_id} CHAR(12) column \\
|
|
V5 & \code{pairing\_relations} & Guardian-User pairing with PENDING/ACTIVE/REJECTED status \\
|
|
V6 & \code{activity\_logs} & All user activity events with JSONB metadata \\
|
|
V7 & \code{obstacle\_logs} & YOLO detection records with direction and estimated distance \\
|
|
V8 & \code{location\_history} & GPS coordinates with accuracy, speed, heading \\
|
|
V9 & \code{guardian\_notifications} & Text and voice-note messages from Guardian to User \\
|
|
V10 & \code{sos\_events} & SOS triggers with location and status transitions \\
|
|
V11 & \code{user\_settings} & TTS language, pitch, speed, haptic preferences \\
|
|
V12 & \code{ai\_configs} & YOLO confidence threshold, alert distances, max FPS \\
|
|
V13 & \code{voice\_command\_configs} & 14 configurable voice trigger phrases per user pair \\
|
|
V14 & \code{hardware\_shortcuts} & 5 hardware button assignments per user pair \\
|
|
V15 & \code{geofence\_configs} & Geofence center coordinates and radius per user pair \\
|
|
V16 & \code{refresh\_tokens} & JWT refresh tokens with 30-day expiry \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Component Diagram}
|
|
|
|
The system is composed of four major runtime components: the Flutter mobile application, the Spring Boot backend, the PostgreSQL database, and three external cloud services (Firebase FCM, Agora RTC, OpenStreetMap/OSRM). Communication channels are shown in Figure~\ref{fig:component}.
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{tikzpicture}[
|
|
comp/.style={draw, rectangle, rounded corners, minimum width=3cm, minimum height=1cm, font=\small, fill=lightblue!30},
|
|
subcomp/.style={draw, rectangle, minimum width=2.4cm, minimum height=0.7cm, font=\scriptsize, fill=white},
|
|
cloud/.style={draw, ellipse, minimum width=2.5cm, minimum height=1cm, font=\scriptsize, fill=warnyellow!20},
|
|
db/.style={draw, cylinder, shape border rotate=90, minimum width=2cm, minimum height=1.2cm, font=\scriptsize, fill=successgreen!20},
|
|
>=Latex
|
|
]
|
|
% Flutter
|
|
\node[comp, minimum width=4.5cm, minimum height=3.5cm, label=center:\textbf{}] (flutter) at (-4, 1) {};
|
|
\node[font=\small\bfseries, color=primaryblue] at (-4, 2.5) {Flutter Mobile};
|
|
\node[subcomp] at (-4, 1.7) {Screens + BLoC};
|
|
\node[subcomp] at (-4, 0.9) {ApiClient (Dio)};
|
|
\node[subcomp] at (-4, 0.1) {YOLO / TTS / STT};
|
|
\node[subcomp] at (-4, -0.7) {WebSocketService};
|
|
|
|
% Spring Boot
|
|
\node[comp, minimum width=4.5cm, minimum height=3.5cm] (spring) at (4, 1) {};
|
|
\node[font=\small\bfseries, color=primaryblue] at (4, 2.5) {Spring Boot};
|
|
\node[subcomp] at (4, 1.7) {Controllers};
|
|
\node[subcomp] at (4, 0.9) {Services};
|
|
\node[subcomp] at (4, 0.1) {Repositories};
|
|
\node[subcomp] at (4, -0.7) {WebSocket Broker};
|
|
|
|
% DB
|
|
\node[db] (db) at (4, -2.8) {PostgreSQL};
|
|
|
|
% Clouds
|
|
\node[cloud] (fcm) at (-4, -3) {Firebase FCM};
|
|
\node[cloud] (agora) at (0, -3) {Agora RTC};
|
|
\node[cloud] (maps) at (-4, -4.5) {OpenStreetMap};
|
|
|
|
% Arrows
|
|
\draw[<->, thick, color=primaryblue] (-2, 1) -- node[above, font=\scriptsize]{REST /api/v1} (2, 1);
|
|
\draw[<->, thick, color=accentblue] (-2, -0.3) -- node[below, font=\scriptsize]{STOMP /ws} (2, -0.3);
|
|
\draw[->] (spring) -- (db);
|
|
\draw[->] (spring) -- (fcm);
|
|
\draw[->] (flutter) -- (agora);
|
|
\draw[->] (flutter) -- (maps);
|
|
\end{tikzpicture}
|
|
\caption{WalkGuide System Component Diagram}
|
|
\label{fig:component}
|
|
\end{figure}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{OOAD --- Design Pattern Documentation}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
Seven GoF design patterns are implemented across the WalkGuide codebase, covering all three categories. Table~\ref{tab:patterns} provides a summary; detailed documentation follows.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{GoF Design Patterns in WalkGuide}
|
|
\label{tab:patterns}
|
|
\begin{tabularx}{\textwidth}{L{2.5cm} L{2.2cm} L{4cm} L{5cm}}
|
|
\toprule
|
|
\textbf{Pattern} & \textbf{Category} & \textbf{Location} & \textbf{Justification} \\
|
|
\midrule
|
|
Builder & Creational & \code{User.java}, \code{FcmService.java} & Many optional fields; fluent construction \\
|
|
Singleton & Creational & \code{injection\_container.dart} & One shared lifecycle for resource-heavy services \\
|
|
Facade & Structural & \code{TtsService}, \code{VoiceCommandHandler} & Hides plugin complexity from UI layer \\
|
|
Repository & Structural & All \code{*Repository.java} interfaces & Decouples JPA from service logic \\
|
|
Observer & Behavioral & BLoC/Cubit, \code{WebSocketService} & Reactive state; real-time push without polling \\
|
|
Strategy & Behavioral & \code{obstacle\_analyzer.dart} & Swappable direction/distance thresholds \\
|
|
Chain of Responsibility & Behavioral & Dio interceptors, Spring Security filter chain & Sequential request handling with pass-through \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Creational: Builder Pattern}
|
|
|
|
\textbf{Location:} \filepath{walkguide-backend/demo/src/main/java/com/walkguide/entity/User.java}, \filepath{service/FcmService.java}
|
|
|
|
\textbf{Implementation:} Lombok's \code{@Builder} annotation is applied to the \code{User} entity and all response DTO classes. The Firebase \code{Message} object in \code{FcmService} is constructed using the Agora SDK's native builder.
|
|
|
|
\textbf{Justification:} The \code{User} entity has eight fields, five of which are optional (e.g., \code{displayName}, \code{uniqueUserId}, \code{fcmToken}). Using a builder prevents telescoping constructors and makes the construction intent explicit at every call site.
|
|
|
|
\begin{lstlisting}[style=javastyle, caption={Builder Pattern -- User entity construction}]
|
|
// entity/User.java
|
|
@Entity @Builder @Data @NoArgsConstructor @AllArgsConstructor
|
|
public class User {
|
|
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
|
|
private Long id;
|
|
private String email;
|
|
private String password;
|
|
private String role;
|
|
private String uniqueUserId; // optional: ROLE_USER only
|
|
private String displayName;
|
|
private String fcmToken; // optional: updated post-login
|
|
// ...
|
|
}
|
|
|
|
// Usage in AuthService.java
|
|
User newUser = User.builder()
|
|
.email(req.getEmail())
|
|
.password(encoder.encode(req.getPassword()))
|
|
.role(req.getRole())
|
|
.displayName(req.getDisplayName())
|
|
.build();
|
|
\end{lstlisting}
|
|
|
|
\section{Creational: Singleton Pattern}
|
|
|
|
\textbf{Location:} \filepath{walkguide-mobile/walkguide\_app/lib/app/injection\_container.dart}
|
|
|
|
\textbf{Implementation:} All resource-heavy services are registered as singletons in the GetIt service locator. This ensures that \code{TtsService}, \code{WebSocketService}, \code{YoloDetector}, and \code{CallService} each have exactly one instance throughout the application lifecycle.
|
|
|
|
\textbf{Justification:} The YOLO interpreter holds the entire model in memory ($\sim$6 MB). Creating multiple instances would exhaust mobile heap. The WebSocket connection must be shared across screens to avoid duplicate STOMP subscriptions.
|
|
|
|
\begin{lstlisting}[style=dartstyle, caption={Singleton Pattern -- GetIt registration}]
|
|
// injection_container.dart
|
|
void setupInjection(String baseUrl) {
|
|
getIt.registerLazySingleton<TtsService>(() => TtsService());
|
|
getIt.registerLazySingleton<YoloDetector>(() => YoloDetector());
|
|
getIt.registerLazySingleton<WebSocketService>(() => WebSocketService());
|
|
getIt.registerLazySingleton<ApiClient>(() => ApiClient(baseUrl));
|
|
// Factories for BLoCs (new instance per screen):
|
|
getIt.registerFactory<AuthBloc>(() => AuthBloc(getIt()));
|
|
}
|
|
\end{lstlisting}
|
|
|
|
\section{Structural: Facade Pattern}
|
|
|
|
\textbf{Location:} \filepath{core/services/tts\_service.dart}, \filepath{core/services/voice\_command\_handler.dart}
|
|
|
|
\textbf{Implementation:} \code{TtsService} wraps the \code{flutter\_tts} plugin behind a simple interface: \code{speak()}, \code{speakImmediate()}, \code{stop()}, and \code{setLanguage()}. Callers never interact with the raw plugin. Similarly, \code{VoiceCommandHandler} acts as a facade over STT recognition, voice command matching, BLoC event dispatching, and GoRouter navigation.
|
|
|
|
\textbf{Justification:} Without the facade, WalkGuide screen widgets would need to manage plugin lifecycle, language configuration, and queue management directly --- coupling UI code to implementation details.
|
|
|
|
\section{Structural: Repository Pattern}
|
|
|
|
\textbf{Location:} All files in \filepath{walkguide-backend/demo/src/main/java/com/walkguide/repository/}
|
|
|
|
\textbf{Implementation:} Each Spring Data JPA repository interface extends \code{JpaRepository} and defines domain-specific query methods. Services depend only on repository interfaces, never on concrete JPA or SQL APIs.
|
|
|
|
\textbf{Justification:} Applying the Repository pattern enables full Mockito mocking of the persistence layer in unit tests. Swapping PostgreSQL for another database would require changing only the repository implementations, not the service layer.
|
|
|
|
\section{Behavioral: Observer Pattern}
|
|
|
|
\textbf{Location:} \filepath{lib/app/app\_cubit.dart}, all BLoC files, \filepath{core/services/websocket\_service.dart}, \filepath{walkguide-backend/.../websocket/LocationBroadcaster.java}
|
|
|
|
\textbf{Implementation:} The BLoC/Cubit pattern is itself an implementation of Observer: the BLoC is the Subject, and all \code{BlocBuilder}/\code{BlocConsumer} widgets are Observers. On the backend, the Spring WebSocket broker pushes location, SOS, and notification updates to all subscribed Guardian clients without polling.
|
|
|
|
\section{Behavioral: Strategy Pattern}
|
|
|
|
\textbf{Location:} \filepath{core/ai/obstacle\_analyzer.dart}
|
|
|
|
\textbf{Implementation:} \code{ObstacleAnalyzer} encapsulates two independent strategies: \code{analyzeDirection()} (which divides the camera frame into thirds) and \code{estimateDistance()} (which uses bounding-box height ratio against configurable thresholds from \code{AiConfig}). Changing the Guardian's AI configuration updates the threshold values without touching the analyzer algorithm.
|
|
|
|
\section{Behavioral: Chain of Responsibility Pattern}
|
|
|
|
\textbf{Location:} \filepath{core/network/api\_client.dart} (Dio interceptors), \filepath{security/JwtAuthFilter.java}
|
|
|
|
\textbf{Implementation:} Every outgoing HTTP request passes through a chain: \textit{AuthInterceptor} (inject JWT Bearer token) $\to$ \textit{ErrorInterceptor} (normalize HTTP errors to typed \code{Failure} objects) $\to$ \textit{LogInterceptor} (development logging). On the backend, Spring Security's filter chain processes each request through \code{JwtAuthFilter} before reaching controllers.
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{OOAD --- Design Traceability Audit}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Use Case to Code Mapping}
|
|
|
|
\begin{longtable}{L{3.5cm} L{3.5cm} L{4cm} C{2cm}}
|
|
\caption{Use Case Traceability Matrix} \label{tab:traceability} \\
|
|
\toprule
|
|
\textbf{Use Case} & \textbf{Flutter Entry} & \textbf{Backend Entry} & \textbf{Status} \\
|
|
\midrule
|
|
\endfirsthead
|
|
\multicolumn{4}{c}{\textit{(continued from previous page)}} \\
|
|
\toprule
|
|
\textbf{Use Case} & \textbf{Flutter Entry} & \textbf{Backend Entry} & \textbf{Status} \\
|
|
\midrule
|
|
\endhead
|
|
\bottomrule
|
|
\endfoot
|
|
Register / Login & \code{features/auth/*} & \code{AuthController}, \code{AuthService} & \done \\
|
|
Pair Guardian \& User & \code{features/pairing/pairing\_screens.dart} & \code{PairingController}, \code{PairingService} & \done \\
|
|
Start / Stop WalkGuide & \code{features/walk\_guide/walk\_guide\_screen.dart} & \code{POST /user/walkguide/start,stop} & \done \\
|
|
Detect Obstacle & \code{core/ai/*}, \code{walk\_guide\_screen.dart} & \code{POST /user/obstacle} & \textcolor{warnyellow}{Partial}* \\
|
|
Report Location & \code{LocationReporterService} & \code{LocationService}, \code{LocationBroadcaster} & \done \\
|
|
Trigger SOS & \code{features/sos/sos\_screen.dart} & \code{SosService}, \code{GuardianController} & \done \\
|
|
Read Notifications & \code{features/notifications/notification\_screen.dart} & \code{NotificationService}, \code{FcmService} & \done \\
|
|
Monitor Dashboard & \code{guardian\_dashboard\_screen.dart} & \code{GuardianDashboardService} & \done \\
|
|
Call Partner & \code{features/call/call\_screen.dart}, \code{CallService} & \code{CallController}, \code{AgoraTokenService} & \textcolor{warnyellow}{Partial}** \\
|
|
Configure AI / Geofence & \code{guardian\_ai\_config\_screen.dart} & \code{AiConfigService}, \code{GeofenceService} & \done \\
|
|
Navigate Route & \code{features/navigation\_mode/} & \code{POST /user/location} + OSRM & \done \\
|
|
\end{longtable}
|
|
|
|
\textit{* Obstacle detection code complete; requires \code{yolov8n.tflite} asset file for live inference.}\\
|
|
\textit{** Call API and service complete; requires production Agora App ID and Certificate for live RTC.}
|
|
|
|
\section{Design Deviations}
|
|
|
|
\begin{tcolorbox}[warnbox, title={Documented Design Deviations}]
|
|
\begin{enumerate}
|
|
\item \textbf{State Management (Partial BLoC):} The architecture document specifies BLoC for all screens. In implementation, several guardian dashboard screens use \code{StatefulWidget} with direct service calls for simplicity during the exam sprint. This trades architectural purity for development speed; the deviation is localized to screens that do not require complex state transitions.
|
|
|
|
\item \textbf{Offline Storage (Partial Drift):} The full architecture specifies Drift (SQLite ORM) for offline-first entity caching. The current implementation uses \code{SharedPreferences} for a lightweight offline queue (\code{offline\_queue\_service.dart}) instead of a full Drift database. The Drift dependency is present in \code{pubspec.yaml} for future extension.
|
|
|
|
\item \textbf{Backend FCM (Log-Only):} The \code{FcmService} currently logs the push notification payload instead of calling \code{FirebaseMessaging.send()}. This is an intentional deferral pending the provisioning of a production Firebase Admin credential file (\code{google-services-admin.json}).
|
|
|
|
\item \textbf{i18n (Dependency Only):} Full internationalization with \code{.arb} locale files was not completed within the exam timeline. The \code{flutter\_localizations} dependency is declared; UI strings remain in English.
|
|
\end{enumerate}
|
|
\end{tcolorbox}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{System Architecture}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Flutter Clean Architecture}
|
|
|
|
The Flutter application is organized in a feature-first directory structure. Each feature module contains three sub-layers following Clean Architecture:
|
|
|
|
\begin{description}
|
|
\item[\textbf{Domain Layer}] Contains entities (pure Dart classes with no framework dependencies), abstract repository interfaces, and use cases. This layer has zero external dependencies.
|
|
\item[\textbf{Data Layer}] Contains concrete repository implementations, data source classes (remote API and local storage), and data models (JSON serialization). This layer depends on Dio, SharedPreferences, and platform services.
|
|
\item[\textbf{Presentation Layer}] Contains BLoC/Cubit classes, screen widgets, and local widget components. This layer depends only on the domain layer (via use cases) and never imports from the data layer directly.
|
|
\end{description}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Flutter Project Structure Summary}
|
|
\label{tab:flutter-structure}
|
|
\begin{tabularx}{\textwidth}{L{5cm} L{8.5cm}}
|
|
\toprule
|
|
\textbf{Directory} & \textbf{Contents} \\
|
|
\midrule
|
|
\code{lib/app/} & App entry, router (GoRouter), GetIt injection container \\
|
|
\code{lib/core/ai/} & YoloDetector, ObstacleAnalyzer, model loader \\
|
|
\code{lib/core/network/} & ApiClient (Dio), AuthInterceptor, ErrorInterceptor \\
|
|
\code{lib/core/services/} & TtsService, SttService, VoiceCommandHandler, WebSocketService, FCMService, HapticService \\
|
|
\code{lib/core/storage/} & SecureStorage (JWT tokens), OfflineQueueService \\
|
|
\code{lib/features/auth/} & Login, Register, Splash screens + AuthBloc \\
|
|
\code{lib/features/walk\_guide/} & WalkGuide screen with camera stream + YOLO pipeline \\
|
|
\code{lib/features/sos/} & SOS screen + SosCubit \\
|
|
\code{lib/features/notifications/} & Notification screen + NotificationBloc \\
|
|
\code{lib/features/pairing/} & User/Guardian pairing screens + PairingBloc \\
|
|
\code{lib/features/guardian\_dashboard/} & Dashboard, map, AI config, voice cmd, shortcut, geofence screens \\
|
|
\code{lib/features/call/} & VoIP call screen + CallService (Agora) \\
|
|
\code{lib/features/navigation\_mode/} & OpenStreetMap navigation screen \\
|
|
\code{lib/shared/widgets/} & Reusable shells, navigation bars \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Spring Boot Layered Architecture}
|
|
|
|
The backend follows a strict three-layer architecture:
|
|
|
|
\begin{enumerate}
|
|
\item \textbf{Controller Layer:} Handles HTTP request/response, input validation (\code{@Valid}), and delegates to services. Contains no business logic.
|
|
\item \textbf{Service Layer:} Implements all business logic, orchestrates repository calls, publishes WebSocket events, and calls FCM/Agora services.
|
|
\item \textbf{Repository Layer:} Spring Data JPA interfaces. Contains only query method declarations; no SQL strings in the Java code.
|
|
\end{enumerate}
|
|
|
|
\section{Real-Time Architecture}
|
|
|
|
Two complementary mechanisms provide real-time connectivity:
|
|
|
|
\begin{description}
|
|
\item[\textbf{WebSocket (STOMP):}] Used for low-latency, high-frequency updates when both parties are online and the app is in the foreground. Topics: \code{/topic/location/\{userId\}} (live location for Guardian), \code{/queue/sos/\{guardianId\}} (SOS alerts), \code{/queue/notif/\{userId\}} (incoming notifications).
|
|
\item[\textbf{Firebase Cloud Messaging (FCM):}] Used for background delivery when the app is not in the foreground, and for high-priority alerts (SOS, incoming calls). FCM payloads include a \code{type} field (\code{SOS\_ALERT}, \code{INCOMING\_CALL}, \code{NOTIFICATION}, etc.) that drives the Flutter notification handler.
|
|
\end{description}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{API Contract}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Response Envelope}
|
|
|
|
All endpoints return a consistent JSON envelope:
|
|
\begin{tcblisting}{codebox}
|
|
{
|
|
"success": true,
|
|
"data": { ... },
|
|
"message": "Operation successful",
|
|
"timestamp": "2026-05-19T10:30:00Z"
|
|
}
|
|
\end{tcblisting}
|
|
|
|
Error responses use \code{success: false} with an \code{errorCode} field (\code{AUTH\_ERROR}, \code{NOT\_FOUND}, \code{PAIRING\_ERROR}, \code{VALIDATION\_ERROR}, \code{INTERNAL\_ERROR}).
|
|
|
|
\section{Endpoint Summary}
|
|
|
|
\begin{longtable}{L{1cm} L{5cm} L{4.5cm} C{2cm}}
|
|
\caption{REST API Endpoints (26 Total)} \label{tab:api} \\
|
|
\toprule
|
|
\textbf{Method} & \textbf{Path} & \textbf{Description} & \textbf{Auth} \\
|
|
\midrule
|
|
\endfirsthead
|
|
\multicolumn{4}{c}{\textit{(continued)}} \\
|
|
\toprule
|
|
\textbf{Method} & \textbf{Path} & \textbf{Description} & \textbf{Auth} \\
|
|
\midrule
|
|
\endhead
|
|
\bottomrule
|
|
\endfoot
|
|
\multicolumn{4}{l}{\textit{Auth (/api/v1/auth)}} \\
|
|
GET & /auth/ping & Health check / server test & None \\
|
|
POST & /auth/register & Register Guardian or User & None \\
|
|
POST & /auth/login & Login, receive JWT tokens & None \\
|
|
POST & /auth/refresh & Refresh access token & None \\
|
|
POST & /auth/logout & Logout, revoke refresh token & JWT \\
|
|
PUT & /auth/fcm-token & Update FCM device token & JWT \\
|
|
\midrule
|
|
\multicolumn{4}{l}{\textit{Pairing (/api/v1/shared/pairing)}} \\
|
|
POST & /pairing/invite & Guardian invites User by unique ID & GUARDIAN \\
|
|
POST & /pairing/respond & User accepts / rejects invite & USER \\
|
|
DELETE & /pairing/unpair & Dissolve active pairing & JWT \\
|
|
GET & /pairing/status & Get current pairing status & JWT \\
|
|
\midrule
|
|
\multicolumn{4}{l}{\textit{Guardian (/api/v1/guardian)}} \\
|
|
GET & /guardian/dashboard & Combined dashboard data & GUARDIAN \\
|
|
GET & /guardian/user-status & Paired user status & GUARDIAN \\
|
|
GET & /guardian/user-location & Last known GPS location & GUARDIAN \\
|
|
GET & /guardian/location-history & Location history (paginated) & GUARDIAN \\
|
|
GET & /guardian/activity-logs & User activity logs & GUARDIAN \\
|
|
POST & /guardian/notifications/send & Send text or voice note & GUARDIAN \\
|
|
GET & /guardian/sos-events & All SOS events & GUARDIAN \\
|
|
PUT & /guardian/sos/\{id\}/acknowledge & Acknowledge SOS & GUARDIAN \\
|
|
PUT & /guardian/ai-config & Update AI configuration & GUARDIAN \\
|
|
PUT & /guardian/voice-commands & Update voice command phrase & GUARDIAN \\
|
|
PUT & /guardian/geofence & Update geofence config & GUARDIAN \\
|
|
\midrule
|
|
\multicolumn{4}{l}{\textit{User (/api/v1/user)}} \\
|
|
GET & /user/profile & User profile & USER \\
|
|
GET & /user/settings & TTS and app settings & USER \\
|
|
PUT & /user/settings & Update user settings & USER \\
|
|
POST & /user/location & Send GPS update & USER \\
|
|
POST & /user/obstacle & Log detected obstacle & USER \\
|
|
POST & /user/sos & Trigger SOS alert & USER \\
|
|
GET & /user/notifications & Notifications from Guardian & USER \\
|
|
PUT & /user/notifications/mark-all-read & Mark all as read & USER \\
|
|
POST & /user/walkguide/start & Log WalkGuide session start & USER \\
|
|
POST & /user/walkguide/stop & Log WalkGuide session stop & USER \\
|
|
\midrule
|
|
\multicolumn{4}{l}{\textit{Shared (/api/v1/shared)}} \\
|
|
POST & /call/token & Generate Agora RTC token & JWT \\
|
|
POST & /call/notify & Send FCM incoming call push & JWT \\
|
|
\end{longtable}
|
|
|
|
The full OpenAPI 3.0 specification is committed to \filepath{walkguide-backend/demo/src/main/resources/openapi.yaml} and rendered by Swagger UI at \code{/swagger-ui.html}.
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Flutter Implementation}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Key Features}
|
|
|
|
\subsection{WalkGuide --- On-Device AI Obstacle Detection}
|
|
|
|
The core feature of WalkGuide is real-time obstacle detection using YOLOv8n (nano variant) running entirely on-device via TensorFlow Lite. The inference pipeline is:
|
|
|
|
\begin{enumerate}
|
|
\item Camera stream delivers \code{CameraImage} frames in YUV420 format.
|
|
\item \code{YoloDetector.detect()} converts YUV to RGB, resizes to $640 \times 640$, normalizes to $[0.0, 1.0]$, and runs the TFLite interpreter.
|
|
\item Output tensor $[1, 84, 8400]$ is post-processed: 8400 anchor boxes $\times$ 84 values (4 coordinates + 80 COCO class probabilities).
|
|
\item Non-Maximum Suppression (NMS, IoU threshold 0.45) removes duplicate detections.
|
|
\item \code{ObstacleAnalyzer} computes direction (LEFT/CENTER/RIGHT from bounding box center-x) and distance estimate (Very Close / Close / Medium / Far from bounding box height ratio).
|
|
\item TTS announcement is generated: \textit{"Caution! Person ahead center. Very close. Please stop."}
|
|
\item Haptic pattern fires proportional to distance severity.
|
|
\item Obstacle is logged to the backend via \code{POST /user/obstacle} with a 3-second debounce per label.
|
|
\end{enumerate}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{YOLO Inference Configuration}
|
|
\label{tab:yolo}
|
|
\begin{tabular}{ll}
|
|
\toprule
|
|
\textbf{Parameter} & \textbf{Value} \\
|
|
\midrule
|
|
Model & YOLOv8n (nano) \\
|
|
Format & TensorFlow Lite Float32 \\
|
|
Input shape & $[1, 640, 640, 3]$ \\
|
|
Output shape & $[1, 84, 8400]$ \\
|
|
CPU threads & 4 \\
|
|
Delegate & NNAPI (Android AI accelerator) \\
|
|
Default confidence threshold & 0.5 (configurable by Guardian) \\
|
|
Default max inference FPS & 5 \\
|
|
Model size & $\approx$ 6 MB \\
|
|
Labels & 80 COCO classes \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Voice Command System}
|
|
|
|
The always-on STT listener (\code{SttService}) runs continuously while the app is in the foreground. Recognized text is passed to \code{VoiceCommandHandler}, which performs case-insensitive substring matching against the 14 configurable trigger phrases stored in the local voice command cache. Matched commands dispatch events to the appropriate BLoC or trigger GoRouter navigation.
|
|
|
|
Default trigger phrases include: \textit{"Start WalkGuide"}, \textit{"Send SOS"}, \textit{"Call Guardian"}, \textit{"Where Am I"}, \textit{"Read All My Notifications"}, and 9 others --- all configurable by the Guardian remotely.
|
|
|
|
\subsection{Guardian Dashboard}
|
|
|
|
The Guardian application provides a real-time monitoring interface:
|
|
\begin{itemize}
|
|
\item \textbf{Live Map:} OpenStreetMap tiles (no API key required) with a moving marker updated via STOMP WebSocket subscription (\code{/topic/location/\{userId\}}).
|
|
\item \textbf{AI Configuration:} Sliders for confidence threshold, alert distances, and max FPS; multi-select for enabled object labels.
|
|
\item \textbf{Geofence:} Tap-to-set center on the map with a configurable radius (50m--5000m); exit triggers an FCM push notification.
|
|
\item \textbf{Notifications:} Send text messages or voice notes to the User; voice notes are recorded using the \code{record} package and played on the User side via \code{just\_audio}.
|
|
\end{itemize}
|
|
|
|
\subsection{Advanced Features}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Advanced Features Implementation Status}
|
|
\label{tab:advanced}
|
|
\begin{tabularx}{\textwidth}{L{5cm} C{2cm} L{6cm}}
|
|
\toprule
|
|
\textbf{Feature} & \textbf{Status} & \textbf{Implementation} \\
|
|
\midrule
|
|
Real-time WebSocket & \done & STOMP via \code{stomp\_dart\_client}; live location + SOS + notifications \\
|
|
Push Notifications (FCM) & \textcolor{warnyellow}{\ding{115}} & Flutter side complete; backend log-only pending credentials \\
|
|
Offline-first with sync & \textcolor{warnyellow}{\ding{115}} & \code{OfflineQueueService} with \code{SharedPreferences} queue \\
|
|
Animated transitions & \done & \code{flutter\_animate} + custom \code{AnimatedContainer} for detection overlay \\
|
|
Internationalization & \textcolor{dangerred}{\ding{55}} & Dependency declared; \code{.arb} files not yet created \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{State Management}
|
|
|
|
The application uses flutter\_bloc (BLoC and Cubit) as the primary state management solution. Key BLoCs include \code{AuthBloc} (login/register/logout), \code{PairingBloc} (invite/respond/unpair), and \code{NotificationBloc} (load/read/TTS). Screen-level Cubits handle simpler local state (e.g., \code{SosCubit}, \code{AppCubit}). The global \code{AppCubit} tracks authentication state across route guards.
|
|
|
|
\section{Navigation (GoRouter)}
|
|
|
|
GoRouter is configured with redirect guards: unauthenticated users are redirected to \code{/server-connect} (if no server URL is saved) or \code{/login}; authenticated users are routed to \code{/user/home} or \code{/guardian/home} based on their role claim from the JWT.
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Spring Boot Implementation}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Security Configuration}
|
|
|
|
Spring Security is configured with stateless session management (no server-side sessions). JWT access tokens expire in 1 hour; refresh tokens expire in 30 days and are stored in the \code{refresh\_tokens} table. Role-based routing:
|
|
|
|
\begin{itemize}
|
|
\item \code{/api/v1/auth/**} --- \code{permitAll()} (public)
|
|
\item \code{/api/v1/guardian/**} --- \code{hasRole("GUARDIAN")}
|
|
\item \code{/api/v1/user/**} --- \code{hasRole("USER")}
|
|
\item \code{/api/v1/shared/**} --- \code{authenticated()} (either role)
|
|
\item \code{/ws/**} --- \code{permitAll()} (WebSocket handshake uses token in STOMP CONNECT frame)
|
|
\end{itemize}
|
|
|
|
\section{Database and Flyway}
|
|
|
|
The application connects to a PostgreSQL instance at the university server (\code{202.46.28.160:2002}). Flyway manages all schema changes; Hibernate is set to \code{ddl-auto=validate} to ensure the live schema matches entity definitions. Sixteen migration scripts (V1--V16) create all tables in dependency order.
|
|
|
|
\section{Key Service Implementations}
|
|
|
|
\subsection{PairingService}
|
|
|
|
When a Guardian accepts a pairing, \code{PairingService.respondToPairing()} performs an atomic sequence:
|
|
\begin{enumerate}
|
|
\item Update \code{PairingRelation} status to \code{ACTIVE}.
|
|
\item Seed 14 default \code{VoiceCommandConfig} records.
|
|
\item Seed 5 default \code{HardwareShortcut} records.
|
|
\item Create one \code{AiConfig} record with default thresholds.
|
|
\item Create one \code{GeofenceConfig} record (disabled by default).
|
|
\item Send FCM notification to the Guardian: "User accepted pairing request."
|
|
\end{enumerate}
|
|
|
|
\subsection{LocationService}
|
|
|
|
On each \code{POST /user/location} call, \code{LocationService}:
|
|
\begin{enumerate}
|
|
\item Saves a \code{LocationHistory} record.
|
|
\item Broadcasts the position via WebSocket to \code{/topic/location/\{userId\}}.
|
|
\item Checks \code{GeofenceConfig} if enabled, computing Haversine distance:
|
|
\end{enumerate}
|
|
|
|
\begin{equation}
|
|
d = 2r \cdot \arcsin\!\left(\sqrt{\sin^2\!\!\left(\frac{\Delta\phi}{2}\right) + \cos\phi_1\cos\phi_2\sin^2\!\!\left(\frac{\Delta\lambda}{2}\right)}\right)
|
|
\end{equation}
|
|
|
|
where $r = 6{,}371{,}000$ m (Earth radius), $\phi$ is latitude in radians, and $\lambda$ is longitude in radians. If $d > \text{radiusMeters}$, an FCM push is sent to the Guardian.
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Flutter Testing \& Benchmarking}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Unit Tests}
|
|
|
|
Unit tests are located in \filepath{walkguide-mobile/walkguide\_app/test/unit/}. All tests use the \code{flutter\_test} framework with Mockito for repository mocking.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Flutter Unit Test Coverage}
|
|
\label{tab:flutter-unit}
|
|
\begin{tabularx}{\textwidth}{L{5cm} L{8cm}}
|
|
\toprule
|
|
\textbf{Test File} & \textbf{Scenarios Covered} \\
|
|
\midrule
|
|
\code{login\_use\_case\_test.dart} & Successful login, wrong password, network failure \\
|
|
\code{register\_use\_case\_test.dart} & ROLE\_USER (generates uniqueUserId), ROLE\_GUARDIAN, duplicate email \\
|
|
\code{obstacle\_analyzer\_test.dart} & LEFT/CENTER/RIGHT direction from bounding box positions; Very Close/Close/Medium/Far distance ratios \\
|
|
\code{voice\_command\_handler\_test.dart} & Case-insensitive matching: "start walkguide", "Start WalkGuide", "START WALK GUIDE"; no false positives \\
|
|
\code{geofence\_calculation\_test.dart} & Haversine accuracy at known coordinates; boundary conditions at radius edge \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Widget Tests}
|
|
|
|
Widget tests in \filepath{test/widget/} verify that core UI components render correctly and dispatch the expected BLoC events.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Flutter Widget Test Coverage}
|
|
\label{tab:flutter-widget}
|
|
\begin{tabular}{ll}
|
|
\toprule
|
|
\textbf{Test File} & \textbf{Key Assertions} \\
|
|
\midrule
|
|
\code{login\_screen\_test.dart} & Form renders, submit button triggers \code{LoginRequested} event \\
|
|
\code{walk\_guide\_screen\_test.dart} & Camera preview widget renders, stop button visible \\
|
|
\code{notification\_screen\_test.dart} & Notification list renders, unread badge visible \\
|
|
\code{sos\_screen\_test.dart} & SOS button visible; tap dispatches \code{TriggerSos} event \\
|
|
\code{manual\_screen\_test.dart} & All 14 default voice commands displayed \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\section{Integration Tests}
|
|
|
|
Integration tests in \filepath{test/integration\_test/} exercise full end-to-end flows against the live Spring Boot backend.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Flutter Integration Test Flows}
|
|
\label{tab:flutter-integration}
|
|
\begin{tabularx}{\textwidth}{L{5cm} L{8cm}}
|
|
\toprule
|
|
\textbf{Test File} & \textbf{Flow Covered} \\
|
|
\midrule
|
|
\code{flow\_1\_login\_dashboard\_logout.dart} & Login with User credentials $\to$ dashboard loads $\to$ logout clears tokens \\
|
|
\code{flow\_2\_walkguide\_start\_stop\_sos.dart} & Start WalkGuide $\to$ receive detection state $\to$ stop WalkGuide $\to$ trigger SOS \\
|
|
\code{flow\_3\_notification\_read\_all.dart} & Guardian sends notification $\to$ User receives $\to$ mark all read $\to$ unread count = 0 \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Performance Benchmark}
|
|
|
|
\begin{tcolorbox}[warnbox, title={Note on Benchmark Evidence}]
|
|
Physical-device benchmarks (DevTools profile mode) must be executed on the target Android device after the \code{yolov8n.tflite} model is added to the assets. The table below documents the benchmark plan and target thresholds per exam requirements. Results are to be filled in after on-device runs and updated in the submitted report.
|
|
\end{tcolorbox}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Flutter Performance Benchmark Plan}
|
|
\label{tab:flutter-bench}
|
|
\begin{tabularx}{\textwidth}{L{3.5cm} L{3cm} R{2.5cm} C{2.5cm}}
|
|
\toprule
|
|
\textbf{Metric} & \textbf{Tool} & \textbf{Threshold} & \textbf{Result} \\
|
|
\midrule
|
|
Memory baseline & DevTools Memory & Report MB & TBD \\
|
|
Memory leak check & DevTools Memory & No steady growth & TBD \\
|
|
Frame rate / jank & DevTools Performance & $\geq$90\% frames $<$ 16 ms & TBD \\
|
|
CPU profile (YOLO inference) & DevTools CPU Profiler & Top 3 ops documented & TBD \\
|
|
API latency (client-side) & Dio interceptor logs & $<$ 1500 ms & TBD \\
|
|
Cold start time & \code{--trace-startup} & $<$ 3000 ms & TBD \\
|
|
APK size & \code{--analyze-size} & $<$ 50 MB & TBD \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Backend Testing \& Benchmarking}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Unit Tests (JUnit 5 + Mockito)}
|
|
|
|
Backend unit tests are in \filepath{src/test/java/com/walkguide/service/}. Each test class mocks all repository dependencies with Mockito.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Backend Unit Test Classes}
|
|
\label{tab:backend-unit}
|
|
\begin{tabularx}{\textwidth}{L{5cm} L{8cm}}
|
|
\toprule
|
|
\textbf{Test Class} & \textbf{Scenarios Covered} \\
|
|
\midrule
|
|
\code{AuthServiceTest} & Register (duplicate email), login (wrong password), refresh token (expired), logout \\
|
|
\code{PairingServiceTest} & Invite (already paired), accept (seed defaults), reject, unpair (cascade delete) \\
|
|
\code{NotificationServiceTest} & Send notification (unpaired guardian), mark read, unread count \\
|
|
\code{SosServiceTest} & Trigger SOS, acknowledge, invalid status transition \\
|
|
\code{LocationServiceTest} & Geofence Haversine distance accuracy, exit detection \\
|
|
\code{AiConfigServiceTest} & Update validation (confidence 0--1), negative distance rejected \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\section{Integration Tests (MockMvc + Testcontainers)}
|
|
|
|
Controller integration tests use \code{@SpringBootTest} with MockMvc and Testcontainers to spin up a real PostgreSQL instance. Flyway migrations run automatically, providing a clean database for each test class.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Backend Integration Test Classes}
|
|
\label{tab:backend-integration}
|
|
\begin{tabular}{ll}
|
|
\toprule
|
|
\textbf{Test Class} & \textbf{Key Assertions} \\
|
|
\midrule
|
|
\code{AuthControllerTest} & POST /register returns 201; POST /login returns 200 with tokens \\
|
|
\code{GuardianControllerTest} & GET /guardian/dashboard returns 403 if role is USER \\
|
|
\code{UserControllerTest} & POST /user/sos returns 201; GET /user/notifications returns paginated list \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\section{JaCoCo Code Coverage}
|
|
|
|
JaCoCo is configured with a minimum threshold of 70\% line coverage on the \code{service} and \code{controller} packages. The HTML coverage report is committed to \filepath{walkguide-backend/demo/target/site/jacoco/index.html} and generated via \code{mvn verify}.
|
|
|
|
\section{Load Benchmarking (k6)}
|
|
|
|
Load testing was performed using k6 with test scripts in \filepath{walkguide-backend/demo/k6-tests/}. Three test profiles were executed: smoke (1--3 VUs), load (30 VUs), and stress.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{k6 Load Test Results --- Auth Flow (30 VUs, Remote PostgreSQL)}
|
|
\label{tab:k6-auth}
|
|
\begin{tabular}{lrr}
|
|
\toprule
|
|
\textbf{Metric} & \textbf{Target} & \textbf{Observed} \\
|
|
\midrule
|
|
Total requests & --- & 1{,}431 \\
|
|
Request rate & $\geq$ 100 req/s & 7.45 req/s \\
|
|
Avg. latency (all endpoints) & $<$ 500 ms & 1{,}553 ms \\
|
|
p95 latency (auth endpoints) & $<$ 800 ms & 4{,}335 ms \\
|
|
p95 latency (all endpoints) & $<$ 500 ms & 4{,}335 ms \\
|
|
Error rate & $<$ 1\% & 0\% \\
|
|
Successful requests & --- & 125 / 1{,}431 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\begin{tcolorbox}[warnbox, title={Latency Explanation --- Remote PostgreSQL Bottleneck}]
|
|
The observed latency figures significantly exceed exam thresholds because the Spring Boot instance was running locally (localhost) while the PostgreSQL database is hosted on the university server at \code{202.46.28.160:2002}. Every database query incurs network round-trip latency of 500--3000 ms across the campus network. Under a co-located deployment (Spring Boot and PostgreSQL on the same server), latency would drop to the 50--200 ms range. This is a deployment infrastructure constraint, not a code performance issue. The error rate of 0\% demonstrates correct API behavior under load.
|
|
\end{tcolorbox}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{k6 Load Test Results --- Location Flow (Local Smoke, 3 VUs)}
|
|
\label{tab:k6-location}
|
|
\begin{tabular}{lrr}
|
|
\toprule
|
|
\textbf{Metric} & \textbf{Target} & \textbf{Observed} \\
|
|
\midrule
|
|
Request rate & $\geq$ 100 req/s & 0.58 req/s \\
|
|
Avg. latency & $<$ 500 ms & 4{,}456 ms \\
|
|
p95 latency & $<$ 500 ms & 21{,}586 ms \\
|
|
Error rate & $<$ 10\% & 0\% \\
|
|
Max VUs & 30 & 3 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{AI Model Benchmark Analysis}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
Per the lecturer's specific requirement, this chapter documents the AI inference benchmark plan for evaluating multiple YOLO model variants of varying sizes. The benchmark measures end-to-end latency from camera frame capture to TTS audio output.
|
|
|
|
\section{Benchmark Methodology}
|
|
|
|
The pipeline latency is decomposed into four measurable segments:
|
|
|
|
\begin{enumerate}
|
|
\item $t_{\text{capture}}$: Time to acquire and pre-process one camera frame (YUV420 $\to$ RGB $\to$ resize $640 \times 640$ $\to$ normalize).
|
|
\item $t_{\text{infer}}$: TFLite interpreter \code{run()} call duration.
|
|
\item $t_{\text{post}}$: NMS post-processing and \code{ObstacleAnalyzer} computation.
|
|
\item $t_{\text{tts}}$: TTS \code{speak()} call to first audio sample playback.
|
|
\end{enumerate}
|
|
|
|
\textbf{Total end-to-end latency:} $t_{\text{total}} = t_{\text{capture}} + t_{\text{infer}} + t_{\text{post}} + t_{\text{tts}}$
|
|
|
|
\section{Model Variants to Benchmark}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{YOLO Model Variants for Benchmarking}
|
|
\label{tab:models}
|
|
\begin{tabular}{lrrrr}
|
|
\toprule
|
|
\textbf{Model} & \textbf{Params} & \textbf{Size (MB)} & \textbf{mAP50} & \textbf{Target $t_{\text{infer}}$ (ms)} \\
|
|
\midrule
|
|
YOLOv8n (nano) & 3.2 M & $\approx$ 6 & 37.3 & $<$ 100 \\
|
|
YOLOv8s (small) & 11.2 M & $\approx$ 22 & 44.9 & $<$ 200 \\
|
|
YOLOv5n (nano) & 1.9 M & $\approx$ 4 & 28.0 & $<$ 80 \\
|
|
YOLOv5s (small) & 7.2 M & $\approx$ 14 & 37.4 & $<$ 150 \\
|
|
MobileNetV3-SSD & 2.9 M & $\approx$ 8 & 22.0 & $<$ 60 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\section{Benchmark Log Format}
|
|
|
|
All benchmark results are logged to a structured in-app log accessible from a hidden developer screen (\code{/dev/ai-benchmark}). Each log entry contains:
|
|
|
|
\begin{tcblisting}{codebox}
|
|
{
|
|
"timestamp": "2026-05-19T10:30:00.123Z",
|
|
"model": "yolov8n",
|
|
"frame_id": 1024,
|
|
"t_capture_ms": 12.4,
|
|
"t_infer_ms": 87.3,
|
|
"t_post_ms": 3.1,
|
|
"t_tts_ms": 42.7,
|
|
"t_total_ms": 145.5,
|
|
"detections": 2,
|
|
"top_label": "person",
|
|
"confidence": 0.82,
|
|
"device": "Xiaomi Redmi Note 12",
|
|
"cpu_cores": 8,
|
|
"ram_gb": 8
|
|
}
|
|
\end{tcblisting}
|
|
|
|
\section{Expected Results (To Be Filled After Physical Device Testing)}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{AI Benchmark Results Template (Physical Device)}
|
|
\label{tab:ai-bench-results}
|
|
\begin{tabular}{lrrrrrr}
|
|
\toprule
|
|
\textbf{Model} & $t_{\text{cap}}$ & $t_{\text{infer}}$ & $t_{\text{post}}$ & $t_{\text{tts}}$ & $t_{\text{total}}$ & \textbf{FPS} \\
|
|
\midrule
|
|
YOLOv8n & TBD & TBD & TBD & TBD & TBD & TBD \\
|
|
YOLOv8s & TBD & TBD & TBD & TBD & TBD & TBD \\
|
|
YOLOv5n & TBD & TBD & TBD & TBD & TBD & TBD \\
|
|
YOLOv5s & TBD & TBD & TBD & TBD & TBD & TBD \\
|
|
MobileNetV3 & TBD & TBD & TBD & TBD & TBD & TBD \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\textit{Note: All columns are in milliseconds. FPS = $1000 / t_{\text{total}}$.}
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Location History Timeline}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
Per the lecturer's requirement, WalkGuide implements a Google Maps Timeline-style location history view. This feature is accessible to the Guardian from the dashboard and groups location data by time segment, transport mode, and distance.
|
|
|
|
\section{Feature Design}
|
|
|
|
The timeline screen groups \code{LocationHistory} records into segments using the following heuristics:
|
|
|
|
\begin{itemize}
|
|
\item \textbf{Time gap $>$ 5 minutes:} New segment begins.
|
|
\item \textbf{Speed $<$ 1.5 m/s (5.4 km/h):} Classified as \textit{Walking}.
|
|
\item \textbf{Speed 1.5--5 m/s (5.4--18 km/h):} Classified as \textit{Cycling / Slow vehicle}.
|
|
\item \textbf{Speed $>$ 5 m/s (18 km/h):} Classified as \textit{Motorized vehicle (motorcycle/car)}.
|
|
\item \textbf{Speed = 0 for $>$ 3 minutes:} Classified as \textit{Stationary}.
|
|
\end{itemize}
|
|
|
|
Each segment displays:
|
|
\begin{enumerate}
|
|
\item Start time and end time (e.g., \textit{08:15 -- 08:42}).
|
|
\item Place name (reverse-geocoded from OSM Nominatim API).
|
|
\item Transport mode icon (walk, bike, motorcycle, car, stationary).
|
|
\item Total distance covered (sum of Haversine distances between consecutive points).
|
|
\item A mini polyline map showing the route.
|
|
\end{enumerate}
|
|
|
|
\section{API Support}
|
|
|
|
The existing \code{GET /guardian/location-history} endpoint (paginated, ordered by \code{created\_at DESC}) provides the raw data. The timeline grouping logic runs client-side in the Guardian Flutter app.
|
|
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
\chapter{Conclusion}
|
|
% ═══════════════════════════════════════════════════════════════════════════
|
|
|
|
\section{Achievements}
|
|
|
|
WalkGuide successfully demonstrates a complete, integrated mobile application system that addresses a genuine social need: safe, independent navigation for visually impaired individuals. The following key achievements were realized:
|
|
|
|
\begin{itemize}
|
|
\item A 26-endpoint Spring Boot REST API with JWT RBAC, Flyway migrations, WebSocket real-time communication, and comprehensive testing infrastructure.
|
|
\item A Flutter mobile application with on-device YOLOv8n obstacle detection, always-on voice command recognition, TTS feedback, guardian monitoring, SOS alerting, and VoIP calling --- all behind a dynamic server URL configuration that makes the APK deployable to any backend without recompilation.
|
|
\item Seven GoF design patterns implemented and documented across both codebases with full traceability to source files.
|
|
\item A guardian ecosystem that gives caregivers remote visibility and configurability: live map tracking, AI threshold tuning, geofencing, voice note delivery, and SOS acknowledgment.
|
|
\end{itemize}
|
|
|
|
\section{Design Lessons Learned}
|
|
|
|
\begin{enumerate}
|
|
\item \textbf{Observer (BLoC) scales better than StatefulWidget} for features with multiple consumers of the same state (e.g., notification badge count, pairing status). The screens that used StatefulWidget required more manual synchronization.
|
|
\item \textbf{Facade pattern pays dividends early:} Wrapping TTS, STT, and haptic APIs behind service facades from day one meant that screen code never needed to be updated when plugin APIs changed.
|
|
\item \textbf{Flyway migration order matters:} Foreign key constraints require strict creation order; planning V1--V16 upfront prevented migration failures caused by missing parent tables.
|
|
\item \textbf{Remote database latency is a first-class architectural concern:} The k6 results revealed that network latency between a local Spring Boot instance and the remote university PostgreSQL server is the dominant performance bottleneck. Co-locating the backend with the database would eliminate this.
|
|
\end{enumerate}
|
|
|
|
\section{Challenges}
|
|
|
|
\begin{itemize}
|
|
\item \textbf{TFLite model integration:} YUV420 $\to$ RGB conversion is not provided by any Flutter package for the \code{CameraImage} format; a custom pixel conversion loop was required.
|
|
\item \textbf{STT + TTS interaction:} The microphone and speaker compete for audio focus on Android. TTS had to be implemented with an interrupt-and-resume mechanism to prevent STT from hearing its own audio output.
|
|
\item \textbf{WebSocket authentication:} Spring Security does not natively protect STOMP WebSocket endpoints with JWT in the same way as REST. A custom handshake interceptor was required.
|
|
\end{itemize}
|
|
|
|
\section{Future Improvements}
|
|
|
|
\begin{itemize}
|
|
\item \textbf{Dual-camera depth estimation:} Using stereo camera data to compute actual metric distances to obstacles, replacing the bounding-box height heuristic.
|
|
\item \textbf{Full i18n:} Complete Bahasa Indonesia and English localization with \code{.arb} files.
|
|
\item \textbf{iOS support:} Requires a separate Firebase configuration and platform-specific audio session management.
|
|
\item \textbf{Custom YOLO model fine-tuning:} Training YOLOv8n on Indonesian urban obstacle datasets (ojek motorcycles, roadside vendors, irregular footpaths) to improve detection accuracy in local environments.
|
|
\item \textbf{Bluetooth accessibility device integration:} Support for dedicated tactile feedback wearables and screen reader integration.
|
|
\end{itemize}
|
|
|
|
% ─── References ────────────────────────────────────────────────────────────
|
|
\chapter*{References}
|
|
\addcontentsline{toc}{chapter}{References}
|
|
|
|
\begin{enumerate}[label={[\arabic*]}]
|
|
\item World Health Organization. (2023). \textit{Blindness and Vision Impairment}. WHO Fact Sheet. Retrieved from https://www.who.int/news-room/fact-sheets/detail/blindness-and-visual-impairment
|
|
|
|
\item Jocher, G., Chaurasia, A., \& Qiu, J. (2023). \textit{Ultralytics YOLO} (Version 8.0). Ultralytics. https://github.com/ultralytics/ultralytics
|
|
|
|
\item TensorFlow Authors. (2024). \textit{TensorFlow Lite for Mobile \& Edge Devices}. Google. https://www.tensorflow.org/lite
|
|
|
|
\item The Flutter Authors. (2024). \textit{Flutter SDK Documentation} (Version 3.x). Google. https://docs.flutter.dev
|
|
|
|
\item Spring Boot Authors. (2024). \textit{Spring Boot Reference Documentation} (Version 3.3.x). VMware. https://docs.spring.io/spring-boot/docs/current/reference/html/
|
|
|
|
\item Gamma, E., Helm, R., Johnson, R., \& Vlissides, J. (1994). \textit{Design Patterns: Elements of Reusable Object-Oriented Software}. Addison-Wesley Professional.
|
|
|
|
\item Martin, R. C. (2017). \textit{Clean Architecture: A Craftsman's Guide to Software Structure and Design}. Prentice Hall.
|
|
|
|
\item Fowler, M. (2002). \textit{Patterns of Enterprise Application Architecture}. Addison-Wesley Professional.
|
|
|
|
\item Agora.io. (2024). \textit{Agora RTC SDK for Flutter Documentation}. https://docs.agora.io/en/
|
|
|
|
\item Firebase Authors. (2024). \textit{Firebase Cloud Messaging Documentation}. Google. https://firebase.google.com/docs/cloud-messaging
|
|
|
|
\item OpenStreetMap Contributors. (2024). \textit{OpenStreetMap}. https://www.openstreetmap.org
|
|
|
|
\item k6. (2024). \textit{k6 --- Load Testing for Engineering Teams}. Grafana Labs. https://k6.io/docs/
|
|
\end{enumerate}
|
|
|
|
% ─── Appendix ──────────────────────────────────────────────────────────────
|
|
\appendix
|
|
\chapter{AI Tool Usage Disclosure}
|
|
|
|
In accordance with the academic integrity requirements of this examination, we disclose the following use of AI coding assistants:
|
|
|
|
\begin{itemize}
|
|
\item \textbf{Claude (Anthropic):} Used to assist with LaTeX report drafting (this document), review of architecture documentation, and generation of PlantUML diagram skeletons. All AI-generated content was reviewed, verified against the actual codebase, and corrected where necessary.
|
|
\item \textbf{GitHub Copilot:} Used during development for boilerplate code completion (DTO classes, repository method signatures). All suggestions were reviewed and integrated manually.
|
|
\end{itemize}
|
|
|
|
No AI tool was used to produce OOAD diagrams without human review. No AI tool was used to fabricate benchmark results.
|
|
|
|
\chapter{Deployment Configuration}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Environment Configuration Reference}
|
|
\label{tab:env}
|
|
\begin{tabularx}{\textwidth}{L{4cm} L{8.5cm}}
|
|
\toprule
|
|
\textbf{Variable} & \textbf{Description} \\
|
|
\midrule
|
|
\code{SPRING\_DATASOURCE\_URL} & \code{jdbc:postgresql://202.46.28.160:2002/uas\_5803024001} \\
|
|
\code{SPRING\_DATASOURCE\_USERNAME} & Provided by university lecturer \\
|
|
\code{SPRING\_DATASOURCE\_PASSWORD} & Provided by university lecturer (gitignored) \\
|
|
\code{JWT\_SECRET} & Random 256-bit base64 string (gitignored) \\
|
|
\code{AGORA\_APP\_ID} & Agora project App ID \\
|
|
\code{AGORA\_APP\_CERTIFICATE} & Agora project certificate (gitignored) \\
|
|
\code{FIREBASE\_ADMIN\_JSON} & Path to \code{google-services-admin.json} (gitignored) \\
|
|
\bottomrule
|
|
\end{tabularx}
|
|
\end{table}
|
|
|
|
\chapter{Voice Command Reference}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\caption{Default Voice Commands (14 Commands)}
|
|
\label{tab:voicecmds}
|
|
\begin{tabular}{ll}
|
|
\toprule
|
|
\textbf{Command Key} & \textbf{Default Trigger Phrase} \\
|
|
\midrule
|
|
\code{OPEN\_WALKGUIDE} & "Open Walkguide" \\
|
|
\code{START\_WALKGUIDE} & "Start Walkguide" \\
|
|
\code{STOP\_WALKGUIDE} & "Stop Walkguide" \\
|
|
\code{CALL\_GUARDIAN} & "Call Guardian" \\
|
|
\code{OPEN\_NOTIFICATION} & "Open Notifications" \\
|
|
\code{READ\_ALL\_NOTIF} & "Read All My Notifications" \\
|
|
\code{OPEN\_SOS} & "Open SOS" \\
|
|
\code{SEND\_SOS} & "Send SOS" \\
|
|
\code{WHERE\_AM\_I} & "Where Am I" \\
|
|
\code{OPEN\_ACTIVITY} & "Open Activity Log" \\
|
|
\code{OPEN\_NAVIGATION} & "Open Navigation" \\
|
|
\code{OPEN\_SETTINGS} & "Open Settings" \\
|
|
\code{REPEAT\_LAST} & "Repeat" \\
|
|
\code{STOP\_TTS} & "Stop" \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
All trigger phrases are configurable remotely by the Guardian via the Guardian Voice Command Configuration screen.
|
|
|
|
\end{document} |