AutoSite Application Debug Guide

Overview

This document provides a comprehensive guide for debugging and testing the AutoSite application, with a particular focus on the AskAI component and its integration with the backend server.

Application Structure

Frontend Components

App.tsx: Main application container that manages the HTML content state and layout
AskAI Component: Handles AI interactions with streaming response processing
Preview Component: Renders HTML content in an iframe with refresh capability

Backend Services

/api/ask-ai: Processes prompts and streams AI responses (full HTML or diff mode)
/api/apply-diffs: Applies diff blocks to original HTML content

Key Features to Test

AskAI Component

Response Handling
- Full HTML mode for initial requests
- Diff mode for follow-up requests
- Streaming implementation with real-time preview updates
Progress Indicators
- Progress bar with percentage
- Response mode indicator (diff/full)
- Loading animations
- Success animation and sound
Error Handling
- Network error handling
- Authentication error handling with login modal
- Malformed response handling

Testing Resources

The following files have been created to assist with testing:

test-plan.md: Comprehensive test plan outlining test cases and approaches
test-html.html: Sample HTML file for testing the application
visual-test-script.js: Browser-based script for testing UI components
api-test-script.js: Node.js script for testing backend API endpoints
debug-report.md: Detailed analysis of the application architecture and potential issues

Running the Application

Prerequisites

Create a .env file based on .env.example with the following variables:
- OAUTH_CLIENT_ID: HuggingFace OAuth client ID
- OAUTH_CLIENT_SECRET: HuggingFace OAuth client secret
- APP_PORT: Port for the backend server (default: 3000)
- REDIRECT_URI: OAuth redirect URI
- DEFAULT_HF_TOKEN: HuggingFace API token for anonymous users

Starting the Application

Start the frontend development server:
```
npm run dev
```
Start the backend server in a separate terminal:
```
node server.js
```
Access the application at:
- Frontend: http://localhost:5173
- Backend API: http://localhost:3000

Testing Procedures

Visual Testing

Open the application in a browser
Open the browser console

Load the visual test script:

const script = document.createElement('script');
script.src = '/visual-test-script.js';
document.head.appendChild(script);

Run the tests:
```
runAllTests();
```

API Testing

Ensure the backend server is running
Run the API test script using Node.js:
```
node api-test-script.js
```

Common Issues and Solutions

Environment Configuration

Missing HuggingFace Token: The application requires a valid HuggingFace API token in the DEFAULT_HF_TOKEN environment variable
Port Conflicts: Ensure ports 3000 (backend) and 5173 (frontend) are available

Network Issues

CORS Errors: If testing the frontend and backend on different ports, CORS issues may occur
Rate Limiting: HuggingFace API has rate limits that may affect testing

UI Issues

Responsive Layout: Test on different screen sizes to verify responsive behavior
Progress Indicator: Verify progress updates correctly during streaming
Preview Updates: Check that preview updates in real-time during streaming

Debugging Tips

Console Logging: The application includes extensive console logging for debugging
Network Monitoring: Use browser DevTools to monitor API requests and responses
State Inspection: Monitor React state changes during AI processing
Visual Verification: Check progress indicators and animations during processing

Conclusion

The AutoSite application demonstrates a well-structured approach to integrating AI assistance into a web development tool. The streaming response handling, progress indicators, and dual-mode response processing provide a solid foundation for an interactive AI-assisted development experience.

Refer to the detailed test plan and debug report for more comprehensive information on testing and potential improvements.