frontend/README.md

Flask Frontend for Autonomous AI Data Analyst Agent

Modern, responsive web UI built with Flask + Jinja2 templates. The browser calls the FastAPI backend directly.

Features

• Flask-based UI: Server-rendered templates with dynamic configuration
• Direct API Calls: Browser talks to FastAPI (CORS-enabled)
• API Key Support: Optional X-API-Key header forwarding
• Real-time Polling: WebSocket-ready status updates via REST polling
• Interactive Visualizations: Plotly charts rendered in browser
• Markdown Rendering: LLM insights with marked.js + DOMPurify sanitization
• Dark Mode UI: Glass-morphism design with smooth animations

Project Structure

frontend/
├── app.py                 # Flask application (UI only)
├── templates/
│   └── index.html         # Jinja2 template (Flask-aware)
├── static/
│   ├── style.css          # Glass-morphism CSS
│   ├── app.js             # Client-side logic (vanilla JS)
│   └── ...
├── requirements.txt       # (Inherited from root)
└── .env                   # Environment variables

Installation

Prerequisites

• Python 3.9+
• FastAPI backend running (see parent README)

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Copy .env.example from root and set Flask-specific variables:

cp ../.env.example .env

Edit .env:

# Flask Frontend Configuration
FLASK_HOST=0.0.0.0
FLASK_PORT=5000
FLASK_DEBUG=false

# Backend Configuration
BACKEND_URL=http://localhost:8000
REQUIRE_API_KEY=false
API_KEY=your-optional-key

# App
APP_VERSION=0.1.0

3. Run Flask Development Server

python frontend/app.py

Or using Flask CLI:

export FLASK_APP=frontend.app
flask run --host 0.0.0.0 --port 5000

4. Open in Browser

http://localhost:5000

The FastAPI backend should still be running on port 8000 (or configured BACKEND_URL).

Environment Variables

Required

• BACKEND_URL: URL of FastAPI backend (default: http://localhost:8000)

Optional

• FLASK_HOST: Host to bind to (default: 0.0.0.0)
• FLASK_PORT: Port to run on (default: 5000)
• FLASK_DEBUG: Enable debug mode (default: false)
• REQUIRE_API_KEY: Require X-API-Key header (default: false)
• API_KEY: Shared API key (if REQUIRE_API_KEY=true)
• APP_VERSION: Application version string

API Endpoints (Called Directly by Browser)

The frontend JavaScript calls the FastAPI backend at BACKEND_URL.

Upload Endpoints

• POST /upload_dataset - Upload CSV file
• POST /upload_sql_table - Ingest from SQL database

Analysis Endpoints

• POST /start_analysis - Start workflow
• GET /analysis_status/{job_id} - Poll job status
• GET /download_report/{job_id}?format=json|html|pdf - Download report

History

• GET /analysis_history - Retrieve past insights

Frontend-Specific

• GET / - Serve the UI
• GET /health - Health check
• GET /api/config - Retrieve frontend config

Authentication

When REQUIRE_API_KEY=false (Default)

Direct access to all endpoints. No authentication needed.

When REQUIRE_API_KEY=true

Include X-API-Key header in all requests:

curl -H "X-API-Key: your-key" http://localhost:5000/health

Browser-based requests: Store API key in browser localStorage:

localStorage.setItem('API_KEY', 'your-key');

The frontend JavaScript automatically forwards this in the X-API-Key header.

Deployment

Development

python frontend/app.py

Production (with Gunicorn)

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 frontend.app:app

Comparison: Flask vs Original Vanilla HTML Frontend

Feature	Flask	Original
Server-side	Yes (Jinja2)	No (Static)
Dynamic Config	Yes (env vars passed to template)	Manual updates
Sessions	Supported	localStorage only
CSRF Protection	Built-in (optional)	Manual
Route Handling	Centralized Flask routes	Direct fetch() calls
Scalability	Multi-worker (Gunicorn)	Single app.main
Development	Debug mode with auto-reload	Manual browser refresh

Architecture Diagram

User Browser
    ↓
[Flask Frontend : 5000]
    ├─ Templates: Jinja2 (index.html)
    ├─ Static: CSS, JS
    └─ Routes: Python UI handlers
    ↓
[FastAPI Backend : 8000]
    ├─ Health checks
    ├─ File uploads
    ├─ Analysis workflows
    └─ Report generation
    ↓
[PostgreSQL Database]
[File Storage: data/uploads, data/reports]

Troubleshooting

"Connection refused" to backend

• Ensure FastAPI backend is running on configured BACKEND_URL
• Check BACKEND_URL environment variable
• Verify firewall rules

"Unauthorized" (401) errors

• If REQUIRE_API_KEY=true, ensure:
  • API key is set in .env
  • Browser has localStorage.API_KEY set to same value
  • X-API-Key header is being sent

"ImportError: No module named 'flask'"

pip install -r requirements.txt

CORS errors in browser

• Ensure CORS_ORIGINS includes http://localhost:5000 (default now does)
• Restart FastAPI after env changes

Development

Debug Mode

FLASK_DEBUG=true

Enables:

• Auto-reload on file changes
• Detailed error pages
• Interactive debugger

Adding New Routes

Edit frontend/app.py:

@app.route("/new-endpoint", methods=["GET"])
def new_endpoint():
  return jsonify({"message": "Hello from Flask!"})

Modifying Templates

Edit frontend/templates/index.html using Jinja2 syntax:

<h1>{{ app_version }}</h1>

Performance Notes

• For high-traffic deployments, use Gunicorn + Nginx reverse proxy
• Consider caching headers for static assets
• Browser caching of reports via ETag headers (future enhancement)

Security

• ✅ API key authentication forwarding
• ✅ CORS handled by backend
• ✅ No sensitive data in logs
• ⚠️ Enable HTTPS in production (via reverse proxy)
• ⚠️ Set secure session cookies (future enhancement)

Notes

• Frontend is stateless (all state stored in backend database)
• JavaScript remains vanilla (no framework dependencies)
• Responsive design tested on Chrome, Firefox, Safari, Edge
• Mobile support via responsive CSS grid layouts