made it faster and added color picker

.dockerignore

@@ -0,0 +1,30 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info
+dist
+build
+.venv
+venv
+env
+ENV
+.env
+*.db
+*.sqlite
+*.sqlite3
+chat.db
+node_modules
+.git
+.gitignore
+README.md
+*.md
+.vscode
+.idea
+*.log
+.pytest_cache
+.coverage
+htmlcov

.gitignore

@@ -0,0 +1,80 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+env.bak/
+venv.bak/
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+chat.db
+*.db-journal
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+
+# Node modules
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# User uploaded images (exclude, keep only logos)
+images/*.png
+!images/AutoForm.png
+!images/favicon.png
+images/*.jpg
+images/*.jpeg
+images/*.gif
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Keep these logo files
+!images/AutoForm.svg

DEPLOY_HF.md

@@ -0,0 +1,158 @@
+# Deploying AutoForm Backend to Hugging Face Spaces
+
+Follow these steps to deploy your backend to: https://huggingface.co/spaces/FireBird-Tech/autoform-backend
+
+## Step 1: Clone the Hugging Face Space Repository
+
+```bash
+# Install Hugging Face CLI if you haven't already
+curl -LsSf https://hf.co/cli/install.sh | bash
+
+# Clone the Space repository
+# You'll need an access token with write permissions
+# Generate one from: https://huggingface.co/settings/tokens
+git clone https://huggingface.co/spaces/FireBird-Tech/autoform-backend
+cd autoform-backend
+```
+
+Or use HTTPS with token:
+```bash
+git clone https://YOUR_USERNAME:YOUR_TOKEN@huggingface.co/spaces/FireBird-Tech/autoform-backend
+cd autoform-backend
+```
+
+## Step 2: Copy Your Backend Files
+
+Copy the following files from your local `backend/` directory to the cloned repository:
+
+```bash
+# From your project root, copy files to the HF Space directory
+cp backend/Dockerfile autoform-backend/
+cp backend/requirements.txt autoform-backend/
+cp -r backend/app autoform-backend/
+cp -r backend/images autoform-backend/
+```
+
+Or manually copy:
+- `backend/Dockerfile` → `autoform-backend/Dockerfile`
+- `backend/requirements.txt` → `autoform-backend/requirements.txt`
+- `backend/app/` → `autoform-backend/app/`
+- `backend/images/` → `autoform-backend/images/`
+
+## Step 3: Create README.md (Optional but Recommended)
+
+Create a `README.md` file in the Space root:
+
+```markdown
+---
+title: AutoForm Backend API
+emoji: 📝
+colorFrom: purple
+colorTo: pink
+sdk: docker
+sdk_version: 4.0.0
+app_port: 7860
+---
+
+# AutoForm Backend API
+
+FastAPI backend for AutoForm - AI-powered form builder.
+
+## API Endpoints
+
+- `/api/health` - Health check
+- `/docs` - Interactive API documentation
+- `/api/forms` - Form management endpoints
+- `/api/public/forms/{token}` - Public form endpoints
+
+## Environment Variables
+
+Set these in your Space settings:
+
+- `DEFAULT_MODEL` - LLM model to use (e.g., `openai/gpt-4o-mini`)
+- `OPENAI_API_KEY` - OpenAI API key (if using OpenAI)
+- `ANTHROPIC_API_KEY` - Anthropic API key (if using Anthropic)
+- `GEMINI_API_KEY` - Google Gemini API key (if using Gemini)
+- `DATABASE_URL` - Database connection string (default: SQLite)
+- `JWT_SECRET` - Secret for JWT tokens
+- `FRONTEND_URL` - Frontend URL for CORS
+- `SESSION_SECRET` - Session secret key
+```
+
+## Step 4: Configure Environment Variables
+
+1. Go to your Space settings: https://huggingface.co/spaces/FireBird-Tech/autoform-backend/settings
+2. Scroll down to "Variables and secrets"
+3. Add these environment variables:
+
+```
+DEFAULT_MODEL=openai/gpt-4o-mini
+OPENAI_API_KEY=your_openai_key
+DATABASE_URL=sqlite:///./data/app.db
+JWT_SECRET=your-jwt-secret-key-here
+FRONTEND_URL=https://your-frontend-url.com
+SESSION_SECRET=your-session-secret-here
+```
+
+**Note:** Add API keys as **secrets** (they'll be encrypted), and other config as **variables**.
+
+## Step 5: Commit and Push
+
+```bash
+cd autoform-backend
+
+# Add all files
+git add Dockerfile requirements.txt app/ images/ README.md
+
+# Commit
+git commit -m "Add AutoForm backend application"
+
+# Push to Hugging Face
+git push
+```
+
+## Step 6: Wait for Build
+
+Hugging Face Spaces will automatically:
+1. Build your Docker image
+2. Deploy the container
+3. Start the application
+
+You can monitor the build logs in the Space's "Logs" tab.
+
+## Step 7: Access Your API
+
+Once deployed, your API will be available at:
+- **API Base URL**: `https://firebird-tech-autoform-backend.hf.space`
+- **API Docs**: `https://firebird-tech-autoform-backend.hf.space/docs`
+- **Health Check**: `https://firebird-tech-autoform-backend.hf.space/api/health`
+
+## Troubleshooting
+
+### Build Fails
+- Check the "Logs" tab in your Space
+- Verify all files were copied correctly
+- Ensure `requirements.txt` is valid
+
+### Application Crashes
+- Check environment variables are set correctly
+- Review application logs in the Space
+- Verify database URL format
+
+### Port Issues
+- Hugging Face Spaces **must** use port 7860
+- The Dockerfile is already configured for this
+
+## Updating the Deployment
+
+To update your deployment:
+
+```bash
+cd autoform-backend
+# Make changes or copy new files
+git add .
+git commit -m "Update backend"
+git push
+```
+
+Hugging Face will automatically rebuild and redeploy.

Dockerfile

@@ -0,0 +1,45 @@
+# Use Python 3.11 (Hugging Face supports 3.9+)
+FROM python:3.11
+
+# Create a non-root user (Hugging Face recommendation)
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies as root, then switch back
+USER root
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Switch back to user
+USER user
+
+# Copy requirements first for better caching
+COPY --chown=user:user requirements.txt requirements.txt
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir --user -r requirements.txt
+
+# Copy application code
+COPY --chown=user:user app/ ./app/
+COPY --chown=user:user images/ ./images/
+
+# Create necessary directories
+RUN mkdir -p /app/data
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+# Expose port (Hugging Face Spaces uses port 7860)
+EXPOSE 7860
+
+# Run the application on port 7860 (Hugging Face requirement)
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

HF_DEPLOY_GUIDE.md

@@ -0,0 +1,134 @@
+# Deploying to Hugging Face Spaces - Correct Method
+
+## The Problem
+
+Hugging Face Spaces rejects binary files and development files like:
+- `.venv/` (virtual environment)
+- `node_modules/`
+- Database files (`.db`, `.sqlite`)
+- User-uploaded images
+
+## Solution: Copy Only Required Files
+
+**Don't push your entire backend directory!** Only copy the files needed for deployment.
+
+## Step-by-Step Instructions
+
+### 1. Clone the Space Repository
+
+```bash
+git clone https://huggingface.co/spaces/FireBird-Tech/autoform-backend
+cd autoform-backend
+```
+
+### 2. Copy ONLY Required Files
+
+Copy only these files (NOT the entire backend directory):
+
+```bash
+# From your project root
+cd autoform-backend
+
+# Copy Dockerfile
+cp ../backend/Dockerfile .
+
+# Copy requirements
+cp ../backend/requirements.txt .
+
+# Copy application code (this excludes venv, db files, etc.)
+cp -r ../backend/app .
+
+# Copy ONLY logo images (not user-uploaded content)
+mkdir -p images
+cp ../backend/images/AutoForm.png images/
+cp ../backend/images/AutoForm.svg images/
+cp ../backend/images/favicon.png images/
+```
+
+### 3. Create README.md
+
+Create `README.md` in the Space root:
+
+```markdown
+---
+title: AutoForm Backend API
+emoji: 📝
+colorFrom: purple
+colorTo: pink
+sdk: docker
+sdk_version: 4.0.0
+app_port: 7860
+---
+
+# AutoForm Backend API
+
+FastAPI backend for AutoForm.
+```
+
+### 4. Verify Files
+
+Make sure you DON'T have:
+- ❌ `.venv/` directory
+- ❌ `venv/` directory
+- ❌ `node_modules/` directory
+- ❌ `*.db` files
+- ❌ `chat.db`
+- ❌ User-uploaded images (keep only logos)
+
+You SHOULD have:
+- ✅ `Dockerfile`
+- ✅ `requirements.txt`
+- ✅ `app/` directory (with Python code)
+- ✅ `images/` directory (with only logo files)
+- ✅ `README.md`
+
+### 5. Commit and Push
+
+```bash
+git add Dockerfile requirements.txt app/ images/ README.md
+git commit -m "Add AutoForm backend"
+git push
+```
+
+## What Files to Include
+
+**Include:**
+- `Dockerfile`
+- `requirements.txt`
+- `app/` directory (all Python source files)
+- `images/AutoForm.png`
+- `images/AutoForm.svg`
+- `images/favicon.png`
+
+**Exclude:**
+- `.venv/` or `venv/`
+- `node_modules/`
+- `*.db` files
+- `chat.db`
+- User-uploaded images (anything in `images/` that's not a logo)
+- `__pycache__/` directories
+- `.env` files
+
+## Quick Copy Script
+
+Create a script to copy only the right files:
+
+```bash
+#!/bin/bash
+# copy_to_hf.sh
+
+HF_DIR="../autoform-backend"  # Adjust path as needed
+
+# Copy essential files
+cp Dockerfile "$HF_DIR/"
+cp requirements.txt "$HF_DIR/"
+cp -r app "$HF_DIR/"
+
+# Copy only logo images
+mkdir -p "$HF_DIR/images"
+cp images/AutoForm.png "$HF_DIR/images/"
+cp images/AutoForm.svg "$HF_DIR/images/"
+cp images/favicon.png "$HF_DIR/images/"
+
+echo "Files copied successfully!"
+```

README.md

@@ -0,0 +1,21 @@
+# Backend (FastAPI)
+
+Run locally:
+
+```bash
+python -m venv .venv && .venv\Scripts\activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+```
+
+Routes:
+
+- `GET /api/health`
+- `POST /api/auth/login`
+- `POST /api/auth/logout`
+- `GET /api/auth/me`
+- `POST /api/chat/send`
+- `POST /api/payment/create-checkout-session`
+- `POST /api/payment/webhook`
+
+

README_HUGGINGFACE.md

@@ -0,0 +1,62 @@
+# AutoForm Backend on Hugging Face Spaces
+
+This Dockerfile allows you to deploy the AutoForm backend API on Hugging Face Spaces.
+
+## Setup Instructions
+
+1. **Create a new Space on Hugging Face**
+   - Go to https://huggingface.co/spaces
+   - Create a new Space
+   - Select **Docker** as the SDK
+
+2. **Configure Environment Variables**
+   
+   In your Space settings, add these secrets/environment variables:
+   
+   ```
+   DEFAULT_MODEL=openai/gpt-4o-mini  # or anthropic/claude-3-5-sonnet-20241022, etc.
+   OPENAI_API_KEY=your_key_here       # if using OpenAI
+   ANTHROPIC_API_KEY=your_key_here    # if using Anthropic
+   GEMINI_API_KEY=your_key_here       # if using Google Gemini
+   DATABASE_URL=sqlite:///./data/app.db
+   JWT_SECRET=your-secret-key-here
+   FRONTEND_URL=https://your-frontend-url.com
+   SESSION_SECRET=your-session-secret-here
+   ```
+
+3. **Upload Files**
+   
+   Upload the following files to your Space:
+   - `Dockerfile` (this file should be in the root)
+   - `requirements.txt`
+   - `app/` directory (entire directory)
+   - `images/` directory (entire directory)
+
+4. **Build and Deploy**
+   
+   Hugging Face Spaces will automatically build and deploy your Docker container.
+
+## Port Configuration
+
+Hugging Face Spaces automatically sets the `PORT` environment variable. The Dockerfile is configured to use port 7860 by default, which is the standard port for Hugging Face Spaces.
+
+## Database
+
+By default, the app uses SQLite stored in `/app/data/app.db`. For production, you may want to use PostgreSQL by setting the `DATABASE_URL` environment variable.
+
+## Health Check
+
+The container includes a health check endpoint at `/api/health` that Hugging Face Spaces can use to monitor your application.
+
+## API Documentation
+
+Once deployed, you can access:
+- API docs: `https://your-space.hf.space/docs`
+- Health check: `https://your-space.hf.space/api/health`
+
+## Notes
+
+- The application runs on port 7860 (Hugging Face standard)
+- Database migrations run automatically on startup (`AUTO_MIGRATE=1`)
+- CORS is configured based on the `FRONTEND_URL` environment variable
+- All logs are output to stdout/stderr for Hugging Face monitoring

STRIPE_SETUP.md

@@ -0,0 +1,269 @@
+# Stripe Subscription System Setup Guide
+
+This guide will help you set up Stripe for the AutoDash subscription system.
+
+## Overview
+
+The AutoDash subscription system includes three tiers:
+- **Free Tier**: $0/month, 25 credits
+- **Pro Tier**: $20/month, 500 credits
+- **Ultra Tier**: Custom pricing, 1000 credits
+
+## Prerequisites
+
+- A Stripe account (create one at https://stripe.com)
+- Stripe CLI for webhook testing (optional but recommended)
+
+## Step 1: Create Products and Prices in Stripe
+
+### 1.1 Log in to Stripe Dashboard
+
+Go to https://dashboard.stripe.com and log in to your account.
+
+### 1.2 Create Products
+
+Navigate to **Products** → **Add Product** and create three products:
+
+#### Free Tier
+- **Name**: AutoDash Free
+- **Description**: Free tier with 25 credits per month
+- **Pricing**:
+  - Price: $0.00
+  - Billing period: Monthly
+  - Note: This is for tracking only, users won't be charged
+
+#### Pro Tier
+- **Name**: AutoDash Pro
+- **Description**: Professional tier with 500 credits per month
+- **Pricing**:
+  - Price: $20.00
+  - Billing period: Monthly (recurring)
+
+#### Ultra Tier
+- **Name**: AutoDash Ultra
+- **Description**: Ultra tier with 1000 credits per month
+- **Pricing**:
+  - Price: $29.99 (or your preferred amount)
+  - Billing period: Monthly (recurring)
+
+### 1.3 Get Price IDs
+
+After creating each product, Stripe will assign a **Price ID** to each. They look like:
+- `price_1234567890abcdef` (this is an example)
+
+Copy these Price IDs - you'll need them for the environment variables.
+
+### 1.4 Get Product IDs (Optional)
+
+You can also copy the **Product IDs** if you want to store them. They look like:
+- `prod_1234567890abcdef`
+
+## Step 2: Get API Keys
+
+### 2.1 Get Secret Key
+
+1. Navigate to **Developers** → **API Keys**
+2. Copy your **Secret key** (starts with `sk_test_` for test mode or `sk_live_` for live mode)
+3. Keep this key secure - never commit it to version control!
+
+### 2.2 Get Webhook Secret
+
+1. Navigate to **Developers** → **Webhooks**
+2. Click **Add endpoint**
+3. Set the endpoint URL to: `https://your-domain.com/api/payment/webhook`
+   - For local testing, you can use the Stripe CLI (see Step 3)
+4. Select the following events to listen for:
+   - `checkout.session.completed`
+   - `customer.subscription.updated`
+   - `customer.subscription.deleted`
+   - `invoice.payment_succeeded`
+   - `invoice.payment_failed`
+5. After creating the endpoint, click to view it and copy the **Signing secret** (starts with `whsec_`)
+
+## Step 3: Configure Environment Variables
+
+Create or update your `backend/.env` file with the following variables:
+
+```env
+# Stripe Configuration
+STRIPE_SECRET_KEY=sk_test_your_secret_key_here
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
+
+# Stripe Price IDs
+STRIPE_FREE_PRICE_ID=price_free_tier_id
+STRIPE_PRO_PRICE_ID=price_pro_tier_id
+STRIPE_ULTRA_PRICE_ID=price_ultra_tier_id
+
+# Stripe Product IDs (optional)
+STRIPE_FREE_PRODUCT_ID=prod_free_tier_id
+STRIPE_PRO_PRODUCT_ID=prod_pro_tier_id
+STRIPE_ULTRA_PRODUCT_ID=prod_ultra_tier_id
+
+# Frontend URL for redirects
+FRONTEND_URL=http://localhost:5173
+```
+
+### Example format (replace with your actual values from Stripe Dashboard):
+
+```env
+STRIPE_SECRET_KEY=sk_test_YOUR_ACTUAL_SECRET_KEY_FROM_STRIPE_DASHBOARD
+STRIPE_WEBHOOK_SECRET=whsec_YOUR_ACTUAL_WEBHOOK_SECRET_FROM_STRIPE_DASHBOARD
+
+STRIPE_FREE_PRICE_ID=price_YOUR_FREE_PRICE_ID
+STRIPE_PRO_PRICE_ID=price_YOUR_PRO_PRICE_ID
+STRIPE_ULTRA_PRICE_ID=price_YOUR_ULTRA_PRICE_ID
+
+FRONTEND_URL=http://localhost:5173
+```
+
+## Step 4: Initialize Database and Plans
+
+### 4.1 Automatic Initialization (Recommended)
+
+The application will automatically create database tables and initialize plans on startup if `AUTO_MIGRATE=1` in your `.env` file.
+
+Just start your backend server:
+
+```bash
+cd backend
+uvicorn app.main:app --reload
+```
+
+### 4.2 Manual Initialization
+
+You can also manually initialize plans using the provided script:
+
+```bash
+cd backend
+python -m app.scripts.init_plans --create-tables
+```
+
+Options:
+- `--create-tables`: Create database tables if they don't exist
+- `--force`: Force update of existing plans with new values
+
+## Step 5: Test with Stripe CLI (Local Development)
+
+For local testing, use the Stripe CLI to forward webhook events:
+
+### 5.1 Install Stripe CLI
+
+Follow instructions at: https://stripe.com/docs/stripe-cli
+
+### 5.2 Login to Stripe CLI
+
+```bash
+stripe login
+```
+
+### 5.3 Forward Webhooks to Local Server
+
+```bash
+stripe listen --forward-to localhost:3001/api/payment/webhook
+```
+
+This will give you a webhook signing secret (starts with `whsec_`). Use this in your `.env` file for local testing.
+
+### 5.4 Test a Payment
+
+```bash
+stripe trigger checkout.session.completed
+```
+
+## Step 6: Verify Setup
+
+### 6.1 Check Plans Endpoint
+
+Visit: `http://localhost:3001/api/plans`
+
+You should see all three plans with their configurations.
+
+### 6.2 Check Credit Balance (Authenticated)
+
+Create a test user by logging in via Google OAuth, then check:
+
+`GET http://localhost:3001/api/credits/balance`
+
+Headers:
+```
+Authorization: Bearer YOUR_JWT_TOKEN
+```
+
+### 6.3 Test Checkout Flow
+
+1. Log in to your application
+2. Navigate to the subscription/pricing page
+3. Click on a plan (Pro or Ultra)
+4. Complete the checkout using Stripe's test card: `4242 4242 4242 4242`
+   - Use any future expiration date
+   - Use any 3-digit CVC
+   - Use any ZIP code
+
+## Step 7: Go Live
+
+When ready to go live:
+
+1. Switch to **Live mode** in Stripe Dashboard
+2. Create new products and prices in live mode
+3. Get new live API keys (`sk_live_...`)
+4. Create a new webhook endpoint for your production URL
+5. Update your production `.env` with live keys
+6. Test thoroughly before announcing!
+
+## Troubleshooting
+
+### Webhook Events Not Received
+
+1. Check that your webhook endpoint is accessible from the internet
+2. Verify the webhook signing secret in your `.env` file
+3. Check Stripe Dashboard → Webhooks → Your endpoint for delivery logs
+4. For local testing, ensure Stripe CLI is running
+
+### Credits Not Resetting
+
+- Check webhook logs for `invoice.payment_succeeded` events
+- Verify the event is being handled correctly in logs
+- Check credit transaction history via `/api/credits/history`
+
+### Plans Not Showing
+
+- Run the initialization script: `python -m app.scripts.init_plans`
+- Check database for subscription_plans table
+- Verify AUTO_MIGRATE is enabled
+
+## Environment Variables Reference
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `STRIPE_SECRET_KEY` | Yes | Stripe API secret key | `sk_test_...` or `sk_live_...` |
+| `STRIPE_WEBHOOK_SECRET` | Yes | Webhook signing secret | `whsec_...` |
+| `STRIPE_FREE_PRICE_ID` | Yes | Price ID for Free tier | `price_...` |
+| `STRIPE_PRO_PRICE_ID` | Yes | Price ID for Pro tier | `price_...` |
+| `STRIPE_ULTRA_PRICE_ID` | Yes | Price ID for Ultra tier | `price_...` |
+| `STRIPE_FREE_PRODUCT_ID` | No | Product ID for Free tier | `prod_...` |
+| `STRIPE_PRO_PRODUCT_ID` | No | Product ID for Pro tier | `prod_...` |
+| `STRIPE_ULTRA_PRODUCT_ID` | No | Product ID for Ultra tier | `prod_...` |
+| `FRONTEND_URL` | Yes | Frontend URL for redirects | `http://localhost:5173` |
+| `AUTO_MIGRATE` | No | Auto-create DB tables on startup | `1` (default) |
+
+## Support
+
+For issues or questions:
+1. Check Stripe Dashboard logs
+2. Check application logs
+3. Review webhook event details in Stripe Dashboard
+4. Consult Stripe documentation: https://stripe.com/docs
+
+## Security Notes
+
+⚠️ **Important Security Reminders:**
+
+- Never commit API keys to version control
+- Use environment variables for all sensitive data
+- Always verify webhook signatures
+- Use HTTPS in production
+- Rotate keys if compromised
+- Use different keys for test/live environments
+- Implement rate limiting on payment endpoints
+- Monitor webhook delivery for anomalies
+

app/SAMPLE_DATA_README.md

@@ -0,0 +1,141 @@
+# Sample Housing Dataset - Comprehensive Real Estate Analytics
+
+## Overview
+This enhanced sample dataset contains **500 realistic property listings** with **33 features** designed to enable comprehensive real estate market analysis and insightful dashboard creation.
+
+## Dataset Features
+
+### Basic Property Information (9 columns)
+- **price**: Property sale price ($361K - $5.08M)
+- **property_type**: Single Family, Condo, Townhouse, or Multi-Family
+- **neighborhood**: Downtown, Suburbs, Waterfront, Historic District, or Business District
+- **bedrooms**: Number of bedrooms (1-6)
+- **bathrooms**: Number of bathrooms (1.0-4.5)
+- **sqft_living**: Interior living space in square feet (800-5,500)
+- **sqft_lot**: Lot size in square feet (2,000-20,000)
+- **floors**: Number of floors (1.0-3.0)
+- **year_built**: Year the property was built (1950-2023)
+
+### Property Characteristics (7 columns)
+- **year_renovated**: Year of last major renovation (0 if never renovated)
+- **property_age**: Age of the property in years
+- **waterfront**: Boolean - waterfront property (12% have this premium feature)
+- **view_quality**: View rating from 0-4 (higher is better)
+- **condition**: Overall condition rating 1-5
+- **grade**: Construction quality grade 3-12 (7-8 is average)
+- **price_segment**: Categorized as Budget, Mid-Range, Premium, or Luxury
+
+### Amenities & Features (4 columns)
+- **parking_spaces**: Number of parking spaces (0-4)
+- **has_pool**: Boolean - property has a swimming pool (15%)
+- **has_fireplace**: Boolean - property has fireplace(s) (35%)
+- **has_basement**: Boolean - property has a basement (45%)
+
+### Neighborhood Quality (3 columns)
+- **school_rating**: School district rating (3-10, higher is better)
+- **crime_index**: Neighborhood crime index (15-85, lower is better)
+- **walkability_score**: Walkability score (30-100, higher is better)
+
+### Market Metrics (3 columns)
+- **price_per_sqft**: Price per square foot (calculated)
+- **days_on_market**: Days the property was listed (1-180)
+- **hoa_fees**: Monthly HOA fees ($0-$800, ~40% of properties)
+
+### Temporal Data (4 columns)
+- **sale_date**: Date of sale (2022-01-01 to 2024-01-01)
+- **sale_month**: Month of sale (1-12)
+- **sale_quarter**: Quarter of sale (Q1-Q4)
+- **sale_year**: Year of sale (2022-2023)
+
+### Location Data (3 columns)
+- **zipcode**: ZIP code (10 different Seattle-area ZIP codes)
+- **lat**: Latitude coordinate
+- **long**: Longitude coordinate
+
+## Key Features for Analysis
+
+### 1. Price Drivers
+The dataset includes realistic relationships between price and features:
+- **Waterfront premium**: +30% average
+- **View quality**: +8% per rating point
+- **Property type**: Single Family and Multi-Family command premiums
+- **Neighborhood**: Waterfront (+25%) and Downtown (+15%) areas are most expensive
+- **School ratings**: Better schools correlate with higher prices
+- **Recent renovations**: +12% for properties renovated after 2015
+
+### 2. Market Segmentation
+Properties are naturally segmented into:
+- **Budget**: < $750K (25%)
+- **Mid-Range**: $750K - $1.2M (30%)
+- **Premium**: $1.2M - $1.8M (25%)
+- **Luxury**: > $1.8M (20%)
+
+### 3. Temporal Trends
+- Sales data spans 2 years (2022-2024)
+- Enables quarter-over-quarter and year-over-year analysis
+- Market velocity metrics through "days_on_market"
+
+### 4. Geographic Analysis
+- 10 different ZIP codes representing diverse neighborhoods
+- Lat/long coordinates for mapping and spatial analysis
+- Neighborhood-level characteristics (crime, walkability, schools)
+
+## Suggested Analysis & Visualizations
+
+### 1. Price Distribution & Trends
+- Price distribution by property type and neighborhood
+- Price trends over time (quarterly/yearly)
+- Price per square foot analysis
+
+### 2. Feature Impact Analysis
+- Impact of bedrooms, bathrooms on price
+- Premium analysis for waterfront, pool, renovations
+- School rating vs. price correlation
+
+### 3. Market Velocity
+- Days on market by price segment
+- Seasonal patterns in sales activity
+- HOA fees impact on marketability
+
+### 4. Geographic Insights
+- Price heatmaps by location
+- Neighborhood quality metrics visualization
+- ZIP code-level market analysis
+
+### 5. Property Characteristics
+- Condition vs. grade distribution
+- Age distribution and renovation patterns
+- Amenity combinations most common in different price ranges
+
+### 6. Comparative Analysis
+- Property type performance
+- Neighborhood comparisons (crime, schools, walkability)
+- Market segment characteristics
+
+## Default Dashboard Query
+The sample data comes with a pre-configured query that generates a comprehensive dashboard showcasing:
+1. KPI cards for key metrics (avg price, total listings)
+2. Price distribution by property type and neighborhood
+3. Quarterly price trends showing market evolution
+4. Feature impact analysis (bedrooms, waterfront, schools)
+5. Geographic price visualization
+6. Condition vs. grade matrix
+7. Market velocity by price segment
+
+## Data Quality
+- **No missing values**: All records are complete
+- **Realistic relationships**: Price adjustments based on actual market factors
+- **Diverse distribution**: Balanced representation across categories
+- **Time-series ready**: Proper date handling for temporal analysis
+- **GIS-ready**: Includes coordinates for mapping
+
+## Use Cases
+This dataset is ideal for demonstrating:
+- Real estate market analysis
+- Predictive pricing models
+- Market segmentation strategies
+- Investment opportunity identification
+- Neighborhood analysis and comparison
+- Temporal market trend analysis
+- Geographic price pattern detection
+

app/core/__init__.py

@@ -0,0 +1,2 @@
+
+

app/core/db.py

@@ -0,0 +1,5 @@
+from ..db import Base, engine, SessionLocal, get_db
+
+__all__ = ["Base", "engine", "SessionLocal", "get_db"]
+
+

app/core/security.py

@@ -0,0 +1,42 @@
+from ..security import create_access_token, get_current_subject
+from ..models import User
+from ..core.db import get_db
+from sqlalchemy.orm import Session
+from fastapi import Depends, HTTPException, status
+
+__all__ = ["create_access_token", "get_current_subject", "get_current_user"]
+
+
+def get_current_user(
+    subject: str = Depends(get_current_subject),
+    db: Session = Depends(get_db)
+) -> User:
+    """
+    Get the current user from the JWT token.
+    The subject is the user's ID (as string).
+    """
+    user = None
+    
+    # Try to find user by ID first (primary method since JWT sub = user.id)
+    try:
+        user_id = int(subject)
+        user = db.query(User).filter(User.id == user_id).first()
+    except (ValueError, TypeError):
+        # Fallback: try to find by email if subject is not numeric
+        user = db.query(User).filter(User.email == subject).first()
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found"
+        )
+    
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User is inactive"
+        )
+    
+    return user
+
+

app/db.py

@@ -0,0 +1,37 @@
+import os
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, DeclarativeBase
+
+
+DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./app.db")
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+if DATABASE_URL.startswith("sqlite"):
+    engine = create_engine(
+        DATABASE_URL,
+        connect_args={"check_same_thread": False},
+    )
+else:
+    engine = create_engine(
+        DATABASE_URL,
+        pool_pre_ping=True,   # validate connections before use to avoid stale sockets
+        pool_recycle=280,     # recycle before Neon's ~5 min idle timeout
+        pool_size=5,
+        max_overflow=10,
+    )
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+

app/main.py

@@ -0,0 +1,124 @@
+import os
+import logging
+from dotenv import load_dotenv
+import dspy
+from pathlib import Path
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.sessions import SessionMiddleware
+
+# Load environment from backend/.env BEFORE importing modules that read env
+_ENV_PATH = Path(__file__).resolve().parent.parent / ".env"
+load_dotenv(dotenv_path=_ENV_PATH, override=False)
+
+logging.basicConfig(
+    level=logging.WARNING,  # Changed from INFO to WARNING to reduce logging
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+from .core.db import Base, engine
+from .routes.health import router as health_router
+from .routes.auth import router as auth_router
+from .routes.google import router as google_router
+from .routes.payment import router as stripe_router
+from .routes.export import router as export_router
+from .routes.credits import router as credits_router
+from .routes.plans import router as plans_router
+from .routes.forms import router as forms_router
+from .routes.responses import router as responses_router
+from .routes.analytics import router as analytics_router
+from .routes.users import router as users_router
+
+app = FastAPI(title="Backend", version="0.1.0")
+
+default_model = os.getenv("DEFAULT_MODEL", "").lower()
+if "anthropic" in default_model:
+    provider = "ANTHROPIC"
+elif "openai" in default_model:
+    provider = "OPENAI"
+elif "gemini" in default_model:
+    provider = "GEMINI"
+else:
+    provider = "UNKNOWN"
+
+
+
+
+default_lm = dspy.LM(default_model, max_tokens=3200,api_key=os.getenv(provider+'_API_KEY'), temperature=1, cache=False)
+
+dspy.configure(lm=default_lm)
+
+# CORS middleware - allow frontend to access backend
+frontend_url = os.getenv("FRONTEND_URL", "http://localhost:5173")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[frontend_url],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Session support for OAuth (Authlib requires request.session)
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=os.getenv("SESSION_SECRET", "change-this-session-secret"),
+    same_site="lax",
+    https_only=bool(int(os.getenv("SESSION_HTTPS_ONLY", "0"))),
+)
+
+
+from .schemas.auth import LoginRequest
+
+# Optional debug route to verify OAuth env at runtime (masked)
+@app.get("/api/auth/debug")
+def auth_debug():
+    cid = os.getenv("GOOGLE_CLIENT_ID", "")
+    rid = os.getenv("GOOGLE_REDIRECT_URI", "")
+    return {
+        "GOOGLE_CLIENT_ID_present": bool(cid),
+        "GOOGLE_CLIENT_ID_prefix": cid[:10] + ("..." if cid else ""),
+        "GOOGLE_REDIRECT_URI": rid,
+    }
+
+
+app.include_router(health_router)
+
+
+# Auth routes
+app.include_router(auth_router)
+
+# Payment routes
+app.include_router(google_router)
+app.include_router(stripe_router)
+
+# Export routes
+app.include_router(export_router)
+
+# Credits routes
+app.include_router(credits_router)
+
+# Plans routes
+app.include_router(plans_router)
+
+# Form routes
+app.include_router(forms_router)
+app.include_router(responses_router)
+app.include_router(analytics_router)
+app.include_router(users_router)
+
+# Initialize DB
+if os.getenv("AUTO_MIGRATE", "1") == "1":
+    Base.metadata.create_all(bind=engine)
+    
+    # Initialize default subscription plans
+    from .services.plan_service import plan_service
+    from .core.db import SessionLocal
+    try:
+        db = SessionLocal()
+        plan_service.initialize_default_plans(db, force=False)
+        db.close()
+        logging.info("Default subscription plans initialized")
+    except Exception as e:
+        logging.error(f"Failed to initialize subscription plans: {e}")
+
+

app/managers/__init__.py

@@ -0,0 +1,2 @@
+
+

app/managers/users.py

@@ -0,0 +1,16 @@
+from sqlalchemy.orm import Session
+from ..models import User
+
+
+def get_or_create_user_by_email(db: Session, *, email: str, name: str | None = None, picture: str | None = None,
+                                provider: str | None = None, provider_id: str | None = None) -> User:
+    user = db.query(User).filter(User.email == email).first()
+    if user:
+        return user
+    user = User(email=email, name=name, picture=picture, provider=provider, provider_id=provider_id)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return user
+
+

app/middleware/__init__.py

@@ -0,0 +1,7 @@
+"""
+Middleware package
+"""
+from .credit_check import require_credits, CreditCheckResult
+
+__all__ = ["require_credits", "CreditCheckResult"]
+

app/middleware/credit_check.py

@@ -0,0 +1,158 @@
+"""
+Credit check middleware for protecting routes with credit requirements
+"""
+from typing import Callable
+from fastapi import Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User
+from ..services.credit_service import credit_service
+from ..services.plan_service import plan_service
+
+
+class CreditCheckResult:
+    """
+    Result of a credit check, passed to route handlers
+    Contains information about the user's credit status
+    """
+    def __init__(self, user: User, balance: int, cost: int, plan_name: str = None):
+        self.user = user
+        self.balance = balance
+        self.cost = cost
+        self.plan_name = plan_name
+
+
+def require_credits(amount: int) -> Callable:
+    """
+    Dependency factory for checking if user has sufficient credits
+    
+    Usage in routes:
+        @router.post("/analyze")
+        async def analyze_data(
+            credits: CreditCheckResult = Depends(require_credits(5)),
+            db: Session = Depends(get_db)
+        ):
+            # Your route logic here
+            # After successful operation, deduct credits:
+            credit_service.deduct_credits(db, credits.user.id, 5, "Data analysis")
+    
+    Args:
+        amount: Number of credits required
+        
+    Returns:
+        Dependency function that checks credits
+    """
+    def credit_checker(
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db)
+    ) -> CreditCheckResult:
+        """
+        Check if the current user has sufficient credits
+        
+        Args:
+            current_user: Authenticated user
+            db: Database session
+            
+        Returns:
+            CreditCheckResult with user and balance info
+            
+        Raises:
+            HTTPException: If user has insufficient credits
+        """
+        # Get user's credit balance
+        user_credits = credit_service.get_user_credits(db, current_user.id)
+        
+        if not user_credits:
+            raise HTTPException(
+                status_code=status.HTTP_402_PAYMENT_REQUIRED,
+                detail={
+                    "error": "no_credits_initialized",
+                    "message": "Credit account not initialized. Please contact support.",
+                    "required": amount,
+                    "balance": 0
+                }
+            )
+        
+        # Check if sufficient credits
+        if user_credits.balance < amount:
+            # Get plan name for better error message
+            plan_name = None
+            if user_credits.plan_id:
+                plan = plan_service.get_plan_by_id(db, user_credits.plan_id)
+                plan_name = plan.name if plan else None
+            
+            raise HTTPException(
+                status_code=status.HTTP_402_PAYMENT_REQUIRED,
+                detail={
+                    "error": "insufficient_credits",
+                    "message": f"Insufficient credits. Required: {amount}, Available: {user_credits.balance}",
+                    "required": amount,
+                    "balance": user_credits.balance,
+                    "plan": plan_name
+                }
+            )
+        
+        # Get plan name for result
+        plan_name = None
+        if user_credits.plan_id:
+            plan = plan_service.get_plan_by_id(db, user_credits.plan_id)
+            plan_name = plan.name if plan else None
+        
+        return CreditCheckResult(
+            user=current_user,
+            balance=user_credits.balance,
+            cost=amount,
+            plan_name=plan_name
+        )
+    
+    return credit_checker
+
+
+class OptionalCreditCheck:
+    """
+    Optional credit check that doesn't raise an error
+    Useful for routes that want to check credits but have fallback behavior
+    """
+    def __init__(self, amount: int):
+        self.amount = amount
+    
+    def __call__(
+        self,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db)
+    ) -> dict:
+        """
+        Check credits without raising an error
+        
+        Returns:
+            Dictionary with has_credits, balance, required, etc.
+        """
+        user_credits = credit_service.get_user_credits(db, current_user.id)
+        
+        if not user_credits:
+            return {
+                "has_credits": False,
+                "balance": 0,
+                "required": self.amount,
+                "user_id": current_user.id
+            }
+        
+        has_sufficient = user_credits.balance >= self.amount
+        
+        # Get plan info
+        plan_name = None
+        if user_credits.plan_id:
+            plan = plan_service.get_plan_by_id(db, user_credits.plan_id)
+            plan_name = plan.name if plan else None
+        
+        return {
+            "has_credits": has_sufficient,
+            "balance": user_credits.balance,
+            "required": self.amount,
+            "user_id": current_user.id,
+            "plan": plan_name
+        }
+

app/middleware/rate_limiter.py

@@ -0,0 +1,169 @@
+"""
+Rate limiting and spam protection middleware
+"""
+from sqlalchemy.orm import Session
+from typing import Optional
+from datetime import datetime, timedelta
+import hashlib
+import json
+import logging
+
+from ..models import SubmissionRateLimit, Form
+
+logger = logging.getLogger(__name__)
+
+
+class SubmissionRateLimiter:
+    """Rate limiting for form submissions"""
+    
+    def __init__(self):
+        self.salt = "autoform_rate_limit_salt"
+    
+    def check_rate_limit(
+        self,
+        db: Session,
+        form_id: int,
+        identifier: str,
+        window_minutes: int = 60,
+        max_submissions: int = 5
+    ) -> bool:
+        """
+        Check if submission rate limit exceeded.
+        
+        Rules:
+        - Max 5 submissions per hour per IP for same form (configurable)
+        - Sliding window implementation
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            identifier: IP hash or device fingerprint
+            window_minutes: Time window in minutes
+            max_submissions: Maximum submissions allowed in window
+        
+        Returns:
+            True if rate limit is OK (allowed), False if exceeded
+        """
+        try:
+            # Calculate window start time
+            window_start = datetime.utcnow() - timedelta(minutes=window_minutes)
+            
+            # Check if there's an existing rate limit record
+            rate_limit = db.query(SubmissionRateLimit).filter(
+                SubmissionRateLimit.identifier == identifier,
+                SubmissionRateLimit.form_id == form_id,
+                SubmissionRateLimit.window_start >= window_start
+            ).first()
+            
+            if rate_limit:
+                # Check if blocked
+                if rate_limit.is_blocked:
+                    logger.warning(f"Rate limit blocked: {identifier} for form {form_id}")
+                    return False
+                
+                # Check submission count
+                if rate_limit.submission_count >= max_submissions:
+                    # Block this identifier
+                    rate_limit.is_blocked = True
+                    db.commit()
+                    logger.warning(f"Rate limit exceeded: {identifier} for form {form_id}")
+                    return False
+                
+                # Increment count
+                rate_limit.submission_count += 1
+                db.commit()
+                return True
+            else:
+                # Create new rate limit record
+                new_rate_limit = SubmissionRateLimit(
+                    identifier=identifier,
+                    form_id=form_id,
+                    submission_count=1,
+                    window_start=datetime.utcnow(),
+                    is_blocked=False
+                )
+                db.add(new_rate_limit)
+                db.commit()
+                return True
+                
+        except Exception as e:
+            logger.error(f"Error checking rate limit: {e}")
+            # On error, allow submission (fail open)
+            return True
+    
+    def check_duplicate(
+        self,
+        db: Session,
+        form_id: int,
+        answers_hash: str,
+        window_minutes: int = 5
+    ) -> bool:
+        """
+        Check for duplicate submissions (same answers within time window).
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            answers_hash: SHA256 hash of sorted answers
+            window_minutes: Time window to check for duplicates
+        
+        Returns:
+            True if duplicate found, False otherwise
+        """
+        # TODO: Implement duplicate detection
+        # Store hashes in rate_limits table or separate duplicate_submissions table
+        # For now, return False (no duplicate)
+        return False
+    
+    def hash_identifier(self, identifier: str) -> str:
+        """Hash identifier (IP address) for storage"""
+        if not identifier:
+            return "unknown"
+        
+        salted = f"{identifier}{self.salt}"
+        return hashlib.sha256(salted.encode()).hexdigest()
+    
+    def hash_answers(self, answers: list) -> str:
+        """Hash answers for duplicate detection"""
+        # Sort and serialize answers for consistent hashing
+        sorted_answers = sorted(
+            answers,
+            key=lambda x: x.get('question_id', 0)
+        )
+        
+        # Create string representation
+        answer_str = json.dumps(sorted_answers, sort_keys=True)
+        
+        return hashlib.sha256(answer_str.encode()).hexdigest()
+    
+    def cleanup_old_records(
+        self,
+        db: Session,
+        days_old: int = 7
+    ):
+        """
+        Clean up old rate limit records.
+        
+        Args:
+            db: Database session
+            days_old: Delete records older than this many days
+        """
+        try:
+            cutoff_date = datetime.utcnow() - timedelta(days=days_old)
+            
+            deleted_count = db.query(SubmissionRateLimit).filter(
+                SubmissionRateLimit.window_start < cutoff_date
+            ).delete()
+            
+            db.commit()
+            
+            if deleted_count > 0:
+                logger.info(f"Cleaned up {deleted_count} old rate limit records")
+                
+        except Exception as e:
+            logger.error(f"Error cleaning up rate limit records: {e}")
+            db.rollback()
+
+
+# Singleton instance
+rate_limiter = SubmissionRateLimiter()

app/models.py

@@ -0,0 +1,541 @@
+from sqlalchemy import String, Integer, Boolean, ForeignKey, DateTime, Text, JSON, Numeric, Enum, Float
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from datetime import datetime
+from decimal import Decimal
+import enum
+from .db import Base
+
+
+class TransactionType(str, enum.Enum):
+    """Credit transaction types"""
+    RESET = "reset"
+    DEDUCT = "deduct"
+    REFUND = "refund"
+    ADJUSTMENT = "adjustment"
+
+
+class QuestionType(str, enum.Enum):
+    """Form question types"""
+    SHORT_ANSWER = "short_answer"
+    LONG_ANSWER = "long_answer"
+    MULTIPLE_CHOICE = "multiple_choice"
+    CHECKBOXES = "checkboxes"
+    DROPDOWN = "dropdown"
+    MULTI_SELECT = "multi_select"
+    NUMBER = "number"
+    EMAIL = "email"
+    PHONE = "phone"
+    LINK = "link"
+    FILE_UPLOAD = "file_upload"
+    DATE = "date"
+    TIME = "time"
+    LINEAR_SCALE = "linear_scale"
+    MATRIX = "matrix"
+    RATING = "rating"
+    PAYMENT = "payment"
+    SIGNATURE = "signature"
+    RANKING = "ranking"
+    WALLET_CONNECT = "wallet_connect"
+
+
+class ConditionType(str, enum.Enum):
+    """Conditional logic condition types"""
+    EQUALS = "equals"
+    NOT_EQUALS = "not_equals"
+    CONTAINS = "contains"
+    NOT_CONTAINS = "not_contains"
+    GREATER_THAN = "greater_than"
+    LESS_THAN = "less_than"
+    IS_EMPTY = "is_empty"
+    IS_NOT_EMPTY = "is_not_empty"
+
+
+class SubmissionStatus(str, enum.Enum):
+    """Form submission status types"""
+    IN_PROGRESS = "in_progress"
+    PARTIAL = "partial"
+    COMPLETE = "complete"
+    ABANDONED = "abandoned"
+
+
+class AnalyticsEventType(str, enum.Enum):
+    """Analytics event types"""
+    FORM_VIEWED = "form_viewed"
+    FORM_STARTED = "form_started"
+    QUESTION_VIEWED = "question_viewed"
+    QUESTION_ANSWERED = "question_answered"
+    QUESTION_SKIPPED = "question_skipped"
+    FORM_ABANDONED = "form_abandoned"
+    FORM_SUBMITTED_PARTIAL = "form_submitted_partial"
+    FORM_SUBMITTED_COMPLETE = "form_submitted_complete"
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    picture: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    provider: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    provider_id: Mapped[str | None] = mapped_column(String(255), index=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+    subscriptions: Mapped[list["Subscription"]] = relationship(back_populates="user")
+    datasets: Mapped[list["Dataset"]] = relationship(back_populates="user")
+    credits: Mapped["UserCredits"] = relationship(back_populates="user", uselist=False)
+    credit_transactions: Mapped[list["CreditTransaction"]] = relationship(back_populates="user")
+    dashboard_queries: Mapped[list["DashboardQuery"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    chat_messages: Mapped[list["ChatMessage"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    public_dashboards: Mapped[list["PublicDashboard"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    forms: Mapped[list["Form"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    public_forms: Mapped[list["PublicForm"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+
+
+class Subscription(Base):
+    __tablename__ = "subscriptions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    plan_id: Mapped[int | None] = mapped_column(ForeignKey("subscription_plans.id"), nullable=True)
+    status: Mapped[str] = mapped_column(String(50), default="inactive")
+    stripe_customer_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    stripe_subscription_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    current_period_start: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    current_period_end: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    cancel_at_period_end: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    user: Mapped[User] = relationship(back_populates="subscriptions")
+    plan: Mapped["SubscriptionPlan"] = relationship(back_populates="subscriptions")
+
+
+class Dataset(Base):
+    __tablename__ = "datasets"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    dataset_id: Mapped[str] = mapped_column(String(100), unique=True, index=True)
+    
+    # Basic metadata
+    filename: Mapped[str] = mapped_column(String(255))
+    row_count: Mapped[int] = mapped_column(Integer)
+    column_count: Mapped[int] = mapped_column(Integer)
+    file_size_bytes: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    
+    # Dataset context from DSPy (rich description)
+    context: Mapped[str | None] = mapped_column(Text, nullable=True)
+    context_generated_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    
+    # Column metadata as JSON
+    columns_info: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    # Store: {"columns": [...], "dtypes": {...}, "statistics": {...}}
+    
+    # Timestamps
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Status tracking
+    context_status: Mapped[str] = mapped_column(String(50), default="pending")
+    # Values: "pending", "generating", "completed", "failed"
+    
+    user: Mapped[User] = relationship(back_populates="datasets")
+    dashboard_queries: Mapped[list["DashboardQuery"]] = relationship(back_populates="dataset", cascade="all, delete-orphan")
+    chat_messages: Mapped[list["ChatMessage"]] = relationship(back_populates="dataset", cascade="all, delete-orphan")
+    public_dashboards: Mapped[list["PublicDashboard"]] = relationship(back_populates="dataset", cascade="all, delete-orphan")
+
+
+class DashboardQuery(Base):
+    __tablename__ = "dashboard_queries"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    dataset_id: Mapped[int] = mapped_column(ForeignKey("datasets.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    query: Mapped[str] = mapped_column(Text)  # User's request
+    query_type: Mapped[str] = mapped_column(String(50))  # "analyze", "edit", "add"
+    dashboard_title: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    charts_data: Mapped[list[dict] | None] = mapped_column(JSON, nullable=True)  # Array of chart objects with code, figure, etc.
+    background_color: Mapped[str | None] = mapped_column(String(7), nullable=True, default="#ffffff")  # Hex color code
+    text_color: Mapped[str | None] = mapped_column(String(7), nullable=True, default="#1a1a1a")  # Hex color code for text
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    
+    dataset: Mapped["Dataset"] = relationship(back_populates="dashboard_queries")
+    user: Mapped["User"] = relationship(back_populates="dashboard_queries")
+
+
+class ChatMessage(Base):
+    __tablename__ = "chat_messages"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    dataset_id: Mapped[int] = mapped_column(ForeignKey("datasets.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    role: Mapped[str] = mapped_column(String(20))  # "user", "assistant"
+    content: Mapped[str] = mapped_column(Text)
+    query_type: Mapped[str | None] = mapped_column(String(50), nullable=True)  # "edit", "add", "data_analysis", "general_qa", "need_clarity", etc.
+    code: Mapped[str | None] = mapped_column(Text, nullable=True)  # Executable code if applicable
+    chart_index: Mapped[int | None] = mapped_column(Integer, nullable=True)  # If related to a chart
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    
+    dataset: Mapped["Dataset"] = relationship(back_populates="chat_messages")
+    user: Mapped["User"] = relationship(back_populates="chat_messages")
+
+
+class PublicDashboard(Base):
+    __tablename__ = "public_dashboards"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    dataset_id: Mapped[int] = mapped_column(ForeignKey("datasets.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    share_token: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    figures_data: Mapped[list[dict] | None] = mapped_column(JSON, nullable=True)  # Array of chart figures
+    dashboard_title: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    background_color: Mapped[str | None] = mapped_column(String(7), nullable=True, default="#ffffff")  # Hex color code
+    text_color: Mapped[str | None] = mapped_column(String(7), nullable=True, default="#1a1a1a")  # Hex color code for text
+    background_opacity: Mapped[float | None] = mapped_column(Float, nullable=True, default=1.0)  # Background opacity
+    use_gradient: Mapped[bool | None] = mapped_column(Boolean, nullable=True, default=False)  # Use gradient background
+    gradient_color_2: Mapped[str | None] = mapped_column(String(7), nullable=True, default="#e5e7eb")  # Second gradient color
+    container_colors: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Container-specific colors
+    chart_colors: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Chart trace colors
+    chart_opacities: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Chart trace opacities
+    apply_to_containers: Mapped[bool | None] = mapped_column(Boolean, nullable=True, default=True)  # Apply colors to all containers
+    is_public: Mapped[bool] = mapped_column(Boolean, default=True)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    dataset: Mapped["Dataset"] = relationship(back_populates="public_dashboards")
+    user: Mapped["User"] = relationship(back_populates="public_dashboards")
+
+
+class SubscriptionPlan(Base):
+    __tablename__ = "subscription_plans"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    name: Mapped[str] = mapped_column(String(100), unique=True, index=True)
+    stripe_price_id: Mapped[str | None] = mapped_column(String(255), nullable=True)  # Legacy field, use stripe_price_id_monthly
+    stripe_price_id_monthly: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    stripe_price_id_yearly: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    stripe_product_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    price_monthly: Mapped[Decimal] = mapped_column(Numeric(10, 2), default=0.0)
+    price_yearly: Mapped[Decimal | None] = mapped_column(Numeric(10, 2), nullable=True)
+    
+    # Credit configuration
+    credits_per_month: Mapped[int] = mapped_column(Integer, default=0)
+    credits_per_analyze: Mapped[int] = mapped_column(Integer, default=5)
+    credits_per_edit: Mapped[int] = mapped_column(Integer, default=2)
+    
+    # Extensible features as JSON
+    features: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    
+    # Plan management
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+    
+    # Timestamps
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    subscriptions: Mapped[list["Subscription"]] = relationship(back_populates="plan")
+    user_credits: Mapped[list["UserCredits"]] = relationship(back_populates="plan")
+
+
+class UserCredits(Base):
+    __tablename__ = "user_credits"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), unique=True, index=True)
+    plan_id: Mapped[int | None] = mapped_column(ForeignKey("subscription_plans.id"), nullable=True)
+    balance: Mapped[int] = mapped_column(Integer, default=0)
+    last_reset_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    user: Mapped[User] = relationship(back_populates="credits")
+    plan: Mapped["SubscriptionPlan"] = relationship(back_populates="user_credits")
+
+
+class CreditTransaction(Base):
+    __tablename__ = "credit_transactions"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    amount: Mapped[int] = mapped_column(Integer)  # Can be negative for deductions
+    transaction_type: Mapped[TransactionType] = mapped_column(Enum(TransactionType), index=True)
+    description: Mapped[str] = mapped_column(Text)
+    transaction_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    
+    # Relationships
+    user: Mapped[User] = relationship(back_populates="credit_transactions")
+
+
+class Form(Base):
+    """Form table for AI-generated forms"""
+    __tablename__ = "forms"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    title: Mapped[str] = mapped_column(String(255))
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    settings: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Theme colors, submit button text, etc.
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    user: Mapped[User] = relationship(back_populates="forms")
+    questions: Mapped[list["FormQuestion"]] = relationship(back_populates="form", cascade="all, delete-orphan", order_by="FormQuestion.question_order")
+    conditional_rules: Mapped[list["ConditionalRule"]] = relationship(back_populates="form", cascade="all, delete-orphan")
+    responses: Mapped[list["FormResponse"]] = relationship(back_populates="form", cascade="all, delete-orphan")
+    chat_messages_form: Mapped[list["ChatMessageForm"]] = relationship(back_populates="form", cascade="all, delete-orphan")
+    versions: Mapped[list["FormVersion"]] = relationship(back_populates="form", cascade="all, delete-orphan")
+    analytics_events: Mapped[list["FormAnalyticsEvent"]] = relationship(back_populates="form", cascade="all, delete-orphan")
+
+
+class FormQuestion(Base):
+    """Form questions table"""
+    __tablename__ = "form_questions"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    
+    question_order: Mapped[int] = mapped_column(Integer)
+    question_type: Mapped[QuestionType] = mapped_column(Enum(QuestionType))
+    question_text: Mapped[str] = mapped_column(Text)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    required: Mapped[bool] = mapped_column(Boolean, default=False)
+    settings: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Type-specific options (choices, validation, etc.)
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="questions")
+    trigger_rules: Mapped[list["ConditionalRule"]] = relationship(foreign_keys="ConditionalRule.trigger_question_id", back_populates="trigger_question", cascade="all, delete-orphan")
+    target_rules: Mapped[list["ConditionalRule"]] = relationship(foreign_keys="ConditionalRule.target_question_id", back_populates="target_question", cascade="all, delete-orphan")
+    answers: Mapped[list["ResponseAnswer"]] = relationship(back_populates="question", cascade="all, delete-orphan")
+    analytics_events: Mapped[list["FormAnalyticsEvent"]] = relationship(back_populates="question", cascade="all, delete-orphan")
+
+
+class ConditionalRule(Base):
+    """Conditional logic rules for showing/hiding questions"""
+    __tablename__ = "conditional_rules"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    trigger_question_id: Mapped[int] = mapped_column(ForeignKey("form_questions.id"), index=True)
+    target_question_id: Mapped[int] = mapped_column(ForeignKey("form_questions.id"), index=True)
+    
+    condition_type: Mapped[ConditionType] = mapped_column(Enum(ConditionType))
+    condition_value: Mapped[str | None] = mapped_column(Text, nullable=True)  # The value to compare against
+    action: Mapped[str] = mapped_column(String(20), default="show")  # "show" or "hide"
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="conditional_rules")
+    trigger_question: Mapped[FormQuestion] = relationship(foreign_keys=[trigger_question_id], back_populates="trigger_rules")
+    target_question: Mapped[FormQuestion] = relationship(foreign_keys=[target_question_id], back_populates="target_rules")
+
+
+class FormResponse(Base):
+    """Form submission responses"""
+    __tablename__ = "form_responses"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    
+    # Enhanced tracking fields
+    status: Mapped[str] = mapped_column(String(20), default="complete", index=True)
+    form_version: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    session_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    
+    # Timestamps
+    submitted_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    last_updated_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True, onupdate=datetime.utcnow)
+    
+    # IP and geolocation
+    ip_address: Mapped[str | None] = mapped_column(String(45), nullable=True)  # IPv6 compatible (legacy)
+    ip_address_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    country: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    city: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    
+    # Traffic source tracking
+    user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
+    referrer: Mapped[str | None] = mapped_column(Text, nullable=True)
+    utm_source: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    utm_medium: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    utm_campaign: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    
+    submission_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # Additional submission metadata
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="responses")
+    answers: Mapped[list["ResponseAnswer"]] = relationship(back_populates="response", cascade="all, delete-orphan")
+    analytics_events: Mapped[list["FormAnalyticsEvent"]] = relationship(back_populates="submission", cascade="all, delete-orphan")
+
+
+class ResponseAnswer(Base):
+    """Individual answers within a form response"""
+    __tablename__ = "response_answers"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_response_id: Mapped[int] = mapped_column(ForeignKey("form_responses.id"), index=True)
+    form_question_id: Mapped[int] = mapped_column(ForeignKey("form_questions.id"), index=True)
+    
+    answer_value: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # JSON to handle all answer types
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    response: Mapped[FormResponse] = relationship(back_populates="answers")
+    question: Mapped[FormQuestion] = relationship(back_populates="answers")
+
+
+class PublicForm(Base):
+    """Public shareable forms"""
+    __tablename__ = "public_forms"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    share_token: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    is_public: Mapped[bool] = mapped_column(Boolean, default=True)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    
+    # Settings
+    allow_multiple_submissions: Mapped[bool] = mapped_column(Boolean, default=True)
+    collect_email: Mapped[bool] = mapped_column(Boolean, default=False)
+    custom_thank_you_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    form: Mapped[Form] = relationship()
+    user: Mapped[User] = relationship(back_populates="public_forms")
+
+
+class ChatMessageForm(Base):
+    """Chat messages for form editing context"""
+    __tablename__ = "chat_messages_form"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    role: Mapped[str] = mapped_column(String(20))  # "user", "assistant"
+    content: Mapped[str] = mapped_column(Text)
+    query_type: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    question_index: Mapped[int | None] = mapped_column(Integer, nullable=True)  # If related to a specific question
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="chat_messages_form")
+    user: Mapped[User] = relationship()
+
+
+class FormVersion(Base):
+    """Form version snapshots for validation and history"""
+    __tablename__ = "form_versions"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    
+    version: Mapped[int] = mapped_column(Integer, nullable=False)
+    schema_snapshot: Mapped[dict] = mapped_column(JSON, nullable=False)  # Full form + questions structure
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, index=True)
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="versions")
+
+
+class FormAnalyticsEvent(Base):
+    """Analytics event tracking for forms"""
+    __tablename__ = "form_analytics_events"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    event_id: Mapped[str] = mapped_column(String(36), unique=True, nullable=False, index=True)  # UUID
+    
+    # Foreign keys
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), index=True)
+    submission_id: Mapped[int | None] = mapped_column(ForeignKey("form_responses.id"), nullable=True, index=True)
+    question_id: Mapped[int | None] = mapped_column(ForeignKey("form_questions.id"), nullable=True, index=True)
+    
+    # Event details
+    event_type: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    session_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    
+    # IP and geolocation
+    ip_address_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    ip_address_raw: Mapped[str | None] = mapped_column(String(45), nullable=True)  # Only if user opts in
+    country: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    city: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    
+    # Traffic source
+    user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
+    referrer: Mapped[str | None] = mapped_column(Text, nullable=True)
+    utm_source: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    utm_medium: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    utm_campaign: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    
+    # Event-specific data
+    time_spent_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    event_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)
+    
+    # Relationships
+    form: Mapped[Form] = relationship(back_populates="analytics_events")
+    submission: Mapped["FormResponse"] = relationship(back_populates="analytics_events")
+    question: Mapped["FormQuestion"] = relationship(back_populates="analytics_events")
+
+
+class SubmissionRateLimit(Base):
+    """Rate limiting for form submissions"""
+    __tablename__ = "submission_rate_limits"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    identifier: Mapped[str] = mapped_column(String(64), nullable=False, index=True)  # IP hash or device fingerprint
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), nullable=False, index=True)
+    
+    submission_count: Mapped[int] = mapped_column(Integer, default=0)
+    window_start: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    is_blocked: Mapped[bool] = mapped_column(Boolean, default=False)
+    
+    # Relationships
+    form: Mapped[Form] = relationship()
+
+
+class WebhookConfig(Base):
+    """Webhook configuration for forms"""
+    __tablename__ = "webhook_configs"
+    
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    form_id: Mapped[int] = mapped_column(ForeignKey("forms.id"), unique=True, nullable=False, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
+    
+    webhook_url: Mapped[str] = mapped_column(Text, nullable=False)
+    secret: Mapped[str] = mapped_column(String(128), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    events: Mapped[list] = mapped_column(JSON, nullable=False)  # Array of event types to trigger on
+    
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    # Relationships
+    form: Mapped[Form] = relationship()
+    user: Mapped[User] = relationship()
+

app/oauth_google.py

@@ -0,0 +1,77 @@
+import os
+import logging
+from urllib.parse import urlencode
+from fastapi import APIRouter, Request, Depends
+from authlib.integrations.starlette_client import OAuth
+from starlette.responses import RedirectResponse
+from sqlalchemy.orm import Session
+from .db import get_db
+from .models import User
+from .security import create_access_token
+from .services.subscription_service import subscription_service
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/auth/google", tags=["auth"])
+FRONTEND_URL = os.getenv("FRONTEND_URL", "http://localhost:5173")
+
+
+GOOGLE_CLIENT_ID = os.getenv("GOOGLE_CLIENT_ID", "")
+GOOGLE_CLIENT_SECRET = os.getenv("GOOGLE_CLIENT_SECRET", "")
+GOOGLE_REDIRECT_URI = os.getenv("GOOGLE_REDIRECT_URI", "http://localhost:8000/api/auth/google/callback")
+
+oauth = OAuth()
+oauth.register(
+    name="google",
+    client_id=GOOGLE_CLIENT_ID,
+    client_secret=GOOGLE_CLIENT_SECRET,
+    server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+    client_kwargs={"scope": "openid email profile"},
+)
+
+
+@router.get("/login")
+async def login(request: Request):
+    redirect_uri = GOOGLE_REDIRECT_URI
+    return await oauth.google.authorize_redirect(request, redirect_uri)
+
+
+@router.get("/callback")
+async def callback(request: Request, db: Session = Depends(get_db)):
+    try:
+        token = await oauth.google.authorize_access_token(request)
+        userinfo = token.get("userinfo") or await oauth.google.parse_id_token(request, token)
+        
+        email = userinfo.get("email")
+        if not email:
+            logger.error("No email in Google OAuth response")
+            return RedirectResponse(url=f"{FRONTEND_URL}/?error=missing_email")
+        
+        user = db.query(User).filter(User.email == email).first()
+        is_new_user = not user
+        
+        if is_new_user:
+            user = User(
+                email=email,
+                name=userinfo.get("name"),
+                picture=userinfo.get("picture"),
+                provider="google",
+                provider_id=userinfo.get("sub")
+            )
+            db.add(user)
+            db.commit()
+            db.refresh(user)
+            
+            # Assign free tier (non-blocking)
+            try:
+                subscription_service.assign_free_tier(db, user)
+            except Exception as e:
+                logger.error(f"Failed to assign free tier to user {user.id}: {e}")
+        
+        jwt_token = create_access_token(str(user.id), {"email": user.email})
+        return RedirectResponse(url=f"{FRONTEND_URL}/?{urlencode({'token': jwt_token})}")
+    
+    except Exception as e:
+        logger.error(f"OAuth callback error: {e}", exc_info=True)
+        return RedirectResponse(url=f"{FRONTEND_URL}/?error=login_failed")
+
+

app/package-lock.json

@@ -0,0 +1,448 @@
+{
+  "name": "app",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "recharts": "^3.6.0"
+      }
+    },
+    "node_modules/@reduxjs/toolkit": {
+      "version": "2.11.2",
+      "resolved": "https://registry.npmjs.org/@reduxjs/toolkit/-/toolkit-2.11.2.tgz",
+      "integrity": "sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@standard-schema/utils": "^0.3.0",
+        "immer": "^11.0.0",
+        "redux": "^5.0.1",
+        "redux-thunk": "^3.1.0",
+        "reselect": "^5.1.0"
+      },
+      "peerDependencies": {
+        "react": "^16.9.0 || ^17.0.0 || ^18 || ^19",
+        "react-redux": "^7.2.1 || ^8.1.3 || ^9.0.0"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        },
+        "react-redux": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@reduxjs/toolkit/node_modules/immer": {
+      "version": "11.1.3",
+      "resolved": "https://registry.npmjs.org/immer/-/immer-11.1.3.tgz",
+      "integrity": "sha512-6jQTc5z0KJFtr1UgFpIL3N9XSC3saRaI9PwWtzM2pSqkNGtiNkYY2OSwkOGDK2XcTRcLb1pi/aNkKZz0nxVH4Q==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/immer"
+      }
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "license": "MIT"
+    },
+    "node_modules/@standard-schema/utils": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/utils/-/utils-0.3.0.tgz",
+      "integrity": "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-array": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.2.tgz",
+      "integrity": "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-color": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
+      "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-ease": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
+      "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-interpolate": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
+      "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-color": "*"
+      }
+    },
+    "node_modules/@types/d3-path": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-3.1.1.tgz",
+      "integrity": "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-scale": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz",
+      "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-time": "*"
+      }
+    },
+    "node_modules/@types/d3-shape": {
+      "version": "3.1.8",
+      "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.8.tgz",
+      "integrity": "sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-path": "*"
+      }
+    },
+    "node_modules/@types/d3-time": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz",
+      "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-timer": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz",
+      "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/use-sync-external-store": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/@types/use-sync-external-store/-/use-sync-external-store-0.0.6.tgz",
+      "integrity": "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==",
+      "license": "MIT"
+    },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/d3-array": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz",
+      "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==",
+      "license": "ISC",
+      "dependencies": {
+        "internmap": "1 - 2"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-color": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
+      "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-ease": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
+      "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-format": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz",
+      "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-interpolate": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
+      "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-path": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz",
+      "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-scale": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz",
+      "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2.10.0 - 3",
+        "d3-format": "1 - 3",
+        "d3-interpolate": "1.2.0 - 3",
+        "d3-time": "2.1.1 - 3",
+        "d3-time-format": "2 - 4"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-shape": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
+      "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-path": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-time": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz",
+      "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-time-format": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz",
+      "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-time": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-timer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+      "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/decimal.js-light": {
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/decimal.js-light/-/decimal.js-light-2.5.1.tgz",
+      "integrity": "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==",
+      "license": "MIT"
+    },
+    "node_modules/es-toolkit": {
+      "version": "1.43.0",
+      "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.43.0.tgz",
+      "integrity": "sha512-SKCT8AsWvYzBBuUqMk4NPwFlSdqLpJwmy6AP322ERn8W2YLIB6JBXnwMI2Qsh2gfphT3q7EKAxKb23cvFHFwKA==",
+      "license": "MIT",
+      "workspaces": [
+        "docs",
+        "benchmarks"
+      ]
+    },
+    "node_modules/eventemitter3": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.1.tgz",
+      "integrity": "sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==",
+      "license": "MIT"
+    },
+    "node_modules/immer": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/immer/-/immer-10.2.0.tgz",
+      "integrity": "sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/immer"
+      }
+    },
+    "node_modules/internmap": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz",
+      "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.3",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.3.tgz",
+      "integrity": "sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==",
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.2.3",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.3.tgz",
+      "integrity": "sha512-yELu4WmLPw5Mr/lmeEpox5rw3RETacE++JgHqQzd2dg+YbJuat3jH4ingc+WPZhxaoFzdv9y33G+F7Nl5O0GBg==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.3"
+      }
+    },
+    "node_modules/react-is": {
+      "version": "19.2.3",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.3.tgz",
+      "integrity": "sha512-qJNJfu81ByyabuG7hPFEbXqNcWSU3+eVus+KJs+0ncpGfMyYdvSmxiJxbWR65lYi1I+/0HBcliO029gc4F+PnA==",
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/react-redux": {
+      "version": "9.2.0",
+      "resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
+      "integrity": "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/use-sync-external-store": "^0.0.6",
+        "use-sync-external-store": "^1.4.0"
+      },
+      "peerDependencies": {
+        "@types/react": "^18.2.25 || ^19",
+        "react": "^18.0 || ^19",
+        "redux": "^5.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "redux": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/recharts": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/recharts/-/recharts-3.6.0.tgz",
+      "integrity": "sha512-L5bjxvQRAe26RlToBAziKUB7whaGKEwD3znoM6fz3DrTowCIC/FnJYnuq1GEzB8Zv2kdTfaxQfi5GoH0tBinyg==",
+      "license": "MIT",
+      "workspaces": [
+        "www"
+      ],
+      "dependencies": {
+        "@reduxjs/toolkit": "1.x.x || 2.x.x",
+        "clsx": "^2.1.1",
+        "decimal.js-light": "^2.5.1",
+        "es-toolkit": "^1.39.3",
+        "eventemitter3": "^5.0.1",
+        "immer": "^10.1.1",
+        "react-redux": "8.x.x || 9.x.x",
+        "reselect": "5.1.1",
+        "tiny-invariant": "^1.3.3",
+        "use-sync-external-store": "^1.2.2",
+        "victory-vendor": "^37.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-is": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/redux": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz",
+      "integrity": "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==",
+      "license": "MIT"
+    },
+    "node_modules/redux-thunk": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/redux-thunk/-/redux-thunk-3.1.0.tgz",
+      "integrity": "sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "redux": "^5.0.0"
+      }
+    },
+    "node_modules/reselect": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/reselect/-/reselect-5.1.1.tgz",
+      "integrity": "sha512-K/BG6eIky/SBpzfHZv/dd+9JBFiS4SWV7FIujVyJRux6e45+73RaUHXLmIR1f7WOMaQ0U1km6qwklRQxpJJY0w==",
+      "license": "MIT"
+    },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/tiny-invariant": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz",
+      "integrity": "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==",
+      "license": "MIT"
+    },
+    "node_modules/use-sync-external-store": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",
+      "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/victory-vendor": {
+      "version": "37.3.6",
+      "resolved": "https://registry.npmjs.org/victory-vendor/-/victory-vendor-37.3.6.tgz",
+      "integrity": "sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ==",
+      "license": "MIT AND ISC",
+      "dependencies": {
+        "@types/d3-array": "^3.0.3",
+        "@types/d3-ease": "^3.0.0",
+        "@types/d3-interpolate": "^3.0.1",
+        "@types/d3-scale": "^4.0.2",
+        "@types/d3-shape": "^3.1.0",
+        "@types/d3-time": "^3.0.0",
+        "@types/d3-timer": "^3.0.0",
+        "d3-array": "^3.1.6",
+        "d3-ease": "^3.0.1",
+        "d3-interpolate": "^3.0.1",
+        "d3-scale": "^4.0.2",
+        "d3-shape": "^3.1.0",
+        "d3-time": "^3.0.0",
+        "d3-timer": "^3.0.1"
+      }
+    }
+  }
+}

app/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "recharts": "^3.6.0"
+  }
+}

app/routes/__init__.py

@@ -0,0 +1,2 @@
+
+

app/routes/analytics.py

@@ -0,0 +1,200 @@
+"""
+Analytics API Routes
+====================
+
+Routes for form analytics and tracking.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from sqlalchemy.orm import Session
+from typing import Optional
+from datetime import datetime
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User, Form, PublicForm
+from ..services.analytics_service import analytics_service
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["analytics"])
+
+
+@router.post("/public/forms/{token}/track")
+async def track_public_event(
+    token: str,
+    event_type: str,
+    session_id: str,
+    request: Request,
+    question_id: Optional[int] = None,
+    time_spent: Optional[int] = None,
+    db: Session = Depends(get_db)
+):
+    """
+    Public endpoint for client-side analytics tracking.
+    No authentication required.
+    """
+    # Find public form by token
+    public_form = db.query(PublicForm).filter(
+        PublicForm.share_token == token,
+        PublicForm.is_public == True
+    ).first()
+    
+    if not public_form:
+        # Silently fail for analytics - don't break form
+        logger.warning(f"Analytics tracking: form not found for token {token}")
+        return {"success": False, "message": "Form not found"}
+    
+    try:
+        # Track event
+        await analytics_service.track_event(
+            db=db,
+            event_type=event_type,
+            form_id=public_form.form_id,
+            session_id=session_id,
+            request=request,
+            question_id=question_id,
+            time_spent_seconds=time_spent
+        )
+        
+        return {"success": True, "message": "Event tracked"}
+        
+    except Exception as e:
+        logger.error(f"Analytics tracking failed: {e}")
+        # Silently fail - analytics shouldn't break form
+        return {"success": False, "message": "Tracking failed"}
+
+
+@router.get("/forms/{form_id}/analytics/funnel")
+async def get_form_funnel(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    question_ids: Optional[str] = None,
+    countries: Optional[str] = None,
+    utm_source: Optional[str] = None
+):
+    """
+    Get funnel analytics for form owner with advanced filtering.
+    Requires authentication.
+    """
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Parse dates
+    start_dt = datetime.fromisoformat(start_date) if start_date else None
+    end_dt = datetime.fromisoformat(end_date) if end_date else None
+    
+    # Parse question IDs
+    question_id_list = [int(x) for x in question_ids.split(',')] if question_ids else None
+    
+    # Parse countries
+    country_list = [x.strip() for x in countries.split(',')] if countries else None
+    
+    # Get funnel analytics
+    funnel_data = await analytics_service.get_funnel_analytics(
+        db=db,
+        form_id=form_id,
+        start_date=start_dt,
+        end_date=end_dt,
+        question_ids=question_id_list,
+        countries=country_list,
+        utm_source=utm_source
+    )
+    
+    return funnel_data
+
+
+@router.get("/forms/{form_id}/analytics/timeseries")
+async def get_time_series(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    question_ids: Optional[str] = None,
+    countries: Optional[str] = None,
+    utm_source: Optional[str] = None
+):
+    """
+    Get time-series data for views and submissions with filtering.
+    Requires authentication.
+    """
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Parse dates
+    start_dt = datetime.fromisoformat(start_date) if start_date else None
+    end_dt = datetime.fromisoformat(end_date) if end_date else None
+    
+    # Parse question IDs
+    question_id_list = [int(x) for x in question_ids.split(',')] if question_ids else None
+    
+    # Parse countries
+    country_list = [x.strip() for x in countries.split(',')] if countries else None
+    
+    # Get time-series data
+    time_series_data = await analytics_service.get_time_series_data(
+        db=db,
+        form_id=form_id,
+        start_date=start_dt,
+        end_date=end_dt,
+        question_ids=question_id_list,
+        countries=country_list,
+        utm_source=utm_source
+    )
+    
+    return time_series_data
+
+
+@router.get("/forms/{form_id}/analytics/summary")
+async def get_analytics_summary(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get high-level analytics summary.
+    Requires authentication.
+    """
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get summary analytics
+    summary_data = await analytics_service.get_summary_analytics(
+        db=db,
+        form_id=form_id
+    )
+    
+    return summary_data

app/routes/auth.py

@@ -0,0 +1,135 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+from ..core.security import create_access_token, get_current_subject, get_current_user
+from ..core.db import get_db
+from ..models import User
+from ..schemas.auth import LoginRequest, TokenResponse
+
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+@router.post("/login", response_model=TokenResponse)
+def login(payload: LoginRequest, db: Session = Depends(get_db)):
+    """
+    Demo/testing login endpoint. For production, use Google OAuth at /api/auth/google/login
+    This creates or gets a test user from the database.
+    """
+    # Find or create test user
+    user = db.query(User).filter(User.email == payload.email).first()
+    if not user:
+        user = User(
+            email=payload.email,
+            name="Test User",
+            provider="test",
+            is_active=True
+        )
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+    
+    token = create_access_token(str(user.id), {"email": user.email})
+    return TokenResponse(token=token, user={"id": str(user.id), "email": user.email})
+
+
+@router.post("/logout")
+def logout():
+    return {"success": True, "message": "Logged out successfully"}
+
+
+@router.get("/me")
+def get_current_user_info(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get current authenticated user's profile information"""
+    # Get user's subscription info
+    from ..models import Subscription, Dataset
+    from datetime import datetime, timezone
+    
+    subscription = db.query(Subscription).filter(
+        Subscription.user_id == current_user.id
+    ).order_by(Subscription.created_at.desc()).first()
+    
+    subscription_info = None
+    if subscription:
+        subscription_info = {
+            "tier": subscription.status,  # e.g., "free", "pro", "enterprise"
+            "status": subscription.status,
+            "stripe_customer_id": subscription.stripe_customer_id,
+            "stripe_subscription_id": subscription.stripe_subscription_id,
+            "created_at": subscription.created_at.isoformat()
+        }
+    
+    # Calculate dashboards created this month
+    now = datetime.now(timezone.utc)
+    start_of_month = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    
+    dashboards_this_month = db.query(Dataset).filter(
+        Dataset.user_id == current_user.id,
+        Dataset.created_at >= start_of_month
+    ).count()
+    
+    return {
+        "id": current_user.id,
+        "email": current_user.email,
+        "name": current_user.name,
+        "picture": current_user.picture,
+        "provider": current_user.provider,
+        "is_active": current_user.is_active,
+        "created_at": current_user.created_at.isoformat(),
+        "dashboards_this_month": dashboards_this_month,
+        "subscription": subscription_info or {
+            "tier": "free",
+            "status": "inactive",
+            "stripe_customer_id": None,
+            "stripe_subscription_id": None,
+            "created_at": None
+        }
+    }
+
+
+class UpdateProfileRequest(BaseModel):
+    name: str | None = None
+
+
+@router.patch("/me")
+def update_user_profile(
+    payload: UpdateProfileRequest,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Update current user's profile"""
+    if payload.name is not None:
+        current_user.name = payload.name
+    
+    db.commit()
+    db.refresh(current_user)
+    
+    return {
+        "message": "Profile updated successfully",
+        "user": {
+            "id": current_user.id,
+            "email": current_user.email,
+            "name": current_user.name,
+            "picture": current_user.picture,
+        }
+    }
+
+
+@router.delete("/me")
+def deactivate_account(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Deactivate user account (soft delete)"""
+    current_user.is_active = False
+    db.commit()
+    
+    return {
+        "message": "Account deactivated successfully",
+        "success": True
+    }
+
+

app/routes/credits.py

@@ -0,0 +1,94 @@
+"""
+Credit management routes
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from typing import List, Dict, Any
+from pydantic import BaseModel
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User
+from ..services.credit_service import credit_service
+
+router = APIRouter(prefix="/api/credits", tags=["credits"])
+
+
+class CreditBalanceResponse(BaseModel):
+    """Response model for credit balance"""
+    balance: int
+    plan_name: str | None
+    plan_id: int | None
+    credits_per_analyze: int
+    credits_per_edit: int
+    last_reset_at: str | None
+    updated_at: str
+
+
+class CreditTransactionResponse(BaseModel):
+    """Response model for a credit transaction"""
+    id: int
+    amount: int
+    transaction_type: str
+    description: str
+    transaction_metadata: Dict[str, Any] | None
+    created_at: str
+
+
+@router.get("/balance", response_model=CreditBalanceResponse)
+def get_credit_balance(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get the current user's credit balance and plan information
+    
+    Returns:
+        Credit balance and plan details
+    """
+    try:
+        # Ensure credits record exists (auto-create if missing)
+        credit_service.get_or_create_user_credits(db, current_user.id)
+        balance_info = credit_service.get_balance_info(db, current_user.id)
+        return balance_info
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/history")
+def get_credit_history(
+    limit: int = 50,
+    offset: int = 0,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get credit transaction history for the current user
+    
+    Args:
+        limit: Maximum number of transactions to return (default 50)
+        offset: Number of transactions to skip (default 0)
+        
+    Returns:
+        List of credit transactions
+    """
+    try:
+        transactions = credit_service.get_credit_history(
+            db, current_user.id, limit=limit, offset=offset
+        )
+        
+        # Convert to response format
+        return [
+            {
+                "id": t.id,
+                "amount": t.amount,
+                "transaction_type": t.transaction_type.value,
+                "description": t.description,
+                "transaction_metadata": t.transaction_metadata,
+                "created_at": t.created_at.isoformat()
+            }
+            for t in transactions
+        ]
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+

app/routes/export.py

@@ -0,0 +1,504 @@
+"""
+Export routes for downloading charts as PNG, ZIP, or PDF
+"""
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import Response
+from pydantic import BaseModel
+from typing import List, Dict, Any, Optional
+import plotly.graph_objects as go
+import os
+import tempfile
+import zipfile
+from datetime import datetime
+from pathlib import Path
+import io
+from PIL import Image
+import base64
+
+# ReportLab imports
+from reportlab.lib.pagesizes import letter
+from reportlab.pdfgen import canvas as pdf_canvas
+from reportlab.lib.utils import ImageReader
+
+router = APIRouter(prefix="/api/export", tags=["export"])
+
+# Path to logo
+LOGO_PATH = Path(__file__).parent.parent.parent / "images" / "AutoForm.png"
+
+
+class ChartExportRequest(BaseModel):
+    """Request model for chart export"""
+    charts: List[Dict[str, Any]]  # List of chart specs with figure data
+    titles: Optional[List[str]] = None  # Optional custom titles
+
+
+class ChartImageRequest(BaseModel):
+    """Request with pre-rendered chart images (avoids kaleido issues)"""
+    charts: List[Dict[str, str]]  # [{"title": "...", "imageData": "data:image/png;base64,..."}]
+
+
+@router.post("/charts-zip-from-images")
+async def export_charts_zip_from_images(request: ChartImageRequest):
+    """
+    Create ZIP from pre-rendered chart images (no kaleido needed!)
+    Frontend exports charts using Plotly.toImage() and sends base64 data
+    """
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            png_files = []
+            
+            for idx, chart in enumerate(request.charts, 1):
+                try:
+                    title = chart.get('title', f'chart_{idx}')
+                    image_data = chart.get('imageData', '')
+                    
+                    # Remove data URL prefix if present
+                    if 'base64,' in image_data:
+                        image_data = image_data.split('base64,')[1]
+                    
+                    # Decode base64 to bytes
+                    img_bytes = base64.b64decode(image_data)
+                    
+                    # Sanitize filename
+                    safe_title = "".join(c for c in title if c.isalnum() or c in (' ', '-', '_')).rstrip()
+                    safe_title = safe_title.replace(' ', '_').lower()
+                    filename = f"{idx:02d}_{safe_title}.png"
+                    filepath = os.path.join(temp_dir, filename)
+                    
+                    # Write image
+                    with open(filepath, 'wb') as f:
+                        f.write(img_bytes)
+                    
+                    png_files.append(filepath)
+                    print(f"[SUCCESS] Added chart {idx} to ZIP: {filename}")
+                    
+                except Exception as e:
+                    print(f"[ERROR] Error processing chart {idx}: {e}")
+                    import traceback
+                    traceback.print_exc()
+                    continue
+            
+            if not png_files:
+                raise HTTPException(status_code=400, detail="No charts could be processed")
+            
+            # Create ZIP
+            zip_path = os.path.join(temp_dir, f"charts_{timestamp}.zip")
+            with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+                for filepath in png_files:
+                    zipf.write(filepath, os.path.basename(filepath))
+            
+            print(f"[SUCCESS] Created ZIP with {len(png_files)} charts")
+            
+            with open(zip_path, 'rb') as f:
+                zip_data = f.read()
+        
+        return Response(
+            content=zip_data,
+            media_type="application/zip",
+            headers={"Content-Disposition": f"attachment; filename=charts_{timestamp}.zip"}
+        )
+        
+    except Exception as e:
+        print(f"[ERROR] Error creating ZIP: {e}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/dashboard-pdf-from-images")
+async def export_pdf_from_images(request: ChartImageRequest):
+    """
+    Create PDF from pre-rendered chart images (no kaleido needed!)
+    Includes Auto-Dash logo on every page
+    """
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            pdf_path = os.path.join(temp_dir, f"report_{timestamp}.pdf")
+            
+            c = pdf_canvas.Canvas(pdf_path, pagesize=letter)
+            page_width, page_height = letter
+            
+            # Load logo
+            logo_img = None
+            if LOGO_PATH.exists():
+                try:
+                    logo_img = Image.open(LOGO_PATH)
+                except Exception as e:
+                    print(f"Could not load logo: {e}")
+            
+            for idx, chart in enumerate(request.charts, 1):
+                try:
+                    print(f"[INFO] Adding chart {idx} to PDF...")
+                    
+                    title = chart.get('title', f'Chart {idx}')
+                    image_data = chart.get('imageData', '')
+                    
+                    # Remove data URL prefix
+                    if 'base64,' in image_data:
+                        image_data = image_data.split('base64,')[1]
+                    
+                    # Decode and load image
+                    img_bytes = base64.b64decode(image_data)
+                    chart_img = Image.open(io.BytesIO(img_bytes))
+                    
+                    # === ADD LOGO (CENTERED AT TOP) ===
+                    if logo_img:
+                        # Smaller logo size
+                        logo_height = 25
+                        logo_aspect = logo_img.width / logo_img.height
+                        logo_width = logo_height * logo_aspect
+                        
+                        # Center logo horizontally
+                        logo_x = (page_width - logo_width) / 2
+                        logo_y = page_height - logo_height - 15
+                        
+                        logo_buffer = io.BytesIO()
+                        logo_img.save(logo_buffer, format='PNG')
+                        logo_buffer.seek(0)
+                        
+                        c.drawImage(ImageReader(logo_buffer), logo_x, logo_y,
+                                   width=logo_width, height=logo_height,
+                                   preserveAspectRatio=True, mask='auto')
+                        
+                        # Center "Auto-Dash" text below logo
+                        c.setFont("Helvetica-Bold", 12)
+                        c.setFillColorRGB(0.2, 0.2, 0.2)
+                        c.drawCentredString(page_width / 2, logo_y - 15, "Auto-Dash")
+                        
+                        # Center subtitle below
+                        c.setFont("Helvetica", 9)
+                        c.setFillColorRGB(0.5, 0.5, 0.5)
+                        c.drawCentredString(page_width / 2, logo_y - 28, "Analytics Dashboard")
+                    
+                    # === ADD CHART ===
+                    img_width, img_height = chart_img.size
+                    aspect_ratio = img_width / img_height
+                    margin = 36
+                    top_margin = 70 if logo_img else 36  # Smaller margin for centered compact logo
+                    bottom_margin = 60
+                    available_width = page_width - (2 * margin)
+                    available_height = page_height - top_margin - bottom_margin
+                    
+                    if available_width / available_height > aspect_ratio:
+                        scaled_height = available_height
+                        scaled_width = scaled_height * aspect_ratio
+                    else:
+                        scaled_width = available_width
+                        scaled_height = scaled_width / aspect_ratio
+                    
+                    # Center chart horizontally and vertically
+                    chart_x = (page_width - scaled_width) / 2
+                    chart_y = bottom_margin + (available_height - scaled_height) / 2
+                    
+                    chart_buffer = io.BytesIO()
+                    chart_img.save(chart_buffer, format='PNG')
+                    chart_buffer.seek(0)
+                    
+                    c.drawImage(ImageReader(chart_buffer), chart_x, chart_y,
+                               width=scaled_width, height=scaled_height)
+                    
+                    # === ADD FOOTER ===
+                    c.setFont("Helvetica", 10)
+                    c.setFillColorRGB(0.4, 0.4, 0.4)
+                    c.drawCentredString(page_width / 2, 25, f"Page {idx} of {len(request.charts)}")
+                    c.setFont("Helvetica", 9)
+                    c.drawString(margin, 25, title)
+                    c.setFont("Helvetica", 8)
+                    c.drawRightString(page_width - margin, 25,
+                                     datetime.now().strftime("%B %d, %Y %I:%M %p"))
+                    
+                    if idx < len(request.charts):
+                        c.showPage()
+                    
+                    print(f"[SUCCESS] Chart {idx} added to PDF successfully")
+                    
+                except Exception as e:
+                    print(f"[ERROR] Error adding chart {idx}: {e}")
+                    import traceback
+                    traceback.print_exc()
+                    continue
+            
+            c.save()
+            print(f"[SUCCESS] PDF created with {len(request.charts)} pages")
+            
+            with open(pdf_path, 'rb') as f:
+                pdf_data = f.read()
+        
+        return Response(
+            content=pdf_data,
+            media_type="application/pdf",
+            headers={"Content-Disposition": f"attachment; filename=report_{timestamp}.pdf"}
+        )
+        
+    except Exception as e:
+        print(f"[ERROR] Error creating PDF: {e}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/charts-zip")
+async def export_charts_as_zip(request: ChartExportRequest):
+    """
+    Export all charts as individual PNG files bundled in a ZIP
+    
+    Returns: ZIP file containing all chart PNGs
+    """
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        # Create temporary directory
+        with tempfile.TemporaryDirectory() as temp_dir:
+            png_files = []
+            
+            # Export each chart as PNG
+            for idx, chart_data in enumerate(request.charts, 1):
+                try:
+                    print(f"[INFO] Processing chart {idx}...")
+                    
+                    # Get figure data
+                    figure = chart_data.get('figure')
+                    if not figure:
+                        print(f"[WARNING] Chart {idx}: No figure data, skipping")
+                        continue
+                    
+                    # Create Plotly figure
+                    fig = go.Figure(figure)
+                    print(f"[SUCCESS] Chart {idx}: Created Plotly figure")
+                    
+                    # Generate filename
+                    title = request.titles[idx-1] if request.titles and len(request.titles) >= idx else f"chart_{idx}"
+                    # Sanitize title for filename
+                    safe_title = "".join(c for c in title if c.isalnum() or c in (' ', '-', '_')).rstrip()
+                    safe_title = safe_title.replace(' ', '_').lower()
+                    
+                    filename = f"{idx:02d}_{safe_title}.png"
+                    filepath = os.path.join(temp_dir, filename)
+                    
+                    print(f"[INFO] Exporting chart {idx} to bytes...")
+                    
+                    # Export to PNG using to_image (doesn't hang like write_image)
+                    img_bytes = fig.to_image(
+                        format='png',
+                        width=1000,
+                        height=800,
+                        scale=2,
+                        engine='kaleido'
+                    )
+                    
+                    # Write bytes to file
+                    with open(filepath, 'wb') as f:
+                        f.write(img_bytes)
+                    
+                    png_files.append(filepath)
+                    print(f"[SUCCESS] Chart {idx} exported successfully: {filename}")
+                    
+                except Exception as e:
+                    print(f"[ERROR] Error exporting chart {idx}: {str(e)}")
+                    import traceback
+                    traceback.print_exc()
+                    continue
+            
+            if not png_files:
+                raise HTTPException(status_code=400, detail="No charts could be exported")
+            
+            # Create ZIP file
+            zip_path = os.path.join(temp_dir, f"charts_{timestamp}.zip")
+            with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+                for filepath in png_files:
+                    zipf.write(filepath, os.path.basename(filepath))
+            
+            # Read ZIP file into memory
+            with open(zip_path, 'rb') as f:
+                zip_data = f.read()
+        
+        # Return ZIP file
+        return Response(
+            content=zip_data,
+            media_type="application/zip",
+            headers={
+                "Content-Disposition": f"attachment; filename=charts_{timestamp}.zip"
+            }
+        )
+        
+    except Exception as e:
+        print(f"Error creating ZIP: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to create ZIP: {str(e)}")
+
+
+@router.post("/dashboard-pdf")
+async def export_dashboard_as_pdf(request: ChartExportRequest):
+    """
+    Export all charts as a single PDF with each chart on a separate page.
+    Includes Auto-Dash logo on every page.
+    
+    Returns: PDF file
+    """
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        # Create temporary directory
+        with tempfile.TemporaryDirectory() as temp_dir:
+            pdf_path = os.path.join(temp_dir, f"report_{timestamp}.pdf")
+            
+            # Create PDF
+            c = pdf_canvas.Canvas(pdf_path, pagesize=letter)
+            page_width, page_height = letter  # 612 x 792 points
+            
+            # Load logo
+            logo_img = None
+            if LOGO_PATH.exists():
+                try:
+                    logo_img = Image.open(LOGO_PATH)
+                except Exception as e:
+                    print(f"Could not load logo: {e}")
+            
+            # Process each chart
+            for idx, chart_data in enumerate(request.charts, 1):
+                try:
+                    print(f"[INFO] Processing PDF page {idx}...")
+                    
+                    # Get figure data
+                    figure = chart_data.get('figure')
+                    if not figure:
+                        print(f"[WARNING] Chart {idx}: No figure data, skipping")
+                        continue
+                    
+                    # Create Plotly figure
+                    fig = go.Figure(figure)
+                    print(f"[SUCCESS] Chart {idx}: Created Plotly figure for PDF")
+                    
+                    # Get chart title
+                    chart_title = request.titles[idx-1] if request.titles and len(request.titles) >= idx else f"Chart {idx}"
+                    
+                    # === ADD LOGO (CENTERED AT TOP) ===
+                    if logo_img:
+                        # Smaller logo size
+                        logo_height = 25
+                        logo_aspect = logo_img.width / logo_img.height
+                        logo_width = logo_height * logo_aspect
+                        
+                        # Center logo horizontally
+                        logo_x = (page_width - logo_width) / 2
+                        logo_y = page_height - logo_height - 15
+                        
+                        logo_buffer = io.BytesIO()
+                        logo_img.save(logo_buffer, format='PNG')
+                        logo_buffer.seek(0)
+                        logo_reader = ImageReader(logo_buffer)
+                        
+                        c.drawImage(
+                            logo_reader,
+                            logo_x, logo_y,
+                            width=logo_width,
+                            height=logo_height,
+                            preserveAspectRatio=True,
+                            mask='auto'
+                        )
+                        
+                        # Center "Auto-Dash" text below logo
+                        # c.setFont("Helvetica-Bold", 12)
+                        # c.setFillColorRGB(0.2, 0.2, 0.2)
+                        # c.drawCentredString(page_width / 2, logo_y - 15, "Auto-Dash")
+                        
+                        # # Center subtitle below
+                        # c.setFont("Helvetica", 9)
+                        # c.setFillColorRGB(0.5, 0.5, 0.5)
+                        # c.drawCentredString(page_width / 2, logo_y - 28, "Analytics Dashboard")
+                    
+                    # === ADD CHART ===
+                    # Export chart to PNG bytes
+                    print(f"[INFO] Exporting chart {idx} to bytes for PDF...")
+                    img_bytes = fig.to_image(format='png', width=1000, height=800, scale=2, engine='kaleido')
+                    chart_img = Image.open(io.BytesIO(img_bytes))
+                    print(f"[SUCCESS] Chart {idx} exported to bytes successfully")
+                    
+                    img_width, img_height = chart_img.size
+                    aspect_ratio = img_width / img_height
+                    
+                    # Calculate available space
+                    margin = 36
+                    top_margin = 70 if logo_img else 36  # Smaller margin for centered compact logo
+                    bottom_margin = 60
+                    
+                    available_width = page_width - (2 * margin)
+                    available_height = page_height - top_margin - bottom_margin
+                    
+                    # Scale to fit
+                    if available_width / available_height > aspect_ratio:
+                        scaled_height = available_height
+                        scaled_width = scaled_height * aspect_ratio
+                    else:
+                        scaled_width = available_width
+                        scaled_height = scaled_width / aspect_ratio
+                    
+                    # Center chart
+                    # Center chart horizontally and vertically
+                    chart_x = (page_width - scaled_width) / 2
+                    chart_y = bottom_margin + (available_height - scaled_height) / 2
+                    
+                    # Draw chart
+                    chart_buffer = io.BytesIO()
+                    chart_img.save(chart_buffer, format='PNG')
+                    chart_buffer.seek(0)
+                    chart_reader = ImageReader(chart_buffer)
+                    
+                    c.drawImage(
+                        chart_reader,
+                        chart_x, chart_y,
+                        width=scaled_width,
+                        height=scaled_height,
+                        preserveAspectRatio=True
+                    )
+                    
+                    # === ADD FOOTER ===
+                    c.setFont("Helvetica", 10)
+                    c.setFillColorRGB(0.4, 0.4, 0.4)
+                    c.drawCentredString(
+                        page_width / 2, 25,
+                        f"Page {idx} of {len(request.charts)}"
+                    )
+                    
+                    c.setFont("Helvetica", 9)
+                    c.drawString(margin, 25, chart_title)
+                    
+                    c.setFont("Helvetica", 8)
+                    c.drawRightString(
+                        page_width - margin, 25,
+                        datetime.now().strftime("%B %d, %Y %I:%M %p")
+                    )
+                    
+                    # New page if not last
+                    if idx < len(request.charts):
+                        c.showPage()
+                        
+                except Exception as e:
+                    print(f"[ERROR] Error adding chart {idx} to PDF: {str(e)}")
+                    import traceback
+                    traceback.print_exc()
+                    continue
+            
+            # Save PDF
+            c.save()
+            
+            # Read PDF into memory
+            with open(pdf_path, 'rb') as f:
+                pdf_data = f.read()
+        
+        # Return PDF
+        return Response(
+            content=pdf_data,
+            media_type="application/pdf",
+            headers={
+                "Content-Disposition": f"attachment; filename=report_{timestamp}.pdf"
+            }
+        )
+        
+    except Exception as e:
+        print(f"Error creating PDF: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to create PDF: {str(e)}")
+

app/routes/forms.py

@@ -0,0 +1,789 @@
+"""
+Forms API Routes
+================
+
+Routes for form CRUD operations, questions, and conditional logic.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from sqlalchemy import desc
+from typing import List
+import secrets
+from datetime import datetime
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User, Form, FormQuestion, ConditionalRule, PublicForm, QuestionType, ConditionType
+from ..schemas.form import (
+    FormCreate, FormUpdate, FormResponse, FormGenerationResponse,
+    QuestionCreate, QuestionUpdate, QuestionResponse,
+    ConditionalRuleCreate, ConditionalRuleResponse,
+    PublicFormCreate, PublicFormResponse,
+    ChatMessage, ChatResponse
+)
+from ..services.form_creator import generate_form_spec, edit_form_spec, validate_question_type, validate_condition_type
+from ..services.credit_service import credit_service
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/forms", tags=["forms"])
+
+
+@router.post("/generate", response_model=FormGenerationResponse)
+async def generate_form(
+    form_data: FormCreate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Generate a new form from natural language description using AI.
+    Costs 5 credits.
+    """
+    # Check credits
+    if not credit_service.check_sufficient_credits(db, current_user.id, 5):
+        raise HTTPException(
+            status_code=status.HTTP_402_PAYMENT_REQUIRED,
+            detail="Insufficient credits. Please upgrade your plan."
+        )
+    
+    try:
+        # Generate form using AI
+        form_spec, questions_spec, rules_spec = await generate_form_spec(
+            user_query=form_data.user_query,
+            user_id=current_user.id
+        )
+        
+        # Create form in database
+        new_form = Form(
+            user_id=current_user.id,
+            title=form_spec.get("title", "New Form"),
+            description=form_spec.get("description"),
+            settings=form_spec.get("settings", {})
+        )
+        db.add(new_form)
+        db.flush()  # Get form ID
+        
+        # Create questions
+        question_id_map = {}  # Map order to actual ID
+        for q_spec in questions_spec:
+            # Final safety check: ensure matrix/ranking settings are lists
+            settings = q_spec.get("settings", {})
+            question_type = q_spec.get("question_type", "")
+            
+            if question_type == "matrix":
+                if isinstance(settings.get("rows"), (int, float)):
+                    num_rows = max(1, int(settings["rows"]))
+                    settings["rows"] = [f"Row {i+1}" for i in range(num_rows)]
+                if isinstance(settings.get("columns"), (int, float)):
+                    num_cols = max(1, int(settings["columns"]))
+                    settings["columns"] = [f"Column {i+1}" for i in range(num_cols)]
+            
+            if question_type == "ranking":
+                if isinstance(settings.get("ranking_items"), (int, float)):
+                    num_items = max(2, int(settings["ranking_items"]))
+                    settings["ranking_items"] = [f"Item {i+1}" for i in range(num_items)]
+            
+            question = FormQuestion(
+                form_id=new_form.id,
+                question_order=q_spec["question_order"],
+                question_type=QuestionType(q_spec["question_type"]),
+                question_text=q_spec["question_text"],
+                description=q_spec.get("description"),
+                required=q_spec.get("required", False),
+                settings=settings
+            )
+            db.add(question)
+            db.flush()
+            question_id_map[q_spec["question_order"]] = question.id
+        
+        # Create conditional rules
+        for rule_spec in rules_spec:
+            trigger_idx = rule_spec.get("trigger_question_index")
+            target_idx = rule_spec.get("target_question_index")
+            
+            if trigger_idx in question_id_map and target_idx in question_id_map:
+                rule = ConditionalRule(
+                    form_id=new_form.id,
+                    trigger_question_id=question_id_map[trigger_idx],
+                    target_question_id=question_id_map[target_idx],
+                    condition_type=ConditionType(rule_spec.get("condition_type", "equals")),
+                    condition_value=rule_spec.get("condition_value"),
+                    action=rule_spec.get("action", "show")
+                )
+                db.add(rule)
+        
+        db.commit()
+        db.refresh(new_form)
+        
+        # Deduct credits
+        credit_service.deduct_credits(
+            user_id=current_user.id,
+            amount=5,
+            description=f"Generated form: {new_form.title}",
+            db=db
+        )
+        
+        return FormGenerationResponse(
+            form=FormResponse.model_validate(new_form),
+            message="Form generated successfully"
+        )
+        
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Form generation failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Form generation failed: {str(e)}"
+        )
+
+
+@router.get("", response_model=List[FormResponse])
+async def list_forms(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    limit: int = 50,
+    offset: int = 0,
+    sort: str = "created_at"
+):
+    """Get all forms for the current user, optionally sorted by created_at or updated_at"""
+    query = db.query(Form).filter(Form.user_id == current_user.id)
+    
+    # Apply sorting
+    if sort == "updated_at":
+        query = query.order_by(desc(Form.updated_at))
+    elif sort == "created_at":
+        query = query.order_by(desc(Form.created_at))
+    else:
+        # Default to created_at if invalid sort parameter
+        query = query.order_by(desc(Form.created_at))
+    
+    forms = query.limit(limit).offset(offset).all()
+    
+    return [FormResponse.model_validate(form) for form in forms]
+
+
+@router.get("/{form_id}", response_model=FormResponse)
+async def get_form(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get a specific form with all questions and rules"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    return FormResponse.model_validate(form)
+
+
+@router.put("/{form_id}", response_model=FormResponse)
+async def update_form(
+    form_id: int,
+    form_update: FormUpdate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Update form metadata (title, description, settings)"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Update fields
+    if form_update.title is not None:
+        form.title = form_update.title
+    if form_update.description is not None:
+        form.description = form_update.description
+    if form_update.settings is not None:
+        form.settings = form_update.settings.model_dump()
+    
+    form.updated_at = datetime.utcnow()
+    
+    db.commit()
+    db.refresh(form)
+    
+    return FormResponse.model_validate(form)
+
+
+@router.delete("/{form_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_form(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Delete a form and all associated data"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    db.delete(form)
+    db.commit()
+    
+    return None
+
+
+# Question endpoints
+@router.post("/{form_id}/questions", response_model=QuestionResponse)
+async def add_question(
+    form_id: int,
+    question_data: QuestionCreate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Add a new question to a form"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    question = FormQuestion(
+        form_id=form_id,
+        question_order=question_data.question_order,
+        question_type=question_data.question_type,
+        question_text=question_data.question_text,
+        description=question_data.description,
+        required=question_data.required,
+        settings=question_data.settings.model_dump() if question_data.settings else {}
+    )
+    
+    db.add(question)
+    db.commit()
+    db.refresh(question)
+    
+    return QuestionResponse.model_validate(question)
+
+
+@router.put("/{form_id}/questions/{question_id}", response_model=QuestionResponse)
+async def update_question(
+    form_id: int,
+    question_id: int,
+    question_update: QuestionUpdate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Update a question"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    question = db.query(FormQuestion).filter(
+        FormQuestion.id == question_id,
+        FormQuestion.form_id == form_id
+    ).first()
+    
+    if not question:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Question not found"
+        )
+    
+    # Update fields
+    if question_update.question_text is not None:
+        question.question_text = question_update.question_text
+    if question_update.question_type is not None:
+        question.question_type = question_update.question_type
+    if question_update.description is not None:
+        question.description = question_update.description
+    if question_update.required is not None:
+        question.required = question_update.required
+    if question_update.question_order is not None:
+        question.question_order = question_update.question_order
+    if question_update.settings is not None:
+        question.settings = question_update.settings.model_dump()
+    
+    question.updated_at = datetime.utcnow()
+    
+    db.commit()
+    db.refresh(question)
+    
+    return QuestionResponse.model_validate(question)
+
+
+@router.delete("/{form_id}/questions/{question_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_question(
+    form_id: int,
+    question_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Delete a question"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    question = db.query(FormQuestion).filter(
+        FormQuestion.id == question_id,
+        FormQuestion.form_id == form_id
+    ).first()
+    
+    if not question:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Question not found"
+        )
+    
+    db.delete(question)
+    db.commit()
+    
+    return None
+
+
+@router.post("/{form_id}/questions/{question_id}/regenerate")
+async def regenerate_question(
+    form_id: int,
+    question_id: int,
+    context: dict,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Regenerate/edit a question using AI based on user's prompt.
+    """
+    # Get the form
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get the question
+    question = db.query(FormQuestion).filter(
+        FormQuestion.id == question_id,
+        FormQuestion.form_id == form_id
+    ).first()
+    
+    if not question:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Question not found"
+        )
+    
+    try:
+        # Get user's edit prompt
+        user_prompt = context.get("prompt", context.get("context", "Improve this question"))
+        
+        # Import the signature for question generation
+        from ..services.agents import FormQuestionGeneratorSignature
+        import dspy
+        
+        # Create context for regeneration with user's instructions
+        question_context = {
+            "brief": f"Edit this question based on user instructions: '{user_prompt}'. Current question: '{question.question_text}'. Current type: {question.question_type}. Current description: '{question.description or 'None'}'",
+            "index": question.question_order,
+            "form_context": {
+                "title": form.title,
+                "description": form.description,
+                "existing_questions": [q.question_text for q in form.questions if q.id != question_id],
+                "user_edit_instructions": user_prompt
+            }
+        }
+        
+        # Generate new question spec
+        generator = dspy.Predict(FormQuestionGeneratorSignature)
+        result = generator(
+            question_context=str(question_context),
+            form_title=form.title
+        )
+        
+        # Parse and validate the result
+        import json
+        question_spec = json.loads(result.question_spec)
+        
+        # Update the question
+        question.question_text = question_spec.get("text", question.question_text)
+        question.description = question_spec.get("description")
+        question.required = question_spec.get("required", question.required)
+        
+        # Update question type if specified
+        if "question_type" in question_spec:
+            try:
+                question.question_type = QuestionType(question_spec["question_type"])
+            except ValueError:
+                pass  # Keep existing type if invalid
+        
+        # Update settings if provided
+        if "settings" in question_spec:
+            question.settings = question_spec["settings"]
+        
+        db.commit()
+        db.refresh(question)
+        
+        return {"question": QuestionResponse.model_validate(question), "message": "Question updated successfully"}
+        
+    except Exception as e:
+        logger.error(f"Question regeneration error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to regenerate question: {str(e)}"
+        )
+
+
+# Conditional logic endpoints
+@router.post("/{form_id}/conditional", response_model=ConditionalRuleResponse)
+async def add_conditional_rule(
+    form_id: int,
+    rule_data: ConditionalRuleCreate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Add a conditional logic rule"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    rule = ConditionalRule(
+        form_id=form_id,
+        trigger_question_id=rule_data.trigger_question_id,
+        target_question_id=rule_data.target_question_id,
+        condition_type=rule_data.condition_type,
+        condition_value=rule_data.condition_value,
+        action=rule_data.action
+    )
+    
+    db.add(rule)
+    db.commit()
+    db.refresh(rule)
+    
+    return ConditionalRuleResponse.model_validate(rule)
+
+
+@router.delete("/{form_id}/conditional/{rule_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_conditional_rule(
+    form_id: int,
+    rule_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Delete a conditional logic rule"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    rule = db.query(ConditionalRule).filter(
+        ConditionalRule.id == rule_id,
+        ConditionalRule.form_id == form_id
+    ).first()
+    
+    if not rule:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Rule not found"
+        )
+    
+    db.delete(rule)
+    db.commit()
+    
+    return None
+
+
+# Public sharing endpoint
+@router.post("/{form_id}/share", response_model=PublicFormResponse)
+async def share_form(
+    form_id: int,
+    share_data: PublicFormCreate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Create a public shareable link for a form"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Check if public form already exists
+    existing = db.query(PublicForm).filter(
+        PublicForm.form_id == form_id
+    ).first()
+    
+    if existing:
+        return PublicFormResponse.model_validate(existing)
+    
+    # Generate unique share token
+    share_token = secrets.token_urlsafe(32)
+    
+    public_form = PublicForm(
+        form_id=form_id,
+        user_id=current_user.id,
+        share_token=share_token,
+        is_public=True,
+        expires_at=share_data.expires_at,
+        allow_multiple_submissions=share_data.allow_multiple_submissions,
+        collect_email=share_data.collect_email,
+        custom_thank_you_message=share_data.custom_thank_you_message
+    )
+    
+    db.add(public_form)
+    db.commit()
+    db.refresh(public_form)
+    
+    return PublicFormResponse.model_validate(public_form)
+
+
+@router.get("/{form_id}/share", response_model=PublicFormResponse)
+async def get_share_info(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get public share information for a form"""
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    public_form = db.query(PublicForm).filter(
+        PublicForm.form_id == form_id
+    ).first()
+    
+    if not public_form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form is not shared"
+        )
+    
+    return PublicFormResponse.model_validate(public_form)
+
+
+# Chat editing endpoint
+@router.post("/{form_id}/chat", response_model=ChatResponse)
+async def chat_edit_form(
+    form_id: int,
+    chat_data: ChatMessage,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Edit form via natural language chat (add/edit components).
+    Uses AI to understand and apply changes to the form.
+    """
+    from sqlalchemy import func
+    import json
+    
+    # Get the form
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    try:
+        # Prepare current form structure
+        current_form_structure = {
+            "title": form.title,
+            "description": form.description,
+            "questions": [
+                {
+                    "id": q.id,
+                    "question_order": q.question_order,
+                    "question_type": q.question_type.value,
+                    "question_text": q.question_text,
+                    "description": q.description,
+                    "required": q.required,
+                    "settings": q.settings
+                }
+                for q in form.questions
+            ],
+            "settings": form.settings
+        }
+        
+        # Use edit_form_spec to process the chat message
+        result = await edit_form_spec(
+            current_form=current_form_structure,
+            edit_request=chat_data.message,
+            user_id=current_user.id
+        )
+        
+        route = result.get("route", "unknown")
+        response = result.get("response")
+        changes_made = result.get("changes_made")
+        
+        # If route is add_component, add the new component
+        if route == "add_component" and response:
+            # Extract component spec from response
+            component_spec = None
+            if hasattr(response, 'component_spec'):
+                try:
+                    component_spec = json.loads(response.component_spec) if isinstance(response.component_spec, str) else response.component_spec
+                except:
+                    component_spec = None
+            
+            if component_spec:
+                # Get the next question order
+                max_order = db.query(func.max(FormQuestion.question_order)).filter(
+                    FormQuestion.form_id == form_id
+                ).scalar() or -1
+                
+                # Create new question
+                new_question = FormQuestion(
+                    form_id=form_id,
+                    question_order=max_order + 1,
+                    question_type=QuestionType(component_spec.get("question_type", "short_answer")),
+                    question_text=component_spec.get("question_text", "New Question"),
+                    description=component_spec.get("description"),
+                    required=component_spec.get("required", False),
+                    settings=component_spec.get("settings", {})
+                )
+                db.add(new_question)
+                db.commit()
+                db.refresh(new_question)
+                
+                return ChatResponse(
+                    route=route,
+                    response={
+                        "new_question": QuestionResponse.model_validate(new_question).model_dump(),
+                        "message": "Component added successfully"
+                    },
+                    changes_made=f"Added new {component_spec.get('question_type')} component"
+                )
+        
+        # If route is edit_component, apply changes
+        elif route == "edit_component" and response:
+            # Extract updated form from response
+            updated_form = None
+            if hasattr(response, 'updated_form'):
+                try:
+                    updated_form = json.loads(response.updated_form) if isinstance(response.updated_form, str) else response.updated_form
+                except:
+                    updated_form = None
+            
+            if updated_form and "components" in updated_form:
+                # Apply updates to existing questions
+                for component in updated_form.get("components", []):
+                    comp_id = component.get("component_id")
+                    if comp_id and comp_id.startswith("comp_"):
+                        # Extract order from component_id (e.g., comp_1 -> 0)
+                        try:
+                            order_idx = int(comp_id.split("_")[1]) - 1
+                            question = db.query(FormQuestion).filter(
+                                FormQuestion.form_id == form_id,
+                                FormQuestion.question_order == order_idx
+                            ).first()
+                            
+                            if question:
+                                if "question_text" in component:
+                                    question.question_text = component["question_text"]
+                                if "question_type" in component:
+                                    question.question_type = QuestionType(component["question_type"])
+                                if "description" in component:
+                                    question.description = component["description"]
+                                if "required" in component:
+                                    question.required = component["required"]
+                                if "settings" in component:
+                                    question.settings = component["settings"]
+                                
+                                question.updated_at = datetime.utcnow()
+                        except (ValueError, IndexError):
+                            continue
+                
+                db.commit()
+                
+                return ChatResponse(
+                    route=route,
+                    response={
+                        "message": "Form updated successfully",
+                        "form": FormResponse.model_validate(form).model_dump()
+                    },
+                    changes_made=changes_made or "Form updated based on your request"
+                )
+        
+        # For general queries or unclear requests, return the response as-is
+        response_data = response
+        if hasattr(response, 'answer'):
+            response_data = {"answer": response.answer}
+        elif hasattr(response, 'model_dump'):
+            response_data = response.model_dump()
+        elif not isinstance(response, dict):
+            response_data = {"message": str(response)}
+        
+        return ChatResponse(
+            route=route,
+            response=response_data,
+            changes_made=changes_made
+        )
+        
+    except Exception as e:
+        logger.error(f"Chat edit failed: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Chat processing failed: {str(e)}"
+        )
+

app/routes/google.py

@@ -0,0 +1,5 @@
+from ..oauth_google import router as google_router
+
+router = google_router
+
+

app/routes/health.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+
+router = APIRouter(prefix="/api", tags=["health"])
+
+
+@router.get("/health")
+def health():
+    return {"ok": True}
+
+

app/routes/payment.py

@@ -0,0 +1,6 @@
+from ..stripe_routes import router as stripe_router
+
+# Re-export stripe router under routes package for consistency
+router = stripe_router
+
+

app/routes/plans.py

@@ -0,0 +1,112 @@
+"""
+Subscription plan routes
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from typing import List, Dict, Any
+from pydantic import BaseModel
+from decimal import Decimal
+
+from ..core.db import get_db
+from ..services.plan_service import plan_service
+
+router = APIRouter(prefix="/api/plans", tags=["plans"])
+
+
+class PlanFeatures(BaseModel):
+    """Plan features model"""
+    max_datasets: int | None = None
+    max_file_size_mb: int | None = None
+    export_formats: List[str] | None = None
+    priority_support: bool | None = None
+    custom_branding: bool | None = None
+    api_access: bool | None = None
+
+
+class PlanResponse(BaseModel):
+    """Response model for a subscription plan"""
+    id: int
+    name: str
+    price_monthly: float
+    price_yearly: float | None = None
+    credits_per_month: int
+    credits_per_analyze: int
+    credits_per_edit: int
+    features: Dict[str, Any]
+    stripe_price_id: str | None  # Legacy field
+    stripe_price_id_monthly: str | None = None
+    stripe_price_id_yearly: str | None = None
+    is_active: bool
+    sort_order: int
+
+
+@router.get("", response_model=List[PlanResponse])
+def get_all_plans(db: Session = Depends(get_db)):
+    """
+    Get all active subscription plans
+    
+    Returns:
+        List of active plans sorted by display order
+    """
+    try:
+        plans = plan_service.get_all_active_plans(db)
+        
+        return [
+            {
+                "id": plan.id,
+                "name": plan.name,
+                "price_monthly": float(plan.price_monthly),
+                "price_yearly": float(plan.price_yearly) if plan.price_yearly else None,
+                "credits_per_month": plan.credits_per_month,
+                "credits_per_analyze": plan.credits_per_analyze,
+                "credits_per_edit": plan.credits_per_edit,
+                "features": plan.features or {},
+                "stripe_price_id": plan.stripe_price_id,  # Legacy
+                "stripe_price_id_monthly": plan.stripe_price_id_monthly,
+                "stripe_price_id_yearly": plan.stripe_price_id_yearly,
+                "is_active": plan.is_active,
+                "sort_order": plan.sort_order
+            }
+            for plan in plans
+        ]
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{plan_id}", response_model=PlanResponse)
+def get_plan(plan_id: int, db: Session = Depends(get_db)):
+    """
+    Get details of a specific plan
+    
+    Args:
+        plan_id: Plan ID
+        
+    Returns:
+        Plan details
+    """
+    try:
+        plan = plan_service.get_plan_by_id(db, plan_id)
+        
+        if not plan:
+            raise HTTPException(status_code=404, detail="Plan not found")
+        
+        return {
+            "id": plan.id,
+            "name": plan.name,
+            "price_monthly": float(plan.price_monthly),
+            "price_yearly": float(plan.price_yearly) if plan.price_yearly else None,
+            "credits_per_month": plan.credits_per_month,
+            "credits_per_analyze": plan.credits_per_analyze,
+            "credits_per_edit": plan.credits_per_edit,
+            "features": plan.features or {},
+            "stripe_price_id": plan.stripe_price_id,  # Legacy
+            "stripe_price_id_monthly": plan.stripe_price_id_monthly,
+            "stripe_price_id_yearly": plan.stripe_price_id_yearly,
+            "is_active": plan.is_active,
+            "sort_order": plan.sort_order
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+

app/routes/responses.py

@@ -0,0 +1,594 @@
+"""
+Form Responses API Routes
+==========================
+
+Routes for form submission and response management.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from sqlalchemy.orm import Session
+from sqlalchemy import desc, func
+from typing import List
+import json
+import csv
+import io
+from datetime import datetime
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User, Form, FormQuestion, FormResponse, ResponseAnswer, PublicForm
+from ..schemas.form import (
+    SubmissionCreate, SubmissionResponse,
+    FormResponseDetail, FormResponsesList, ResponseAnswerDetail,
+    PublicFormDetail, FormResponse as FormSchema
+)
+from ..schemas.validation import PartialSubmissionCreate, AutoSaveResponse
+from ..services.validation_service import validation_service
+from ..services.analytics_service import analytics_service
+from ..services.webhook_service import webhook_service
+from ..middleware.rate_limiter import rate_limiter
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["responses"])
+
+
+@router.post("/public/forms/{token}/submit", response_model=SubmissionResponse)
+async def submit_form(
+    token: str,
+    submission: SubmissionCreate,
+    request: Request,
+    db: Session = Depends(get_db)
+):
+    """
+    Public endpoint for submitting a form response.
+    No authentication required.
+    """
+    # Find public form by token
+    public_form = db.query(PublicForm).filter(
+        PublicForm.share_token == token,
+        PublicForm.is_public == True
+    ).first()
+    
+    if not public_form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found or no longer accepting responses"
+        )
+    
+    # Check if expired
+    if public_form.expires_at and public_form.expires_at < datetime.utcnow():
+        raise HTTPException(
+            status_code=status.HTTP_410_GONE,
+            detail="This form has expired"
+        )
+    
+    # Get the form
+    form = db.query(Form).filter(Form.id == public_form.form_id).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get client IP
+    client_ip = request.client.host if request.client else None
+    
+    try:
+        # Create form response
+        form_response = FormResponse(
+            form_id=form.id,
+            ip_address=client_ip,
+            submission_metadata=submission.metadata or {}
+        )
+        db.add(form_response)
+        db.flush()
+        
+        # Create answers
+        for answer_data in submission.answers:
+            answer = ResponseAnswer(
+                form_response_id=form_response.id,
+                form_question_id=answer_data.question_id,
+                answer_value=answer_data.answer_value.model_dump()
+            )
+            db.add(answer)
+        
+        db.commit()
+        db.refresh(form_response)
+        
+        return SubmissionResponse(
+            id=form_response.id,
+            form_id=form.id,
+            submitted_at=form_response.submitted_at,
+            message=public_form.custom_thank_you_message or "Thank you for your submission!"
+        )
+        
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Form submission failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to submit form"
+        )
+
+
+@router.post("/public/forms/{token}/autosave", response_model=AutoSaveResponse)
+async def autosave_submission(
+    token: str,
+    submission: PartialSubmissionCreate,
+    request: Request,
+    db: Session = Depends(get_db)
+):
+    """
+    Auto-save partial submission after each question.
+    No authentication required.
+    """
+    # Find public form by token
+    public_form = db.query(PublicForm).filter(
+        PublicForm.share_token == token,
+        PublicForm.is_public == True
+    ).first()
+    
+    if not public_form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get form
+    form = db.query(Form).filter(Form.id == public_form.form_id).first()
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get client IP
+    client_ip = request.client.host if request.client else None
+    ip_hash = rate_limiter.hash_identifier(client_ip) if client_ip else "unknown"
+    
+    try:
+        # Find existing in-progress submission for this session
+        existing_response = db.query(FormResponse).filter(
+            FormResponse.form_id == form.id,
+            FormResponse.session_id == submission.session_id,
+            FormResponse.status.in_(["in_progress", "partial"])
+        ).first()
+        
+        if existing_response:
+            # Update existing response
+            existing_response.last_updated_at = datetime.utcnow()
+            existing_response.status = "in_progress"
+            
+            # Update answers
+            for answer_data in submission.answers:
+                # Check if answer exists
+                existing_answer = db.query(ResponseAnswer).filter(
+                    ResponseAnswer.form_response_id == existing_response.id,
+                    ResponseAnswer.form_question_id == answer_data.get('question_id')
+                ).first()
+                
+                if existing_answer:
+                    # Update existing answer
+                    existing_answer.answer_value = answer_data.get('answer_value', {})
+                else:
+                    # Create new answer
+                    new_answer = ResponseAnswer(
+                        form_response_id=existing_response.id,
+                        form_question_id=answer_data.get('question_id'),
+                        answer_value=answer_data.get('answer_value', {})
+                    )
+                    db.add(new_answer)
+            
+            form_response = existing_response
+        else:
+            # Create new form response
+            form_response = FormResponse(
+                form_id=form.id,
+                session_id=submission.session_id,
+                status="in_progress",
+                form_version=submission.form_version,
+                started_at=datetime.utcnow(),
+                last_updated_at=datetime.utcnow(),
+                ip_address=client_ip,
+                ip_address_hash=ip_hash,
+                utm_source=submission.utm_source,
+                utm_medium=submission.utm_medium,
+                utm_campaign=submission.utm_campaign,
+                submission_metadata=submission.metadata or {}
+            )
+            db.add(form_response)
+            db.flush()
+            
+            # Create answers
+            for answer_data in submission.answers:
+                answer = ResponseAnswer(
+                    form_response_id=form_response.id,
+                    form_question_id=answer_data.get('question_id'),
+                    answer_value=answer_data.get('answer_value', {})
+                )
+                db.add(answer)
+        
+        db.commit()
+        db.refresh(form_response)
+        
+        # Validate answers (non-blocking)
+        validation_result = validation_service.validate_submission(
+            db=db,
+            form_id=form.id,
+            answers=submission.answers,
+            is_complete=False
+        )
+        
+        return AutoSaveResponse(
+            success=True,
+            submission_id=form_response.id,
+            validation=validation_result,
+            message="Auto-saved successfully"
+        )
+        
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Auto-save failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to auto-save"
+        )
+
+
+@router.get("/public/forms/{token}", response_model=PublicFormDetail)
+async def get_public_form(
+    token: str,
+    db: Session = Depends(get_db)
+):
+    """
+    Get public form structure for filling out.
+    No authentication required.
+    """
+    public_form = db.query(PublicForm).filter(
+        PublicForm.share_token == token,
+        PublicForm.is_public == True
+    ).first()
+    
+    if not public_form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Check if expired
+    if public_form.expires_at and public_form.expires_at < datetime.utcnow():
+        raise HTTPException(
+            status_code=status.HTTP_410_GONE,
+            detail="This form has expired"
+        )
+    
+    form = db.query(Form).filter(Form.id == public_form.form_id).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    return PublicFormDetail(
+        form=FormSchema.model_validate(form),
+        public_settings=public_form
+    )
+
+
+@router.get("/forms/{form_id}/responses", response_model=FormResponsesList)
+async def get_form_responses(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    limit: int = 100,
+    offset: int = 0
+):
+    """
+    Get all responses for a form.
+    Requires authentication and form ownership.
+    """
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get total count
+    total_count = db.query(func.count(FormResponse.id)).filter(
+        FormResponse.form_id == form_id
+    ).scalar()
+    
+    # Get responses with answers
+    responses = db.query(FormResponse).filter(
+        FormResponse.form_id == form_id
+    ).order_by(desc(FormResponse.submitted_at)).limit(limit).offset(offset).all()
+    
+    # Build detailed response list
+    response_details = []
+    for response in responses:
+        answers = []
+        for answer in response.answers:
+            question = db.query(FormQuestion).filter(
+                FormQuestion.id == answer.form_question_id
+            ).first()
+            
+            if question:
+                answers.append(ResponseAnswerDetail(
+                    question_id=question.id,
+                    question_text=question.question_text,
+                    question_type=question.question_type,
+                    answer_value=answer.answer_value or {}
+                ))
+        
+        response_details.append(FormResponseDetail(
+            id=response.id,
+            form_id=response.form_id,
+            submitted_at=response.submitted_at,
+            ip_address=response.ip_address,
+            answers=answers
+        ))
+    
+    return FormResponsesList(
+        total_count=total_count,
+        responses=response_details
+    )
+
+
+@router.get("/forms/{form_id}/responses/{response_id}", response_model=FormResponseDetail)
+async def get_single_response(
+    form_id: int,
+    response_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Get a single form response by ID"""
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    response = db.query(FormResponse).filter(
+        FormResponse.id == response_id,
+        FormResponse.form_id == form_id
+    ).first()
+    
+    if not response:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Response not found"
+        )
+    
+    # Build answer details
+    answers = []
+    for answer in response.answers:
+        question = db.query(FormQuestion).filter(
+            FormQuestion.id == answer.form_question_id
+        ).first()
+        
+        if question:
+            answers.append(ResponseAnswerDetail(
+                question_id=question.id,
+                question_text=question.question_text,
+                question_type=question.question_type,
+                answer_value=answer.answer_value or {}
+            ))
+    
+    return FormResponseDetail(
+        id=response.id,
+        form_id=response.form_id,
+        submitted_at=response.submitted_at,
+        ip_address=response.ip_address,
+        answers=answers
+    )
+
+
+@router.get("/forms/{form_id}/responses/export/csv")
+async def export_responses_csv(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Export form responses as CSV"""
+    from fastapi.responses import StreamingResponse
+    
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get all questions for headers
+    questions = db.query(FormQuestion).filter(
+        FormQuestion.form_id == form_id
+    ).order_by(FormQuestion.question_order).all()
+    
+    # Get all responses
+    responses = db.query(FormResponse).filter(
+        FormResponse.form_id == form_id
+    ).order_by(desc(FormResponse.submitted_at)).all()
+    
+    # Create CSV in memory
+    output = io.StringIO()
+    writer = csv.writer(output)
+    
+    # Write headers
+    headers = ["Response ID", "Submitted At", "IP Address"]
+    headers.extend([q.question_text for q in questions])
+    writer.writerow(headers)
+    
+    # Write data rows
+    for response in responses:
+        row = [
+            response.id,
+            response.submitted_at.isoformat(),
+            response.ip_address or ""
+        ]
+        
+        # Create answer map
+        answer_map = {
+            answer.form_question_id: answer.answer_value
+            for answer in response.answers
+        }
+        
+        # Add answers in question order
+        for question in questions:
+            answer_value = answer_map.get(question.id, {})
+            
+            # Format answer based on type
+            if isinstance(answer_value, dict):
+                # Extract the most relevant field
+                if "text" in answer_value:
+                    row.append(answer_value["text"])
+                elif "number" in answer_value:
+                    row.append(str(answer_value["number"]))
+                elif "choices" in answer_value:
+                    row.append(", ".join(answer_value["choices"]))
+                elif "date" in answer_value:
+                    row.append(answer_value["date"])
+                elif "rating" in answer_value:
+                    row.append(str(answer_value["rating"]))
+                else:
+                    row.append(json.dumps(answer_value))
+            else:
+                row.append(str(answer_value))
+        
+        writer.writerow(row)
+    
+    # Prepare response
+    output.seek(0)
+    
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": f"attachment; filename=form_{form_id}_responses.csv"
+        }
+    )
+
+
+@router.get("/forms/{form_id}/responses/export/json")
+async def export_responses_json(
+    form_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Export form responses as JSON"""
+    from fastapi.responses import JSONResponse
+    
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    # Get all responses
+    responses = db.query(FormResponse).filter(
+        FormResponse.form_id == form_id
+    ).order_by(desc(FormResponse.submitted_at)).all()
+    
+    # Build export data
+    export_data = {
+        "form_id": form_id,
+        "form_title": form.title,
+        "exported_at": datetime.utcnow().isoformat(),
+        "total_responses": len(responses),
+        "responses": []
+    }
+    
+    for response in responses:
+        response_data = {
+            "id": response.id,
+            "submitted_at": response.submitted_at.isoformat(),
+            "ip_address": response.ip_address,
+            "answers": []
+        }
+        
+        for answer in response.answers:
+            question = db.query(FormQuestion).filter(
+                FormQuestion.id == answer.form_question_id
+            ).first()
+            
+            if question:
+                response_data["answers"].append({
+                    "question_id": question.id,
+                    "question_text": question.question_text,
+                    "question_type": question.question_type.value,
+                    "answer_value": answer.answer_value
+                })
+        
+        export_data["responses"].append(response_data)
+    
+    return JSONResponse(
+        content=export_data,
+        headers={
+            "Content-Disposition": f"attachment; filename=form_{form_id}_responses.json"
+        }
+    )
+
+
+@router.delete("/forms/{form_id}/responses/{response_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_response(
+    form_id: int,
+    response_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """Delete a specific form response"""
+    # Verify form ownership
+    form = db.query(Form).filter(
+        Form.id == form_id,
+        Form.user_id == current_user.id
+    ).first()
+    
+    if not form:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Form not found"
+        )
+    
+    response = db.query(FormResponse).filter(
+        FormResponse.id == response_id,
+        FormResponse.form_id == form_id
+    ).first()
+    
+    if not response:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Response not found"
+        )
+    
+    db.delete(response)
+    db.commit()
+    
+    return None
+

app/routes/users.py

@@ -0,0 +1,69 @@
+"""
+User Context API Routes
+========================
+
+Routes for user context and onboarding.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from sqlalchemy import func, desc
+
+from ..core.db import get_db
+from ..core.security import get_current_user
+from ..models import User, Form, Subscription
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/me", tags=["users"])
+
+
+@router.get("/context")
+async def get_user_context(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get user context for UI decisions.
+    
+    Returns information about user state, forms, and subscription.
+    """
+    # Count user's forms
+    form_count = db.query(func.count(Form.id)).filter(
+        Form.user_id == current_user.id
+    ).scalar() or 0
+    
+    # Get last form
+    last_form = db.query(Form).filter(
+        Form.user_id == current_user.id
+    ).order_by(desc(Form.created_at)).first()
+    
+    # Get subscription info
+    subscription = db.query(Subscription).filter(
+        Subscription.user_id == current_user.id
+    ).order_by(desc(Subscription.created_at)).first()
+    
+    has_active_subscription = False
+    plan_name = "Free"
+    
+    if subscription and subscription.status == "active":
+        has_active_subscription = True
+        if subscription.plan:
+            plan_name = subscription.plan.name
+    
+    return {
+        "is_new_user": form_count == 0,
+        "form_count": form_count,
+        "last_form_id": last_form.id if last_form else None,
+        "has_active_subscription": has_active_subscription,
+        "plan_name": plan_name,
+        "onboarding_completed": form_count > 0,  # User has created at least one form
+        "user": {
+            "id": current_user.id,
+            "email": current_user.email,
+            "name": current_user.name,
+            "picture": current_user.picture
+        }
+    }

app/schemas/__init__.py

@@ -0,0 +1,2 @@
+
+

app/schemas/auth.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, EmailStr
+
+
+class LoginRequest(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class TokenResponse(BaseModel):
+    token: str
+    token_type: str = "bearer"
+    user: dict
+
+

app/schemas/chat.py

@@ -0,0 +1,34 @@
+from pydantic import BaseModel
+from typing import Optional, Dict, Any, Literal
+
+
+class ChatRequest(BaseModel):
+    message: str
+    dataset_id: Optional[str] = None
+    fig_data: Optional[Dict[str, Any]] = None
+    plotly_code: Optional[str] = None
+
+
+class ChatResponse(BaseModel):
+    reply: str
+    user: str | None = None
+    matched_chart: Optional[Dict[str, Any]] = None
+    code_type: Optional[Literal['plotly_edit', 'analysis', 'add_chart_query']] = None
+    executable_code: Optional[str] = None
+    query_type: Optional[str] = None  # The detected query type (for showing action buttons on need_clarity)
+
+
+class FixVisualizationRequest(BaseModel):
+    plotly_code: str
+    error_message: str
+    dataset_id: Optional[str] = None
+
+
+class RetryCodeRequest(BaseModel):
+    user_query: str
+    dataset_id: str
+    code_type: str  # 'plotly_edit' or 'analysis'
+    plotly_code: Optional[str] = None  # Only for plotly_edit
+    data_context: str
+
+

app/schemas/form.py

@@ -0,0 +1,274 @@
+"""
+Pydantic schemas for form-related operations
+"""
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional, List, Dict, Any, Union
+from datetime import datetime
+from ..models import QuestionType, ConditionType
+
+
+# Question schemas
+class QuestionSettings(BaseModel):
+    """Settings for different question types"""
+    choices: Optional[List[str]] = None  # For multiple choice, checkboxes, dropdown
+    min_value: Optional[int] = None  # For number, linear scale
+    max_value: Optional[int] = None
+    min_length: Optional[int] = None  # For text inputs
+    max_length: Optional[int] = None
+    placeholder: Optional[str] = None
+    scale_min_label: Optional[str] = None  # For linear scale
+    scale_max_label: Optional[str] = None
+    rows: Optional[Union[int, List[str]]] = None  # For matrix questions - accepts int or list
+    columns: Optional[Union[int, List[str]]] = None  # For matrix questions - accepts int or list
+    file_types: Optional[List[str]] = None  # For file upload
+    max_file_size: Optional[int] = None
+    payment_amount: Optional[float] = None  # For payment questions
+    currency: Optional[str] = None
+    ranking_items: Optional[Union[int, List[str]]] = None  # For ranking questions - accepts int or list
+    
+    class Config:
+        extra = "allow"  # Allow additional fields
+
+
+class QuestionBase(BaseModel):
+    question_text: str
+    question_type: QuestionType
+    description: Optional[str] = None
+    required: bool = False
+    settings: Optional[QuestionSettings] = None
+
+
+class QuestionCreate(QuestionBase):
+    question_order: int
+    form_id: int
+
+
+class QuestionUpdate(BaseModel):
+    question_text: Optional[str] = None
+    question_type: Optional[QuestionType] = None
+    description: Optional[str] = None
+    required: Optional[bool] = None
+    question_order: Optional[int] = None
+    settings: Optional[QuestionSettings] = None
+
+
+class QuestionResponse(QuestionBase):
+    id: int
+    form_id: int
+    question_order: int
+    created_at: datetime
+    updated_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# Conditional logic schemas
+class ConditionalRuleBase(BaseModel):
+    trigger_question_id: int
+    target_question_id: int
+    condition_type: ConditionType
+    condition_value: Optional[str] = None
+    action: str = "show"  # "show" or "hide"
+    
+    @field_validator('action')
+    @classmethod
+    def validate_action(cls, v):
+        if v not in ["show", "hide"]:
+            raise ValueError('Action must be "show" or "hide"')
+        return v
+
+
+class ConditionalRuleCreate(ConditionalRuleBase):
+    form_id: int
+
+
+class ConditionalRuleResponse(ConditionalRuleBase):
+    id: int
+    form_id: int
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# Form schemas
+class FormSettings(BaseModel):
+    """Form-level settings"""
+    background_color: str = "#ffffff"
+    text_color: str = "#000000"
+    accent_color: str = "#9333ea"  # Purple
+    bold_text_color: Optional[str] = "#9333ea"  # Bold text and buttons
+    submit_button_text: str = "Submit"
+    show_progress_bar: bool = True
+    
+    class Config:
+        extra = "allow"
+
+
+class FormBase(BaseModel):
+    title: str
+    description: Optional[str] = None
+    settings: Optional[FormSettings] = None
+
+
+class FormCreate(BaseModel):
+    """Schema for creating a form from AI generation"""
+    user_query: str  # The natural language description
+    title: Optional[str] = None  # Optional - will be generated by AI if not provided
+    description: Optional[str] = None  # Optional - will be generated by AI if not provided
+    settings: Optional[FormSettings] = None  # Optional - defaults applied if not provided
+
+
+class FormUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    settings: Optional[FormSettings] = None
+
+
+class FormResponse(FormBase):
+    id: int
+    user_id: int
+    created_at: datetime
+    updated_at: datetime
+    questions: List[QuestionResponse] = []
+    conditional_rules: List[ConditionalRuleResponse] = []
+    
+    class Config:
+        from_attributes = True
+
+
+# Form generation response
+class FormGenerationResponse(BaseModel):
+    """Response from AI form generation"""
+    form: FormResponse
+    message: str = "Form generated successfully"
+
+
+# Answer and submission schemas
+class AnswerValue(BaseModel):
+    """Answer value for different question types"""
+    text: Optional[str] = None  # For text inputs
+    number: Optional[float] = None  # For number inputs
+    date: Optional[str] = None  # For date/time
+    choices: Optional[List[str]] = None  # For multiple choice, checkboxes
+    file_url: Optional[str] = None  # For file uploads
+    rating: Optional[int] = None  # For ratings
+    signature: Optional[str] = None  # Base64 signature image
+    wallet_address: Optional[str] = None  # For wallet connect
+    matrix_answers: Optional[Dict[str, str]] = None  # For matrix questions
+    ranked_items: Optional[List[str]] = None  # For ranking questions
+    
+    class Config:
+        extra = "allow"
+
+
+class SubmitAnswer(BaseModel):
+    question_id: int
+    answer_value: AnswerValue
+
+
+class SubmissionCreate(BaseModel):
+    """Schema for submitting a form response"""
+    answers: List[SubmitAnswer]
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class SubmissionResponse(BaseModel):
+    """Response after successful submission"""
+    id: int
+    form_id: int
+    submitted_at: datetime
+    message: str = "Form submitted successfully"
+    
+    class Config:
+        from_attributes = True
+
+
+class ResponseAnswerDetail(BaseModel):
+    """Detailed answer in a response"""
+    question_id: int
+    question_text: str
+    question_type: QuestionType
+    answer_value: Dict[str, Any]
+    
+    class Config:
+        from_attributes = True
+
+
+class FormResponseDetail(BaseModel):
+    """Detailed view of a single form response"""
+    id: int
+    form_id: int
+    submitted_at: datetime
+    ip_address: Optional[str]
+    answers: List[ResponseAnswerDetail]
+    
+    class Config:
+        from_attributes = True
+
+
+class FormResponsesList(BaseModel):
+    """List of form responses with summary"""
+    total_count: int
+    responses: List[FormResponseDetail]
+
+
+# Public form schemas
+class PublicFormCreate(BaseModel):
+    form_id: int
+    expires_at: Optional[datetime] = None
+    allow_multiple_submissions: bool = True
+    collect_email: bool = False
+    custom_thank_you_message: Optional[str] = None
+
+
+class PublicFormResponse(BaseModel):
+    id: int
+    form_id: int
+    share_token: str
+    is_public: bool
+    expires_at: Optional[datetime]
+    allow_multiple_submissions: bool
+    collect_email: bool
+    custom_thank_you_message: Optional[str]
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+class PublicFormDetail(BaseModel):
+    """Public form structure for submissions"""
+    form: FormResponse
+    public_settings: PublicFormResponse
+    
+    class Config:
+        from_attributes = True
+
+
+# Export schemas
+class ExportFormat(BaseModel):
+    format: str = Field(..., pattern="^(csv|json)$")
+
+
+class ExportResponse(BaseModel):
+    download_url: str
+    format: str
+    total_responses: int
+
+
+# Chat editing schemas
+class ChatMessage(BaseModel):
+    """Schema for chat-based form editing"""
+    message: str = Field(..., min_length=1, max_length=1000)
+
+
+class ChatResponse(BaseModel):
+    """Response from chat-based form editing"""
+    route: str  # add_component, edit_component, general_form_query, need_more_clarity
+    response: Dict[str, Any]  # Updated component or form structure or answer text
+    changes_made: Optional[str] = None  # Summary of changes if applicable
+    
+    class Config:
+        from_attributes = True

app/schemas/validation.py

@@ -0,0 +1,64 @@
+"""
+Validation schemas for form submissions
+"""
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+
+class FieldValidationError(BaseModel):
+    """Individual field validation error"""
+    question_id: int
+    field: str
+    message: str
+    error_type: str  # "required", "invalid_format", "out_of_range", "invalid_choice", etc.
+
+
+class ValidationResponse(BaseModel):
+    """Structured validation response"""
+    is_valid: bool
+    errors: List[FieldValidationError] = []
+    warnings: List[FieldValidationError] = []
+
+
+class PartialSubmissionCreate(BaseModel):
+    """Schema for auto-save partial submissions"""
+    session_id: str = Field(..., min_length=1, max_length=64)
+    form_version: Optional[int] = None
+    answers: List[Dict[str, Any]]  # Flexible for partial data
+    metadata: Optional[Dict[str, Any]] = None
+    
+    # UTM parameters
+    utm_source: Optional[str] = None
+    utm_medium: Optional[str] = None
+    utm_campaign: Optional[str] = None
+
+
+class CompleteSubmissionCreate(BaseModel):
+    """Schema for final submission (inherits from existing SubmissionCreate)"""
+    session_id: str = Field(..., min_length=1, max_length=64)
+    form_version: Optional[int] = None
+    answers: List[Dict[str, Any]]
+    metadata: Optional[Dict[str, Any]] = None
+    honeypot: Optional[str] = None  # Should be empty
+    
+    # UTM parameters
+    utm_source: Optional[str] = None
+    utm_medium: Optional[str] = None
+    utm_campaign: Optional[str] = None
+
+
+class ValidationContext(BaseModel):
+    """Context for validation including anti-tampering token"""
+    form_id: int
+    session_id: str
+    validation_token: str
+    timestamp: datetime
+
+
+class AutoSaveResponse(BaseModel):
+    """Response from auto-save endpoint"""
+    success: bool
+    submission_id: Optional[int] = None
+    validation: ValidationResponse
+    message: str = "Auto-saved successfully"

app/scripts/__init__.py

@@ -0,0 +1,4 @@
+"""
+Scripts package
+"""
+

app/scripts/init_plans.py

@@ -0,0 +1,103 @@
+"""
+Initialization script for default subscription plans
+Run this script to create/update the default Free, Pro, and Ultra plans
+"""
+import sys
+import os
+from pathlib import Path
+
+# Add parent directory to path to allow imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from sqlalchemy.orm import Session
+from app.db import SessionLocal, engine, Base
+from app.services.plan_service import plan_service
+from app.models import SubscriptionPlan
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def init_database():
+    """Create all database tables"""
+    logger.info("Creating database tables...")
+    Base.metadata.create_all(bind=engine)
+    logger.info("Database tables created successfully")
+
+
+def init_plans(db: Session, force: bool = False):
+    """
+    Initialize default subscription plans
+    
+    Args:
+        db: Database session
+        force: If True, update existing plans with new values
+    """
+    logger.info("Initializing subscription plans...")
+    
+    plans = plan_service.initialize_default_plans(db, force=force)
+    
+    logger.info(f"Successfully initialized {len(plans)} plans:")
+    for plan in plans:
+        logger.info(f"  - {plan.name}: ${plan.price_monthly}/month, {plan.credits_per_month} credits")
+    
+    return plans
+
+
+def main():
+    """Main initialization function"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Initialize subscription plans")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force update of existing plans"
+    )
+    parser.add_argument(
+        "--create-tables",
+        action="store_true",
+        help="Create database tables if they don't exist"
+    )
+    
+    args = parser.parse_args()
+    
+    # Create tables if requested
+    if args.create_tables:
+        init_database()
+    
+    # Initialize plans
+    db = SessionLocal()
+    try:
+        plans = init_plans(db, force=args.force)
+        logger.info("✓ Plan initialization complete!")
+        
+        # Display plan details
+        print("\n" + "="*60)
+        print("SUBSCRIPTION PLANS")
+        print("="*60)
+        for plan in plans:
+            print(f"\n{plan.name} Tier:")
+            print(f"  Price: ${plan.price_monthly}/month")
+            print(f"  Credits: {plan.credits_per_month}/month")
+            print(f"  Per Dashboard: {plan.credits_per_analyze} credits")
+            print(f"  Per Edit: {plan.credits_per_edit} credits")
+            print(f"  Stripe Price ID (Monthly): {plan.stripe_price_id_monthly or plan.stripe_price_id or 'Not set'}")
+            print(f"  Stripe Price ID (Yearly): {plan.stripe_price_id_yearly or 'Not set'}")
+            if plan.features:
+                print(f"  Features: {', '.join(str(k) + '=' + str(v) for k, v in plan.features.items())}")
+        print("\n" + "="*60)
+        
+    except Exception as e:
+        logger.error(f"Error initializing plans: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    main()
+

app/security.py

@@ -0,0 +1,38 @@
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+from jose import jwt, JWTError
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+
+JWT_SECRET = os.getenv("JWT_SECRET", "dev-secret-change-me")
+JWT_ALG = "HS256"
+JWT_TTL_MIN = int(os.getenv("JWT_TTL_MIN", "60"))
+
+
+def create_access_token(sub: str, extra: Optional[dict] = None) -> str:
+    now = datetime.now(tz=timezone.utc)
+    payload = {
+        "sub": sub,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(minutes=JWT_TTL_MIN)).timestamp()),
+    }
+    if extra:
+        payload.update(extra)
+    return jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALG)
+
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+def get_current_subject(creds: HTTPAuthorizationCredentials = Depends(bearer_scheme)) -> str:
+    if not creds or creds.scheme.lower() != "bearer":
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    try:
+        payload = jwt.decode(creds.credentials, JWT_SECRET, algorithms=[JWT_ALG])
+        return str(payload.get("sub"))
+    except JWTError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+
+

app/services/agents.py

@@ -0,0 +1,532 @@
+"""
+DSPy-based Form Generation System
+==================================
+
+This module uses DSPy to generate forms from natural language queries.
+It includes a multi-stage pipeline:
+1. Planner: Converts user query to form plan with components
+2. Component Signature: Generates renderable form components with metadata
+3. Conditional Logic: Defines relationships between components
+
+FRONTEND TECH STACK:
+- React with TypeScript
+- Headless UI (@headlessui/react) for accessible dialogs, modals, and interactive components
+- React Markdown (react-markdown) with remark-gfm for markdown rendering
+- Tally-inspired minimal design with inline styles (no CSS frameworks)
+- Purple accent color (#9333ea) throughout
+- Clean, generous whitespace (48px between questions)
+- Subtle borders and transitions
+"""
+
+import dspy
+import json
+import logging
+import os
+from typing import Dict, Any, List, Optional
+
+# Set up logger for the module
+logger = logging.getLogger("dspy_forms")
+logger.setLevel(logging.WARNING)
+if not logger.handlers:
+    ch = logging.StreamHandler()
+    formatter = logging.Formatter('[%(asctime)s][%(levelname)s] %(message)s')
+    ch.setFormatter(formatter)
+    logger.addHandler(ch)
+
+
+# ============================================================================
+# FORM GENERATION SIGNATURES
+# ============================================================================
+
+class FormPlannerSignature(dspy.Signature):
+    """
+    You are an AI form designer that creates comprehensive form plans from user descriptions.
+    
+    TASK:
+    Convert a natural language form request into a structured JSON form plan with component specifications.
+    
+    OUTPUT FORMAT (JSON):
+    {
+        "title": "Form Title",
+        "description": "Brief description of form purpose",
+        "submit_button_text": "Submit" or custom text,
+        "components": [
+            {
+                "component_id": "comp_1",
+                "type": "question_type",
+                "brief": "Brief description of what this component captures",
+                "required": true/false,
+                "order": 0
+            }
+        ],
+        "conditional_logic": [
+            {
+                "trigger_component_id": "comp_1",
+                "target_component_id": "comp_3",
+                "condition_type": "equals",
+                "condition_value": "Yes",
+                "action": "show"
+            }
+        ]
+    }
+    
+    COMPONENT TYPES (use exact strings):
+    - short_answer: Single line text
+    - long_answer: Multi-line text
+    - multiple_choice: Radio buttons (one selection)
+    - checkboxes: Multiple selections
+    - dropdown: Select dropdown
+    - multi_select: Multi-select dropdown
+    - number: Numeric input
+    - email: Email validation
+    - phone: Phone number
+    - link: URL input
+    - file_upload: File attachment
+    - date: Date picker
+    - time: Time picker
+    - linear_scale: Scale (1-10)
+    - matrix: Grid questions
+    - rating: Star rating
+    - payment: Payment field
+    - signature: Digital signature
+    - ranking: Rank items
+    - wallet_connect: Web3 wallet
+    - button: Custom action button
+    
+    CONDITIONAL LOGIC RULES:
+    - condition_type: equals, not_equals, contains, not_contains, greater_than, less_than, is_empty, is_not_empty
+    - action: show, hide
+    
+    CRITICAL GUIDELINES:
+    1. **FOLLOW USER'S EXACT SPECIFICATIONS** - If user says "Valima, Nikkah, Barat", use those EXACT terms, not substitutes
+    2. **DO NOT SUBSTITUTE** terms - Use the exact names, labels, and options the user provides
+    3. **USE DIVERSE QUESTION TYPES** - Mix short_answer, multiple_choice, checkboxes, dropdown, date, rating, etc.
+    4. **USE CHECKBOXES for multiple selections** - When users can select multiple items (e.g., "Which events will you attend?")
+    5. **USE MULTIPLE_CHOICE for single selection** - When users pick one option (e.g., "Are you attending? Yes/No")
+    6. Choose appropriate component types based on the data being collected
+    7. Mark essential components as required
+    8. Order components logically (general to specific)
+    9. Include 3-5 components typically
+    10. Add conditional logic where it makes sense (e.g., show follow-up based on previous answer)
+    11. Generate component_ids like "comp_1", "comp_2", etc.
+    12. **PREFER STRUCTURED INPUTS** over text when possible (use checkboxes, dropdowns, ratings instead of open text)
+    
+    **IMPORTANT: PRESERVE USER'S TERMINOLOGY**
+    - If user mentions specific event names (Valima, Nikkah, Barat, etc.), use those EXACT names
+    - If user mentions specific options or choices, use those EXACT options
+    - Do NOT replace cultural, local, or specific terms with generic alternatives
+    - Do NOT assume Western/US conventions unless specifically requested
+    
+    COMMON FORM PATTERNS (adapt to user's context):
+    - Contact forms: name (short_answer), email, phone, message (long_answer)
+    - Registration forms: name, email, password, interests (checkboxes), preferences (dropdown)
+    - Feedback forms: name (optional), rating, satisfaction (linear_scale), comments (long_answer)
+    - Applications: name, email, skills (checkboxes), experience level (dropdown)
+    - Event registration: name, email, events attending (checkboxes), meal preference (dropdown), dietary restrictions (checkboxes)
+    - Survey forms: demographics (dropdowns), agreement scales (linear_scale), multiple choice questions, open-ended responses (long_answer)
+    - RSVP forms: attendance (multiple_choice: Yes/No), guest count (number), dietary needs (checkboxes)
+    
+    FORM TITLE BEST PRACTICES:
+    - **ALWAYS wrap title in double asterisks** for bold formatting: "**Your Form Title**"
+    - Be specific and clear (e.g., "**Customer Feedback Survey**" not "Form")
+    - Use action words when appropriate (e.g., "**Submit Your Application**", "**Register for Event**")
+    - Keep under 60 characters for readability
+    - Match the tone to the form purpose (professional for applications, friendly for feedback)
+    
+    CRITICAL: The title field MUST always start and end with ** to render as bold markdown.
+    Example: "title": "**Wedding RSVP**" NOT "title": "Wedding RSVP"
+    
+    Always include a meaningful form title and description that clearly explains the purpose.
+    """
+    user_query = dspy.InputField(desc="Natural language description of the form needed")
+    form_plan = dspy.OutputField(desc="JSON form plan with title, description, components list, and conditional_logic")
+
+
+class ComponentSignatureGenerator(dspy.Signature):
+    """
+    Generate detailed component specifications that the frontend can render.
+    
+    FRONTEND CAPABILITIES:
+    - Headless UI for modals and interactive components
+    - Markdown support in question text and descriptions
+    - Inline editing with QuestionEditor component
+    - Tally-inspired minimal design with clean typography
+    - Purple accent (#9333ea) for focused/selected states
+    
+    INPUT:
+    - component_brief: Brief description from planner
+    - component_type: Type of component
+    - component_id: Unique identifier
+    - form_context: Overall form context
+    
+    OUTPUT FORMAT (JSON):
+    {
+        "component_id": "comp_1",
+        "question_type": "type from list",
+        "question_text": "Clear question text (markdown supported)",
+        "description": "Optional helper text (markdown supported)",
+        "required": true/false,
+        "settings": {
+            // Type-specific settings
+            "choices": ["Option 1", "Option 2"],  // For multiple_choice, checkboxes, dropdown
+            "min_value": 1,  // For number, linear_scale
+            "max_value": 10,
+            "placeholder": "Enter text here",  // For text inputs
+            "scale_min_label": "Not at all",  // For linear_scale
+            "scale_max_label": "Extremely",
+            "rows": ["Row 1", "Row 2"],  // For matrix (MUST be array of strings)
+            "columns": ["Col 1", "Col 2"],  // For matrix (MUST be array of strings)
+            "file_types": [".pdf", ".doc"],  // For file_upload
+            "max_file_size": 5242880,  // bytes
+            "ranking_items": ["Item 1", "Item 2"]  // For ranking (MUST be array of strings)
+        },
+        "validation_rules": {
+            "min_length": 5,  // For text inputs
+            "max_length": 100,
+            "pattern": "regex_pattern",  // For custom validation
+            "error_message": "Custom error message"
+        }
+    }
+    
+    RULES:
+    1. **USE USER'S EXACT TERMINOLOGY** - If the brief mentions specific terms (e.g., "Valima", "Nikkah", "Barat"), use those EXACT terms
+    2. **DO NOT SUBSTITUTE** cultural, local, or specific terms with generic alternatives
+    3. **MATCH COMPONENT TYPE TO DATA** - For multiple selections, use checkboxes; for single selection, use multiple_choice or dropdown
+    4. Provide choices exactly as described by user (or 3-5 sensible options if not specified)
+    5. Use descriptive labels for scales (e.g., "Not at all" to "Extremely")
+    6. Set reasonable limits for numbers and file sizes
+    7. Include helpful placeholder text for text inputs
+    8. Add description for complex components (matrix, ranking, file uploads)
+    9. Include validation rules where appropriate
+    10. CRITICAL: rows, columns, and ranking_items MUST be arrays of strings, never integers
+    11. Question text and descriptions support markdown (use **bold**, *italic*, lists, etc.)
+    12. Keep text clear and conversational - the design is minimal and clean
+    13. **GENERATE COMPLETE CHOICES** - Always provide actual choice options, not placeholders like "Option 1", "Option 2"
+    
+    EXAMPLES OF PRESERVING USER TERMINOLOGY:
+    - User says "Valima, Nikkah, Barat" → choices: ["Valima", "Nikkah", "Barat"] (NOT "Reception, Ceremony, etc.")
+    - User says "yes/no" → choices: ["Yes", "No"] (NOT "Agree/Disagree" unless asked)
+    - User mentions specific names/terms → use them exactly as written
+    """
+    component_brief = dspy.InputField(desc="Brief description from planner")
+    component_type = dspy.InputField(desc="Component type")
+    component_id = dspy.InputField(desc="Unique component identifier")
+    form_context = dspy.InputField(desc="Overall form context for better component generation")
+    component_spec = dspy.OutputField(desc="Complete JSON component specification ready for frontend rendering")
+
+
+class FormEditorSignature(dspy.Signature):
+    """
+    Edit an existing form based on user requests.
+    
+    FRONTEND CAPABILITIES:
+    - Headless UI for dialogs and modals
+    - Markdown support in all text fields
+    - Inline editing with QuestionEditor component
+    - Tally-inspired minimal design
+    - Purple accent color throughout
+    
+    INPUT:
+    - edit_request: Natural language edit instruction
+    - current_form: JSON of current form structure
+    
+    EDIT TYPES:
+    1. Add components: Insert new components at appropriate position
+    2. Remove components: Delete specified components
+    3. Modify components: Change text, type, or settings
+    4. Reorder components: Change component sequence
+    5. Update form metadata: Change title, description, settings
+    6. Update conditional logic: Add/remove/modify rules
+    
+    OUTPUT FORMAT (JSON):
+    {
+        "title": "Updated title",
+        "description": "Updated description",
+        "components": [
+            // Updated components array with component_id, type, settings, etc.
+        ],
+        "conditional_logic": [
+            // Updated conditional logic rules
+        ],
+        "submit_button_text": "Submit"
+    }
+    
+    RULES:
+    1. Preserve existing components unless explicitly asked to change
+    2. Maintain component_id consistency
+    3. Update conditional logic if component_ids change
+    4. Apply changes precisely as requested
+    5. Return complete updated form structure
+    """
+    edit_request = dspy.InputField(desc="User's edit instruction")
+    current_form = dspy.InputField(desc="Current form structure as JSON")
+    updated_form = dspy.OutputField(desc="Complete updated form structure as JSON")
+    changes_made = dspy.OutputField(desc="Summary of changes applied")
+
+
+class ComponentMatcherSignature(dspy.Signature):
+    """Match user query to a specific component in the form. Return component_id or null."""
+    query = dspy.InputField(desc="user query about a component")
+    components = dspy.InputField(desc="JSON: [{'id':'comp_1','type':'short_answer','text':'Question text'},...]")
+    component_id = dspy.OutputField(desc="Matching component_id or null if no match")
+
+
+class FormChatRouterSignature(dspy.Signature):
+    """Route user queries for form editing/addition ONLY.
+    
+    ROUTING RULES:
+    
+    - **add_component**: User wants to ADD a new form component/question/field.
+      Keywords: "add", "include", "insert", "create field", "add question"
+      Examples: "Add an email field", "Include a phone number question", "Add a rating field"
+    
+    - **edit_component**: User wants to MODIFY an existing component.
+      Keywords: "change", "modify", "update", "edit", "make it", "adjust"
+      Examples: "Change the email field to required", "Update the rating scale to 1-5"
+    
+    - **general_form_query**: General questions about the form structure or capabilities, or questions that may be irrelevant to form editing.
+      Examples: "What fields are in this form?", "How does conditional logic work?", "What time is it?", "Who won the game last night?"
+    
+    - **need_more_clarity**: Query is ambiguous, unclear, or possibly irrelevant.
+    
+    IMPORTANT: This router is ONLY for form editing/building. NO data analysis.
+    """
+    user_query = dspy.InputField(desc="The user's query about the form")
+    form_context = dspy.InputField(desc="Context about the form structure")
+    query_type = dspy.OutputField(desc="One of: 'add_component', 'edit_component', 'general_form_query', 'need_more_clarity'")
+    reasoning = dspy.OutputField(desc="Brief explanation of why this route was chosen")
+
+
+CLARITY_RESPONSE = (
+    "I'm sorry, I couldn't understand your request.\n\n"
+    "#### Here's what I can help you with:\n"
+    "- **Add** a new component or field to your form\n"
+    "- **Edit** or **modify** an existing component\n"
+    "- Answer **general questions** about your form\n\n"
+    "Please clarify what you'd like to do, or ask for help with one of the options above!"
+)
+
+
+class FormChatFunction(dspy.Module):
+    """Chat functionality for form editing - ONLY add or edit components."""
+    
+    def __init__(self):
+        self.add_component_mod = dspy.Predict(ComponentSignatureGenerator)
+        self.edit_form_mod = dspy.Predict(FormEditorSignature)
+        self.general_qa = dspy.Predict("user_query, form_context -> answer")
+        self.router = dspy.Predict(FormChatRouterSignature)
+        self.recheck_router = dspy.Predict(FormChatRouterSignature)
+        self.CLARITY_RESPONSE = CLARITY_RESPONSE
+    
+    async def aforward(self, user_query: str, form_context: str, current_form: dict = None):
+        """
+        Handle user queries for form editing/addition.
+        
+        Args:
+            user_query: User's natural language request
+            form_context: JSON string of current form structure
+            current_form: Dict of current form structure (optional)
+        
+        Returns:
+            dict with 'route' and 'response' keys
+        """
+        with dspy.context(lm=dspy.LM('openai/gpt-4o-mini', api_key=os.getenv('OPENAI_API_KEY'), max_tokens=1500, temperature=1)):
+            route = self.router(user_query=user_query, form_context=form_context)
+            query_type = route.query_type
+            
+            # If unclear, try recheck router
+            if 'need_more_clarity' in query_type:
+                recheck = self.recheck_router(user_query=user_query, form_context=form_context)
+                if 'need_more_clarity' not in recheck.query_type:
+                    query_type = recheck.query_type
+        
+        if 'add_component' in query_type:
+            # Extract component details from query
+            # Generate a new component_id
+            existing_ids = []
+            if current_form and 'components' in current_form:
+                existing_ids = [c.get('component_id', '') for c in current_form.get('components', [])]
+            
+            new_id = f"comp_{len(existing_ids) + 1}"
+            
+            # CRITICAL: Include the original user query in the form context and brief
+            if form_context:
+                # Parse form_context if it's a string
+                if isinstance(form_context, str):
+                    parsed_context = json.loads(form_context)
+                else:
+                    parsed_context = form_context
+                
+                # Merge with original user request
+                enhanced_form_context = json.dumps({
+                    **parsed_context,
+                    'ORIGINAL_USER_REQUEST': user_query,
+                    'IMPORTANT': 'Use the EXACT terms from ORIGINAL_USER_REQUEST. Do NOT substitute cultural, local, or specific terms.'
+                })
+            else:
+                enhanced_form_context = json.dumps({'ORIGINAL_USER_REQUEST': user_query})
+            
+            enhanced_brief = f"{user_query}. CRITICAL: Use the exact terms mentioned by the user. Do NOT substitute any terms like 'Valima', 'Nikkah', 'Barat' with generic alternatives."
+            
+            response = self.add_component_mod(
+                component_brief=enhanced_brief,
+                component_type="short_answer",  # Default, will be inferred
+                component_id=new_id,
+                form_context=enhanced_form_context
+            )
+        elif 'edit_component' in query_type:
+            if current_form:
+                response = self.edit_form_mod(
+                    edit_request=user_query,
+                    current_form=json.dumps(current_form)
+                )
+            else:
+                response = "No form available to edit."
+        elif 'general_form_query' in query_type:
+            response = self.general_qa(user_query=user_query, form_context=form_context)
+        elif 'need_more_clarity' in query_type:
+            response = self.CLARITY_RESPONSE
+        else:
+            response = self.general_qa(user_query=user_query, form_context=form_context)
+        
+        route.query_type = query_type
+        return_dict = {'route': route, 'response': response}
+        
+        return return_dict
+
+
+# ============================================================================
+# FORM GENERATION MODULE
+# ============================================================================
+
+class FormGenerationModule(dspy.Module):
+    """Main module for generating forms from natural language."""
+    
+    def __init__(self):
+        self.planner = dspy.Predict(FormPlannerSignature)
+        self.component_generator = dspy.Predict(ComponentSignatureGenerator)
+    
+    async def aforward(self, user_query: str):
+        """
+        Generate a complete form from a user query.
+        
+        Args:
+            user_query: Natural language description of the form
+        
+        Returns:
+            dict with complete form structure including components and conditional logic
+        """
+        # Step 1: Generate form plan with component briefs and conditional logic
+        with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'), max_tokens=2000)):
+            plan = self.planner(user_query=user_query)
+        
+        form_plan = plan.form_plan
+        if isinstance(form_plan, str):
+            try:
+                form_plan = json.loads(form_plan)
+            except json.JSONDecodeError:
+                logger.error("Failed to parse form plan JSON")
+                return {'error': 'Failed to generate form plan'}
+        
+        logger.info(f"Form plan generated: {form_plan.get('title', 'Untitled')}")
+        
+        # Step 2: Generate detailed component specifications
+        components = form_plan.get('components', [])
+        detailed_components = []
+        
+        # CRITICAL: Include original user_query so components use exact terminology
+        form_context = json.dumps({
+            'title': form_plan.get('title'),
+            'description': form_plan.get('description'),
+            'total_components': len(components),
+            'ORIGINAL_USER_REQUEST': user_query,  # Pass the exact user request
+            'IMPORTANT': 'Use the EXACT terms from ORIGINAL_USER_REQUEST. Do NOT substitute cultural or local terms.'
+        })
+        
+        for comp in components:
+            try:
+                # Include original user query in component brief for exact terminology
+                enhanced_brief = f"{comp.get('brief', '')}. IMPORTANT: Use exact terms from user's original request: '{user_query}'. Do NOT substitute any terms."
+                
+                with dspy.context(lm=dspy.LM("openai/gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'), max_tokens=1000)):
+                    component_spec = self.component_generator(
+                        component_brief=enhanced_brief,
+                        component_type=comp.get('type', 'short_answer'),
+                        component_id=comp.get('component_id', f"comp_{len(detailed_components) + 1}"),
+                        form_context=form_context
+                    )
+                
+                comp_spec = component_spec.component_spec
+                if isinstance(comp_spec, str):
+                    try:
+                        comp_spec = json.loads(comp_spec)
+                    except json.JSONDecodeError:
+                        logger.error(f"Failed to parse component spec for {comp.get('component_id')}")
+                        continue
+                
+                # Ensure order is preserved
+                comp_spec['order'] = comp.get('order', len(detailed_components))
+                detailed_components.append(comp_spec)
+                
+            except Exception as e:
+                logger.error(f"Error generating component {comp.get('component_id')}: {e}")
+                continue
+        
+        # Step 3: Build final form structure
+        final_form = {
+            'title': form_plan.get('title', 'Untitled Form'),
+            'description': form_plan.get('description', ''),
+            'submit_button_text': form_plan.get('submit_button_text', 'Submit'),
+            'components': detailed_components,
+            'conditional_logic': form_plan.get('conditional_logic', []),
+            'settings': form_plan.get('settings', {})
+        }
+        
+        return final_form
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+def validate_form_structure(form_data: dict) -> tuple[bool, str]:
+    """
+    Validate form structure.
+    
+    Args:
+        form_data: Form dictionary to validate
+    
+    Returns:
+        (is_valid, error_message)
+    """
+    if not isinstance(form_data, dict):
+        return False, "Form data must be a dictionary"
+    
+    if 'title' not in form_data:
+        return False, "Form must have a title"
+    
+    if 'components' not in form_data or not isinstance(form_data['components'], list):
+        return False, "Form must have a components list"
+    
+    if len(form_data['components']) == 0:
+        return False, "Form must have at least one component"
+    
+    # Validate each component has required fields
+    for i, comp in enumerate(form_data['components']):
+        if 'component_id' not in comp:
+            return False, f"Component {i} missing component_id"
+        if 'question_type' not in comp:
+            return False, f"Component {comp.get('component_id')} missing question_type"
+        if 'question_text' not in comp:
+            return False, f"Component {comp.get('component_id')} missing question_text"
+    
+    return True, ""
+
+
+def extract_component_ids(form_data: dict) -> list:
+    """Extract all component IDs from form structure."""
+    if not isinstance(form_data, dict):
+        return []
+    
+    components = form_data.get('components', [])
+    return [comp.get('component_id') for comp in components if 'component_id' in comp]

app/services/analytics_service.py

@@ -0,0 +1,450 @@
+"""
+Analytics service for form tracking and insights
+"""
+from sqlalchemy.orm import Session
+from sqlalchemy import func, desc, and_
+from typing import Optional, Dict, Any, List
+from datetime import datetime, timedelta
+from fastapi import Request
+import hashlib
+import uuid
+import logging
+
+from ..models import FormAnalyticsEvent, Form, FormQuestion, FormResponse, AnalyticsEventType
+
+logger = logging.getLogger(__name__)
+
+
+class AnalyticsService:
+    """Service for tracking and analyzing form usage"""
+    
+    def __init__(self):
+        self.ip_salt = "autoform_salt_2026"  # Use environment variable in production
+    
+    async def track_event(
+        self,
+        db: Session,
+        event_type: str,
+        form_id: int,
+        session_id: str,
+        request: Request,
+        submission_id: Optional[int] = None,
+        question_id: Optional[int] = None,
+        time_spent_seconds: Optional[int] = None,
+        metadata: Optional[Dict] = None
+    ):
+        """
+        Track analytics event with automatic enrichment.
+        
+        Args:
+            db: Database session
+            event_type: Type of event (form_viewed, question_answered, etc.)
+            form_id: ID of the form
+            session_id: Session ID
+            request: FastAPI Request object
+            submission_id: Optional submission ID
+            question_id: Optional question ID
+            time_spent_seconds: Optional time spent
+            metadata: Optional additional metadata
+        """
+        try:
+            # Extract IP address
+            client_ip = None
+            if request.client:
+                client_ip = request.client.host
+            
+            # Hash IP for privacy
+            ip_hash = self._hash_ip(client_ip) if client_ip else "unknown"
+            
+            # Extract user agent
+            user_agent = request.headers.get("user-agent")
+            
+            # Extract referrer
+            referrer = request.headers.get("referer") or request.headers.get("referrer")
+            
+            # Extract UTM parameters from query params or referrer
+            utm_source = None
+            utm_medium = None
+            utm_campaign = None
+            
+            if hasattr(request, 'query_params'):
+                utm_source = request.query_params.get('utm_source')
+                utm_medium = request.query_params.get('utm_medium')
+                utm_campaign = request.query_params.get('utm_campaign')
+            
+            # Perform IP geolocation (basic - can be enhanced with MaxMind)
+            country, city = await self._get_geo_location(client_ip)
+            
+            # Create event
+            event = FormAnalyticsEvent(
+                event_id=str(uuid.uuid4()),
+                form_id=form_id,
+                submission_id=submission_id,
+                question_id=question_id,
+                event_type=event_type,
+                session_id=session_id,
+                ip_address_hash=ip_hash,
+                ip_address_raw=None,  # Only store if user opts in
+                country=country,
+                city=city,
+                user_agent=user_agent,
+                referrer=referrer,
+                utm_source=utm_source,
+                utm_medium=utm_medium,
+                utm_campaign=utm_campaign,
+                time_spent_seconds=time_spent_seconds,
+                event_metadata=metadata or {}
+            )
+            
+            db.add(event)
+            db.commit()
+            
+            logger.info(f"Tracked event: {event_type} for form {form_id}, session {session_id}")
+            
+        except Exception as e:
+            logger.error(f"Failed to track analytics event: {e}")
+            # Don't raise - analytics failures shouldn't break form submission
+            db.rollback()
+    
+    async def get_time_series_data(
+        self,
+        db: Session,
+        form_id: int,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None,
+        question_ids: Optional[List[int]] = None,
+        countries: Optional[List[str]] = None,
+        utm_source: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Get time-series data for views and submissions.
+        
+        Returns daily counts of views and submissions within the date range.
+        """
+        # Default date range: last 30 days
+        if not end_date:
+            end_date = datetime.utcnow()
+        if not start_date:
+            start_date = end_date - timedelta(days=30)
+        
+        # Build base filter
+        filters = [
+            FormAnalyticsEvent.form_id == form_id,
+            FormAnalyticsEvent.created_at >= start_date,
+            FormAnalyticsEvent.created_at <= end_date
+        ]
+        
+        if question_ids:
+            filters.append(FormAnalyticsEvent.question_id.in_(question_ids))
+        if countries:
+            filters.append(FormAnalyticsEvent.country.in_(countries))
+        if utm_source:
+            filters.append(FormAnalyticsEvent.utm_source == utm_source)
+        
+        # Get daily views
+        views_query = db.query(
+            func.date(FormAnalyticsEvent.created_at).label('date'),
+            func.count(FormAnalyticsEvent.id).label('count')
+        ).filter(
+            and_(*filters),
+            FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_VIEWED.value
+        ).group_by(func.date(FormAnalyticsEvent.created_at)).all()
+        
+        # Get daily submissions
+        submissions_query = db.query(
+            func.date(FormAnalyticsEvent.created_at).label('date'),
+            func.count(FormAnalyticsEvent.id).label('count')
+        ).filter(
+            and_(*filters),
+            FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_SUBMITTED_COMPLETE.value
+        ).group_by(func.date(FormAnalyticsEvent.created_at)).all()
+        
+        # Build complete date range
+        current_date = start_date.date()
+        end = end_date.date()
+        time_series = []
+        
+        views_dict = {str(row.date): row.count for row in views_query}
+        submissions_dict = {str(row.date): row.count for row in submissions_query}
+        
+        while current_date <= end:
+            date_str = str(current_date)
+            time_series.append({
+                "date": date_str,
+                "views": views_dict.get(date_str, 0),
+                "submissions": submissions_dict.get(date_str, 0)
+            })
+            current_date += timedelta(days=1)
+        
+        return {
+            "time_series": time_series,
+            "total_views": sum(v["views"] for v in time_series),
+            "total_submissions": sum(v["submissions"] for v in time_series)
+        }
+    
+    async def get_funnel_analytics(
+        self,
+        db: Session,
+        form_id: int,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None,
+        question_ids: Optional[List[int]] = None,
+        countries: Optional[List[str]] = None,
+        utm_source: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Generate funnel analytics for a form.
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            start_date: Optional start date for filtering
+            end_date: Optional end date for filtering
+        
+        Returns:
+            Dictionary with funnel analytics data
+        """
+        # Default date range: last 30 days
+        if not end_date:
+            end_date = datetime.utcnow()
+        if not start_date:
+            start_date = end_date - timedelta(days=30)
+        
+        # Base query filter
+        filters = [
+            FormAnalyticsEvent.form_id == form_id,
+            FormAnalyticsEvent.created_at >= start_date,
+            FormAnalyticsEvent.created_at <= end_date
+        ]
+        
+        if question_ids:
+            filters.append(FormAnalyticsEvent.question_id.in_(question_ids))
+        if countries:
+            filters.append(FormAnalyticsEvent.country.in_(countries))
+        if utm_source:
+            filters.append(FormAnalyticsEvent.utm_source == utm_source)
+        
+        base_filter = and_(*filters)
+        
+        # Count events by type
+        total_views = db.query(func.count(FormAnalyticsEvent.id)).filter(
+            base_filter,
+            FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_VIEWED.value
+        ).scalar() or 0
+        
+        total_starts = db.query(func.count(FormAnalyticsEvent.id)).filter(
+            base_filter,
+            FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_STARTED.value
+        ).scalar() or 0
+        
+        total_completes = db.query(func.count(FormAnalyticsEvent.id)).filter(
+            base_filter,
+            FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_SUBMITTED_COMPLETE.value
+        ).scalar() or 0
+        
+        # Calculate completion rate
+        completion_rate = (total_completes / total_views * 100) if total_views > 0 else 0
+        
+        # Get form questions
+        form = db.query(Form).filter(Form.id == form_id).first()
+        if not form:
+            return {}
+        
+        # Build question funnel
+        question_funnel = []
+        for question in sorted(form.questions, key=lambda q: q.question_order):
+            viewed = db.query(func.count(FormAnalyticsEvent.id)).filter(
+                base_filter,
+                FormAnalyticsEvent.question_id == question.id,
+                FormAnalyticsEvent.event_type == AnalyticsEventType.QUESTION_VIEWED.value
+            ).scalar() or 0
+            
+            answered = db.query(func.count(FormAnalyticsEvent.id)).filter(
+                base_filter,
+                FormAnalyticsEvent.question_id == question.id,
+                FormAnalyticsEvent.event_type == AnalyticsEventType.QUESTION_ANSWERED.value
+            ).scalar() or 0
+            
+            skipped = db.query(func.count(FormAnalyticsEvent.id)).filter(
+                base_filter,
+                FormAnalyticsEvent.question_id == question.id,
+                FormAnalyticsEvent.event_type == AnalyticsEventType.QUESTION_SKIPPED.value
+            ).scalar() or 0
+            
+            # Calculate average time spent
+            avg_time_result = db.query(
+                func.avg(FormAnalyticsEvent.time_spent_seconds)
+            ).filter(
+                base_filter,
+                FormAnalyticsEvent.question_id == question.id,
+                FormAnalyticsEvent.time_spent_seconds.isnot(None)
+            ).scalar()
+            
+            avg_time_spent = float(avg_time_result) if avg_time_result else 0.0
+            
+            # Calculate drop-off rate
+            drop_off_rate = (skipped / viewed * 100) if viewed > 0 else 0
+            
+            question_funnel.append({
+                "question_id": question.id,
+                "question_text": question.question_text,
+                "question_order": question.question_order,
+                "viewed": viewed,
+                "answered": answered,
+                "skipped": skipped,
+                "drop_off_rate": round(drop_off_rate, 2),
+                "avg_time_spent": round(avg_time_spent, 2)
+            })
+        
+        # Traffic sources analysis
+        traffic_sources = {}
+        utm_source_data = db.query(
+            FormAnalyticsEvent.utm_source,
+            func.count(FormAnalyticsEvent.id).label('count')
+        ).filter(
+            base_filter,
+            FormAnalyticsEvent.utm_source.isnot(None)
+        ).group_by(FormAnalyticsEvent.utm_source).all()
+        
+        for source, count in utm_source_data:
+            # Calculate completion rate for this source
+            source_completes = db.query(func.count(FormAnalyticsEvent.id)).filter(
+                base_filter,
+                FormAnalyticsEvent.utm_source == source,
+                FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_SUBMITTED_COMPLETE.value
+            ).scalar() or 0
+            
+            completion_rate_source = (source_completes / count * 100) if count > 0 else 0
+            
+            traffic_sources[source] = {
+                "count": count,
+                "completion_rate": round(completion_rate_source, 2)
+            }
+        
+        # Geographic distribution
+        geographic_distribution = {}
+        country_data = db.query(
+            FormAnalyticsEvent.country,
+            func.count(FormAnalyticsEvent.id).label('views')
+        ).filter(
+            base_filter,
+            FormAnalyticsEvent.country.isnot(None)
+        ).group_by(FormAnalyticsEvent.country).all()
+        
+        for country, views in country_data:
+            country_completes = db.query(func.count(FormAnalyticsEvent.id)).filter(
+                base_filter,
+                FormAnalyticsEvent.country == country,
+                FormAnalyticsEvent.event_type == AnalyticsEventType.FORM_SUBMITTED_COMPLETE.value
+            ).scalar() or 0
+            
+            geographic_distribution[country] = {
+                "views": views,
+                "completes": country_completes
+            }
+        
+        return {
+            "total_views": total_views,
+            "total_starts": total_starts,
+            "total_completes": total_completes,
+            "completion_rate": round(completion_rate, 2),
+            "question_funnel": question_funnel,
+            "traffic_sources": traffic_sources,
+            "geographic_distribution": geographic_distribution,
+            "date_range": {
+                "start": start_date.isoformat(),
+                "end": end_date.isoformat()
+            }
+        }
+    
+    async def get_summary_analytics(
+        self,
+        db: Session,
+        form_id: int
+    ) -> Dict[str, Any]:
+        """
+        Get high-level analytics summary for a form.
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+        
+        Returns:
+            Dictionary with summary analytics
+        """
+        # Total responses
+        total_responses = db.query(func.count(FormResponse.id)).filter(
+            FormResponse.form_id == form_id
+        ).scalar() or 0
+        
+        # Complete vs partial
+        complete_responses = db.query(func.count(FormResponse.id)).filter(
+            FormResponse.form_id == form_id,
+            FormResponse.status == "complete"
+        ).scalar() or 0
+        
+        # Recent activity (last 7 days)
+        seven_days_ago = datetime.utcnow() - timedelta(days=7)
+        recent_responses = db.query(func.count(FormResponse.id)).filter(
+            FormResponse.form_id == form_id,
+            FormResponse.submitted_at >= seven_days_ago
+        ).scalar() or 0
+        
+        # Average completion time (if tracked)
+        avg_completion_seconds = db.query(
+            func.avg(
+                func.extract('epoch', FormResponse.submitted_at - FormResponse.started_at)
+            )
+        ).filter(
+            FormResponse.form_id == form_id,
+            FormResponse.started_at.isnot(None),
+            FormResponse.status == "complete"
+        ).scalar()
+        
+        avg_completion_minutes = (avg_completion_seconds / 60) if avg_completion_seconds else None
+        
+        return {
+            "total_responses": total_responses,
+            "complete_responses": complete_responses,
+            "partial_responses": total_responses - complete_responses,
+            "recent_responses_7d": recent_responses,
+            "avg_completion_minutes": round(avg_completion_minutes, 2) if avg_completion_minutes else None
+        }
+    
+    def _hash_ip(self, ip_address: str) -> str:
+        """Hash IP address for privacy"""
+        if not ip_address:
+            return "unknown"
+        
+        # SHA256 hash with salt
+        salted = f"{ip_address}{self.ip_salt}"
+        return hashlib.sha256(salted.encode()).hexdigest()
+    
+    async def _get_geo_location(self, ip_address: Optional[str]) -> tuple:
+        """
+        Get geographic location from IP address.
+        
+        For now, returns None. In production:
+        - Use MaxMind GeoLite2 database (free, local lookup)
+        - Or use ipapi.co API (rate-limited)
+        
+        Args:
+            ip_address: IP address to lookup
+        
+        Returns:
+            Tuple of (country, city)
+        """
+        if not ip_address:
+            return (None, None)
+        
+        # TODO: Implement with MaxMind GeoLite2 or ipapi.co
+        # For localhost/development, return None
+        if ip_address in ['127.0.0.1', 'localhost', '::1']:
+            return ('Local', 'Development')
+        
+        # Placeholder - implement actual geolocation
+        return (None, None)
+
+
+# Singleton instance
+analytics_service = AnalyticsService()

app/services/credit_service.py

@@ -0,0 +1,392 @@
+"""
+Credit management service for handling user credit operations
+"""
+from sqlalchemy.orm import Session
+from sqlalchemy import and_
+from datetime import datetime
+from typing import Optional, Dict, Any
+import logging
+
+from ..models import User, UserCredits, CreditTransaction, TransactionType, SubscriptionPlan, Subscription
+from .plan_service import plan_service
+
+logger = logging.getLogger(__name__)
+
+
+class CreditService:
+    """Service for managing user credits"""
+    
+    def get_user_credits(self, db: Session, user_id: int) -> Optional[UserCredits]:
+        """
+        Get the current credit balance for a user
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            
+        Returns:
+            UserCredits object or None if not found
+        """
+        return db.query(UserCredits).filter(UserCredits.user_id == user_id).first()
+    
+    def get_or_create_user_credits(self, db: Session, user_id: int, plan_id: Optional[int] = None) -> UserCredits:
+        """
+        Get or create credit record for a user. If plan_id is null, assigns free tier.
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            plan_id: Optional plan ID (if None and credits don't exist, assigns free tier)
+            
+        Returns:
+            UserCredits object
+        """
+        credits = self.get_user_credits(db, user_id)
+        if not credits:
+            # If no plan_id provided, get free tier
+            if plan_id is None:
+                free_plan = plan_service.get_plan_by_name(db, "Free")
+                if free_plan:
+                    plan_id = free_plan.id
+                    # Initialize with free tier credits
+                    credits = UserCredits(
+                        user_id=user_id,
+                        plan_id=plan_id,
+                        balance=free_plan.credits_per_month,
+                        last_reset_at=datetime.utcnow()
+                    )
+                    db.add(credits)
+                    
+                    # Also create subscription record
+                    subscription = db.query(Subscription).filter(
+                        Subscription.user_id == user_id
+                    ).order_by(Subscription.created_at.desc()).first()
+                    
+                    if not subscription:
+                        subscription = Subscription(
+                            user_id=user_id,
+                            plan_id=free_plan.id,
+                            status="active"
+                        )
+                        db.add(subscription)
+                        logger.info(f"Created subscription record for user {user_id} with free tier")
+                    
+                    # Log credit transaction for initial free tier assignment
+                    transaction = CreditTransaction(
+                        user_id=user_id,
+                        amount=free_plan.credits_per_month,
+                        transaction_type=TransactionType.RESET,
+                        description="Initial free tier assignment",
+                        transaction_metadata={"plan_id": free_plan.id, "plan_name": free_plan.name}
+                    )
+                    db.add(transaction)
+                else:
+                    # Fallback if free plan doesn't exist
+                    credits = UserCredits(
+                        user_id=user_id,
+                        plan_id=None,
+                        balance=0,
+                        last_reset_at=None
+                    )
+                    db.add(credits)
+            else:
+                credits = UserCredits(
+                    user_id=user_id,
+                    plan_id=plan_id,
+                    balance=0,
+                    last_reset_at=None
+                )
+                db.add(credits)
+            db.commit()
+            db.refresh(credits)
+            logger.info(f"Created credit record for user {user_id} with plan_id={plan_id}")
+        elif credits.plan_id is None:
+            # Existing credits but no plan_id - assign free tier
+            # Only reset balance if user was never assigned credits before (last_reset_at is None)
+            # This prevents users who exhausted credits from getting free credits again
+            free_plan = plan_service.get_plan_by_name(db, "Free")
+            if free_plan:
+                old_balance = credits.balance
+                credits.plan_id = free_plan.id
+                # Only reset balance if user was never assigned credits before
+                # (last_reset_at is None means they never had credits initialized)
+                if credits.balance == 0 and credits.last_reset_at is None:
+                    credits.balance = free_plan.credits_per_month
+                    credits.last_reset_at = datetime.utcnow()
+                credits.updated_at = datetime.utcnow()
+                
+                # Also ensure subscription record exists
+                subscription = db.query(Subscription).filter(
+                    Subscription.user_id == user_id
+                ).order_by(Subscription.created_at.desc()).first()
+                
+                if not subscription:
+                    # Create subscription record
+                    subscription = Subscription(
+                        user_id=user_id,
+                        plan_id=free_plan.id,
+                        status="active"
+                    )
+                    db.add(subscription)
+                    logger.info(f"Created subscription record for user {user_id} with free tier")
+                elif subscription.plan_id != free_plan.id:
+                    # Update existing subscription to free tier
+                    subscription.plan_id = free_plan.id
+                    subscription.status = "active"
+                    logger.info(f"Updated subscription for user {user_id} to free tier")
+                
+                # Log credit transaction if balance changed
+                if old_balance != credits.balance:
+                    transaction = CreditTransaction(
+                        user_id=user_id,
+                        amount=credits.balance - old_balance,
+                        transaction_type=TransactionType.RESET,
+                        description="Free tier assignment - balance reset",
+                        transaction_metadata={"plan_id": free_plan.id, "plan_name": free_plan.name, "old_balance": old_balance}
+                    )
+                    db.add(transaction)
+                
+                db.commit()
+                db.refresh(credits)
+                logger.info(f"Assigned free tier to user {user_id} (existing credits record)")
+        return credits
+    
+    def check_sufficient_credits(self, db: Session, user_id: int, amount: int) -> bool:
+        """
+        Check if user has sufficient credits (pre-check before operation)
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            amount: Required credit amount
+            
+        Returns:
+            True if user has enough credits, False otherwise
+        """
+        credits = self.get_user_credits(db, user_id)
+        if not credits:
+            logger.warning(f"No credit record found for user {user_id}")
+            return False
+        
+        has_sufficient = credits.balance >= amount
+        logger.info(f"User {user_id} credit check: balance={credits.balance}, required={amount}, sufficient={has_sufficient}")
+        return has_sufficient
+    
+    def deduct_credits(
+        self, 
+        db: Session, 
+        user_id: int, 
+        amount: int, 
+        description: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> UserCredits:
+        """
+        Deduct credits from user account (post-operation deduction)
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            amount: Amount to deduct (positive number)
+            description: Description of the transaction
+            metadata: Optional metadata dictionary
+            
+        Returns:
+            Updated UserCredits object
+            
+        Raises:
+            ValueError: If user has insufficient credits
+        """
+        credits = self.get_user_credits(db, user_id)
+        if not credits:
+            raise ValueError(f"No credit record found for user {user_id}")
+        
+        if credits.balance < amount:
+            raise ValueError(f"Insufficient credits: balance={credits.balance}, required={amount}")
+        
+        # Deduct credits
+        credits.balance -= amount
+        credits.updated_at = datetime.utcnow()
+        
+        # Log transaction
+        transaction = CreditTransaction(
+            user_id=user_id,
+            amount=-amount,  # Negative for deduction
+            transaction_type=TransactionType.DEDUCT,
+            description=description,
+            transaction_metadata=metadata or {}
+        )
+        db.add(transaction)
+        db.commit()
+        db.refresh(credits)
+        
+        logger.info(f"Deducted {amount} credits from user {user_id}. New balance: {credits.balance}")
+        return credits
+    
+    def add_credits(
+        self,
+        db: Session,
+        user_id: int,
+        amount: int,
+        description: str,
+        transaction_type: TransactionType = TransactionType.ADJUSTMENT,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> UserCredits:
+        """
+        Add credits to user account (for adjustments, refunds, etc.)
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            amount: Amount to add (positive number)
+            description: Description of the transaction
+            transaction_type: Type of transaction (ADJUSTMENT, REFUND, etc.)
+            metadata: Optional metadata dictionary
+            
+        Returns:
+            Updated UserCredits object
+        """
+        credits = self.get_or_create_user_credits(db, user_id)
+        
+        # Add credits
+        credits.balance += amount
+        credits.updated_at = datetime.utcnow()
+        
+        # Log transaction
+        transaction = CreditTransaction(
+            user_id=user_id,
+            amount=amount,  # Positive for addition
+            transaction_type=transaction_type,
+            description=description,
+            transaction_metadata=metadata or {}
+        )
+        db.add(transaction)
+        db.commit()
+        db.refresh(credits)
+        
+        logger.info(f"Added {amount} credits to user {user_id}. New balance: {credits.balance}")
+        return credits
+    
+    def reset_credits(
+        self,
+        db: Session,
+        user_id: int,
+        plan_id: Optional[int] = None,
+        description: str = "Monthly credit reset"
+    ) -> UserCredits:
+        """
+        Reset user credits to their plan limit
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            plan_id: Optional plan ID (if None, uses current plan)
+            description: Description for the transaction
+            
+        Returns:
+            Updated UserCredits object
+        """
+        credits = self.get_or_create_user_credits(db, user_id, plan_id)
+        
+        # Get plan details
+        if plan_id:
+            plan = db.query(SubscriptionPlan).filter(SubscriptionPlan.id == plan_id).first()
+        elif credits.plan_id:
+            plan = db.query(SubscriptionPlan).filter(SubscriptionPlan.id == credits.plan_id).first()
+        else:
+            # Default to free tier if no plan
+            plan = db.query(SubscriptionPlan).filter(SubscriptionPlan.name == "Free").first()
+        
+        if not plan:
+            raise ValueError(f"No plan found for user {user_id}")
+        
+        # Reset to plan limit
+        old_balance = credits.balance
+        credits.balance = plan.credits_per_month
+        credits.plan_id = plan.id
+        credits.last_reset_at = datetime.utcnow()
+        credits.updated_at = datetime.utcnow()
+        
+        # Log transaction
+        transaction = CreditTransaction(
+            user_id=user_id,
+            amount=credits.balance - old_balance,  # Can be positive or negative
+            transaction_type=TransactionType.RESET,
+            description=description,
+            transaction_metadata={"plan_id": plan.id, "plan_name": plan.name, "old_balance": old_balance}
+        )
+        db.add(transaction)
+        db.commit()
+        db.refresh(credits)
+        
+        logger.info(f"Reset credits for user {user_id} to {credits.balance} (plan: {plan.name})")
+        return credits
+    
+    def get_credit_history(
+        self,
+        db: Session,
+        user_id: int,
+        limit: int = 50,
+        offset: int = 0
+    ) -> list[CreditTransaction]:
+        """
+        Get credit transaction history for a user
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            limit: Number of transactions to return
+            offset: Number of transactions to skip
+            
+        Returns:
+            List of CreditTransaction objects
+        """
+        return (
+            db.query(CreditTransaction)
+            .filter(CreditTransaction.user_id == user_id)
+            .order_by(CreditTransaction.created_at.desc())
+            .limit(limit)
+            .offset(offset)
+            .all()
+        )
+    
+    def get_balance_info(self, db: Session, user_id: int) -> Dict[str, Any]:
+        """
+        Get comprehensive balance information for a user
+        
+        Args:
+            db: Database session
+            user_id: User ID
+            
+        Returns:
+            Dictionary with balance, plan info, and limits
+        """
+        credits = self.get_user_credits(db, user_id)
+        if not credits:
+            return {
+                "balance": 0,
+                "plan_name": None,
+                "plan_id": None,
+                "credits_per_analyze": 0,
+                "credits_per_edit": 0,
+                "last_reset_at": None,
+                "updated_at": datetime.utcnow().isoformat()
+            }
+        
+        plan = None
+        if credits.plan_id:
+            plan = db.query(SubscriptionPlan).filter(SubscriptionPlan.id == credits.plan_id).first()
+        
+        return {
+            "balance": credits.balance,
+            "plan_name": plan.name if plan else None,
+            "plan_id": credits.plan_id,
+            "credits_per_analyze": plan.credits_per_analyze if plan else 0,
+            "credits_per_edit": plan.credits_per_edit if plan else 0,
+            "last_reset_at": credits.last_reset_at.isoformat() if credits.last_reset_at else None,
+            "updated_at": credits.updated_at.isoformat()
+        }
+
+
+# Singleton instance
+credit_service = CreditService()
+

app/services/export_service.py

@@ -0,0 +1,480 @@
+"""
+Export service for form responses (CSV, Excel, PDF)
+"""
+from sqlalchemy.orm import Session
+from sqlalchemy import desc
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+import io
+import csv
+import json
+import logging
+
+# Excel support
+from openpyxl import Workbook
+from openpyxl.styles import Font, Alignment, PatternFill
+from openpyxl.chart import BarChart, Reference
+
+# PDF support
+from reportlab.lib.pagesizes import letter, A4
+from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+from reportlab.lib.units import inch
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle
+from reportlab.lib import colors
+
+from ..models import Form, FormQuestion, FormResponse, ResponseAnswer
+
+logger = logging.getLogger(__name__)
+
+
+class ExportService:
+    """Service for exporting form responses in various formats"""
+    
+    async def export_csv(
+        self,
+        db: Session,
+        form_id: int,
+        include_incomplete: bool = False,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None,
+        anonymize_pii: bool = False
+    ) -> io.StringIO:
+        """
+        Enhanced CSV export with filtering.
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            include_incomplete: Include incomplete submissions
+            start_date: Optional start date filter
+            end_date: Optional end date filter
+            anonymize_pii: Anonymize personally identifiable information
+        
+        Returns:
+            StringIO object with CSV data
+        """
+        # Get form
+        form = db.query(Form).filter(Form.id == form_id).first()
+        if not form:
+            raise ValueError(f"Form {form_id} not found")
+        
+        # Get questions
+        questions = sorted(form.questions, key=lambda q: q.question_order)
+        
+        # Build query for responses
+        query = db.query(FormResponse).filter(FormResponse.form_id == form_id)
+        
+        # Apply filters
+        if not include_incomplete:
+            query = query.filter(FormResponse.status == "complete")
+        
+        if start_date:
+            query = query.filter(FormResponse.submitted_at >= start_date)
+        
+        if end_date:
+            query = query.filter(FormResponse.submitted_at <= end_date)
+        
+        responses = query.order_by(desc(FormResponse.submitted_at)).all()
+        
+        # Create CSV in memory
+        output = io.StringIO()
+        writer = csv.writer(output)
+        
+        # Build headers
+        headers = [
+            "Response ID",
+            "Status",
+            "Submitted At",
+            "Started At",
+            "Completion Time (minutes)",
+            "IP Address" if not anonymize_pii else "IP Hash",
+            "Country",
+            "City",
+            "UTM Source",
+            "UTM Medium",
+            "UTM Campaign"
+        ]
+        headers.extend([q.question_text for q in questions])
+        writer.writerow(headers)
+        
+        # Write data rows
+        for response in responses:
+            # Calculate completion time
+            completion_minutes = None
+            if response.started_at and response.submitted_at:
+                delta = response.submitted_at - response.started_at
+                completion_minutes = round(delta.total_seconds() / 60, 2)
+            
+            row = [
+                response.id,
+                response.status,
+                response.submitted_at.isoformat() if response.submitted_at else "",
+                response.started_at.isoformat() if response.started_at else "",
+                completion_minutes if completion_minutes else "",
+                response.ip_address_hash if anonymize_pii else (response.ip_address or ""),
+                response.country or "",
+                response.city or "",
+                response.utm_source or "",
+                response.utm_medium or "",
+                response.utm_campaign or ""
+            ]
+            
+            # Create answer map
+            answer_map = {
+                answer.form_question_id: answer.answer_value
+                for answer in response.answers
+            }
+            
+            # Add answers in question order
+            for question in questions:
+                answer_value = answer_map.get(question.id, {})
+                formatted_answer = self._format_answer_for_export(answer_value)
+                row.append(formatted_answer)
+            
+            writer.writerow(row)
+        
+        output.seek(0)
+        return output
+    
+    async def export_excel(
+        self,
+        db: Session,
+        form_id: int,
+        include_incomplete: bool = False
+    ) -> io.BytesIO:
+        """
+        Export as Excel with multiple sheets.
+        
+        Sheets:
+        1. Responses - All response data
+        2. Summary - Statistics and charts
+        3. Metadata - Form structure info
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            include_incomplete: Include incomplete submissions
+        
+        Returns:
+            BytesIO object with Excel workbook
+        """
+        # Get form
+        form = db.query(Form).filter(Form.id == form_id).first()
+        if not form:
+            raise ValueError(f"Form {form_id} not found")
+        
+        # Create workbook
+        wb = Workbook()
+        
+        # Sheet 1: Responses
+        ws_responses = wb.active
+        ws_responses.title = "Responses"
+        
+        # Get questions
+        questions = sorted(form.questions, key=lambda q: q.question_order)
+        
+        # Headers
+        headers = ["Response ID", "Status", "Submitted At", "Country", "City"]
+        headers.extend([q.question_text for q in questions])
+        ws_responses.append(headers)
+        
+        # Style headers
+        header_fill = PatternFill(start_color="9333EA", end_color="9333EA", fill_type="solid")
+        header_font = Font(color="FFFFFF", bold=True)
+        
+        for cell in ws_responses[1]:
+            cell.fill = header_fill
+            cell.font = header_font
+            cell.alignment = Alignment(horizontal="center", vertical="center")
+        
+        # Get responses
+        query = db.query(FormResponse).filter(FormResponse.form_id == form_id)
+        if not include_incomplete:
+            query = query.filter(FormResponse.status == "complete")
+        
+        responses = query.order_by(desc(FormResponse.submitted_at)).all()
+        
+        # Write data
+        for response in responses:
+            answer_map = {
+                answer.form_question_id: answer.answer_value
+                for answer in response.answers
+            }
+            
+            row = [
+                response.id,
+                response.status,
+                response.submitted_at.isoformat() if response.submitted_at else "",
+                response.country or "",
+                response.city or ""
+            ]
+            
+            for question in questions:
+                answer_value = answer_map.get(question.id, {})
+                formatted_answer = self._format_answer_for_export(answer_value)
+                row.append(formatted_answer)
+            
+            ws_responses.append(row)
+        
+        # Auto-size columns
+        for column in ws_responses.columns:
+            max_length = 0
+            column_letter = column[0].column_letter
+            for cell in column:
+                try:
+                    if len(str(cell.value)) > max_length:
+                        max_length = len(str(cell.value))
+                except:
+                    pass
+            adjusted_width = min(max_length + 2, 50)
+            ws_responses.column_dimensions[column_letter].width = adjusted_width
+        
+        # Sheet 2: Summary
+        ws_summary = wb.create_sheet("Summary")
+        ws_summary['A1'] = "Form Analytics Summary"
+        ws_summary['A1'].font = Font(size=16, bold=True)
+        
+        ws_summary['A3'] = "Total Responses:"
+        ws_summary['B3'] = len(responses)
+        
+        complete_count = sum(1 for r in responses if r.status == "complete")
+        ws_summary['A4'] = "Complete Responses:"
+        ws_summary['B4'] = complete_count
+        
+        ws_summary['A5'] = "Completion Rate:"
+        ws_summary['B5'] = f"{(complete_count / len(responses) * 100):.1f}%" if responses else "0%"
+        
+        # Sheet 3: Metadata
+        ws_meta = wb.create_sheet("Metadata")
+        ws_meta['A1'] = "Form Metadata"
+        ws_meta['A1'].font = Font(size=16, bold=True)
+        
+        ws_meta['A3'] = "Form Title:"
+        ws_meta['B3'] = form.title
+        
+        ws_meta['A4'] = "Form ID:"
+        ws_meta['B4'] = form.id
+        
+        ws_meta['A5'] = "Export Date:"
+        ws_meta['B5'] = datetime.utcnow().isoformat()
+        
+        ws_meta['A6'] = "Total Questions:"
+        ws_meta['B6'] = len(questions)
+        
+        ws_meta['A8'] = "Questions:"
+        for idx, question in enumerate(questions, start=9):
+            ws_meta[f'A{idx}'] = f"Q{question.question_order}:"
+            ws_meta[f'B{idx}'] = question.question_text
+            ws_meta[f'C{idx}'] = question.question_type.value
+        
+        # Save to BytesIO
+        output = io.BytesIO()
+        wb.save(output)
+        output.seek(0)
+        
+        return output
+    
+    async def export_pdf(
+        self,
+        db: Session,
+        form_id: int,
+        response_id: int
+    ) -> io.BytesIO:
+        """
+        Export single response as formatted PDF.
+        
+        Args:
+            db: Database session
+            form_id: ID of the form
+            response_id: ID of the response
+        
+        Returns:
+            BytesIO object with PDF data
+        """
+        # Get form and response
+        form = db.query(Form).filter(Form.id == form_id).first()
+        if not form:
+            raise ValueError(f"Form {form_id} not found")
+        
+        response = db.query(FormResponse).filter(
+            FormResponse.id == response_id,
+            FormResponse.form_id == form_id
+        ).first()
+        
+        if not response:
+            raise ValueError(f"Response {response_id} not found")
+        
+        # Create PDF in memory
+        buffer = io.BytesIO()
+        doc = SimpleDocTemplate(buffer, pagesize=letter)
+        
+        # Build content
+        story = []
+        styles = getSampleStyleSheet()
+        
+        # Title style
+        title_style = ParagraphStyle(
+            'CustomTitle',
+            parent=styles['Heading1'],
+            fontSize=24,
+            textColor=colors.HexColor('#9333EA'),
+            spaceAfter=30
+        )
+        
+        # Add title
+        story.append(Paragraph(form.title, title_style))
+        story.append(Spacer(1, 0.2 * inch))
+        
+        # Add metadata
+        metadata_data = [
+            ["Response ID:", str(response.id)],
+            ["Submitted:", response.submitted_at.strftime("%Y-%m-%d %H:%M:%S") if response.submitted_at else "N/A"],
+            ["Status:", response.status.title()],
+        ]
+        
+        if response.country:
+            metadata_data.append(["Location:", f"{response.city}, {response.country}" if response.city else response.country])
+        
+        metadata_table = Table(metadata_data, colWidths=[2*inch, 4*inch])
+        metadata_table.setStyle(TableStyle([
+            ('FONTNAME', (0, 0), (0, -1), 'Helvetica-Bold'),
+            ('FONTSIZE', (0, 0), (-1, -1), 10),
+            ('TEXTCOLOR', (0, 0), (0, -1), colors.HexColor('#6B7280')),
+            ('ALIGN', (0, 0), (0, -1), 'RIGHT'),
+            ('VALIGN', (0, 0), (-1, -1), 'TOP'),
+            ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
+        ]))
+        
+        story.append(metadata_table)
+        story.append(Spacer(1, 0.4 * inch))
+        
+        # Add divider
+        story.append(Paragraph("<hr width='100%'/>", styles['Normal']))
+        story.append(Spacer(1, 0.3 * inch))
+        
+        # Create answer map
+        answer_map = {
+            answer.form_question_id: answer.answer_value
+            for answer in response.answers
+        }
+        
+        # Add questions and answers
+        question_style = ParagraphStyle(
+            'Question',
+            parent=styles['Heading3'],
+            fontSize=12,
+            textColor=colors.HexColor('#1F2937'),
+            spaceAfter=6
+        )
+        
+        answer_style = ParagraphStyle(
+            'Answer',
+            parent=styles['Normal'],
+            fontSize=11,
+            textColor=colors.HexColor('#4B5563'),
+            leftIndent=20,
+            spaceAfter=20
+        )
+        
+        for idx, question in enumerate(sorted(form.questions, key=lambda q: q.question_order), 1):
+            # Question text
+            question_text = f"<b>{idx}. {question.question_text}</b>"
+            if question.required:
+                question_text += " <font color='red'>*</font>"
+            
+            story.append(Paragraph(question_text, question_style))
+            
+            # Answer
+            answer_value = answer_map.get(question.id, {})
+            formatted_answer = self._format_answer_for_pdf(answer_value)
+            story.append(Paragraph(formatted_answer, answer_style))
+        
+        # Add footer
+        story.append(Spacer(1, 0.5 * inch))
+        footer_style = ParagraphStyle(
+            'Footer',
+            parent=styles['Normal'],
+            fontSize=8,
+            textColor=colors.HexColor('#9CA3AF'),
+            alignment=1  # Center
+        )
+        story.append(Paragraph(
+            f"Generated by AutoForm on {datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S')} UTC",
+            footer_style
+        ))
+        
+        # Build PDF
+        doc.build(story)
+        buffer.seek(0)
+        
+        return buffer
+    
+    def _format_answer_for_export(self, answer_value: Dict[str, Any]) -> str:
+        """Format answer value for CSV/Excel export"""
+        if not answer_value:
+            return ""
+        
+        # Text answer
+        if "text" in answer_value and answer_value["text"]:
+            return str(answer_value["text"])
+        
+        # Number answer
+        if "number" in answer_value and answer_value["number"] is not None:
+            return str(answer_value["number"])
+        
+        # Choices (multiple choice, checkboxes)
+        if "choices" in answer_value and answer_value["choices"]:
+            return ", ".join(answer_value["choices"])
+        
+        # Date
+        if "date" in answer_value and answer_value["date"]:
+            return str(answer_value["date"])
+        
+        # Rating
+        if "rating" in answer_value and answer_value["rating"] is not None:
+            return str(answer_value["rating"])
+        
+        # Matrix answers
+        if "matrix_answers" in answer_value and answer_value["matrix_answers"]:
+            matrix_str = "; ".join([
+                f"{row}: {col}" for row, col in answer_value["matrix_answers"].items()
+            ])
+            return matrix_str
+        
+        # Ranked items
+        if "ranked_items" in answer_value and answer_value["ranked_items"]:
+            return ", ".join(answer_value["ranked_items"])
+        
+        # File upload
+        if "file_url" in answer_value and answer_value["file_url"]:
+            return answer_value["file_url"]
+        
+        # Wallet address
+        if "wallet_address" in answer_value and answer_value["wallet_address"]:
+            return answer_value["wallet_address"]
+        
+        # Signature
+        if "signature" in answer_value and answer_value["signature"]:
+            return "[Signature provided]"
+        
+        # Fallback: JSON dump
+        return json.dumps(answer_value)
+    
+    def _format_answer_for_pdf(self, answer_value: Dict[str, Any]) -> str:
+        """Format answer value for PDF display"""
+        if not answer_value:
+            return "<i>No answer provided</i>"
+        
+        formatted = self._format_answer_for_export(answer_value)
+        
+        if not formatted:
+            return "<i>No answer provided</i>"
+        
+        # Escape HTML special characters for ReportLab
+        formatted = formatted.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+        
+        return formatted
+
+
+# Singleton instance
+export_service = ExportService()

app/services/form_creator.py

@@ -0,0 +1,382 @@
+"""
+Form Creator Module
+===================
+
+This module integrates with DSPy to generate form structures from natural language queries.
+Uses the new FormGenerationModule architecture.
+"""
+
+import json
+import logging
+import os
+from typing import Dict, Any, List, Tuple
+from .agents import FormGenerationModule, FormChatFunction
+import dspy
+
+logger = logging.getLogger(__name__)
+
+
+# Validation metrics for signature outputs
+def validate_form_plan(form_result: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """
+    Validate that the form plan from FormPlannerSignature is complete.
+    
+    Returns:
+        tuple: (is_valid, error_messages)
+    """
+    errors = []
+    
+    # Check required fields
+    if not form_result.get("title"):
+        errors.append("Missing required field: title")
+    
+    if not form_result.get("components"):
+        errors.append("Missing required field: components (must have at least one)")
+    elif not isinstance(form_result.get("components"), list):
+        errors.append("Field 'components' must be a list")
+    elif len(form_result.get("components")) == 0:
+        errors.append("Components list is empty (must have at least one)")
+    
+    # Validate each component has required fields
+    components = form_result.get("components", [])
+    for idx, comp in enumerate(components):
+        if not comp.get("component_id"):
+            errors.append(f"Component {idx}: missing component_id")
+        if not comp.get("question_type"):
+            errors.append(f"Component {idx}: missing question_type")
+        if not comp.get("question_text"):
+            errors.append(f"Component {idx}: missing question_text")
+        
+        # Validate question type
+        valid_types = [
+            "short_answer", "long_answer", "multiple_choice", "checkboxes",
+            "dropdown", "multi_select", "number", "email", "phone", "link",
+            "file_upload", "date", "time", "linear_scale", "matrix", "rating",
+            "payment", "signature", "ranking", "wallet_connect"
+        ]
+        if comp.get("question_type") not in valid_types:
+            errors.append(f"Component {idx}: invalid question_type '{comp.get('question_type')}'")
+    
+    # Validate conditional logic references valid components
+    component_ids = {comp.get("component_id") for comp in components}
+    conditional_logic = form_result.get("conditional_logic", [])
+    
+    for idx, rule in enumerate(conditional_logic):
+        trigger_id = rule.get("trigger_component_id")
+        target_id = rule.get("target_component_id")
+        
+        if trigger_id not in component_ids:
+            errors.append(f"Conditional rule {idx}: invalid trigger_component_id '{trigger_id}'")
+        if target_id not in component_ids:
+            errors.append(f"Conditional rule {idx}: invalid target_component_id '{target_id}'")
+        
+        valid_conditions = ["equals", "not_equals", "contains", "not_contains", "greater_than", "less_than", "is_empty", "is_not_empty"]
+        if rule.get("condition_type") not in valid_conditions:
+            errors.append(f"Conditional rule {idx}: invalid condition_type '{rule.get('condition_type')}'")
+        
+        if rule.get("action") not in ["show", "hide"]:
+            errors.append(f"Conditional rule {idx}: invalid action '{rule.get('action')}'")
+    
+    is_valid = len(errors) == 0
+    return is_valid, errors
+
+
+def validate_component_settings(question_type: str, settings: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """
+    Validate that component settings match the question type requirements.
+    
+    Returns:
+        tuple: (is_valid, error_messages)
+    """
+    errors = []
+    
+    # Check type-specific required settings
+    if question_type in ["multiple_choice", "checkboxes", "dropdown", "multi_select"]:
+        if not settings.get("choices"):
+            errors.append(f"Question type '{question_type}' requires 'choices' in settings")
+        elif not isinstance(settings.get("choices"), list) or len(settings.get("choices")) < 2:
+            errors.append(f"Question type '{question_type}' requires at least 2 choices")
+    
+    if question_type == "linear_scale":
+        if "min_value" not in settings or "max_value" not in settings:
+            errors.append(f"Question type 'linear_scale' requires 'min_value' and 'max_value' in settings")
+    
+    if question_type == "matrix":
+        if not settings.get("rows") or not settings.get("columns"):
+            errors.append(f"Question type 'matrix' requires 'rows' and 'columns' in settings")
+    
+    if question_type == "ranking":
+        if not settings.get("ranking_items") or len(settings.get("ranking_items", [])) < 2:
+            errors.append(f"Question type 'ranking' requires at least 2 'ranking_items' in settings")
+    
+    if question_type == "payment":
+        if "payment_amount" not in settings:
+            errors.append(f"Question type 'payment' requires 'payment_amount' in settings")
+    
+    is_valid = len(errors) == 0
+    return is_valid, errors
+
+
+async def generate_form_spec(
+    user_query: str,
+    user_id: int = None
+) -> Tuple[Dict[str, Any], List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """
+    Generate form specification based on the user's query using FormGenerationModule.
+    
+    Args:
+        user_query: Natural language description of the form needed
+        user_id: User ID for context
+        
+    Returns:
+        tuple: (form_data, questions_list, conditional_rules_list)
+            - form_data: Dict with title, description, settings
+            - questions_list: List of question dicts with type, text, options, etc.
+            - conditional_rules_list: List of conditional logic rules
+    """
+    try:
+        # Configure DSPy with OpenAI
+        api_key = os.getenv('OPENAI_API_KEY')
+        if not api_key:
+            raise ValueError("OPENAI_API_KEY environment variable not set")
+        
+        # Initialize FormGenerationModule
+        generator = FormGenerationModule()
+        
+        # Generate form structure
+        logger.info(f"Generating form for query: {user_query}")
+        form_result = await generator.aforward(user_query=user_query)
+        
+        # Check for error in result
+        if isinstance(form_result, dict) and 'error' in form_result:
+            logger.error(f"Form generation error: {form_result['error']}")
+            raise Exception(form_result['error'])
+        
+        # VALIDATION METRIC: Validate form plan structure
+        is_valid, validation_errors = validate_form_plan(form_result)
+        if not is_valid:
+            logger.error(f"Form plan validation failed: {validation_errors}")
+            raise Exception(f"Invalid form plan: {'; '.join(validation_errors)}")
+        
+        # Extract form metadata
+        form_data = {
+            "title": form_result.get("title", "New Form"),
+            "description": form_result.get("description", ""),
+            "settings": form_result.get("settings", {
+                "background_color": "#ffffff",
+                "text_color": "#000000",
+                "accent_color": "#9333ea",
+                "submit_button_text": form_result.get("submit_button_text", "Submit"),
+                "show_progress_bar": True
+            })
+        }
+        
+        # Transform components to questions_list
+        # Components use component_id, but database uses question_order (0-indexed)
+        components = form_result.get("components", [])
+        questions_list = []
+        component_id_to_order = {}  # Map component_id to question_order
+        
+        for idx, component in enumerate(components):
+            component_id = component.get("component_id", f"comp_{idx + 1}")
+            component_id_to_order[component_id] = idx
+            
+            # Map component structure to question structure
+            question_type = component.get("question_type", "short_answer")
+            settings = component.get("settings", {})
+            
+            # FIX: Handle AI generating numbers instead of arrays for matrix/ranking
+            # THIS MUST HAPPEN BEFORE VALIDATION
+            if question_type == "matrix":
+                # Ensure settings dict exists
+                if not isinstance(settings, dict):
+                    settings = {}
+                
+                # Convert rows: handle int, float, None, or non-list
+                rows_value = settings.get("rows")
+                if isinstance(rows_value, (int, float)):
+                    num_rows = max(1, int(rows_value))
+                    settings["rows"] = [f"Row {i+1}" for i in range(num_rows)]
+                    logger.info(f"Converted matrix rows from {num_rows} to array of {num_rows} strings")
+                elif not isinstance(rows_value, list):
+                    settings["rows"] = ["Row 1", "Row 2", "Row 3"]
+                    logger.info(f"Set default matrix rows (was: {type(rows_value).__name__})")
+                
+                # Convert columns: handle int, float, None, or non-list
+                columns_value = settings.get("columns")
+                if isinstance(columns_value, (int, float)):
+                    num_cols = max(1, int(columns_value))
+                    settings["columns"] = [f"Column {i+1}" for i in range(num_cols)]
+                    logger.info(f"Converted matrix columns from {num_cols} to array of {num_cols} strings")
+                elif not isinstance(columns_value, list):
+                    settings["columns"] = ["Column 1", "Column 2", "Column 3"]
+                    logger.info(f"Set default matrix columns (was: {type(columns_value).__name__})")
+            
+            if question_type == "ranking":
+                # Ensure settings dict exists
+                if not isinstance(settings, dict):
+                    settings = {}
+                
+                # Convert ranking_items: handle int, float, None, or non-list
+                ranking_value = settings.get("ranking_items")
+                if isinstance(ranking_value, (int, float)):
+                    num_items = max(2, int(ranking_value))
+                    settings["ranking_items"] = [f"Item {i+1}" for i in range(num_items)]
+                    logger.info(f"Converted ranking_items from {num_items} to array of {num_items} strings")
+                elif not isinstance(ranking_value, list):
+                    settings["ranking_items"] = ["Item 1", "Item 2", "Item 3"]
+                    logger.info(f"Set default ranking_items (was: {type(ranking_value).__name__})")
+            
+            # VALIDATION METRIC: Validate component settings
+            settings_valid, settings_errors = validate_component_settings(question_type, settings)
+            if not settings_valid:
+                logger.warning(f"Component {idx} settings validation failed: {settings_errors}")
+                # Add defaults for failed settings instead of rejecting
+                if question_type in ["multiple_choice", "checkboxes", "dropdown", "multi_select"] and not settings.get("choices"):
+                    settings["choices"] = ["Option 1", "Option 2", "Option 3"]
+                if question_type == "linear_scale" and ("min_value" not in settings or "max_value" not in settings):
+                    settings["min_value"] = 1
+                    settings["max_value"] = 10
+            
+            question_data = {
+                "question_order": component.get("order", idx),
+                "question_type": question_type,
+                "question_text": component.get("question_text", f"Question {idx + 1}"),
+                "description": component.get("description"),
+                "required": component.get("required", False),
+                "settings": settings
+            }
+            
+            # Add validation rules if present
+            if "validation_rules" in component:
+                question_data["settings"]["validation_rules"] = component["validation_rules"]
+            
+            questions_list.append(question_data)
+        
+        # Transform conditional logic: map component_ids to question indices
+        conditional_rules = []
+        raw_rules = form_result.get("conditional_logic", [])
+        
+        for rule in raw_rules:
+            trigger_id = rule.get("trigger_component_id")
+            target_id = rule.get("target_component_id")
+            
+            # Map component IDs to question indices
+            if trigger_id in component_id_to_order and target_id in component_id_to_order:
+                conditional_rule = {
+                    "trigger_question_index": component_id_to_order[trigger_id],
+                    "target_question_index": component_id_to_order[target_id],
+                    "condition_type": rule.get("condition_type", "equals"),
+                    "condition_value": rule.get("condition_value"),
+                    "action": rule.get("action", "show")
+                }
+                conditional_rules.append(conditional_rule)
+            else:
+                logger.warning(f"Skipping rule with invalid component IDs: {trigger_id} -> {target_id}")
+        
+        # VALIDATION METRIC: Ensure output is complete and serializable
+        try:
+            # Test JSON serialization to ensure frontend can render
+            json.dumps({
+                "form_data": form_data,
+                "questions": questions_list,
+                "rules": conditional_rules
+            })
+            logger.info(f"✓ Form generation complete: {len(questions_list)} questions, {len(conditional_rules)} rules")
+            logger.info(f"✓ Validation passed: Complete closed JSON ready for frontend")
+        except Exception as e:
+            logger.error(f"✗ JSON serialization failed: {e}")
+            raise Exception(f"Form generation produced non-serializable output: {e}")
+        
+        return form_data, questions_list, conditional_rules
+        
+    except Exception as e:
+        logger.error(f"Form generation failed: {e}", exc_info=True)
+        # Return minimal valid form structure
+        return {
+            "title": "New Form",
+            "description": user_query,
+            "settings": {
+                "background_color": "#ffffff",
+                "text_color": "#000000",
+                "accent_color": "#9333ea",
+                "submit_button_text": "Submit",
+                "show_progress_bar": True
+            }
+        }, [], []
+
+
+async def edit_form_spec(
+    current_form: Dict[str, Any],
+    edit_request: str,
+    user_id: int = None
+) -> Dict[str, Any]:
+    """
+    Edit an existing form based on user request using FormChatFunction.
+    
+    Args:
+        current_form: Current form structure with questions
+        edit_request: Natural language edit request
+        user_id: User ID for context
+        
+    Returns:
+        dict: Updated form structure or changes to apply
+    """
+    try:
+        # Initialize FormChatFunction
+        chat_function = FormChatFunction()
+        
+        # Prepare form context
+        form_context = json.dumps({
+            "title": current_form.get("title"),
+            "description": current_form.get("description"),
+            "components": current_form.get("questions", []),  # Pass as components for consistency
+            "settings": current_form.get("settings", {})
+        })
+        
+        # Process chat request
+        result = await chat_function.aforward(
+            user_query=edit_request,
+            form_context=form_context,
+            current_form=current_form
+        )
+        
+        # Extract response
+        route = result.get('route')
+        response = result.get('response')
+        
+        logger.info(f"Form edit route: {route.query_type if hasattr(route, 'query_type') else 'unknown'}")
+        
+        return {
+            "route": route.query_type if hasattr(route, 'query_type') else 'unknown',
+            "response": response,
+            "changes_made": getattr(response, 'changes_made', None) if hasattr(response, 'changes_made') else None
+        }
+            
+    except Exception as e:
+        logger.error(f"Form edit failed: {e}", exc_info=True)
+        return {
+            "route": "error",
+            "response": str(e),
+            "changes_made": None
+        }
+
+
+def validate_question_type(question_type: str) -> bool:
+    """Validate that question type is supported"""
+    valid_types = [
+        "short_answer", "long_answer", "multiple_choice", "checkboxes",
+        "dropdown", "multi_select", "number", "email", "phone", "link",
+        "file_upload", "date", "time", "linear_scale", "matrix", "rating",
+        "payment", "signature", "ranking", "wallet_connect", "button"
+    ]
+    return question_type in valid_types
+
+
+def validate_condition_type(condition_type: str) -> bool:
+    """Validate that condition type is supported"""
+    valid_conditions = [
+        "equals", "not_equals", "contains", "not_contains",
+        "greater_than", "less_than", "is_empty", "is_not_empty"
+    ]
+    return condition_type in valid_conditions

app/services/plan_service.py

@@ -0,0 +1,321 @@
+"""
+Subscription plan service for managing pricing tiers
+"""
+from sqlalchemy.orm import Session
+from typing import Optional, List, Dict, Any
+from decimal import Decimal
+import logging
+import os
+
+from ..models import SubscriptionPlan
+
+logger = logging.getLogger(__name__)
+
+
+class PlanService:
+    """Service for managing subscription plans"""
+    
+    def get_all_active_plans(self, db: Session) -> List[SubscriptionPlan]:
+        """
+        Get all active subscription plans
+        
+        Args:
+            db: Database session
+            
+        Returns:
+            List of active SubscriptionPlan objects, sorted by sort_order
+        """
+        return (
+            db.query(SubscriptionPlan)
+            .filter(SubscriptionPlan.is_active == True)
+            .order_by(SubscriptionPlan.sort_order)
+            .all()
+        )
+    
+    def get_plan_by_id(self, db: Session, plan_id: int) -> Optional[SubscriptionPlan]:
+        """
+        Get a specific plan by ID
+        
+        Args:
+            db: Database session
+            plan_id: Plan ID
+            
+        Returns:
+            SubscriptionPlan object or None if not found
+        """
+        return db.query(SubscriptionPlan).filter(SubscriptionPlan.id == plan_id).first()
+    
+    def get_plan_by_name(self, db: Session, name: str) -> Optional[SubscriptionPlan]:
+        """
+        Get a plan by name
+        
+        Args:
+            db: Database session
+            name: Plan name
+            
+        Returns:
+            SubscriptionPlan object or None if not found
+        """
+        return db.query(SubscriptionPlan).filter(SubscriptionPlan.name == name).first()
+    
+    def get_plan_by_stripe_price_id(self, db: Session, stripe_price_id: str) -> Optional[SubscriptionPlan]:
+        """
+        Get a plan by Stripe price ID (checks both monthly and yearly)
+        
+        Args:
+            db: Database session
+            stripe_price_id: Stripe price ID
+            
+        Returns:
+            SubscriptionPlan object or None if not found
+        """
+        return db.query(SubscriptionPlan).filter(
+            (SubscriptionPlan.stripe_price_id == stripe_price_id) |
+            (SubscriptionPlan.stripe_price_id_monthly == stripe_price_id) |
+            (SubscriptionPlan.stripe_price_id_yearly == stripe_price_id)
+        ).first()
+    
+    def create_plan(
+        self,
+        db: Session,
+        name: str,
+        price_monthly: Decimal,
+        credits_per_month: int,
+        credits_per_analyze: int = 5,
+        credits_per_edit: int = 2,
+        stripe_price_id: Optional[str] = None,
+        stripe_price_id_monthly: Optional[str] = None,
+        stripe_price_id_yearly: Optional[str] = None,
+        price_yearly: Optional[Decimal] = None,
+        stripe_product_id: Optional[str] = None,
+        features: Optional[Dict[str, Any]] = None,
+        sort_order: int = 0
+    ) -> SubscriptionPlan:
+        """
+        Create a new subscription plan
+        
+        Args:
+            db: Database session
+            name: Plan name
+            price_monthly: Monthly price
+            credits_per_month: Monthly credit allocation
+            credits_per_analyze: Credits per dashboard creation
+            credits_per_edit: Credits per edit operation
+            stripe_price_id: Legacy Stripe price ID (for backward compatibility)
+            stripe_price_id_monthly: Stripe monthly price ID
+            stripe_price_id_yearly: Stripe yearly price ID
+            price_yearly: Yearly price
+            stripe_product_id: Stripe product ID
+            features: Optional feature dictionary
+            sort_order: Display order
+            
+        Returns:
+            Created SubscriptionPlan object
+        """
+        # Use legacy stripe_price_id as monthly if monthly not provided
+        if stripe_price_id_monthly is None and stripe_price_id is not None:
+            stripe_price_id_monthly = stripe_price_id
+        
+        plan = SubscriptionPlan(
+            name=name,
+            price_monthly=price_monthly,
+            price_yearly=price_yearly,
+            credits_per_month=credits_per_month,
+            credits_per_analyze=credits_per_analyze,
+            credits_per_edit=credits_per_edit,
+            stripe_price_id=stripe_price_id,  # Keep for backward compatibility
+            stripe_price_id_monthly=stripe_price_id_monthly,
+            stripe_price_id_yearly=stripe_price_id_yearly,
+            stripe_product_id=stripe_product_id,
+            features=features or {},
+            sort_order=sort_order,
+            is_active=True
+        )
+        db.add(plan)
+        db.commit()
+        db.refresh(plan)
+        logger.info(f"Created plan: {name} (${price_monthly}/month, {credits_per_month} credits)")
+        return plan
+    
+    def update_plan(
+        self,
+        db: Session,
+        plan_id: int,
+        **kwargs
+    ) -> Optional[SubscriptionPlan]:
+        """
+        Update a subscription plan
+        
+        Args:
+            db: Database session
+            plan_id: Plan ID
+            **kwargs: Fields to update
+            
+        Returns:
+            Updated SubscriptionPlan object or None if not found
+        """
+        plan = self.get_plan_by_id(db, plan_id)
+        if not plan:
+            return None
+        
+        for key, value in kwargs.items():
+            if hasattr(plan, key):
+                setattr(plan, key, value)
+        
+        db.commit()
+        db.refresh(plan)
+        logger.info(f"Updated plan {plan_id}: {plan.name}")
+        return plan
+    
+    def deactivate_plan(self, db: Session, plan_id: int) -> bool:
+        """
+        Deactivate a plan (soft delete)
+        
+        Args:
+            db: Database session
+            plan_id: Plan ID
+            
+        Returns:
+            True if successful, False if plan not found
+        """
+        plan = self.get_plan_by_id(db, plan_id)
+        if not plan:
+            return False
+        
+        plan.is_active = False
+        db.commit()
+        logger.info(f"Deactivated plan {plan_id}: {plan.name}")
+        return True
+    
+    def initialize_default_plans(self, db: Session, force: bool = False) -> List[SubscriptionPlan]:
+        """
+        Initialize default subscription plans (Free, Pro, Ultra)
+        Idempotent - won't create duplicates unless force=True
+        
+        Args:
+            db: Database session
+            force: If True, recreate plans even if they exist
+            
+        Returns:
+            List of created/existing plans
+        """
+        plans = []
+        
+        # Default plan configurations
+        default_plans = [
+            {
+                "name": "Free",
+                "price_monthly": Decimal("0.00"),
+                "price_yearly": Decimal("0.00"),
+                "credits_per_month": 25,
+                "credits_per_analyze": 5,
+                "credits_per_edit": 2,
+                "stripe_price_id": os.getenv("STRIPE_FREE_PRICE_MONTHLY_ID"),  # Legacy support
+                "stripe_price_id_monthly": os.getenv("STRIPE_FREE_PRICE_MONTHLY_ID"),
+                "stripe_price_id_yearly": os.getenv("STRIPE_FREE_PRICE_YEARLY_ID"),
+                "stripe_product_id": os.getenv("STRIPE_FREE_PRODUCT_ID"),
+                "features": {
+                    "max_datasets": 3,
+                    "max_file_size_mb": 10,
+                    "export_formats": ["png", "csv"]
+                },
+                "sort_order": 0
+            },
+            {
+                "name": "Pro",
+                "price_monthly": Decimal("20.00"),
+                "price_yearly": Decimal("192.00"),  # $20 * 12 * 0.8 (20% discount)
+                "credits_per_month": 500,
+                "credits_per_analyze": 5,
+                "credits_per_edit": 2,
+                "stripe_price_id": os.getenv("STRIPE_PRO_PRICE_MONTHLY_ID"),  # Legacy support
+                "stripe_price_id_monthly": os.getenv("STRIPE_PRO_PRICE_MONTHLY_ID"),
+                "stripe_price_id_yearly": os.getenv("STRIPE_PRO_PRICE_YEARLY_ID"),
+                "stripe_product_id": os.getenv("STRIPE_PRO_PRODUCT_ID"),
+                "features": {
+                    "max_datasets": 50,
+                    "max_file_size_mb": 100,
+                    "export_formats": ["png", "csv", "pdf", "xlsx"],
+                    "priority_support": True
+                },
+                "sort_order": 1
+            },
+            {
+                "name": "Ultra",
+                "price_monthly": Decimal("30"),
+                "price_yearly": Decimal("288"),  # $29.99 * 12 * 0.8 (20% discount)
+                "credits_per_month": 1000,
+                "credits_per_analyze": 5,
+                "credits_per_edit": 2,
+                "stripe_price_id": os.getenv("STRIPE_ULTRA_PRICE_MONTHLY_ID"),  # Legacy support
+                "stripe_price_id_monthly": os.getenv("STRIPE_ULTRA_PRICE_MONTHLY_ID"),
+                "stripe_price_id_yearly": os.getenv("STRIPE_ULTRA_PRICE_YEARLY_ID"),
+                "stripe_product_id": os.getenv("STRIPE_ULTRA_PRODUCT_ID"),
+                "features": {
+                    "max_datasets": -1,  # Unlimited
+                    "max_file_size_mb": 500,
+                    "export_formats": ["png", "csv", "pdf", "xlsx", "json"],
+                    "priority_support": True,
+                    "custom_branding": True,
+                    "api_access": True
+                },
+                "sort_order": 2
+            }
+        ]
+        
+        for plan_config in default_plans:
+            existing = self.get_plan_by_name(db, plan_config["name"])
+            
+            if existing and not force:
+                logger.info(f"Plan '{plan_config['name']}' already exists, skipping")
+                plans.append(existing)
+            elif existing and force:
+                # Update existing plan
+                for key, value in plan_config.items():
+                    if key != "name":  # Don't update name
+                        setattr(existing, key, value)
+                db.commit()
+                db.refresh(existing)
+                logger.info(f"Updated existing plan: {plan_config['name']}")
+                plans.append(existing)
+            else:
+                # Create new plan
+                plan = self.create_plan(db, **plan_config)
+                plans.append(plan)
+        
+        return plans
+    
+    def get_plan_info(self, db: Session, plan_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Get comprehensive plan information
+        
+        Args:
+            db: Database session
+            plan_id: Plan ID
+            
+        Returns:
+            Dictionary with plan details or None if not found
+        """
+        plan = self.get_plan_by_id(db, plan_id)
+        if not plan:
+            return None
+        
+        return {
+            "id": plan.id,
+            "name": plan.name,
+            "price_monthly": float(plan.price_monthly),
+            "price_yearly": float(plan.price_yearly) if plan.price_yearly else None,
+            "credits_per_month": plan.credits_per_month,
+            "credits_per_analyze": plan.credits_per_analyze,
+            "credits_per_edit": plan.credits_per_edit,
+            "features": plan.features or {},
+            "stripe_price_id": plan.stripe_price_id,  # Legacy
+            "stripe_price_id_monthly": plan.stripe_price_id_monthly,
+            "stripe_price_id_yearly": plan.stripe_price_id_yearly,
+            "is_active": plan.is_active
+        }
+
+
+# Singleton instance
+plan_service = PlanService()
+