documentation.tex

\hypertarget{finance-friends-documentation}{%
\section{Finance Friends
Documentation}\label{finance-friends-documentation}}

\hypertarget{final-deployment}{%
\subsection{Final Deployment}\label{final-deployment}}

Finance Friends is now live and accessible! Here's how you can explore
the platform and learn more about the project.

\hypertarget{introduction}{%
\subsection{Introduction}\label{introduction}}

Finance Friends is a revolutionary platform designed to make learning
about financial literacy a fun, interactive, and engaging experience for
children. By leveraging advanced AI technology alongside a captivating
narrative and interactive gameplay, Finance Friends introduces children
to fundamental financial concepts and practical knowledge.

\hypertarget{overview}{%
\subsubsection{Overview}\label{overview}}

At its core, Finance Friends is a gamified learning platform where
children embark on a journey through various thematic locations. Each
location is meticulously designed to focus on different aspects of
financial literacy, including financial mathematics, credits, savings,
investments, taxes, and free conversation. This approach not only makes
learning about finance more relatable but also ensures a comprehensive
educational experience.

\hypertarget{key-features}{%
\subsubsection{Key Features}\label{key-features}}

\begin{itemize}
\tightlist
\item
  \textbf{Gamified Learning Experience:} A journey with 6 main
  characters across 6 unique locations, each meticulously crafted to
  focus on different financial modules.
\item
  \textbf{Interactive Chatbot Education:} An intelligent chatbot,
  powered by the latest technologies such as Node.js, MongoDB, and
  Python scripts using LangChain, guides children through predefined
  lessons in an understandable and engaging manner.
\item
  \textbf{On-Demand Learning:} Recognizing the dynamic nature of
  learning, Finance Friends allows children to interact with the chatbot
  at their own pace, encouraging them to ask questions and seek
  clarifications whenever needed.
\end{itemize}

\hypertarget{target-audience}{%
\subsubsection{Target Audience}\label{target-audience}}

The primary audience for Finance Friends is children who are at the
beginning of their educational journey. The platform is designed to be
intuitive and user-friendly, making it accessible for children with
varying degrees of familiarity with technology and finance.

Through this documentation, you will gain a comprehensive understanding
of the platform, its features, and detailed guides on installation,
configuration, and usage, along with the API documentation for further
customization and integration.

Join us as we embark on this journey to make financial literacy an
accessible, enjoyable, and essential part of every child's education.

\hypertarget{key-features-1}{%
\subsection{Key Features}\label{key-features-1}}

Finance Friends is not just a learning platform; it's an interactive,
engaging, and comprehensive journey into financial literacy for
children. Here are some of the standout features that make Finance
Friends an essential tool for learning:

\hypertarget{comprehensive-user-management}{%
\subsubsection{1. Comprehensive User
Management}\label{comprehensive-user-management}}

\begin{itemize}
\tightlist
\item
  \textbf{Seamless Registration and Login:} Ensures an easy and secure
  entry into the world of financial learning.
\item
  \textbf{Personalized User Profiles:} Users have their own profiles,
  capturing their learning progress, preferences, and achievements,
  allowing for a tailored learning experience.
\end{itemize}

\hypertarget{engaging-personalized-experiences}{%
\subsubsection{2. Engaging Personalized
Experiences}\label{engaging-personalized-experiences}}

\begin{itemize}
\tightlist
\item
  \textbf{Custom Welcome Messages:} Users are welcomed with messages
  that make them feel recognized and valued, setting a positive tone for
  their learning journey.
\item
  \textbf{Interactive Learning Sessions:} Each session is an adventure,
  with content tailored to the user's pace and style, making complex
  financial concepts more understandable and engaging.
\end{itemize}

\hypertarget{dynamic-learning-modules}{%
\subsubsection{3. Dynamic Learning
Modules}\label{dynamic-learning-modules}}

\begin{itemize}
\tightlist
\item
  \textbf{Diverse Financial Topics:} A wide array of modules ensures a
  well-rounded understanding of financial literacy, from savings and
  investments to taxes and financial mathematics.
\item
  \textbf{Real-time Interactive Chatbot:} An intelligent chatbot
  accompanies users, ready to answer questions, clarify doubts, and
  provide guidance.
\end{itemize}

\hypertarget{innovative-assessment-tools}{%
\subsubsection{4. Innovative Assessment
Tools}\label{innovative-assessment-tools}}

\begin{itemize}
\tightlist
\item
  \textbf{Quizzes and Knowledge Checks:} Regular quizzes and assessments
  help reinforce learning, ensuring that key concepts are understood and
  retained.
\item
  \textbf{AI-Powered Quiz Evaluation:} Quizzes are evaluated instantly
  with AI, providing immediate feedback and explanations, enhancing the
  learning process.
\end{itemize}

\hypertarget{motivation-and-progress-tracking}{%
\subsubsection{5. Motivation and Progress
Tracking}\label{motivation-and-progress-tracking}}

\begin{itemize}
\tightlist
\item
  \textbf{Leaderboards:} Friendly competition is fostered through
  leaderboards, motivating users to engage more with the content and
  strive for improvement.
\item
  \textbf{Progress Tracking:} Users can track their learning journey,
  see their progress in different modules, and set personal learning
  goals.
\end{itemize}

Finance Friends combines these features to provide an educational
experience that's not just informative but also engaging, interactive,
and tailored to each user's needs. The platform ensures that learning
about finance is a fun, rewarding, and enriching experience for every
child.

\hypertarget{getting-started}{%
\subsection{Getting Started}\label{getting-started}}

This section guides you through setting up your development environment
for both the backend and frontend components of Finance Friends.

\hypertarget{backend-setup}{%
\subsubsection{Backend Setup}\label{backend-setup}}

\hypertarget{prerequisites}{%
\paragraph{Prerequisites}\label{prerequisites}}

Before setting up the backend, ensure you have the following installed:
- Node.js - npm (Node Package Manager) - MongoDB (local setup or MongoDB
Atlas URI) - Python 3 (with Pip)

\hypertarget{installing}{%
\paragraph{Installing}\label{installing}}

Follow these steps to set up your backend development environment:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  \textbf{Clone the Repository}:
  \texttt{git\ clone\ https://github.com/FinanceFriend/backend.git}
\item
  \textbf{Navigate to the Directory}: \texttt{cd\ backend}
\item
  \textbf{Install Dependencies}: \texttt{npm\ install}
\item
  \textbf{Set Up Environment Variables}:
\end{enumerate}

\begin{itemize}
\item
  Create a \texttt{.env} file in the root of your project.
\item
  Add your MongoDB URI and other necessary environment variables.
  Example:

\begin{verbatim}
MONGODB_URI=your_mongodb_uri
OPENAI_API_KEY=your_api_key
PORT=3001
\end{verbatim}
\end{itemize}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{4}
\item
  \textbf{Start the Server}: \texttt{npm\ start}
\item
  \textbf{Verify Installation}:
\end{enumerate}

\begin{itemize}
\tightlist
\item
  Open \texttt{http://localhost:3001} in your web browser. You should
  see a confirmation message indicating that the server is running.
\end{itemize}

\hypertarget{setting-up-python-environment}{%
\paragraph{Setting Up Python
Environment}\label{setting-up-python-environment}}

To run the Python script with \texttt{langchain}, follow these steps:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  \textbf{Create a Virtual Environment}:
  \texttt{python3\ -m\ venv\ venv}
\end{enumerate}

\begin{itemize}
\tightlist
\item
  This will create a directory called \texttt{venv} in your project
  folder.
\end{itemize}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{1}
\tightlist
\item
  \textbf{Activate the Virtual Environment}:
\end{enumerate}

\begin{itemize}
\item
  On Windows:

\begin{verbatim}
venv\Scripts\activate
\end{verbatim}
\item
  On macOS and Linux:

\begin{verbatim}
source venv/bin/activate
\end{verbatim}
\item
  Your command prompt should now indicate that you are in a virtual
  environment.
\end{itemize}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{2}
\item
  \textbf{Install Python Dependencies}:
  \texttt{pip\ install\ -r\ requirements.txt}
\item
  \textbf{Run the Python Script}:
\end{enumerate}

\begin{itemize}
\tightlist
\item
  With the dependencies installed, you can now run your Python script
  within the virtual environment.
\end{itemize}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{4}
\tightlist
\item
  \textbf{Deactivate the Virtual Environment}:
\end{enumerate}

\begin{itemize}
\item
  Once you're done, you can deactivate the virtual environment by
  running:

\begin{verbatim}
deactivate
\end{verbatim}
\end{itemize}

\hypertarget{frontend-setup}{%
\subsubsection{Frontend Setup}\label{frontend-setup}}

This is a Next.js project bootstrapped with \texttt{create-next-app}.

\hypertarget{getting-started-1}{%
\paragraph{Getting Started}\label{getting-started-1}}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  \textbf{Install Necessary npm Dependencies}:
  \texttt{npm\ install\ -\/-force}
\item
  \textbf{Run the Development Server}: \texttt{npm\ run\ dev} or
  \texttt{yarn\ dev}
\item
  \textbf{Verify Installation}:
\end{enumerate}

\begin{itemize}
\tightlist
\item
  Open \texttt{http://localhost:3000} with your browser to see the
  result.
\end{itemize}

Follow these steps to get your backend and frontend up and running. If
you encounter any issues, refer to the FAQs or reach out to the support
team.

\hypertarget{api-documentation}{%
\subsection{API Documentation}\label{api-documentation}}

This section provides a comprehensive guide to the API of Finance
Friends, detailing the available endpoints, their functionalities, and
how to interact with them.

\hypertarget{overview-of-the-api}{%
\subsubsection{Overview of the API}\label{overview-of-the-api}}

The Finance Friends API is designed to provide a seamless and secure way
to interact with the platform, enabling users to access and manage
resources programmatically. It is built with RESTful principles in mind,
ensuring a predictable and consistent way to access the platform's data
and services.

\hypertarget{backend-endpoints}{%
\subsubsection{Backend endpoints}\label{backend-endpoints}}

\hypertarget{user-registration}{%
\paragraph{1. User Registration}\label{user-registration}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/register}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: This endpoint is used to create a new user
  account.
\item
  \textbf{Request Body}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The desired username of the
    user.
  \item
    \texttt{email}: String (required) - The user's email address.
  \item
    \texttt{password}: String (required) - The user's password.
  \item
    \texttt{dateOfBirth}: Date (required) - The user's date of birth.
  \item
    \texttt{countryOfOrigin}: String (required) - The user's country of
    origin.
  \item
    \texttt{preferredLanguage}: String (required) - The user's preferred
    language.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message describing the outcome.
  \item
    \texttt{user}: Object - Contains user information (excluding
    password).
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{400\ Bad\ Request} if the username already exists,
    the email already exists, or the email format is incorrect.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\item
  \textbf{Security Notes}:

  \begin{itemize}
  \tightlist
  \item
    Passwords are hashed before being stored.
  \item
    Email validation is performed to check the format.
  \end{itemize}
\end{itemize}

\hypertarget{user-login}{%
\paragraph{2. User Login}\label{user-login}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/login}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: This endpoint is used for user authentication.
\item
  \textbf{Request Body}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{login}: String (required) - The user's username or email
    address.
  \item
    \texttt{password}: String (required) - The user's password.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message describing the outcome.
  \item
    \texttt{user}: Object - Contains user information (username and
    email).
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{400\ Bad\ Request} if either field is missing or if
    the user is not found.
  \item
    Returns \texttt{401\ Unauthorized} if the password does not match.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\item
  \textbf{Security Notes}:

  \begin{itemize}
  \tightlist
  \item
    Password verification is performed using bcrypt.
  \end{itemize}
\end{itemize}

\hypertarget{fetch-user-profile}{%
\paragraph{3. Fetch User Profile}\label{fetch-user-profile}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/user/:username}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Fetches the profile details of a specific user
  by their username.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The username of the user
    whose profile is being requested.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{user}: Object - Contains the requested user's information
    (excluding password).
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{404\ Not\ Found} if the user does not exist.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{fetch-all-users}{%
\paragraph{4. Fetch All Users}\label{fetch-all-users}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/users}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Retrieves a list of all users. This endpoint is
  intended for admin use.
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{users}: Array - A list of user objects, each containing user
    information (excluding passwords).
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{401\ Unauthorized} if the user is not authorized
    (non-admin).
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{update-user-information}{%
\paragraph{5. Update User Information}\label{update-user-information}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/user/:username}
\item
  \textbf{Method}: \texttt{PUT}
\item
  \textbf{Description}: Allows users to update their account
  information.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The current username of the
    user whose profile is being updated.
  \end{itemize}
\item
  \textbf{Request Body} (Any or all of the following):

  \begin{itemize}
  \tightlist
  \item
    \texttt{newUsername}: String (optional) - The new username for the
    user.
  \item
    \texttt{email}: String (optional) - The new email address for the
    user.
  \item
    \texttt{dateOfBirth}: Date (optional) - The new date of birth for
    the user.
  \item
    \texttt{countryOfOrigin}: String (optional) - The new country of
    origin for the user.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message describing the outcome.
  \item
    \texttt{user}: Object - Contains the updated user's information.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{400\ Bad\ Request} if the new username or email
    already exists, or if the email format is incorrect.
  \item
    Returns \texttt{404\ Not\ Found} if the original user is not found.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\item
  \textbf{Security Notes}:

  \begin{itemize}
  \tightlist
  \item
    Ensure this endpoint is accessible only to the authenticated user or
    users with admin privileges.
  \item
    Validate the email format before processing updates.
  \end{itemize}
\end{itemize}

\hypertarget{delete-user}{%
\paragraph{6. Delete User}\label{delete-user}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/user/:username}
\item
  \textbf{Method}: \texttt{DELETE}
\item
  \textbf{Description}: Deletes a specific user's account.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The username of the user to
    be deleted.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message describing the outcome.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{404\ Not\ Found} if the user does not exist.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{fetch-user-stats}{%
\paragraph{7. Fetch User Stats}\label{fetch-user-stats}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/stats/:username}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Retrieves the statistics associated with a
  specific user.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The username of the user
    whose stats are being requested.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{data}: Object - Contains the user's statistics.

    \begin{itemize}
    \tightlist
    \item
      \texttt{username}: String - The username of the user.
    \item
      \texttt{completionPercentages}: Array of Numbers - An array of
      completion percentages.
    \item
      \texttt{points}: Array of Numbers - An array of points.
    \item
      \texttt{correctAnswers}: Number - The count of correct answers.
    \item
      \texttt{incorrectAnswers}: Number - The count of incorrect
      answers.
    \item
      \texttt{totalCompletion}: Number - The average of all completion
      percentages.
    \item
      \texttt{totalPoints}: Number - The sum of all points.
    \item
      \texttt{correctAnswersPercentage}: Number - The percentage of
      correct answers.
    \item
      \texttt{progress}: Array of Objects - Each object contains
      \texttt{blockId} and \texttt{minilessonId} representing the user's
      progress.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{404\ Not\ Found} if the stats for the given username
    are not found.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{update-user-stats}{%
\paragraph{8. Update User Stats}\label{update-user-stats}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/stats/:username}
\item
  \textbf{Method}: \texttt{PUT}
\item
  \textbf{Description}: Updates the statistics associated with a
  specific user.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required) - The username of the user
    whose stats are to be updated.
  \end{itemize}
\item
  \textbf{Request Body} (Any or all of the following):

  \begin{itemize}
  \tightlist
  \item
    \texttt{newPoints}: Number (optional) - The new points to be added
    to the user's total on the index of \texttt{locationId}.
  \item
    \texttt{locationId}: Number (optional) - Identifier of location
    where \texttt{newPoints} are to be increased.
  \item
    \texttt{correctAnswers}: Number (optional) - The amount to increase
    total correctAnswers of a user.
  \item
    \texttt{incorrectAnswers}: Number (optional) - The amount to
    increase total incorrectAnswers of a user.
  \item
    \texttt{progress}: Object (optional) - An object containing the
    progress update. When this field is updated, the completion
    percentages are automatically recalculated and updated. The object
    should have the following structure:

    \begin{itemize}
    \tightlist
    \item
      \texttt{locationName}: String (required for progress update) - The
      name of the location.
    \item
      \texttt{locationId}: Number (required for progress update) - The
      index in the progress array to update.
    \item
      \texttt{lessonId}: Number (required for progress update) - The new
      lesson ID to set.
    \item
      \texttt{minilessonId}: Number (required for progress update) - The
      new minilesson ID to set.
    \item
      \texttt{blockId}: Number (required for progress update) - The new
      block ID to set.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message describing the outcome.
  \item
    \texttt{data}: Object - Contains the updated stats for the user.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{400\ Bad\ Request} if the provided data is invalid
    or if required fields are missing.
  \item
    Returns \texttt{404\ Not\ Found} if no stats are found for the given
    username.
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{general-leaderboard}{%
\paragraph{9. General Leaderboard}\label{general-leaderboard}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/leaderboard}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: This method provides a leaderboard of the first
  100 users, sorted by their total points. It supports optional
  filtering based on the user's age and country of origin. Each user's
  entry includes their username, country, age, total points, and rank.
\item
  \textbf{Query Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{age} (optional): Integer - Specifies the age to filter the
    leaderboard.
  \item
    \texttt{country} (optional): String - Specifies the country to
    filter the leaderboard.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{leaderboard}: Array of Objects - List of user rankings, each
    containing:

    \begin{itemize}
    \tightlist
    \item
      \texttt{username}: String - The user's username.
    \item
      \texttt{countryOfOrigin}: String - The user's country of origin.
    \item
      \texttt{age}: Number - The user's age, calculated from their date
      of birth.
    \item
      \texttt{totalPoints}: Number - The total points accumulated by the
      user.
    \item
      \texttt{rank}: Number - The user's rank in the leaderboard. Users
      with the same number of points share the same rank.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    On server-side errors, returns \texttt{500\ Internal\ Server\ Error}
    with an error message.
  \end{itemize}
\end{itemize}

\hypertarget{get-leaderboard-by-user}{%
\paragraph{10. Get Leaderboard By User}\label{get-leaderboard-by-user}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/leaderboard/:username}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Retrieves the ranking information of a specific
  user across different leaderboards (general, age-based, and
  country-based). This method finds the user's rank in each of these
  categories. If the user is not found, a 404 error is returned.
\item
  \textbf{Path Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String - The username of the user for whom to
    retrieve leaderboard data.
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{userData}: Object - Contains the ranking information of the
    user in different leaderboards. It includes:

    \begin{itemize}
    \tightlist
    \item
      \texttt{username}: String - The user's username.
    \item
      \texttt{age}: Number - The user's age, calculated from their date
      of birth.
    \item
      \texttt{country}: String - The user's country of origin.
    \item
      \texttt{generalRank}: Number - The user's rank in the general
      leaderboard.
    \item
      \texttt{ageRank}: Number - The user's rank in the age-specific
      leaderboard.
    \item
      \texttt{countryRank}: Number - The user's rank in the
      country-specific leaderboard.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    If the user is not found, returns \texttt{404\ Not\ Found} with an
    appropriate error message.
  \item
    On server-side errors, returns \texttt{500\ Internal\ Server\ Error}
    with an error message.
  \end{itemize}
\end{itemize}

\hypertarget{langchain-endpoints}{%
\subsubsection{Langchain endpoints}\label{langchain-endpoints}}

\hypertarget{get-welcome-message}{%
\paragraph{1. Get Welcome Message}\label{get-welcome-message}}

\begin{itemize}
\item
  \textbf{Endpoint}: \texttt{api/langchain/welcome}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: Generates a personalized welcome message for a
  new or returning user. For new users, the message introduces the
  module, the user's guide (friend), and provides both a child-friendly
  and a parent-focused description of the module. For returning users,
  it includes a motivational message, highlighting their progress and
  the next steps in their learning journey. This message is generated
  using the OpenAI language model.
\item
  \textbf{Request Body}:

  The request body is a JSON object with the following structure:
  \texttt{json\ \ \ \{\ \ \ \ \ "currentBlock":\ 0,\ \ \ \ \ "currentLesson":\ 0,\ \ \ \ \ "currentMinilesson":\ 0,\ \ \ \ \ "land":\ \{\ \ \ \ \ \ \ "id":\ 0,\ \ \ \ \ \ \ "name":\ "string",\ \ \ \ \ \ \ "friendName":\ "string",\ \ \ \ \ \ \ "friendType":\ "string",\ \ \ \ \ \ \ "moduleName":\ "string",\ \ \ \ \ \ \ "moduleDecriptionKids":\ "string",\ \ \ \ \ \ \ "moduleDescriptionParents":\ "string"\ \ \ \ \ \},\ \ \ \ \ "progress":\ 0,\ \ \ \ \ "user":\ \{\ \ \ \ \ \ \ "username":\ "string",\ \ \ \ \ \ \ "dateOfBirth":\ "string",\ \ \ \ \ \ \ "preferredLanguage":\ "string"\ \ \ \ \ \}\ \ \ \}}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - The customized welcome message.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{get-lesson-message}{%
\paragraph{2. Get Lesson Message}\label{get-lesson-message}}

\begin{itemize}
\item
  \textbf{Endpoint}: \texttt{/api/langchain/lessonMessage}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: Generates a message for the current mini-lesson
  or a quiz based on the user's progress. For lesson messages, it
  includes a theoretical explanation and a playful scenario. For quiz
  messages, it generates a 5-question quiz based on the mini-lesson
  content, formatted as JSON objects with question details. This
  approach is aimed at enhancing the learning experience in a fun,
  interactive way, using the OpenAI language model. This call
  automatically updates user progress.
\item
  \textbf{Request Body}:

  The request body is a JSON object with the following structure:

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
  \DataTypeTok{"currentBlock"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
  \DataTypeTok{"currentLesson"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
  \DataTypeTok{"currentMinilesson"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
  \DataTypeTok{"land"}\FunctionTok{:} \FunctionTok{\{}
    \DataTypeTok{"id"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"name"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
    \DataTypeTok{"friendName"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
    \DataTypeTok{"friendType"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
    \DataTypeTok{"moduleName"}\FunctionTok{:} \StringTok{"string"}
  \FunctionTok{\},}
  \DataTypeTok{"user"}\FunctionTok{:} \FunctionTok{\{}
    \DataTypeTok{"username"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
    \DataTypeTok{"dateOfBirth"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
    \DataTypeTok{"preferredLanguage"}\FunctionTok{:} \StringTok{"string"}
  \FunctionTok{\}}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - The lesson message.
  \item
    \texttt{nextIds}: Object - Next \texttt{lessonId},
    \texttt{minilessonId} and \texttt{blockId} that await for user's
    completion. All fields are null if location is completely done.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{get-ai-answer-from-user-message}{%
\paragraph{3. Get AI Answer From User
Message}\label{get-ai-answer-from-user-message}}

\begin{itemize}
\item
  \textbf{Endpoint}: \texttt{/api/langchain/userMessage}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: Save message that user have sent and respond
  with AI-generated message in chat-like conversation.
\item
  \textbf{Request Body}:

  The request body is a JSON object with the following structure:

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
  \DataTypeTok{"currentLesson"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
  \DataTypeTok{"currentMinilesson"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
  \DataTypeTok{"land"}\FunctionTok{:} \FunctionTok{\{}
      \DataTypeTok{"id"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
      \DataTypeTok{"name"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
      \DataTypeTok{"friendName"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
      \DataTypeTok{"friendType"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
      \DataTypeTok{"moduleName"}\FunctionTok{:} \StringTok{"string"}

  \FunctionTok{\},}
  \DataTypeTok{"user"}\FunctionTok{:} \FunctionTok{\{}
      \DataTypeTok{"username"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
      \DataTypeTok{"dateOfBirth"}\FunctionTok{:} \StringTok{"string"}\FunctionTok{,}
      \DataTypeTok{"preferredLanguage"}\FunctionTok{:} \StringTok{"string"}

  \FunctionTok{\},}
  \DataTypeTok{"message"}\FunctionTok{:} \StringTok{"string"}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: String - A message we want.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{get-freeform-chat-message}{%
\paragraph{4. Get Freeform Chat
Message}\label{get-freeform-chat-message}}

\begin{itemize}
\item
  \textbf{Endpoint}: \texttt{/api/langchain/freeformUserMessage}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: This endpoint enables a freeform chat experience
  in the ``Imagination Jungle'' module, where users interact with Cleo
  the Chameleon. It supports both text-based conversations and image
  generation based on user input. For text chats, Cleo offers
  educational and respectful responses. Inappropriate or offensive
  content triggers a response emphasizing positive communication. If the
  user opts for image generation, the endpoint returns an image URL
  based on the provided message.
\item
  \textbf{Request Body}:

  The request body should be a JSON object with the following structure:
  ```json \{ ``user'': \{ ``username'': ``string'', ``dateOfBirth'':
  ``string'', ``preferredLanguage'': ``string'' \}, ``landId'': 5,
  ``message'': ``string'', ``type'': ``text'' // or ``image'' to
  generate an image response \}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: Depending on the \texttt{type} parameter in the
    request, this can be either:

    \begin{itemize}
    \tightlist
    \item
      String - The response from Cleo the Chameleon for text-based
      chats.
    \item
      String - A URL to the generated image for image requests.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for server-side
    issues.
  \end{itemize}
\end{itemize}

\hypertarget{implementation-details}{%
\subparagraph{Implementation Details:}\label{implementation-details}}

This endpoint corresponds to the \texttt{getFreeformMessage} function in
the backend. It processes the user's message, and depending on the
requested type (text or image), invokes the appropriate Python script.
For text responses, the \texttt{executePython} function uses OpenAI's
language model to generate Cleo's response based on the
\texttt{templateText} input template, considering the user's age,
language, and chat history. For image responses, it executes a different
script to generate an image URL based on the message. The endpoint also
handles detection of inappropriate or offensive content to ensure a
respectful chat environment.

\hypertarget{get-user-chat}{%
\paragraph{5. Get User Chat}\label{get-user-chat}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/chat}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Retrieves chat of user for location.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{username}: String (required)
  \item
    \texttt{location\_id}: Integer (required)
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{messages}: List of chat messages in which each message
    contains sender (User or AI) and content.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{get-lessons-and-mini-lessons-names}{%
\paragraph{6. Get Lessons and Mini-Lessons
Names}\label{get-lessons-and-mini-lessons-names}}

\begin{itemize}
\tightlist
\item
  \textbf{Endpoint}: \texttt{/api/langchain/lessonNames}
\item
  \textbf{Method}: \texttt{GET}
\item
  \textbf{Description}: Retrieves lessons and mini lessons names for
  location.
\item
  \textbf{URL Parameters}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{locationName}: String (required)
  \end{itemize}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: List of lessons in which each lesson containts its
    name and array of mini-lessons names.
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for any server-side
    errors.
  \end{itemize}
\end{itemize}

\hypertarget{evaluate-user-answer-to-a-question}{%
\paragraph{7. Evaluate User Answer to a
Question}\label{evaluate-user-answer-to-a-question}}

\begin{itemize}
\item
  \textbf{Endpoint}: \texttt{/api/langchain/evaluateQuestion}
\item
  \textbf{Method}: \texttt{POST}
\item
  \textbf{Description}: This endpoint evaluates a user's answer to a
  given question. It determines the relevance and correctness of the
  answer compared to a provided example of a correct answer. The
  evaluation and explanation are generated using the OpenAI language
  model, tailored to the specified language.
\item
  \textbf{Request Body}:

  The request body should be a JSON object with the following structure:
  ```json \{ ``user'': \{ ``username'': ``string'',
  ``preferredLanguage'': ``string'' \}, ``question'': ``string'',
  ``userAnswer'': ``string'', ``correctAnswerExample'': ``string'' \}
\item
  \textbf{Response}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{success}: Boolean - Indicates if the operation was
    successful.
  \item
    \texttt{message}: JSON Object - Contains two fields:

    \begin{itemize}
    \tightlist
    \item
      \texttt{evaluation}: String - Indicates the correctness of the
      user's answer (`correct' or `incorrect').
    \item
      \texttt{explanation}: String - Provides a rationale for the
      evaluation of the user's answer.
    \end{itemize}
  \end{itemize}
\item
  \textbf{Error Handling}:

  \begin{itemize}
  \tightlist
  \item
    Returns \texttt{500\ Internal\ Server\ Error} for server-side
    issues.
  \end{itemize}
\end{itemize}

\hypertarget{implementation-details-1}{%
\subparagraph{Implementation Details:}\label{implementation-details-1}}

The \texttt{getQuestionEvaluation} function in the backend handles this
endpoint. It receives the user's answer, the question, the preferred
language, and an example of a correct answer. These inputs are then
passed to a Python script that utilizes the OpenAI language model to
evaluate the answer's correctness and relevance. The script employs
structured output parsing to ensure the response is formatted as a JSON
object with the evaluation and explanation.

\hypertarget{examples-and-tutorials}{%
\subsection{Examples and Tutorials}\label{examples-and-tutorials}}

Dive into this section for a series of step-by-step guides and
real-world use-case examples designed to help you seamlessly interact
with and harness the full potential of the Finance Friends platform.
Whether you're a new user or looking to explore more advanced features,
these tutorials and scenarios will provide the practical insights you
need.

\hypertarget{step-by-step-guides}{%
\subsubsection{Step-by-Step Guides}\label{step-by-step-guides}}

\hypertarget{getting-started-with-user-registration}{%
\paragraph{1. Getting Started with User
Registration}\label{getting-started-with-user-registration}}

Navigate the initial steps of joining the Finance Friends community by
creating a new user account. - \textbf{Prepare Registration Details}:
Gather essential details such as username, email, and password. -
\textbf{Send Registration Request}: Utilize the \texttt{/api/register}
endpoint to submit your registration details. - \textbf{Handle
Response}: Confirm successful registration and note any instructions or
welcome messages.

\hypertarget{interacting-with-the-chatbot}{%
\paragraph{2. Interacting with the
Chatbot}\label{interacting-with-the-chatbot}}

Engage with our intelligent chatbot for a personalized learning journey
and instant support. - \textbf{Set Up User Profile}: Ensure your profile
reflects your learning preferences and style. - \textbf{Initiate
Conversation}: Use the designated endpoint to send your queries or
messages to the chatbot. - \textbf{Process Chatbot Response}: Understand
and act on the guidance provided by the chatbot, tailoring your learning
path accordingly.

\hypertarget{use-case-driven-examples}{%
\subsubsection{Use-Case Driven
Examples}\label{use-case-driven-examples}}

\hypertarget{scenario-1-tracking-learning-progress}{%
\paragraph{Scenario 1: Tracking Learning
Progress}\label{scenario-1-tracking-learning-progress}}

Monitor your journey through the diverse financial modules and visualize
your achievements over time. - \textbf{Access Progress Dashboard}:
Utilize specific features or endpoints to view your learning milestones.
- \textbf{Analyze Performance}: Gain insights into your quiz scores,
module completion rates, and areas for improvement.

\hypertarget{scenario-2-participating-in-quizzes}{%
\paragraph{Scenario 2: Participating in
Quizzes}\label{scenario-2-participating-in-quizzes}}

Test your knowledge and reinforce your learning through interactive
quizzes, receiving instant feedback. - \textbf{Engage with Quiz
Modules}: Navigate to the quiz section corresponding to your current
learning module. - \textbf{Submit Responses}: Answer the quiz questions
and submit your responses through the platform. - \textbf{Review
Feedback}: Receive real-time evaluation of your answers and understand
the rationale behind each solution.

By following these guides and exploring the use-case scenarios, you'll
be able to make the most of the Finance Friends platform, turning
financial learning into a fun, engaging, and rewarding experience. Each
step and scenario is designed to enhance your interaction with the
platform, ensuring a smooth and productive journey into the world of
financial literacy.

\hypertarget{project-management-and-design-tools}{%
\subsection{Project Management and Design
Tools}\label{project-management-and-design-tools}}

The development of Finance Friends is meticulously organized and
creatively designed using industry-leading tools:

\hypertarget{notion-for-project-management}{%
\subsubsection{Notion for Project
Management}\label{notion-for-project-management}}

\begin{itemize}
\tightlist
\item
  \textbf{Overview}: Our team uses
  \href{https://kvrancic.notion.site/Projekt-R-FINANCE-FRIEND-dcb6bebd85f348d3a2020f5d7a4dfdee?pvs=4}{Notion}
  as the central hub for project management. It helps us track progress,
  organize tasks, and document every phase of the project.
\end{itemize}

\hypertarget{figma-for-design}{%
\subsubsection{Figma for Design}\label{figma-for-design}}

\begin{itemize}
\tightlist
\item
  \textbf{Creativity at Work}: The user interface of Finance Friends is
  crafted using
  \href{https://www.figma.com/file/5AHqaEfYj0bNcMXTiKgUHE/Finance-Friends-UI?type=design\&node-id=0\%3A1\&mode=design\&t=lhfWHWlmmc4kGdFD-1}{Figma},
  ensuring an engaging and child-friendly experience. Figma aids our
  designers in creating intuitive and attractive designs that resonate
  with our young audience.
\end{itemize}

\hypertarget{repositories}{%
\subsection{Repositories}\label{repositories}}

Our codebase is split into backend and frontend repositories, each
containing all necessary components and documentation for setting up and
running the respective parts of the platform.

\hypertarget{backend-repository}{%
\subsubsection{Backend Repository}\label{backend-repository}}

\begin{itemize}
\tightlist
\item
  \textbf{Technology Stack}: The backend is built on Node.js and
  MongoDB, supplemented by Python scripts utilizing LangChain for
  advanced functionalities.
\item
  \textbf{Repository Link}:
  \href{https://github.com/FinanceFriend/backend}{Backend Repository}
\end{itemize}

\hypertarget{frontend-repository}{%
\subsubsection{Frontend Repository}\label{frontend-repository}}

\begin{itemize}
\tightlist
\item
  \textbf{User Interface}: The frontend is developed using React,
  ensuring a dynamic and responsive user experience.
\item
  \textbf{Repository Link}:
  \href{https://github.com/FinanceFriend/frontend}{Frontend Repository}
\end{itemize}

\hypertarget{team-and-contributions}{%
\subsection{Team and Contributions}\label{team-and-contributions}}

Finance Friends is brought to life by a dedicated team of developers and
guided by experienced mentors. Our project thrives on collaboration and
academic contributions.

\hypertarget{authors}{%
\subsubsection{Authors}\label{authors}}

\begin{itemize}
\tightlist
\item
  Karlo Vrančić
\item
  Filip Buljan
\item
  Pavle Ergović
\item
  Karla Šmuk
\item
  Martina Rodić
\end{itemize}

\hypertarget{mentor}{%
\subsubsection{Mentor}\label{mentor}}

\begin{itemize}
\tightlist
\item
  \textbf{Guidance and Insight}: Our project is mentored by Prof.~Ivica
  Botički, whose expertise and guidance have been invaluable in the
  development of Finance Friends.
\end{itemize}

\hypertarget{academic-contributions}{%
\subsubsection{Academic Contributions}\label{academic-contributions}}

\begin{itemize}
\tightlist
\item
  \textbf{Collaboration}: As a university project, we welcome feedback,
  suggestions, and contributions from fellow students and faculty
  members. Please refer to our contribution guidelines in the respective
  repositories for more information.
\end{itemize}

\hypertarget{license-and-acknowledgements}{%
\subsection{License and
Acknowledgements}\label{license-and-acknowledgements}}

\hypertarget{license}{%
\subsubsection{License}\label{license}}

\begin{itemize}
\tightlist
\item
  \textbf{Academic Integrity}: This project is part of an academic
  program and adheres to the university's guidelines and policies.
\end{itemize}

\hypertarget{acknowledgements}{%
\subsubsection{Acknowledgements}\label{acknowledgements}}

\begin{itemize}
\tightlist
\item
  \textbf{Special Thanks}: Our heartfelt gratitude goes to Prof.~Ivica
  Botički for his continuous support and mentorship. His insights have
  significantly shaped the trajectory and success of Finance Friends.
\end{itemize}