\documentclass[12pt]{article}

% refer to configurations.tex for the LaTeX setup of this template
\input{configurations.tex}

% Optional user settings
\setboolean{showinstructions}{true} % set to false to hide instructions
\setboolean{showexamples}{true} % set to false to hide examples
\setboolean{showexplanations}{true} % set to false to hide explanations
\setcounter{tocdepth}{4}
\begin{document}
\maketitlepage
\tableofcontents
\listoffigures
\listoftables
\newpage
\section{Abstract}
\enquote{Is switching from a gasoline engine to an electric or hybrid vehicle worth it?} 
The decision involves multiple factors: while fuel prices are high, electric vehicles also come with significant upfront costs, raising questions about cost-effectiveness and environmental impact. \\

Consumers and researchers alike need accessible tools to evaluate such factors in the context of sustainability. As the transportation sector embraces eco-friendly vehicles, the demand grows for user-centered tools that clarify energy consumption data for both industry experts and general users.  \\

This interdisciplinary project responds to this need by creating a web-based application that integrates the Virginia Tech Transportation Institute (VTTI) models for vehicle energy consumption within a graphical user interface. By making these sophisticated models accessible, the platform empowers both researchers and non-expert users to make data-driven decisions on vehicle energy efficiency and environmental impact. \\

Past studies, such as those by Madziel and Campisi, highlight the impact of variables like temperature, vehicle load, and driving style on electric vehicle (EV) energy usage \cite{Madziel2023}. Our platform provides an intuitive interface, enabling users to upload speed data, select a vehicle type, and view real-time energy analytics through interactive charts. \\

The system includes support for:
\begin{itemize}
    \item Internal Combustion Engine Vehicles  \textbf{(ICEV)}
    \item Battery Electric Vehicles \textbf{(BEV)}
    \item Hybrid Electric Vehicles \textbf{(HEV)}
    \item Hydrogen Fuel Cell Vehicles \textbf{(HFCV)}
\end{itemize}

Built using React and Python Flask, the site includes data upload, calculation results, and visualization features for all user levels. By bridging complex analytics with user-friendly design, this platform supports informed, data-driven decisions in sustainable transportation.

\subsection{Keywords}
\textbf{electric vehicles; energy consumption analysis; sustainability; web-based analytics; vehicle energy modeling; user interface design; React; Flask} \newpage

\section{Introduction}

Electric and hybrid vehicles (EVs) are increasingly viewed as key solutions to reducing emissions and oil dependency in the automotive industry. However, the complexity of predicting energy consumption across varying driving conditions remains a significant challenge for the widespread adoption of EVs, as factors like ambient temperature, road topography, and driving behavior impact energy use and efficiency. Existing studies, such as those by Skuza and Jurecki, demonstrate that variables such as vehicle load and wind resistance directly influence energy consumption rates, impacting the perceived usability of EVs due to “range anxiety” concerns among drivers \cite{Skuza_2022}.  \\

This project integrates VTTI’s energy consumption models into a web platform that allows users to upload speed data, select vehicle type, and receive accurate and immediate energy consumption insights. By democratizing access to these models, our platform facilitates greater understanding and comparison of energy use across vehicle types. Allowing general users and researches to make more informed decisions regarding energy-efficient transportation. \\





\begin{table}[h!]
\centering
\setlength{\tabcolsep}{8pt} % Adjust column padding
\renewcommand{\arraystretch}{1.5} % Adjust row spacing for better readability
\begin{methodbox}{\subsection{Project Team}}
\begin{tabular}{|p{0.3\textwidth}|p{0.65\textwidth}|}
\hline
\textbf{Student} & \textbf{Role} \\ \hline
Courtney Quinn & Backend Lead, Group Leader \\ \hline
Rohin Batra & Backend Support \\ \hline
Eric Tapia & Backend Support \\ \hline
Layla Scott & Frontend Lead \\ \hline
Christina Chao & Frontend Support, Meeting Minutes \\ \hline
\end{tabular}
\end{methodbox}
\caption{Roles and Responsibilities of Students}
\label{tab:students_roles}
\end{table}




\subsection{Project Motivation} 


Research being done on electric and hybrid vehicles generates the need for accessible tools to analyze factors influencing energy consumption. According to Wang et al., countless variables impact energy efficiency, such as driving behavior, road topography, and climate conditions—representing only a fraction of the full range \cite{Wang2015}. Condensing and visualizing these variables in a comprehensive tool would greatly benefit researchers. \\

Additionally, user-friendly tools play a crucial role in providing public education, which can help create trust in technology that without can be a major barrier to EV adoption \cite{KRISHNA2021100364}. Our project addresses the need of user-friendly tools in the transportation sector by integrating Virginia Tech Transportation Institute’s (VTTI) energy models into a web-based application, enabling users to assess energy consumption across various vehicle types. \\

This platform supports sustainable transportation practices and broadens understanding of energy efficiency, aiding policy and industry shifts toward eco-friendly mobility. By making VTTI’s models accessible in a user-friendly format, we provide a tool that allows users to upload vehicle data, select vehicle types, and view consumption analytics, promoting informed, data-driven decisions in the transportation sector. \\

\subsection{Problem Statement} \label{sec:intro}
Our primary challenge was to transform VTTI’s energy calculation code—originally limited to a command-line interface—into a user-friendly, web-based tool. Although the code accurately calculates energy usage, its reliance on a terminal limits accessibility for users without programming expertise. \\

The code enables calculations for four vehicle types: 
\begin{methodbox}{Engines}
    \begin{itemize} \item Internal Combustion Engine Vehicles (ICEV) \item Battery Electric Vehicles (BEV) \item Hybrid Electric Vehicles (HEV) \item Hydrogen Fuel Cell Vehicles (HFCV) \end{itemize} 
\end{methodbox}
    



To broaden its usability, we created a web interface that allows users to upload data and view results without technical knowledge, making energy calculations accessible to a diverse audience, from researchers to automotive developers. \\

\subsection{Approach}
\label{sec:intro:approach}

Our approach to developing an accessible, web-based tool for energy consumption analysis in different vehicles centered on user accessibility, accuracy, and scalability.\\

The objective was to make VTTI’s energy calculation models, previously accessible only via a command-line interface, available to a wider audience through a user-friendly web application.
We adopted a strategy focused on:
\begin{itemize}
    \item \textbf{Usability}: Ensuring non-experts can navigate the tool intuitively. The focus was on designing a user interface that adheres to VT’s brand standards while aligning with broader industry UI best practices.
   \item \textbf{Accuracy}: Maintaining the integrity of the original energy calculations by utilizing them to their full capacity without modification.
    \item \textbf{Scalability}: Designing with the potential for future feature expansion and broader data handling in mind. 
\end{itemize}


\subsection{High-Level Methodology}

We transformed the command-line-based code into backend functions that could be accessed through API endpoints, seamlessly integrating with the frontend. To achieve this, we developed endpoints to receive user inputs and pass them to the original methods, making minor adjustments to the parameters in the existing code. Specifically, we removed hardcoded vehicle parameters, enabling dynamic input via file uploads from the frontend. This approach allowed us to send custom data to the Python code while preserving its core functionality. \\

The system design emphasizes a clear separation between the frontend and backend. The backend, implemented using Python Flask, processes API requests, validates input data, and returns energy consumption results. Meanwhile, the frontend, built with React, delivers a user-friendly and interactive interface for tasks such as data upload, vehicle selection, and data visualization. Visualizations were primarily created using Chart.js, complemented by additional React components styled with CSS. This modular and adaptable architecture not only enhances usability but also ensures scalability, enabling further development and integration of new features in the future.

\section{Requirements}

Building a web interface for vehicle energy calculations requires careful consideration of both user needs and technical requirements. The system must maintain calculation accuracy while providing an intuitive interface that doesn't require programming knowledge. Our requirements gathering process involved discussions with VTTI researchers, analysis of the existing codebase, and consideration of target user groups.

\subsection{User Requirements} 

The system is designed to accommodate two main user profiles, an admin user and non-admin users. The non-admin users can be described by three primary user groups—researchers, industry professionals, and students—each with specific expectations and goals for the tool.

\subsubsection{Admin User Needs}

Admin users require a comprehensive level of access to manage and maintain the tool effectively. They need the ability to view all user collections, which provides oversight of the data being analyzed and shared within the system. Additionally, admins must be able to view, edit, and upload vehicle parameters, ensuring that calculation models remain accurate and up-to-date for all users. Like other user groups, admins can create their own collections for analysis and research, but with added privileges to oversee and modify core system settings and parameters.

Admin user functionality includes: \begin{itemize} \item View all user collections \item View, edit, and upload vehicle parameters \item Create their own collections (same as other users) \end{itemize}


\subsubsection{Researcher Needs}
Researchers, have an expert understanding of speed profiles, vehicle characteristics, and the transportation industry. They develop algorithms and profiles to analyze energy consumption.While some researchers may have programming skills, others may not, so providing a graphical user interface (GUI) ensures that everyone can access, display, and retrieve their data effectively. 

Main functionality to cater towards researchers:
\begin{itemize}
    \item Upload speed profiles in CSV or TXT format
    \item Select from four vehicle types (ICEV, BEV, HEV, HFCV)
    \item View energy consumption calculations
    \item Download calculation results
\end{itemize}

\subsubsection{Industry Professional Needs}
Industry professionals seek a streamlined tool that provides reliable energy consumption estimations for different vehicle types. This group is particularly interested in the visualization of results, as graphical representations aid in decision-making processes and reports. Furthermore, they need the ability to export these visualized data outputs to facilitate in-depth analysis outside the web application.

Consdierations for Industry Professionals:
\begin{itemize}
    \item Energy consumption estimations
    \item Visualization of results
    \item Export data for analysis
\end{itemize}

\subsubsection{Student Needs}

Finally, students, who are likely to use this tool in a more exploratory or educational context, benefit from an interface that simplifies vehicle energy calculations. They should be able to access and compare calculation results for various vehicle types easily, enabling them to gain insights relevant to their coursework and research assignments.

Student users will need: 
\begin{itemize}
    \item Simple interface for vehicle energy calculations
    \item Access to calculation results for coursework
    \item Ability to compare different vehicle types
\end{itemize}

The primary users of this system fall into three categories: researchers, industry professionals, and students. Each group has specific needs:

\subsection{Technical Requirements}
\label{sec:requirements:sec2}
To ensure that the system operates reliably, specific technical criteria have been established. The application requires \textbf{Python version 3.7 or higher} (preferably 3.8 or 3.9) to run the backend as well as \textbf{Node.js} (version 14 or higher) and npm for the front end. 

\subsubsection{Performance Requirements}
Our system is working with very large data files


The system must also meet several performance requirements. It needs to effectively process speed profile data provided in CSV or TXT formats, executing calculations with consistency and accuracy. Furthermore, it is essential for the web-based results to match those of the original terminal-based calculations, ensuring reliability and familiarity for existing users. Given that the application is designed primarily for single-user calculations, it must also manage its resources efficiently to maintain performance.
\begin{itemize}
    \item Process CSV and TXT files from speed profile data
    \item Complete calculations consistently
    \item Match results from original terminal-based code
    \item Handle single user calculations effectively
\end{itemize}


\subsubsection{Security Requirements}
Security requirements include basic file upload validation to safeguard against malicious files, as well as a user login system that restricts access to authorized users. Administrative controls should be in place to enable access restriction, ensuring that certain functionalities are only available to users with specific permissions.
\begin{itemize}
    \item Basic file upload validation
    \item User login system
    \item Admin access controls
\end{itemize}

\subsection{Functional Requirements}
\label{sec:requirements:sec3}

The system must provide specific functionalities:

\subsubsection{Core Features}
\begin{itemize}
    \item File Upload System
    \begin{itemize}
        \item Accept CSV and TXT formats
        \item Basic file validation
        \item Error feedback for users
    \end{itemize}
    
    \item Calculation Engine
    \begin{itemize}
        \item Implement vehicle type calculations
        \item Use VTTI's calculation models
        \item Show calculation results
    \end{itemize}
    
    \item Data Visualization
    \begin{itemize}
        \item Display calculation results
        \item Show basic data charts
    \end{itemize}
\end{itemize}

\subsubsection{Administrative Features}
\begin{itemize}
    \item Vehicle Parameters
    \begin{itemize}
        \item View vehicle parameters
        \item Update calculation values
    \end{itemize}
    
    \item User Management
    \begin{itemize}
        \item Basic user account management
        \item Admin access control
    \end{itemize}
\end{itemize}

\subsection{Conclusion}
\label{sec:requirements:conclusion}

These requirements ensure our web application successfully transforms the terminal-based calculation code into an accessible tool. The focus on user experience, combined with basic technical specifications, creates a system that serves both technical and non-technical users.

Key considerations maintained throughout the requirements:
\begin{itemize}
    \item Accessibility for non-programmers
    \item Basic calculation functionality
    \item Simple user interface
    \item File upload capabilities
    \item User authentication
\end{itemize}

These requirements guide our design and implementation decisions, ensuring the final product meets VTTI's needs for a web-based vehicle energy calculation tool.


\section{Design}


The Vehicle Energy Estimation Web Application transforms VTTI's terminal-based calculations into an accessible web interface. Our design focuses on creating a user-friendly system while maintaining calculation accuracy.
\subsection{System Architecture}

The overall system architecture follows a client-server model:

\begin{figure}[htb]
    \includegraphics[width=\textwidth]{gfx/system_architecture.png}
    \caption{System Architecture}
    \label{fig:system:architecture}
\end{figure}

The architecture consists of:
\begin{itemize}
    \item User Interface: File upload and result display
    \item Frontend: JS React-based component system
    \item Backend: Flask handles all the api generation and calls to backend Python calculations
    \item Database: SQLite storage system
\end{itemize}
\newpage

\subsection{Frontend Architecture}
\label{sec:design:sec1}

The React-based frontend follows a component hierarchy that manages user flow and authentication:

\begin{figure}[htb]
    \includegraphics[width=\textwidth]{gfx/frontend.jpeg}
    \caption{Frontend Component Structure}
    \label{fig:design:frontend}
\end{figure}

Key components include:
\begin{itemize}
    \item AuthProvider: Manages user authentication state
    \item Routes: Handles navigation and protected routes
    \item Welcome Page: Entry point for users
    \item Collections: Manages speed profile uploads and results
    \item Admin: Creates another user type with more advanced DB roles
\end{itemize}

\subsection{Database Design}
\label{sec:design:sec2}

The database schema supports user management and calculation storage:

\begin{figure}[htb]
    \includegraphics[width=\textwidth]{gfx/db-schema.pdf}
    \caption{Database Schema}
    \label{fig:system:database}
\end{figure}
\newpage

The schema includes four main tables:
\begin{itemize}
    \item users: Stores user authentication information
    \item vehicle\_types: Manages available vehicle types
    \item vehicle\_params: Stores calculation parameters
    \item user\_collections: Records calculation collections and results
\end{itemize}

Each table serves a specific purpose:
\begin{itemize}
    \item users: Username, password, and admin status
    \item vehicle\_types: Vehicle type definitions
    \item vehicle\_params: Calculation parameters for each vehicle type
    \item user\_collections: Speed profiles and calculation results
\end{itemize}

\subsection{Backend Design}
The backend is implemented using Flask and follows a standard structure with a single \texttt{app.py} file as the entry point. Flask provides a lightweight and modular framework for building web applications. \\

For developers unfamiliar with Flask, a recommended resource is the official Flask documentation, available at \url{https://flask.palletsprojects.com/en/stable/tutorial/layout/}. This tutorial provides a step-by-step guide to setting up a Flask application, defining functions, and establishing database connections. Following their instructions ensures proper implementation and adherence to Flask's best practices.


\subsection{Design Decisions}
\label{sec:design:conclusion}

Our design choices were guided by the need for maintainability, scalability, and efficiency. Key priorities included:
\begin{itemize}
    \item A component-based frontend architecture to ensure maintainability and scalability.
    \item A clear separation between the frontend and backend for modularity and ease of updates.
    \item A relational database structure to manage data efficiently and securely.
\end{itemize}

The frontend component structure was designed to support:
\begin{itemize}
    \item \textbf{Protected Routes:} Ensuring that certain pages are accessible only to authenticated users.
    \item \textbf{Consistent Navigation Flow:} Providing a user-friendly and intuitive interface.
    \item \textbf{Centralized State Management:} Streamlining data handling across the application.
    \item \textbf{Reusable UI Components:} Reducing development time and maintaining consistency in the user interface.
\end{itemize}

The database design enables:
\begin{itemize}
    \item \textbf{Efficient Data Relationships:} Optimizing queries and reducing redundancy.
    \item \textbf{Secure User Data Storage:} Safeguarding sensitive user information.
    \item \textbf{Flexible Parameter Management:} Allowing dynamic updates and scalability for future changes.
    \item \textbf{Session History Tracking:} Recording user activity for improved analytics and traceability.
\end{itemize}

This architecture effectively transitions VTTI's terminal-based calculations into a web-accessible platform, ensuring data integrity, user accessibility, and calculation accuracy while aligning with modern web development standards.



\section{Implementation}

\subsection{Frontend Development}
The frontend of our system is implemented using React JS. React's component-based architecture allows for the creation of reusable UI elements, which significantly enhances the maintainability and scalability of the application. This modular approach ensures that the interface is intuitive and adaptable to the needs of diverse users.\\

React is particularly well-suited for developing single-page applications (SPAs). While SPAs may experience a slower initial load time, they provide faster updates and subsequent responses, offering a smooth and responsive user experience.\\


\subsubsection{Key Frontend Features}

The frontend includes several essential features designed to enhance usability and functionality:

\begin{itemize}
    \item \textbf{User Authentication System}: Connects to server-side secure login and signup functionality, ensuring that only authorized users can access or manage web-pages with sensitive data.
    \item \textbf{File Upload Interface}: Allows users to upload speed and data files. This interface is intuitive, guiding users through the process and validating inputs to prevent errors.
    \item \textbf{Results Visualization}: Displays energy consumption results in the form of interactive charts, providing clear insights into vehicle performance. This visualization helps users quickly interpret data without needing advanced technical knowledge.
    \item \textbf{Vehicle Type Selection}: Enables users to select the type of vehicle they are analyzing. The selection dynamically adjusts calculations based on vehicle specifications, enhancing accuracy and user engagement.
    \item \textbf{Admin Controls}: The admin interface provides controls for managing user accounts, modifying vehicle profiles, and accessing application settings. These controls allow administrators to maintain the system and support a broader user base.
\end{itemize}

\subsubsection{Component Hierarchy and Architecture}


The component hierarchy in our React application follows a logical and intuitive structure, which helps keep the code organized and maintainable. The structure is designed to separate concerns and facilitate the development of specific functionality within each component. Key components are nested to reflect their relationships and dependencies. \\

Additionally, \hyperref[fig:design:frontend]{Figure~\ref*{fig:design:frontend}} provides a more in-depth view of the component structure, while \hyperref[fig:React Components Hierarchy and Architecture]{Figure~\ref*{fig:React Components Hierarchy and Architecture}} offers a high-level overview of the main components and their interactions.


\begin{figure}[ht]
    \centering
    \includegraphics[width=\textwidth]{gfx/react-component-arch.pdf} % fits to text width
    \caption{React Components Hierarchy and Architecture}
    \label{fig:React Components Hierarchy and Architecture}
\end{figure}
\newpage
This hierarchy demonstrates how the components are organized and interact with each other.



\subsection{Backend Development}
\label{sec:implementation:sec2}



\subsubsection{Libraries}
\begin{itemize}
    \item \texttt{Flask} for API and cross-origin resource sharing. 
   \item \texttt{werkzeug}: Provides secure password hashing and authentication utilities.
    \item \texttt{sqlite3} for lightweight database management. 
    \item \texttt{dotenv} for environment variable configuration. 
\end{itemize}

The Flask backend handles all calculations and data management. Main components include:

\subsection{API Endpoints}
The frontend communicates with the backend through a set of API endpoints, which provide functionality for authentication, data management, and energy estimation. Below is a summary of the available endpoints:

\begin{itemize}
    \item \textbf{Authentication Endpoints}:
    \begin{itemize}
        \item \texttt{POST /api/signup}:
        \begin{itemize}
            \item Registers a new user.
            \item Required Parameters: \texttt{username}, \texttt{password}.
            \item Response: JSON with success message or error.
        \end{itemize}
        \item \texttt{POST /api/login}:
        \begin{itemize}
            \item Authenticates a user.
            \item Required Parameters: \texttt{username}, \texttt{password}.
            \item Response: JSON indicating login success, user role, or error.
        \end{itemize}
    \end{itemize}
    
    \item \textbf{Vehicle Management Endpoints}:
    \begin{itemize}
        \item \texttt{GET /api/vehicle-types}:
        \begin{itemize}
            \item Retrieves all available vehicle types.
            \item Response: JSON list of vehicle types.
        \end{itemize}
        \item \texttt{POST /api/admin/vehicle-types} (Admin Only):
        \begin{itemize}
            \item Adds a new vehicle type.
            \item Required Parameters: \texttt{type\_name}, \texttt{full\_name}, \texttt{engine\_id}.
            \item Response: JSON with success message or error.
        \end{itemize}
        \item \texttt{DELETE /api/admin/vehicle-types/<type\_id>} (Admin Only):
        \begin{itemize}
            \item Deletes a vehicle type.
            \item Response: JSON with success message or error.
        \end{itemize}
    \end{itemize}
    
    \item \textbf{Energy Estimation Endpoints}:
    \begin{itemize}
        \item \texttt{POST /api/estimate}:
        \begin{itemize}
            \item Estimates energy consumption based on speed profile and vehicle type.
            \item Required Parameters: Speed profile file, \texttt{username}, \texttt{vehicle\_type\_id}, \texttt{collection\_id}.
            \item Response: JSON with energy estimation results.
        \end{itemize}
    \end{itemize}

    \item \textbf{Collections Endpoints}:
    \begin{itemize}
        \item \texttt{POST /api/collections}:
        \begin{itemize}
            \item Creates a new collection.
            \item Required Parameters: Speed profile file, \texttt{username}, \texttt{name}.
            \item Response: JSON with collection ID or error.
        \end{itemize}
        \item \texttt{GET /api/collections/<username>}:
        \begin{itemize}
            \item Retrieves all collections for a user.
            \item Response: JSON list of collections.
        \end{itemize}
        \item \texttt{DELETE /api/collections/<collection\_id>}:
        \begin{itemize}
            \item Deletes a specific collection.
            \item Required Parameter: \texttt{username}.
            \item Response: JSON with success message or error.
        \end{itemize}
    \end{itemize}
\end{itemize}

Refer to the source code (\texttt{automated\_vehicles\_fuel\_energy\_estimation/app.py})  for full details on the logic and parameter validation for each endpoint.



\subsection{Energy Calculation Integration}
\label{sec:implementation:sec3}

We integrated VTTI's terminal-based calculations into our web system. The process works as follows:

\begin{enumerate}
    \item User uploads speed profile file
    \item System validates file format and content
    \item Backend processes data through calculation engines
    \item Results are stored in database
    \item Frontend displays formatted results
\end{enumerate}

Calculations can be found at
\texttt{automated\_vehicles\_fuel\_energy\_estimation/getEnergy.py} in the repository
\begin{methodbox}{Example Calculation}
 \begin{minted}{python}
def calculate_total_fuel_ICEV(v, Alpha_0, Alpha_1, Alpha_2, Power_kW):
    MODEL1 = np.maximum(Alpha_0 + Alpha_1 * Power_kW 
                       + Alpha_2 * Power_kW**2, Alpha_0)
    total_fuel = np.sum(MODEL1)
    distance_m = np.sum(v)
    return {
        'total_fuel_liters': total_fuel,
        'distance': distance_m
    }
    \end{minted}
\end{methodbox}

\section{Testing/Evaluation/Assessment}

Testing for the Vehicle Energy Estimation Web Application focused on ensuring the accuracy of backend functionality, user authentication, and system operations. Due to time constraints during this semester-long project, we opted for manual testing and debugging rather than implementing unit tests, particularly for the frontend.

\subsection{Frontend Testing}
\label{sec:testing:frontend}

The frontend was primarily tested through direct interaction with the graphical user interface (GUI) and the browser's developer tools (e.g., Inspect Element). While this method allowed us to identify and resolve most issues, no formal unit tests or test-driven development (TDD) practices were implemented.  \\

We acknowledge that formal unit tests for React components would improve reliability and maintainability. However, the trade-off was to allocate time for debugging and iterative development instead. Future iterations of the project should prioritize implementing unit tests for key components to ensure consistency and catch regressions efficiently.

\subsection{Backend Testing}
\label{sec:testing:backend}

The backend was thoroughly tested using \texttt{curl} commands to validate the functionality of all API endpoints. \texttt{curl} commands can be executed directly from your terminal. Our chosen IDE, Visual Studio Code (VS Code), provided an integrated terminal that was utilized for testing. Below is an outline of the testing methodology:

\subsubsection{Testing Steps}
\begin{enumerate}
    \item Start with a fresh database:
    \begin{minted}{bash}
    rm energy_estimation.db
    python app.py
    \end{minted}
    \item Verify the home route:
    \begin{minted}{bash}
    curl http://localhost:5000/
    \end{minted}
    \item Test user registration and authentication:
    \begin{minted}{bash}
    curl -X POST http://localhost:5000/api/signup \
    -H "Content-Type: application/json" \
    -d '{"username":"testuser", "password":"testpass"}'

    curl -X POST http://localhost:5000/api/login \
    -H "Content-Type: application/json" \
    -d '{"username":"testuser", "password":"testpass"}'
    \end{minted}
    \item Validate core API functionality:
    \begin{itemize}
        \item Retrieve vehicle types:
        \begin{minted}{bash}
        curl http://localhost:5000/api/vehicle-types
        \end{minted}
        \item Upload vehicle parameters:
        \begin{minted}[breaklines]{bash}
        curl -X POST http://localhost:5000/api/admin/upload-vehicle-params \
        -F "file=@veh_parameters.txt" \
        -u admin:1234
        \end{minted}
        \item Test energy estimation for all vehicle types:
        \begin{minted}{bash}
        curl -X POST http://localhost:5000/api/estimate \
        -F "file=@speed_profile.txt" \
        -F "username=testuser" \
        -F "vehicle_type_id=1" # ICEV
        \end{minted}
        \textit{(Repeat for other types: BEV, HEV, HFCV)}
    \end{itemize}
    \item Test error handling:
    \begin{minted}[breaklines]{bash}
    # Missing parameter file
    curl -X POST http://localhost:5000/api/admin/upload-vehicle-params \
    -u admin:1234

    # Invalid vehicle type
    curl -X POST http://localhost:5000/api/estimate \
    -F "file=@speed_profile.txt" \
    -F "username=testuser" \
    -F "vehicle_type_id=999"
    \end{minted}
\end{enumerate}

\subsubsection{Results}
\begin{itemize}
    \item All core endpoints functioned as expected, including user authentication, vehicle parameter uploads, and energy estimation.
    \item Error handling worked for missing files, invalid inputs, and unauthorized actions.
\end{itemize}

\subsection{Database Testing}
While we did not implement explicit tests for SQL operations, database functionality was implicitly verified during backend testing. Observed behaviors include:
\begin{itemize}
    \item Proper storage and retrieval of user and session data.
    \item Accurate logging of calculation results.
    \item Secure access controls for admin operations.
\end{itemize}

Future work should include automated tests for database transactions to ensure consistency and prevent potential edge-case failures.

\subsection{Future Improvements}
\label{sec:testing:future}

We identified several areas for improvement based on our testing experience:

\subsubsection{Short-Term Improvements}
\begin{itemize}
    \item Implement frontend unit tests for React components.
    \item Automate backend tests using a framework like Pytest.
    \item Enhance error messages for better user feedback.
\end{itemize}

\subsubsection{Long-Term Considerations}
\begin{itemize}
    \item Integrate TDD practices to improve development efficiency and reliability.
    \item Expand test coverage for SQL queries and database interactions.
    \item Optimize performance for large datasets.
\end{itemize}

\subsubsection{Summary of Results}
\label{sec:testing:summary}
\begin{table}[h!]
\begin{center}
\begin{tabular}{|l|c|c|}
\hline
\textbf{Feature} & \textbf{Status} & \textbf{Notes} \\
\hline
Frontend & Tested & GUI-tested, no unit tests \\
\hline
Backend & Passed & All endpoints verified \\
\hline
Database & Verified & Basic operations functional \\
\hline
\end{tabular}
\end{center}
\caption{Testing Summary}
\end{table}

Despite the absence of formal unit tests, our testing confirmed the core functionality of the application, laying a solid foundation for future enhancements.


\newpage
\section{User Manual}

This manual guides users through the Vehicle Energy Estimation Web Application. This system allows you to analyze energy consumption for different vehicle types by uploading speed profile data.

\subsection{Getting Started}

\subsubsection{Welcome Page}
\begin{enumerate}
    \item Open \url{http://tml.cs.vt.edu:5000/}
 in your web browser.
    \item Click the \textbf{"Sign Up"} button if you’re a new user. 
    \item Or the \textbf{"Login"} button if you are a returning user.
\end{enumerate}

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/welcome.png}
    \caption{Welcome or Landing Page}
    \label{fig:signup}
\end{figure} 

\subsubsection{Signing Up}
\begin{figure}[h!]
    \centering
   \includegraphics[width=\textwidth]{gfx/signup.png}
    \caption{Account Registration form for new users.}
    \label{fig:registration}
\end{figure}
\begin{enumerate}
    \item Complete the registration form by entering a username and password.
    \item Click the orange \textbf{"Sign-Up"} button and your new login information will be created.
\end{enumerate} 
\subsubsection{Login}
\begin{enumerate}
    \item Returning users should enter their prior username and password
    \item Click the maroon \textbf{"Log In"} button to proceed
\end{enumerate}
\vspace{-5mm}
\begin{figure}[h!]
    \centering
   \includegraphics[width=\textwidth]{gfx/login.png}
    \caption{Login Form}
    \label{fig:registration}
\end{figure} \newpage

\subsection{Collection Dashboard}
After logging in, you will see the main dashboard, which is the User Collections. These collections provide a way to store like data in one central area. Note: new users will not have any collections, proceed to \hyperref[sec:go]{7.2.1} to get started.
\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/collections.png}
    \caption{User Collections Page}
    \label{fig:main-interface}
\end{figure}
\subsubsection{Create a Collection} \label{sec:go}

\begin{enumerate}
    \item Click the maroon \textbf{"Create Collection"} button to get started.

    \begin{figure}[h!]
        \centering
        \includegraphics[width=\textwidth]{gfx/create-collection.png}
        \caption{User collections page with no collections}
        \label{fig:create-collection-page}
    \end{figure} \newpage

    \item  A form will appear where you can define your collection.

    \begin{itemize}
    \item \textbf{Required Fields:}
    \begin{itemize}
        \item \textbf{Collection Name:} Give your collection a descriptive name.
        \item \textbf{Speed Profile:} Specify the speed profile for your collection.
        \begin{tcolorbox}[colback=gray!10, colframe=gray!80, title={Example File Formats}]
            You must upload either a \texttt{.csv} or \texttt{.txt} file.\\ Below are examples of both formats:

            \begin{tabular}{|p{0.45\textwidth}|p{0.45\textwidth}|}
\hline
\textbf{.txt} & \textbf{.csv} \\ \hline
\parbox[t]{\linewidth}{%
\texttt{65\\56\\72\\102\\...\\}%
} & 
\parbox[t]{\linewidth}{%
\texttt{65,56,72,102, ...}%
} \\ \hline
\end{tabular}
\caption{Sample Speed Profile File Format}
        \end{tcolorbox}
        
    \end{itemize}
    \item \textbf{Optional Fields:}
    \begin{itemize}
        \item \textbf{Description:} Add details to describe your collection.
        \item \textbf{Image:} Upload an image to visually represent your collection.
    \end{itemize}
   
\end{itemize}


    \begin{figure}[h!]
        \centering
        \includegraphics[width=\textwidth]{gfx/create-collection-form.png}
        \caption{Collection creation form}
        \label{fig:create-collection-form}
    \end{figure} \newpage

     \item When you have finished filling out the form click the maroon \textbf{"Create Collection"} button
     \begin{figure}[h!]
        \centering
        \includegraphics[width=\textwidth]{gfx/submit-form.png}
        \caption{Submitting Collection Form}
        \label{fig:create-collection-form}
    \end{figure}
\end{enumerate}

\subsection{Analyze Collection Data}
\label{sec:analyze}
Upon creating a new collection you will be redirected to the Data Analytics Page. It will appear blank at first. Follow the directions below to populate the page. 
\vspace{-3mm}
\begin{figure}[h!]
        \centering
        \includegraphics[width=\textwidth]{gfx/collection-analytics.png}
        \caption{Initial Collection Anayltics Page}
        \label{fig:create-collection-form}
    \end{figure}

\subsubsection{Sidebar Tasks}

To run the models on your uploaded speed profile, follow these steps:

\begin{enumerate}
    \item Check the engine types you would like to analyze in the sidebar.  
    \item  Click the maroon \textbf{"Analyze Selected Engines"} button.  
   \begin{itemize}
       \item If the button is grey and not maroon, you need to select at least one engine type before proceeding.
   \end{itemize}


   \begin{figure}[h!]
       \centering
       \includegraphics[width=0.3\textwidth]{gfx/sidebar.png}
       \caption{Sidebar: Analyze Selected Engines}
       \label{fig:sidebar-analyze-engines}
   \end{figure}
\newpage
\item After running the analysis, key metrics for the selected engines will be displayed.

   \begin{figure}[h!]
       \centering
       \includegraphics[width=\textwidth]{gfx/key-metrics.png}
       \caption{Key Metrics Displayed}
       \label{fig:key-metrics}
   \end{figure}

\item To view graphical representations, return to the sidebar and select\\ \textbf{"Efficiency Analysis"}.  

 \begin{figure}[h!]
       \centering
       \includegraphics[width=\textwidth]{gfx/Efficiency Analysis.png}
       \caption{Efficiency Analysis Graphs Displayed}
       \label{fig:key-metrics}
   \end{figure}
\end{enumerate}

\subsection{Return to Collections Dashboard}

To return to your Collections Dashboard, follow these steps:

\begin{enumerate}
    \item Hover your cursor over the profile icon located at the top-right corner of the screen.
    \item From the dropdown menu that appears, select the \textbf{"Collections"} option to access your dashboard.
\end{enumerate}

Additional options available in the dropdown menu:

\begin{itemize}
    \item Revisit the landing or welcome page.
    \item Log out to end your session.
\end{itemize}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.6\textwidth]{gfx/dropdown.png} % Resized to 50% of text width
    \caption{Dropdown Menu on Profile Icon Hover}
    \label{fig:dropdown-hover}
\end{figure}
\newpage
\subsection{Read, Update, Delete a Collection}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.7\textwidth]{gfx/collection-crud.png} % Resized to 70% of text width
    \caption{Collection Management Options}
\end{figure}

Each collection comes with the following core functionality to help you manage and interact with it:

\begin{itemize}
    \item \textbf{Read (Download):} Allows you to download the data associated with the collection.
    \item \textbf{Update (Edit):} Enables you to make changes to the collection's name, description, image, or speed profile.
    \item \textbf{Delete:} Permanently removes the collection and its data.

\end{itemize}

\textbf{Note:} Figure 17 also includes the "Analyze" option, which was covered in \hyperref[sec:analyze]{Section 7.3}.
\newpage
\subsubsection{Read (Download)}
\label{sec:download}

To download the data from a collection, follow these steps:

\begin{enumerate}
    \item \textbf{Locate the Download Button:}  
    Navigate to the collection you want to download and click the download button, as shown in Figure \ref{fig:download-collection}.
    
    \begin{figure}[h!]
        \centering
        \includegraphics[width=\textwidth]{gfx/download-collection.png} 
        \caption{Download Button on Collection Page}
        \label{fig:download-collection}
    \end{figure}

    \item A \texttt{.zip} file containing the collection's data will be sent to your downloads folder.

    \item Once the \texttt{.zip} file is downloaded, \hyperref[sec:extract]{extract its contents}. The extracted folder will include all data files related to the collection. An example of the extracted files is shown in Figure \ref{fig:download-files}.
    
    \begin{figure}[h!]
        \centering
        \includegraphics[width=0.7\textwidth]{gfx/download-files.png} 
        \caption{Extracted Files from Downloaded Collection}
        \label{fig:download-files}
    \end{figure}
    
    \newpage

    \item \textbf{Contents of the Downloaded Folder:}

    The folder contains the following:

    \begin{itemize}
        \item \textbf{Top-level Files:}
        \begin{itemize}
            \item \texttt{speed\_profile.csv}: Contains the speed profile data for analysis.
            \item \texttt{vehicle\_comparison.csv}: Summary comparison of vehicles.
            \item \texttt{README.txt}: A text file with additional information about the contents and usage.
        \end{itemize}

        \item \textbf{Results Directory:}
        \begin{itemize}
            \item \textbf{ICEV (Internal Combustion Engine Vehicle):}
            \begin{itemize}
                \item \texttt{analysis\_results.json}: Contains analysis results for ICEV.
                \item \texttt{time\_series.csv}: Time series data for ICEV.
                \item \texttt{parameters.txt}: Parameters used for ICEV analysis.
            \end{itemize}
            \item \textbf{BEV (Battery Electric Vehicle):}
            \begin{itemize}
                \item \texttt{analysis\_results.json}: Contains analysis results for BEV.
                \item \texttt{time\_series.csv}: Time series data for BEV.
                \item \texttt{parameters.txt}: Parameters used for BEV analysis.
            \end{itemize}
            \item \textbf{HEV (Hybrid Electric Vehicle):}
            \begin{itemize}
                \item \texttt{analysis\_results.json}: Contains analysis results for HEV.
                \item \texttt{time\_series.csv}: Time series data for HEV.
                \item \texttt{parameters.txt}: Parameters used for HEV analysis.
            \end{itemize}
            \item \textbf{HFCV (Hydrogen Fuel Cell Vehicle):}
            \begin{itemize}
                \item \texttt{analysis\_results.json}: Contains analysis results for HFCV.
                \item \texttt{time\_series.csv}: Time series data for HFCV.
                \item \texttt{parameters.txt}: Parameters used for HFCV analysis.
            \end{itemize}
        \end{itemize}
    \end{itemize}
\end{enumerate}


\begin{tcolorbox}[extractionbox, title=How to Extract ZIP Files]
\label{sec:extract}
\textbf{Windows:}
\begin{itemize}
    \item Right-click the ZIP file and select \textbf{"Extract All"}.
    \item Choose a destination folder and click \textbf{"Extract"}.
\end{itemize}

\textbf{MacOS:}
\begin{itemize}
    \item Double-click the ZIP file to extract its contents in the same directory.
\end{itemize}

\textbf{Linux:}
\begin{itemize}
    \item Use the file manager to right-click the ZIP file and select \textbf{"Extract Here"} or \textbf{"Extract To"}.
    \item Alternatively, use the terminal command: \texttt{unzip file.zip}.
\end{itemize}
\end{tcolorbox}
\newpage

\subsubsection{Update (Edit)}

To update a collection, click the \textbf{"Edit"} button on the collection card (see Figure \ref{fig:collection-crud}). This will take you back to the same form as the \hyperref[sec:go]{"Create Collection"} page, pre-filled with the current details of the collection.

You can update the following:
\begin{itemize}
    \item \textbf{Collection Name:} Modify the name of your collection.
    \item \textbf{Description:} Edit the description of your collection.
    \item \textbf{Collection Image:} Change or upload a new image to represent the collection.
    \item \textbf{Speed Profile:} Upload a new speed profile file (\texttt{.csv} or \texttt{.txt} format).
\end{itemize}

Once you have made the necessary changes, click the maroon \textbf{"Update Collection"} button at the bottom of the form to save your edits.

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.5\textwidth]{gfx/collection-crud.png}
    \caption{Collection Card}
    \label{fig:collection-crud}
\end{figure}

\subsubsection{Delete}

To delete a collection, click the red \textbf{"Delete"} button on the collection card (see Figure \ref{fig:collection-crud}). A confirmation prompt will appear to ensure that you want to proceed with the deletion.\\

\textbf{Note: Deleting a collection is a permanent action and cannot be undone. Ensure that you have downloaded any necessary data before confirming the deletion.}
\subsection{Log Out}

After managing your collections, don’t forget to log out to ensure your account remains secure. 

To log out:
\begin{enumerate}
    \item Click on the profile icon located at the top-right corner of the screen.
    \item From the dropdown menu, select \textbf{"Logout"}.
\end{enumerate}
\textbf{Note: Logging out is especially important if you are using a shared or public computer to protect your data.}

\newpage
\section{Admin Manual}

\subsection{Accessing the Admin Portal}
\begin{enumerate}
    \item Open \url{http://tml.cs.vt.edu:5000/} in your web browser.
    \item Click the \textbf{Login} button.
\end{enumerate}
\vspace{2mm}
\begin{methodbox}{\subsection{Login Credentials}}
\begin{itemize}
    \item \textbf{Username:} \texttt{admin}
    \item \textbf{Password:} \texttt{1234}
\end{itemize}
\end{methodbox}
\vspace{5mm}

\subsection{Admin Dashboard}
Administrators have extended permissions compared to regular users. \\Key functionalities include:
\begin{itemize}
    \item \textbf{Create Collections:} Similar to regular user functionality.
    \item \textbf{Manage User Profiles:} View and edit user information.
    \item \textbf{Manage Vehicle Profiles:} View and edit vehicle details.
\end{itemize}

The Admin Dashboard, shown in Figure~\ref{fig:admin-dashboard}, provides access to these features.

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/admin-dashboard.png}
    \caption{Admin Dashboard}
    \label{fig:admin-dashboard}
\end{figure}

\newpage

\subsection{Admin Collections}
Admin collections function identically to regular user collections. For a detailed guide, refer to the User Manual, \hyperref[sec:go]{Section 7.2.1}.

\subsection{User Management}
To access and manage user information, administrators can click on the \textbf{User Management} card in the Admin Dashboard (Figure~\ref{fig:admin-dashboard}). This action will open a table, as shown in Figure~\ref{fig:user-management-table}, displaying detailed information about all current users, including the following fields:
\begin{itemize}
    \item \textbf{Username:} The unique identifier of each user.
    \item \textbf{Database Role:} Indicates whether the user is a regular user or an administrator.
    \item \textbf{Number of Collections:} The total number of collections created by the user.
    \item \textbf{Actions:} A button to view and manage the user's collections.
\end{itemize}

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/user-table.png}
    \caption{User Management Table}
    \label{fig:user-management-table}
\end{figure}

After clicking the \textbf{"View Collections"} button for a specific user, administrators can perform the following actions:
\begin{itemize}
    \item \textbf{Analyze Collections:} Perform real-time data analysis on the user's collections to derive insights. Refer to \hyperref[sec:analyze]{User Manual, Section 7.3} for guidance.
    \item \textbf{Download Collections:} Export the collection data as a \texttt{.zip} file for further processing or record-keeping. Refer to \hyperref[sec:download]{User Manual, Section 7.5.1} for details.
\end{itemize}

The interface for viewing and managing user collections is shown in Figure~\ref{fig:admin-user-collections}.

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/admin-user-collections.png}
    \caption{Admin View of User Collections}
    \label{fig:admin-user-collections}
\end{figure}

\subsection{Vehicle Parameters}
The Vehicle Parameters section allows administrators to view, edit, and create new vehicle configurations. 

\subsubsection{Viewing Current Configurations}
The table at the top of the page (Figure~\ref{fig:vehicle-parameters}) displays the current configurations for the current engine types.

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/vehicle-parameters.png}
    \caption{Vehicle Parameters Overview}
    \label{fig:vehicle-parameters}
\end{figure}

\subsubsection{Updating Vehicle Configurations}
Administrators can update vehicle configurations through the \textbf{Update Parameters} section (Figure~\ref{fig:update-parameters}). This process involves two key steps:

\begin{enumerate}
    \item \textbf{Add the Engine or Vehicle Type Name}: Use the \textbf{Add New Vehicle Type} form to create a new engine or vehicle type by providing an abbreviation, full name, and a unique engine type ID (Figure~\ref{fig:add-new-vehicle-type}).
    \item \textbf{Upload the Updated Vehicle Parameters File}: After adding the new type, prepare and upload a \texttt{.txt} or \texttt{.csv} file that includes parameter data for all engine types—both existing and newly added. Ensure the file adheres to the required format, including consistent IDs for all engine types.
\end{enumerate}

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/upload-parameters.png}
    \caption{Updating and Uploading Vehicle Parameters}
    \label{fig:update-parameters}
\end{figure}

\subsubsection{Adding a New Vehicle Type}
When adding a new vehicle type, the system prompts the administrator with a form to input details (Figure~\ref{fig:add-new-vehicle-type}). The form contains the following fields:
\begin{itemize}
    \item \textbf{Abbreviation}: A short code representing the vehicle type (e.g., \texttt{PHEV} for Plug-in Hybrid Electric Vehicle).
    \item \textbf{Full Name}: The full name of the vehicle type.
    \item \textbf{Engine Type ID}: A unique numerical identifier for the vehicle type (e.g., \texttt{5}). Ensure this ID is consistent across all updates, including the parameters file and any backend functions.
\end{itemize}

\begin{figure}[h!]
    \centering
    \includegraphics[width=0.7\textwidth]{gfx/add-new-vehicle-type.png}
    \caption{Add New Vehicle Type Form}
    \label{fig:add-new-vehicle-type}
\end{figure}

\subsubsection{Important Notes on Backend Limitations}
Currently, our system's backend and interface do not provide functionality for uploading or managing the Python data analysis code used in visualizations. Administrators must manually update the codebase to include a calculation function for any additional vehicle types. This process requires:
\begin{itemize}
    \item Adding a new function in \texttt{getEnergy.py} to handle the specific calculations for the new vehicle type.
    \item Ensuring that the assigned \textbf{Engine Type ID} is consistent across all three forms:
    \begin{enumerate}
        \item The \textbf{Add New Vehicle Type} form.
        \item The updated \texttt{.txt} or \texttt{.csv} parameter file.
        \item The backend Python code (e.g., in \texttt{getEnergy.py}).
    \end{enumerate}
\end{itemize}

\textbf{Important}: Failure to maintain consistency in the Engine Type ID may result in errors during parameter processing, data analysis, or visualizations.
\newpage
\subsubsection{File Format Requirements}
To upload vehicle configurations, the file must adhere to the following format:
\begin{itemize}
    \item Each line represents a single vehicle configuration, with space-separated values.
    \item The file includes the following columns:
    \begin{itemize}
        \item \textbf{Vehicle Identification:} Columns 1-2 for type and engine details.
        \item \textbf{Physical Properties:} Columns 3-8 for mass, length, friction coefficient, engine power, and battery power.
        \item \textbf{Operation Parameters:} Columns 9-30 for performance coefficients, motor parameters, and power management.
    \end{itemize}
\end{itemize}



For a detailed example, refer to the File Format Requirements box in Figure~\ref{fig:file-format-example}. This box includes a sample entry for a Battery Electric Vehicle (BEV) configuration and specifies the required data structure.

\begin{figure}[h!]
    \centering
    \includegraphics[width=\textwidth]{gfx/file-format-example.png}
    \caption{File Format Example for Vehicle Configurations}
    \label{fig:file-format-example}
\end{figure}


\newpage
\section{Developer Manual}
{\footnotesize \textbf{Project Repository:} \url{https://git.cs.vt.edu/courtneyq/automated_vehicles_fuel_energy_estimation}}\\

This manual provides technical documentation for developers who will maintain or extend the Vehicle Energy Estimation Web Application. The system consists of a React front-end, Flask back-end, and SQLite database, with integration of VTTI's energy calculation models.\\

The project follows this organization:

\begin{methodbox}{\subsection{Project Structure}}
\begin{verbatim}
├── README.md                # Project documentation
├── app.py                   # Main Flask application
├── config.py                # Configuration settings
├── getEnergy.py             # Energy calculation logic
├── setup.sql                # Database schema setup
├── requirements.txt         # Python dependencies
├── energy_estimation.db     # SQLite database for development
├── spd-hfcv.txt             # Example speed profile for HFCV
├── veh_parameters.txt       # Example vehicle parameters
├── front-end/               # React frontend source code
│   ├── package.json         # Frontend dependencies
│   ├── public/              # Static assets
│   │   ├── images/          # Relevant image assets
│   │   └── index.html       # Main HTML template
│   └── src/                 # React application source files
│       ├── App.js           # Main React component
│       ├── components/      # Shared UI components
│       │   ├── header/      # Header components
│       │   ├── security/    # Authentication and protected routes
│       │   └── sidebar/     # Sidebar components
│       ├── pages/           # Page-specific components
│       │   ├── admin/       # Admin dashboard and utilities
│       │   ├── body/        # Body layout
│       │   ├── collections/ # User collections
│       │   ├── login/       # Login page
│       │   ├── signup/      # Signup page
│       │   └── welcome/     # Welcome page
\end{verbatim}
\end{methodbox}




\subsection{Development Environment Setup}
\subsubsection{Prerequisites}
\begin{itemize}
    \item Python 3.7+ (Python 3.8 or 3.9 recommended)
    \item Node.js (version 14+) and npm
    \item SQLite
\end{itemize}

\begin{methodbox}{\subsubsection{Backend Setup} }
Enter the following commands in a Bash or Powershell terminal in order:
\begin{minted}[breaklines]{bash}
# Clone the repository (This command is entered all in one line)
git clone https://git.cs.vt.edu/courtneyq/automated_vehicles_fuel_energy_estimation

# Navigate to project directory
cd automated_vehicles_fuel_energy_estimation/

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install individual dependencies from requirements.txt
# Note: Skip the python 3.12 line (first line)
pip install [each dependency separately]

# Run the Flask application
python app.py
\end{minted}
\end{methodbox}

\begin{methodbox}{\subsubsection{Frontend Setup} }
Enter the following commands in another Bash or Powershell terminal in order:
\begin{minted}{bash}
# Navigate to frontend directory
cd automated_vehicles_fuel_energy_estimation/front-end/

# Install dependencies
# Run this command once the project is first cloned
npm install react-scripts@latest
# Else run this command for any new libraries that you add
npm install

# Start development server
npm start
\end{minted}
\end{methodbox}

The frontend should run on \texttt{http://localhost:3000}\\
and the backend on \texttt{http://localhost:5000}.
\subsection{Future Development}
When contributing to the project:
\begin{methodbox}{\subsubsection{Git Workflow} }
\begin{minted}{bash}
# Create a new branch
git checkout -b your-feature-branch-name

# Make changes and commit
git add --all
git commit -m "your message in quotes"

# Push changes
git push origin your-feature-branch-name

# Create Pull Request through GitLab interface
\end{minted}
\end{methodbox}

\subsubsection{Troubleshooting}
Common issues and solutions:
\begin{itemize}
    \item Port conflicts: Use \texttt{PORT=3001 npm start} for frontend
    \item Database issues: Re-run \texttt{python init\_db.py}
    \item Virtual environment: Ensure correct Python version
    \item Dependencies: Install individually if \texttt{requirements.txt} fails
\end{itemize}

For questions or access to the repository, contact the team:
\begin{itemize}
    \item Backend Lead: Courtney Quinn (\textbf{courtneyq@vt.edu})
    \item Frontend Lead: Layla Scott (\textbf{laylas@vt.edu})
    \item Client: Dr. Mohamed Farag (\textbf{mmagdy@vt.edu})
\end{itemize}

\subsection{Docker Setup and Deployment Guide}

\subsubsection{Prerequisites}
\begin{itemize}
    \item Docker installed on your machine. Download from \href{https://www.docker.com/products/docker-desktop}{Docker}.
    \item Access to the project repository.
    \item Ensure all Docker-based deployments are made from the \texttt{deploy} branch.
\end{itemize}

\subsubsection{Setup and Deployment}

Run the following commands in a Bash or PowerShell terminal in order:

\begin{methodbox}{Deployment Commands}
\begin{minted}[breaklines]{bash}
# Switch to the deploy branch
git checkout deploy

# Pull the latest changes
git pull origin deploy

# Build the Docker image
sudo docker build -t automated-vehicles .

# Run the Docker container with database persistence
sudo docker run --env-file .env -p 5000:5000 -v $(pwd)/energy_estimation.db:/app/energy_estimation.db automated-vehicles
\end{minted}
\end{methodbox}

\subsubsection{Accessing the Application}
Navigate to \texttt{http://localhost:5000} in your browser to use the integrated frontend and backend.

\subsubsection{Development Workflow}

If you have updated the code on the \texttt{deploy} branch and want to redeploy:
\begin{methodbox}{Redeploy Workflow}
\begin{enumerate}
    \item \textbf{Pull the Latest Code:}
    \begin{minted}{bash}
git checkout deploy
git pull origin deploy
    \end{minted}

    \item \textbf{Stop the Running Container:}
    \begin{minted}{bash}
sudo docker ps
sudo docker stop <CONTAINER_ID_OR_NAME>
    \end{minted}

    \item \textbf{Rebuild the Docker Image:}
    \begin{minted}{bash}
sudo docker build -t automated-vehicles .
    \end{minted}

    \item \textbf{Start the Container Again with Database Persistence:}
   \begin{minted}[breaklines]{bash}
sudo docker run --env-file .env -p 5000:5000 -v $(pwd)/energy_estimation.db:/app/energy_estimation.db automated-vehicles
    \end{minted}
\end{enumerate}
\end{methodbox}

\subsubsection{Troubleshooting}

\begin{methodbox}{Deploy Branch Enforcement}
    \textbf{Deploy Branch Enforcement:} Ensure all deployment changes are pushed to the \texttt{deploy} branch. Deployment from other branches is not supported.
\end{methodbox}[title=, colframe=gray!50, colback=gray!10, sharp corners]


\begin{methodbox}{No Space Left on Device} 
If you encounter this error during \texttt{docker build}:
\begin{minted}[breaklines]{bash}
ERROR: failed to update builder last activity time: no space left on device
\end{minted}

\textbf{Solution: Clean Up Docker Storage:}
\begin{minted}[breaklines]{bash}
docker system prune -a --volumes
\end{minted}
\end{methodbox}

\begin{methodbox}{Port Conflicts}
    If port \texttt{5000} is unavailable:
\begin{minted}[breaklines]{bash}
sudo docker run --env-file .env -p 8080:5000 -v $(pwd)/energy_estimation.db:/app/energy_estimation.db automated-vehicles
\end{minted}
\end{methodbox}
\begin{methodbox}{Debugging Issues}
    \begin{itemize}
    \item Check the container logs:
    \begin{minted}[breaklines]{bash}
sudo docker logs <CONTAINER_ID_OR_NAME>
    \end{minted}

    \item Inspect the running container:
    \begin{minted}[breaklines]{bash}
docker exec -it <CONTAINER_ID_OR_NAME> /bin/bash
    \end{minted}
\end{itemize}
\end{methodbox}
\begin{methodbox}{Missing Frontend or API}
    Ensure the React build files exist in the \texttt{static} folder:
\begin{minted}[breaklines]{bash}
docker exec -it <CONTAINER_ID_OR_NAME> ls /app/static
\end{minted}

Verify Flask is correctly serving the React front end:
\begin{itemize}
    \item Open a browser and navigate to \texttt{http://localhost:5000}.
    \item Check browser developer tools for errors in the \textbf{Console} or \textbf{Network} tabs.
\end{itemize}
\end{methodbox}


\section{Reflection}
\begin{table}[h!]
\centering
\setlength{\tabcolsep}{8pt} % Adjust column padding
\renewcommand{\arraystretch}{1.5} % Adjust row spacing for better readability
\begin{methodbox}{\subsection{Schedule}}
\begin{tabular}{|l|p{10cm}|} % Use p{} for wrapping long text
\hline
\textbf{Month}        & \textbf{Tasks} \\ \hline
\textbf{September 2023} & 
- Initial project setup \newline
- Basic React frontend creation \newline
- Flask backend configuration \\ \hline
\textbf{October 2023}   & 
- Database implementation \newline
- User authentication system \newline
- File upload functionality \newline
- Integration of VTTI calculations \\ \hline
\textbf{November 2023}  & 
- Testing and debugging \newline
- User interface improvements \newline
- Documentation creation \\ \hline
\end{tabular}
\end{methodbox}
\caption{Project Schedule}
\label{tab:project_schedule}
\end{table}


\subsection{Problems}
During development, we encountered a variety of technical challenges that required careful consideration and creative problem-solving. One of the initial difficulties was establishing a seamless connection between the frontend and backend of the application. This involved overcoming communication mismatches and ensuring proper data flow between the two components.\\

Another significant challenge was the implementation of file upload functionality. Ensuring that files were correctly validated, uploaded, and processed while maintaining security added complexity to the development process. Additionally, managing database relationships proved problematic, as initial attempts at structuring the schema resulted in inefficiencies and inconsistencies.\\

Beyond these architectural hurdles, maintaining the accuracy of calculation results was another critical issue. Ensuring that our system aligned with the original VTTI algorithms required extensive testing and debugging. Finally, handling user sessions securely while ensuring a smooth user experience was particularly challenging, as it involved managing authentication, preserving session states, and protecting sensitive data.

\subsection{Solutions}
To address these challenges, we implemented a series of targeted solutions. For the frontend-backend communication issue, we established proper configurations, which included defining clear API endpoints and ensuring compatibility between the two systems.\\

The file upload problem was mitigated by creating a robust file validation system that could efficiently handle various file types while ensuring security. To resolve database relationship issues, we redesigned the database schema to better align with the application's data requirements, improving performance and reducing inconsistencies.\\

Extensive testing was conducted to maintain the accuracy of calculation results, where we compared outputs from our system against VTTI's original algorithms to identify and resolve discrepancies. For session management, we implemented secure session handling techniques, including encryption and token-based authentication, to protect user data while ensuring a seamless user experience.

\subsection{Future Work}
Although the current implementation is functional and achieves its primary objectives, there are several areas where enhancements can be made to improve usability and functionality. For instance, adding features such as password recovery and login with Google or other quick-access functions would streamline the user experience. In terms of the user interface, future work could include incorporating enhanced data visualizations to make calculation results more intuitive and user-friendly. Redesigning the file upload interface for better usability and providing clearer error messages would also improve the user experience significantly.\\

Another critical area of improvement is documentation. More detailed user guides would help users better understand and navigate the system, while expanded API documentation would make it easier for developers to integrate the system into their workflows. Additionally, creating comprehensive troubleshooting guides would enable users to resolve common issues independently. These enhancements would collectively make the system more accessible and user-focused while continuing to support VTTI’s goal of providing accurate and reliable vehicle energy calculations through a web interface.


\section{Acknowledgments}
We want to thank everyone who contributed to the creation of the Vehicle Energy Estimation Web Application. This project came together thanks to their guidance, expertise, and support.\\

First, we are incredibly grateful to \textbf{Dr. Mohamed Farag}, who served as both our professor and client. His mentorship and technical advice were integral to our project. His expertise in information systems guided our work with data management and system design. The course structure and his feedback gave us a solid framework for building the project.\\

A special thank you to the \textbf{Virginia Tech Transportation Institute} (\textbf{VTTI}) for providing the research and models that power our application. Their collaboration with students shows the importance of combining research and technology to solve real-world challenges.\\

We appreciate the support from \textbf{our classmates in CS 4624} for their useful feedback during presentations.\\

A huge thank you goes to our team for their dedication and collaboration:
\begin{itemize}
    \item \textbf{Courtney Quinn} -- Backend Lead, Group Leader
    \item \textbf{Layla Scott} -- Frontend Lead
    \item \textbf{Rohin Batra} -- Backend Support
    \item \textbf{Eric Tapia} -- Backend Support
    \item \textbf{Christina Chao} -- Frontend Support, Meeting Minutes
\end{itemize}

Each team member brought unique skills to the table, helping us tackle challenges and deliver a strong final product. This project highlights the importance of teamwork and combining skills from different fields to solve real-world problems.\\

We hope this project will support future research in vehicle energy consumption and serve as a useful tool for transportation studies.

\section*{References}
\nocite{Siepe2024}
\printbibliography[heading=none]

\end{document}