AI Assistant Documentation

Overview

AI Assistant is a web-based chat interface that allows users to interact with AI models through text and voice input. The application is hosted at ai.shieldstack.dev and provides a modern, responsive interface for AI-powered conversations.

Features

1. Text Chat Interface

A modern, responsive chat interface with real-time message streaming and markdown support.

2. Voice Input (Speech-to-Text)

Click the microphone button to speak your questions. The application uses the browser's built-in Web Speech API to convert speech to text.

3. Configurable AI Backend

Supports multiple AI API formats:

• OpenAI: Compatible with OpenAI API and similar endpoints
• Anthropic: Native support for Claude API
• Custom: Flexible format for other AI providers

4. Conversation History

The application maintains conversation context for coherent multi-turn dialogues.

5. Markdown Formatting

Supports formatted text, code blocks, and inline code for better readability.

Usage Guide

Getting Started

1. Navigate to https://ai.shieldstack.dev
2. Click the settings icon (gear) in the top right
3. Configure your AI API endpoint and credentials
4. Start chatting!

Using Text Input

1. Type your message in the text area at the bottom
2. Press Enter (or click the send button) to send
3. Wait for the AI to respond

Using Voice Input

1. Click the microphone button
2. Speak your question clearly
3. The speech will be automatically converted to text
4. The message will be sent automatically when you stop speaking

Configuration

API Settings

To configure the AI backend, click the settings icon and fill in the following:

Default Configuration

The application comes pre-configured with the following defaults:

API Endpoint: https://qqnqlyiy8exjax-5000.proxy.runpod.net/v1/chat/completions
API Format: openai
Model: gpt-3.5-turbo

Technical Details

Directory Structure

/var/www/ai/
├── index.html              # Main chat interface
├── assets/
│   ├── css/
│   │   └── style.css      # Styling
│   └── js/
│       └── chat.js        # Chat functionality
└── documents/
    └── index.html         # This documentation

Nginx Configuration

Config File: /etc/nginx/conf.d/ai.shieldstack.dev.conf

Key features:

• SSL/TLS encryption with Let's Encrypt
• HTTP to HTTPS redirect
• Security headers (X-Frame-Options, CSP, etc.)
• Static asset caching (1 year)
• Directory listing for /documents

SSL Certificate

Technology Stack

• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• Web Server: Nginx
• SSL: Let's Encrypt
• Speech Recognition: Web Speech API
• API Communication: Fetch API

Browser Compatibility

Troubleshooting

Common Issues

1. "API request failed" Error

Cause: Incorrect API endpoint or authentication.

Solution:

• Verify your API endpoint URL is correct
• Check that your API key is valid
• Ensure the API format matches your endpoint (openai, anthropic, custom)
• Check browser console for detailed error messages

2. Microphone Not Working

Cause: Browser permissions or unsupported browser.

Solution:

• Allow microphone access when prompted
• Check browser settings → Site Settings → Microphone
• Use Chrome, Edge, or Safari (Firefox doesn't support Web Speech API)
• Ensure HTTPS is enabled (required for microphone access)

3. Slow Response Times

Cause: API server latency or network issues.

Solution:

• Check your internet connection
• Verify the API endpoint is responsive
• Try a different AI model (smaller models are faster)

4. Settings Not Saving

Cause: Browser localStorage disabled or private browsing mode.

Solution:

• Disable private/incognito mode
• Enable localStorage in browser settings
• Clear browser cache and cookies

Server-Side Issues

Nginx Not Starting

sudo systemctl status nginx
sudo nginx -t
sudo systemctl restart nginx

SSL Certificate Issues

# Test certificate
sudo certbot certificates

# Renew certificate manually
sudo certbot renew

# Force renewal
sudo certbot renew --force-renewal

Check Logs

# Nginx access log
sudo tail -f /var/log/nginx/ai.shieldstack.dev-access.log

# Nginx error log
sudo tail -f /var/log/nginx/ai.shieldstack.dev-error.log

Maintenance

Regular Tasks

• SSL Certificate: Auto-renews via certbot (check monthly)
• Nginx: Restart after config changes
• Logs: Monitor and rotate as needed
• Updates: Keep system packages updated

Backup Recommendations

• Backup /var/www/ai/ directory
• Backup /etc/nginx/conf.d/ai.shieldstack.dev.conf
• Backup SSL certificates from /etc/letsencrypt/

File Permissions

sudo chown -R appsforte:appsforte /var/www/ai
sudo chmod -R 755 /var/www/ai
sudo chmod 644 /var/www/ai/index.html

Changelog

Version 1.0 - October 14, 2025

• Initial deployment
• Text and voice chat interface
• Configurable AI backend support
• SSL/HTTPS enabled
• Responsive design
• Comprehensive documentation