codenuk_backend_mine/services/ai-mockup-service/docs/WIREFRAME_PERSISTENCE_README.md

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

# 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:

# 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

cd backend
python app.py

API Endpoints

Save Wireframe

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

GET /api/wireframes/{wireframe_id}

Update Wireframe

PUT /api/wireframes/{wireframe_id}
Content-Type: application/json

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

Delete Wireframe

DELETE /api/wireframes/{wireframe_id}

Get User Wireframes

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