Frontend Redesign

[sammybigbux]

DeckHub Frontend Development Guide

Welcome to the DeckHub project! This project is an interactive platform designed to help students prepare for certification exams using modern cognitive research techniques. DeckHub offers multiple-choice and open-ended question formats, with real-time feedback to guide learners through exam content.

Issue Overview

DeckHub is undergoing a UI redesign to improve user experience. Your task as the frontend developer is to implement the new UI based on the wireframe provided in Figma and apply it to the existing platform.

Key Resources:

• Wireframe: Demo of Wireframe (Wireframe itself provided on request)
• Current Website: DeckHub Live Platform
• Project Repository: GitHub Repo

You can test your changes by either running the project locally (setup instructions are provided later in this document) or by pushing to the staging branch to deploy the updates to our cloud environment.

The following sections will guide you through the project structure and the steps required to set up and deploy the project.

Local Setup

Secure files from Google Drive are required to host this locally but if you push to staging branch the Github Actions will deploy to Google Cloud.

1. Install dependencies:

    npm install

2. Set up a .env file in the main directory:

    LOCAL=True
    OPEN_API_KEY=(your OpenAI key)

3. Set up a .env file in the backend directory:

    STRIPE_SECRET_KEY=(your Stripe secret key)
    WEBHOOK_SECRET=(your webhook secret)

4. Navigate to the backend directory and install Python requirements:

    pip install -r requirements.txt

5. Place the firebase_key.json file into the backend directory:

   • This is a secret file located in the Google Drive and needs to be requested from the project owner.

6. Create an OpenAI assistant and update the assistant ID:

   • Visit OpenAI Playground, create an AI assistant, and use the prompt provided in the Google Drive.
   • Update the assistant_id at the top of the app.py file to the assistant you created. You will need to replace the current assistant ID with the one generated from the assistant you're using:

     assistant_id = "asst_your_new_assistant_id"

7. Run the backend:

   • From the /src/backend directory, start the backend server:

     python app.py

8. Run the frontend:

   • Go back to the main directory, and start the development server:

     npm run dev

Project Structure

You can find a guide to each section in the README.md files in their respective directories. The project consists of the following main components:

• Frontend: Located in the /routes directory, the frontend is built using Vite and Svelte. It handles the user interface, interactions, and communication with the backend services.

• Backend: Found in the /src/backend directory, the backend is built using Flask. It handles API endpoints, user sessions, and database interactions via Firebase. The backend also includes routes for managing user

Front end overview

The frontend of the platform is built using Svelte with TypeScript and utilizes Svelte stores for state management, Firebase for authentication (userId, isLoggedIn), and Skeleton UI for components like Avatars and ProgressBars. It interacts with a backend hosted on either localhost or a cloud server (base_url).

Key Pages and Functionality

1. My-Cards Page (my-cards.svelte)

• Purpose: Displays the user's purchased decks and allows them to search through their decks.
• Stores:
  • allDecks and userOwnedDeckNames store the available decks and the decks owned by the user.
  • searchQuery stores the search input, and the derived store filteredDecks filters decks based on the search query and ownership.
• Functions:
  • handleInput updates the search input field.
  • On mount, the page fetches all decks using the /get_decks endpoint and then fetches the user-specific decks using the /get_user_decks endpoint, passing the Firebase token for authentication (idToken).
• UI Elements:
  • Decks are listed with an option to either download (for owned decks) or purchase (for decks not owned).

2. Search Page (search.svelte)

• Purpose: A place for users to search all products and decks.
• Stores:
  • searchQuery is used to store user input from the search bar.
  • decks holds all decks fetched from the backend.
  • filteredDecks is derived from searchQuery and decks to filter the decks based on the user’s input.
• Functions:
  • handleInput updates searchQuery as the user types.
  • On mount, the function makes a GET request to /get_decks to populate decks. Additionally, it fetches the user’s decks via /get_user_decks using the Firebase token (idToken).
• UI Elements:
  • A search bar filters available decks.
  • Each deck has buttons to either purchase or open based on user ownership status.

3. User-Info Page (user-info.svelte)

• Purpose: Displays user account information such as payment info, past orders, and allows log out.
• Stores:
  • tabSet tracks which tab (Payment Information, Past Orders, Funding, Log out) is currently active.
• Functions:
  • onMount: Checks the URL hash to set the active tab.
• UI Elements:
  • The page consists of tabbed content where each tab shows a specific section of the user's information.

4. Chat Pages (Learn, Understand, Apply)

The chat pages (e.g., learn-multiple, learn-open, understand-multiple, apply-multiple) are built on similar structures with differences based on the mode (multiple choice or open-ended).

Learn-Multiple Page (learn-multiple.svelte)

• Purpose: Delivers multiple-choice questions to the user based on terms relevant to their study.
• Stores:
  • messageFeed holds the conversation history.
  • related_terms holds terms related to the current question.
  • currentTerm and currentQuestionData store the current question’s data.
• Functions:
  • retrieveTermsData: Fetches the user's progress (total and solved terms).
  • retrieveQuestion: Fetches the next question from the backend and updates the chat.
  • displayAnswerResponse: Displays feedback (correct/incorrect) when the user answers a question.
  • toggle_multi: Switches between multiple-choice and open-ended modes.
  • updateStatus: Updates the user’s progress after answering correctly.
  • sendMessage: Sends a user query to the backend and streams back a response.
• UI Elements:
  • The page includes a chat interface where the AI Coach guides the user through questions.
  • Users answer multiple-choice questions by clicking on buttons representing the options.

Learn-Open Page (learn-open.svelte)

• Purpose: Similar to learn-multiple but for open-ended questions.
• Key Differences:
  • Instead of multiple-choice, users submit their own written responses.
  • The function change_difficulty adjusts the AI's response difficulty.

General Components

Across all pages, common components include:

• Avatar: Displays the profile picture of the user or AI in the chat.
• ProgressBar: Shows the user's progress within the session (e.g., total terms completed out of total terms).
• Textareas for user input and buttons for interactions such as answering questions or navigating through sections.

Firebase Integration

• The userId store from Firebase handles user authentication.
• Firebase authentication (onAuthStateChanged) is used to get the user’s token (idToken), which is required for accessing protected routes like /get_user_decks and /get_terms_data.

Svelte Lifecycle Hooks

• onMount: Used on most pages to fetch initial data (e.g., decks, user info, or terms).
• onDestroy: Ensures that any environment setup (like threads or sessions) is cleaned up when the user navigates away.
  • For instance, cleanupEnv ensures the user’s environment is reset when they leave the chat pages.

Conclusion

The frontend of the platform is a combination of Svelte’s reactivity, store management, Firebase authentication, and backend interactions. Each page is structured around a core set of stores (decks, userDecks, messageFeed) and functions (retrieveQuestion, sendMessage, updateStatus) that ensure a dynamic and interactive learning experience for users. The UI is cleanly structured with Skeleton UI components to enhance visual consistency across the platform.

Backend Structure Overview

The backend primarily consists of:

• Main Application (app.py): This contains the core logic for handling requests from the frontend, interacting with Firebase Firestore and Cloud Storage, and managing users and terms through helper classes.
• Helper Classes:
  • UserManager: Manages users, their sessions, and their data files.
  • TermManager: Manages the terms and their statuses for each user.
• Firebase Initialization Files:
  • firebase_admin_init_cloud.py: Initializes Firebase Admin SDK for cloud deployments using credentials stored in Secret Manager.
  • firebase_admin_init_local.py: Initializes Firebase Admin SDK for local deployments using a service account file stored locally.

Application Workflow

app.py

The app.py file defines the main Flask application that handles various endpoints. It handles:

• Initializing and cleaning user environments (/initialize_env, /cleanup_env)
• Starting and managing user sessions (/start_thread, /send_message)
• Handling term-based functionality (/get_terms_data, /get_question, /update_status, etc.)
• Interacting with Firestore and Stripe for user data and payment processing (/create_user_if_not_exists, /api/create-checkout-session, /webhook)

Key components include:

1. Firebase Setup:

   • Firebase Admin SDK is initialized with either local or cloud credentials (depending on environment).
   • Firestore is used for storing user data, while Cloud Storage is used to store and retrieve the terms.json files for each user.

2. Data Loading:

   • The backend loads static data from learn_data.json, understand_data.json, and apply_data.json from the static_data directory. These are used in various term-based operations.

3. User and Term Management:

   • The backend relies heavily on UserManager and TermManager for managing user sessions and interacting with terms.json.
   • UserManager handles downloading/uploading the user’s terms.json from/to Cloud Storage and initializing sessions.
   • TermManager handles loading the user's terms data, providing questions, and updating the status of terms.

Helper Classes

UserManager

• Manages User Sessions:
  • For each user, a new TermManager instance is created to handle the user's interaction with the current module (learn, understand, apply).
  • The user's terms.json file is downloaded from Cloud Storage (or initialized with default terms) when a session is started and uploaded when the session ends.
• Functions:
  • initialize_user_session: Initializes a user’s session, creates a TermManager for them, and retrieves their terms.json file.
  • manage_user_json: Downloads the user's terms.json from Cloud Storage if it exists, or creates one from a default template if it doesn't.
  • cleanup_user_session: Uploads the terms.json file back to Cloud Storage and deletes the local file when the session is cleaned up.

TermManager

• Manages User's Terms:
  • Loads, updates, and provides terms-related data for a user.
  • Each user's progress (solved terms) is tracked in their terms.json.
• Functions:
  • _read_json: Reads the user's terms.json.
  • write_terms_to_file: Writes the updated terms to terms.json at the end of the session.
  • retrieve_question: Retrieves a question for the user based on their unsolved terms.
  • update_status: Updates the status of a term to mark it as solved.
  • get_correct_response and get_incorrect_response: Fetch correct or incorrect responses for terms.

Firebase Initialization Files

firebase_admin_init_cloud.py

• Fetches Firebase credentials from Google Secret Manager.
• Initializes the Firebase Admin SDK with those credentials for Cloud deployments.
• Initializes Firestore and Cloud Storage connections.

firebase_admin_init_local.py

• Loads Firebase credentials from a local firebase_key.json file for local development.
• Initializes the Firebase Admin SDK for local use.
• Initializes Firestore and Cloud Storage connections.

GitHub Actions CI/CD System Summary

The project uses GitHub Actions to automate the deployment of both the backend and frontend. Separate workflows handle deployments to the production and staging environments for both the backend and frontend.

---

1. Backend Deployment to Production (deployment-production-backend.yml)

• Trigger: This workflow triggers when changes are pushed to the main branch and those changes are within the src/backend/ directory.
• Key Steps:
  1. Checkout the code using actions/checkout@v4.
  2. Authenticate with Google Cloud using a service account.
  3. Build a Docker image for the backend and push it to Google Container Registry (GCR).
  4. Deploy the Docker image to Google Cloud Run (production) and set environment variables like OPENAI_API_KEY, STRIPE_SECRET_KEY, etc.
  5. Run backend tests using unittest.

2. Frontend Deployment to Production (deployment-production-frontend.yml)

• Trigger: This workflow triggers on pushes to the main branch.
• Key Steps:
  1. Checkout the code using actions/checkout@v4.
  2. Install dependencies and build the frontend using npm ci and npm run build.
  3. Authenticate with Google Cloud and deploy the frontend to Firebase Hosting (production) using the Firebase CLI.
  4. Echo the production URL for easy reference (https://deckhub.web.app/).

---

3. Backend Deployment to Staging (deploy-staging-backend.yml)

• Trigger: This workflow triggers on pushes to the staging branch and only runs if there are changes in the src/backend/ directory.
• Key Steps:
  1. Checkout the code using actions/checkout@v4.
  2. Authenticate with Google Cloud using a service account.
  3. Build a Docker image for the backend and push it to GCR.
  4. Deploy the Docker image to Google Cloud Run (staging) and set environment variables.
  5. Run backend tests using unittest, but this time against the staging URL (https://deckhub-backend-staging-1086653848406.us-central1.run.app).

4. Frontend Deployment to Staging (deploy-staging-frontend.yml)

• Trigger: This workflow triggers on pushes to the staging branch.
• Key Steps:
  1. Checkout the code using actions/checkout@v4.
  2. Install dependencies and build the frontend using npm ci and npm run build.
  3. Authenticate with Google Cloud and deploy the frontend to Firebase Hosting (staging).
  4. Echo the staging URL for easy reference (https://deckhubapp--staging-8dva1oxn.web.app/).

---

[ffshreyansh]

Hi @sammybigbux

Shreyansh this side, Can you please provide access to the Figma. Would love to have a quick meeting with you over the Ui revamp plan.

I have mostly worked with NextJs(React) & TailwindCSS. This is an ideal project for me as per my expertise. Let's collaborate.

[ffshreyansh]

@sammybigbux saw your google drive's video, If the Ui shown in the video is the expected output I will convert the UI into pixel perfect frontend, ensuring responsiveness in layout across all devices. With expected frontend functionality with clean code.

Let me know if we can connect!

Best Regards Shreyansh www.shreyanshkr.com www.tellcrow.com