# Wireframe Persistence System

This document explains the new wireframe persistence system that automatically saves and loads wireframes to prevent data loss on page refresh.

## Overview

The wireframe persistence system consists of:
1. **PostgreSQL Database Schema** - Stores wireframes, elements, and versions
2. **Backend API Endpoints** - Handle CRUD operations for wireframes
3. **Frontend Auto-save** - Automatically saves wireframes every 30 seconds
4. **Manual Save Controls** - Manual save button and keyboard shortcuts

## Database Schema

### Tables Created

1. **`wireframes`** - Main wireframe metadata
   - `id` - Unique identifier
   - `user_id` - Reference to user
   - `project_id` - Optional project reference
   - `name` - Wireframe name
   - `description` - Wireframe description
   - `device_type` - mobile/tablet/desktop
   - `dimensions` - Width and height
   - `metadata` - Additional data (prompt, generation settings)
   - `is_active` - Soft delete flag

2. **`wireframe_elements`** - Individual shapes/elements
   - `id` - Element identifier
   - `wireframe_id` - Reference to wireframe
   - `element_type` - Type of element (shape, text, image, group)
   - `element_data` - Complete TLDraw element data
   - `position` - X, Y coordinates
   - `size` - Width and height
   - `style` - Color, stroke width, fill
   - `parent_id` - For grouped elements
   - `z_index` - Layering order

3. **`wireframe_versions`** - Version control
   - `id` - Version identifier
   - `wireframe_id` - Reference to wireframe
   - `version_number` - Sequential version number
   - `version_name` - Human-readable version name
   - `snapshot_data` - Complete wireframe state at version
   - `created_by` - User who created version

## Setup Instructions

### 1. Database Setup

```bash
# Install PostgreSQL dependencies
cd backend
pip install -r requirements.txt

# Copy and configure environment variables
cp env.example .env
# Edit .env with your database credentials

# Run database setup script
python setup_database.py
```

### 2. Environment Variables

Create a `.env` file in the `backend/` directory:

```env
# Claude API Configuration
CLAUDE_API_KEY=your-claude-api-key-here

# Flask Configuration
FLASK_ENV=development
PORT=5000

# Database Configuration
DB_HOST=localhost
DB_NAME=tech4biz_wireframes
DB_USER=postgres
DB_PASSWORD=your-database-password
DB_PORT=5432
```

### 3. Start Backend

```bash
cd backend
python app.py
```

## API Endpoints

### Save Wireframe
```http
POST /api/wireframes
Content-Type: application/json

{
  "wireframe": {
    "name": "Wireframe Name",
    "description": "Description",
    "device_type": "desktop",
    "dimensions": {"width": 1440, "height": 1024},
    "metadata": {"prompt": "User prompt"}
  },
  "elements": [...],
  "user_id": "user-uuid",
  "project_id": "project-uuid"
}
```

### Get Wireframe
```http
GET /api/wireframes/{wireframe_id}
```

### Update Wireframe
```http
PUT /api/wireframes/{wireframe_id}
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated Description",
  "elements": [...],
  "user_id": "user-uuid"
}
```

### Delete Wireframe
```http
DELETE /api/wireframes/{wireframe_id}
```

### Get User Wireframes
```http
GET /api/wireframes/user/{user_id}
```

## Frontend Features

### Auto-save
- Wireframes are automatically saved every 30 seconds
- Auto-save can be toggled on/off
- Last save time is displayed

### Manual Save
- Manual save button in top-right corner
- Keyboard shortcut: `Ctrl+S` (or `Cmd+S` on Mac)

### Save Status
- Green indicator shows last save time
- Auto-save toggle checkbox
- Manual save button

## Usage

### Creating Wireframes
1. Generate wireframe using AI prompt
2. Wireframe is automatically saved to database
3. Continue editing - changes are auto-saved

### Loading Wireframes
1. Wireframes are automatically loaded on page refresh
2. Use API endpoints to load specific wireframes
3. Version history is maintained

### Keyboard Shortcuts
- `Ctrl+S` - Save wireframe
- `Ctrl+K` - Trigger prompt input (planned)
- `Ctrl+Delete` - Clear canvas

## Data Flow

1. **User creates/edits wireframe** → TLDraw editor
2. **Auto-save triggers** → Every 30 seconds
3. **Data serialized** → Convert TLDraw shapes to database format
4. **API call** → Send to backend
5. **Database storage** → Save to PostgreSQL
6. **Version created** → New version entry for tracking

## Benefits

- **No data loss** on page refresh
- **Automatic backup** every 30 seconds
- **Version control** for wireframe changes
- **User isolation** - each user sees only their wireframes
- **Project organization** - wireframes can be grouped by project
- **Scalable storage** - PostgreSQL handles large wireframes efficiently

## Troubleshooting

### Database Connection Issues
- Check PostgreSQL is running
- Verify database credentials in `.env`
- Ensure database `tech4biz_wireframes` exists

### Auto-save Not Working
- Check browser console for errors
- Verify backend is running on correct port
- Check network tab for failed API calls

### Wireframes Not Loading
- Check if wireframe exists in database
- Verify user_id matches
- Check API endpoint responses

## Future Enhancements

- **Real-time collaboration** - Multiple users editing same wireframe
- **Export formats** - PNG, PDF, HTML export
- **Template library** - Reusable wireframe components
- **Advanced versioning** - Branch and merge wireframes
- **Search and filtering** - Find wireframes by content or metadata