Chartbot Technical Documentation

1. Overview

Chartbot is a high-performance, dependency-free conversational AI web application. It leverages modern web technologies to provide a seamless and feature-rich user experience. The application is designed to be a standalone client-side solution, interacting with external APIs for AI-powered chat and Text-to-Speech (TTS) functionalities. The entire user interface and application logic are encapsulated within three core files: index.html, styles.css, and script.js, demonstrating a minimalist yet powerful approach to web development.

2. Technology Stack

The project is built with a focus on simplicity and performance, intentionally avoiding any external frameworks or libraries for its core functionality.

• HTML5: For the semantic structure of the application.
• CSS3: For styling and layout, including modern features like Custom Properties (Variables), Flexbox, and Animations.
• JavaScript (ES6+): For all client-side logic, including state management, API interaction, and DOM manipulation.
• Groq API: The primary backend service for generating conversational responses and AI-powered TTS.
• Deepgram API: An alternative provider for AI-powered TTS.
• Browser Web APIs:
  • Fetch API for making asynchronous HTTP requests to the AI services.
  • SpeechSynthesis API for native browser-based text-to-speech.
  • SpeechRecognition API for voice-to-text input.
  • LocalStorage API for persisting user settings like the dark mode theme.

3. File Structure

The repository is organized into a flat structure for simplicity, with documentation and credits housed in a separate directory.

/
├── index.html              # The main HTML file, entry point of the application
├── styles.css              # All CSS styles for the application
├── script.js               # All JavaScript logic
├── HAMBURGER/
│   ├── documentation.html  # This documentation file
│   └── Credits.html        # Credits and attributions
└── ... (other repo files)
        

4. Core Concepts

4.1. State Management

The application state is managed through a set of global JavaScript variables. This approach was chosen for its simplicity and to avoid external dependencies. Key state variables include:

• conversationHistory: An array of objects that stores the back-and-forth between the user and the AI. This is crucial for providing context to the AI for follow-up questions. The history is trimmed to the last 3 pairs of messages to manage token usage.
• systemPrompt: A string that holds the current system prompt for the AI, which can be modified by the user via the /system command.
• isRecording, isVoiceMode, browserTtsEnabled, aiTtsEnabled: Boolean flags to manage the state of the microphone and TTS functionalities.

4.2. API Interaction

All interactions with external services are handled asynchronously using the Fetch API.

Groq API

The fetchGroqResponse function is responsible for sending the conversation history and system prompt to the Groq API's chat completions endpoint. The API key is retrieved from the input field and sent as a Bearer token in the Authorization header.

TTS Services (Groq & Deepgram)

The speak function orchestrates the TTS functionality. Based on user settings, it will either use the browser's native SpeechSynthesis or make a POST request to the selected AI TTS provider (Groq or Deepgram). The response is an audio blob, which is converted to an object URL and played using an HTML <Audio> element.

4.3. Command System

The command system is a client-side implementation that intercepts user inputs starting with a forward slash (/). The sendMessage function checks for this pattern and, if found, delegates the handling to the handleCommand function. This function uses a switch statement to route the command to the appropriate logic. This design allows for easy extension with new commands.

5. API Reference (Slash Commands)

The following commands are available to the user. They are processed entirely on the client-side.

Command	Arguments	Description
/help	None	Displays a formatted help message with all available commands and their usage.
/clear	None	Resets the conversationHistory array and clears the chatbox's inner HTML.
/theme	<color>	Dynamically changes the --primary-color CSS variable. Accepts a predefined set of colors: chartreuse, blue, red, purple.
/system	<prompt>	Updates the global systemPrompt variable with the provided text. This new prompt will be used in subsequent API calls to Groq.
/history	None	Iterates over the conversationHistory array and displays a formatted representation of the conversation history in the chatbox.

6. Customization

6.1. Adding a New Theme Color

To add a new theme color:

1. Open script.js.
2. In the handleCommand function, add your new color to the validColors array.
3. Add a corresponding entry to the colorMap object with the color name and its hex code.

// Example: Adding a 'green' theme
const validColors = ['chartreuse', 'blue', 'red', 'purple', 'green'];
// ...
const colorMap = {
    'chartreuse': '#7FFF00',
    'blue': '#007bff',
    'red': '#dc3545',
    'purple': '#6f42c1',
    'green': '#28a745'
};

6.2. Adding a New Command

To add a new command:

1. Open script.js.
2. In the handleCommand function, add a new case to the switch statement for your new command (e.g., case '/yourcommand':).
3. Implement the logic for your command within the new case.
4. Update the /help command's message to include your new command.

7. Contact

For any questions or support, please contact the developer at david.jad@icloud.com.