File: docs/TECHNICAL_GUIDE.md

🛠️ Technical Documentation

This document describes the technical architecture and code for the Gita Netlify project.

📁 Project Structure

  • /index.html: The main HTML file. Contains all DOM elements.
  • /css/styles.css: All application styles, including theme variables.
  • /js/app.js: Main application logic, event listeners, and state management.
  • /js/themes.js: Handles theme switching and saving to localStorage.
  • /data/: Contains all application data, structured as JavaScript files:
    • chapter-1.js ... chapter-18.js: Contains the core text data for each chapter, including transliteration, word-by-word meanings, and expert commentaries. This data is loaded based on user selection in the English/Hindi/Sanskrit tabs.
    • epithets.js: The database for the epithet popup feature.
    • gita-db.js: Initializes the main chapter database object (CHAPTER_DATA_DB).
  • /audio/: Contains all m4a and mp3 audio files, organized by narrator.
  • /images/: Contains all static images (icons, logos, etc.).
  • /github/: Contains related files from GitHub.

📄 index.html

The index.html file provides the core structure. Key element IDs used by the JavaScript files are:

Main Controls

  • #search-input: The user text-input for search.
  • #search-clear-btn: The button to clear the search input.
  • #chapter-select: The dropdown menu for chapter selection.
  • #verse-select: The dropdown menu for verse selection.
  • #prev-chapter-btn: Button to navigate to the previous chapter.
  • #next-chapter-btn: Button to navigate to the next chapter.
  • #prev-verse-btn: Button to navigate to the previous verse.
  • #next-verse-btn: Button to navigate to the next verse.
  • #recitation-select: The dropdown to select the audio narrator (Meenu or Vibhushan).
  • #stats-btn: The icon/button to open the statistics modal.
  • #settings-btn: The gear icon (⚙️) to open the settings modal.

Content Display

  • #verse-container: The main main element where chapter/verse content is rendered.
  • #global-audio-player: The <audio> element for playing chapter audio.
  • #search-results-container: The main container for displaying search results.
  • #search-results-list: The div where individual search results are populated.

Modals & Popups

  • #settings-modal: The modal for theme settings.
  • #theme-toggle: The checkbox/switch to toggle between light/dark themes.
  • #theme-picker-grid: The container holding the individual theme color swatches.
  • #stats-modal: The modal for statistics.
  • #epithet-tooltip: The popup div that displays epithet definitions.
  • #epithet-tooltip-title: The h4 title for the epithet.
  • #epithet-tooltip-text: The <p> tag for the epithet's description.
  • #ai-chat-modal: The modal for the AI chat feature.
  • #ai-chat-query: The text input for the user's AI chat question.
  • #ai-chat-submit-btn: The submit button for the AI chat query.

🎨 css/styles.css

The stylesheet is organized as follows:

  • Root Variables: :root contains all base colors, fonts, and spacing variables. The theme-switching logic in themes.js works by updating these CSS variables.
  • General Layout: Styles for body, header, main, footer.
  • Components: Styles for specific components like .player, .modal, .chapter-list.
  • Utility Classes: Helper classes (e.g., .hidden, .active).

⚙️ js/app.js

This single file contains all application logic, event listeners, and state management, including theme and settings control. The functions are organized as follows:

1. Initialization & Core Navigation

These functions set up the page and handle chapter/verse navigation.

populateChapterSelect() Runs on load to create the 18 chapter options in the #chapter-select dropdown. populateVerseSelect(chapterNum) Populates the #verse-select dropdown based on the number of verses in the given chapter. loadChapter(chapterNum, targetSimpleVerse = '1') The main function to load and display all content for a selected chapter. jumpToVerseFromSelect(verseNumString) Event listener for the verse dropdown to scroll to the selected verse. jumpToVerse(chapterNum, verseNum) Scrolls the page to the specified verse card. goToNextChapter() goToPrevChapter() updateNavButtons(chapterNum) Enables/disables the prev/next chapter buttons. goToNextVerse() goToPrevVerse() updateVerseNavButtons()

2. Content Rendering

These functions build the HTML for verses, tabs, and epithets.

createVerseCard(verse, index) Creates the main HTML card for a single verse, including its text and audio button. createTabsInterface(translations, commentaries, verseIndex) Builds the tabbed (English/Hindi/Sanskrit) interface for commentaries. showLangTab(event, tabId) Handles the click event on a language tab to show its content. highlightEpithets(text) Scans text and wraps any known epithets in a clickable <span>. buildEpithetRegex() Creates the master regex from the epithets.js data. showEpithet(event, epithetKey) Displays the #epithet-tooltip popup with the definition. hideEpithet()

3. Verse Observer (Scrollspy)

These functions track which verse is currently on screen.

setupVerseObserver() Initializes the IntersectionObserver. handleVerseIntersection(entries, observer) The observer's callback, which updates the URL and highlighted verse. highlightVerse(element) Applies a visual highlight to the active verse. customScrollToElement(element) A helper function for smooth scrolling.

4. Search Functionality

performSearch(query) Executes the search over the data. displaySearchResults(results, query) Renders the list of search results. highlightMatch(text, query) Helper function to bold the matching text in results. clearSearch()

5. Audio Control

playSanskritAudio(button, verseNum) Plays the audio for a specific verse. stopCurrentAudio() Stops any currently playing verse audio. setButtonState(button, state) Updates the play/pause icon on a button. resetCurrentButton()

6. AI (Gemini) Chat Modal

openAiChat(verseNum, iast, fullContext) Opens the AI chat modal with the verse context. closeAiChat() handleAiChatSubmit() Gets the user query and calls the Gemini API. callGeminiChat(verseText, userQuestion) The async function that makes the API request to Gemini. displayAiResponse(text, isError = false) Shows the AI's answer or an error in the modal. checkApiKey(featureName) Checks if the API key is set before allowing a feature.

7. Theme & Settings Modal

openSettingsModal() closeSettingsModal() populateThemePicker() Creates the 20 theme swatches in the settings modal. applyTheme(themeIndex) Applies a theme by setting CSS root variables. toggleThemeMode(event) The event handler for the light/dark theme toggle switch. updateActiveTheme() Updates the visual state of the theme picker. saveSettings() Saves API key, theme, and mode to localStorage. loadSettings() Loads settings from localStorage on page start. getSavedThemeIndex() getSavedMode() updateApiKeyStatus()

8. Statistics Modal

openStatsModal() closeStatsModal() calculateAndDisplayStats() Populates the statistics modal with data.

9. Utility

showLoader(isLoading) Shows or hides the main page loader.

🎨 js/themes.js

This file does not contain application logic. Its sole purpose is to define and store the theme data.

  • It contains a single large constant (e.g., THEMES or similar), which is an array or object holding the color definitions for all 20+ light and dark theme palettes.
  • This data is loaded by index.html and then used by the functions in app.js (like populateThemePicker and applyTheme) to build the settings modal and apply the theme colors via CSS variables.