automaker/reference/prompts/app_spec.txt

<project_specification>
  <project_name>AI Image Design Studio - Creative AI Image Generation Platform</project_name>

  <overview>
    Build a professional AI image generation and iteration platform that integrates with fal.ai and multiple AI image
    generation models. The application provides a powerful dashboard for creating, iterating, and managing AI-generated
    images with advanced prompt engineering, variation generation, upscaling, and project organization capabilities.
    Features include a beautiful landing page, user authentication, project-based workflows, image history, prompt
    library, batch generation, and comprehensive image management tools.
  </overview>

  <technology_stack>
    <api_key>
      key is in .env file as FAL_KEY
    </api_key>
    <frontend>
      <framework>Next.js 16 (React-based framework with App Router and SSR)</framework>
      <styling>Tailwind CSS with shadcn/ui components</styling>
      <state_management>TanStack Query for server state, React hooks for local state</state_management>
      <routing>Next.js App Router (built into Next.js 16)</routing>
      <image_display>React Image Gallery, image zoom, lightbox</image_display>
      <forms>React Hook Form with Zod validation</forms>
      <component_library>shadcn</component_library>
      <drag_drop>dnd-kit for drag and drop functionality</drag_drop>
    </frontend>
    <backend>
      <framework>Next.js 16 API routes (Route Handlers)</framework>
      <database>PostgreSQL 16+</database>
      <orm>Drizzle ORM with migrations</orm>
      <ai_integration>fal.ai SDK for image generation (Flux, Stable Diffusion, etc.)</ai_integration>
      <file_storage>S3-compatible storage for generated images (locally use a locally running s3 service in docker)</file_storage>
      <authentication>Better Auth</authentication>
    </backend>
    <deployment>
      <containerization>Docker Compose for local development</containerization>
      <database_service>PostgreSQL container with persistent volume</database_service>
      <environment>Environment variables for API keys and configuration</environment>
    </deployment>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      - Docker and Docker Compose installed
      - Node.js 22+ installed
      - pnpm package manager
      - FAL_API_KEY environment variable configured
      - DATABASE_URL for PostgreSQL connection
      - docker-compose.yml for easy local database setup
    </environment_setup>
  </prerequisites>

  <core_features>
    <landing_page>
      - Hero section with stunning AI-generated image showcase
      - Animated gradient backgrounds and smooth transitions
      - Feature highlights (multiple models, iterations, projects)
      - Model showcase carousel (Flux, SDXL, etc.)
      - Example gallery of generated images
      - Pricing tiers (if applicable) or usage info
      - Call-to-action buttons (Sign Up, Try Demo)
      - Footer with links and social media
      - Responsive design with mobile optimization
      - Testimonials or use cases section
      - FAQ section about AI image generation
    </landing_page>

    <authentication>
      - User registration with email/password
      - Email verification flow
      - Login with session management
      - OAuth providers (Google, GitHub optional)
      - Password reset functionality
      - Profile management
      - Avatar upload
      - Account settings
      - Two-factor authentication (optional)
      - Session timeout and security
    </authentication>

    <dashboard>
      - Overview cards (total images, credits used, projects)
      - Recent generations gallery
      - Quick generation shortcut
      - Model status indicators
      - Usage statistics chart
      - Favorite images grid
      - Recent projects list
      - Activity feed
      - Quick actions menu
      - Welcome onboarding for new users
    </dashboard>

    <image_generation>
      - Multi-model support via fal.ai:
        - Flux models (Flux Pro, Flux Dev, Flux Schnell)
        - Stable Diffusion XL and variants
        - Other fal.ai supported models
      - Prompt input with rich text editor
      - Negative prompt support
      - Image parameters panel:
        - Aspect ratio selector (1:1, 16:9, 9:16, 4:3, 3:4, custom)
        - Resolution/size selection
        - Number of images (1-4 per generation)
        - Seed control (for reproducibility)
        - Guidance scale/CFG scale
        - Steps/inference steps
        - Sampler selection
        - Style presets
      - Model-specific advanced settings
      - Real-time generation with progress indicator
      - Queue system for batch generations
      - Generation history sidebar
      - Save generation settings as presets
      - One-click regenerate with variations
    </image_generation>

    <image_iteration>
      - Image-to-image transformations
      - Variation generation (similar images with seed variation)
      - Inpainting/outpainting support
      - Prompt refinement suggestions
      - Parameter tweaking while viewing results
      - A/B testing different prompts
      - Remix previous generations
      - Style transfer
      - Upscaling (2x, 4x, 8x)
      - Background removal
      - Image editing tools integration
      - Comparison view (side-by-side)
      - Iteration history tree view
      - Quick iteration from any image
    </image_iteration>

    <project_management>
      - Create projects to organize generations
      - Project-level settings and defaults
      - Drag and drop images between projects
      - Project sharing (read-only links)
      - Project templates
      - Bulk operations (move, delete, export)
      - Project tags and categories
      - Project cover image selection
      - Project description and notes
      - Archive projects
      - Duplicate projects
      - Export entire project as ZIP
      - Project analytics (generations count, cost)
    </project_management>

    <image_gallery>
      - Grid view with responsive columns
      - Masonry layout option
      - List view with metadata
      - Image lightbox with zoom
      - Infinite scroll or pagination
      - Filter by:
        - Date range
        - Model used
        - Project
        - Tags
        - Favorites
        - Aspect ratio
        - Resolution
      - Sort by date, name, likes, model
      - Multi-select for bulk actions
      - Quick preview on hover
      - Image metadata display
      - Download original images
      - Share individual images
      - Add to collections
    </image_gallery>

    <prompt_engineering>
      - Prompt library with categories
      - Save favorite prompts
      - Prompt templates
      - Style modifiers quick-add buttons
      - Quality boosters (4k, detailed, masterpiece, etc.)
      - Artist style suggestions
      - Prompt weighting/emphasis syntax support
      - Prompt history tracking
      - Community prompt sharing (optional)
      - Import/export prompts
      - Prompt variations generator
      - Smart prompt suggestions based on model
      - Prompt strength visualization
    </prompt_engineering>

    <batch_generation>
      - Queue multiple prompts
      - Grid of variations (same prompt, different seeds)
      - Prompt list processing
      - CSV import for bulk prompts
      - Template-based generation (fill-in variables)
      - Scheduled generation
      - Priority queue management
      - Batch export functionality
      - Generation presets for batches
      - Progress tracking for batches
      - Pause/resume batch jobs
      - Estimated completion time
    </batch_generation>

    <image_management>
      - Favorites/starring system
      - Tagging and labeling
      - Collections/boards (like Pinterest)
      - Image rating system (1-5 stars)
      - Comments/notes on images
      - Image comparison tool
      - Duplicate detection
      - Storage usage tracking
      - Bulk download as ZIP
      - Image metadata export (JSON/CSV)
      - Image versioning
      - Trash/recycle bin (soft delete)
      - Auto-cleanup old images (optional)
    </image_management>

    <model_showcase>
      - Model comparison matrix
      - Model capabilities and best use cases
      - Sample images per model
      - Speed vs quality indicators
      - Cost per generation display
      - Model documentation links
      - Recommended settings per model
      - Model update notifications
      - New model announcements
      - Model performance stats
    </model_showcase>

    <credits_usage>
      - Credit balance display
      - Usage history and breakdown
      - Cost per generation tracking
      - Monthly usage charts
      - Credit purchase flow (if monetized)
      - Usage alerts and limits
      - Credit expiration notices
      - Refund/unused credits handling
      - Usage optimization tips
      - Model cost comparison
    </credits_usage>

    <collaboration>
      - Share projects with team members (mock or real)
      - Comment on images
      - Collaborative boards
      - Export for client review
      - Public gallery option
      - Embed images on websites
      - Share via direct link
      - Social media sharing
      - Team workspace (optional)
      - Permission levels (view/edit/admin)
    </collaboration>

    <advanced_features>
      - ControlNet integration (if fal.ai supports)
      - LoRA model support
      - Custom model fine-tuning (links to fal.ai)
      - IP adapter for style consistency
      - Multi-prompt composition
      - Prompt blending/interpolation
      - Animation generation (if supported)
      - Video-to-image frames
      - API key management for developers
      - Webhook notifications
      - CLI tool for power users
      - Shortcuts and keyboard navigation
    </advanced_features>

    <settings_preferences>
      - Theme (Light, Dark, Auto, Custom)
      - Default model selection
      - Default generation parameters
      - Auto-save settings
      - Gallery view preferences
      - Notification preferences
      - Privacy settings
      - Data retention policies
      - Export/import user data
      - Account deletion
      - Language selection
      - Timezone settings
      - Keyboard shortcuts customization
    </settings_preferences>

    <responsive_design>
      - Mobile-first approach
      - Touch-optimized controls
      - Responsive image grid
      - Mobile generation interface
      - Swipe gestures for gallery
      - Progressive Web App (PWA)
      - Offline capability for viewing saved images
      - Mobile-optimized forms
      - Tablet landscape optimization
    </responsive_design>

    <accessibility>
      - WCAG 2.1 AA compliance
      - Keyboard navigation
      - Screen reader support
      - Alt text for generated images
      - High contrast mode
      - Focus management
      - ARIA labels
      - Reduced motion support
      - Accessible color palette
    </accessibility>

    <performance>
      - Image lazy loading
      - Thumbnail generation
      - Progressive image loading
      - CDN integration for images
      - Optimistic UI updates
      - Request caching
      - Database query optimization
      - Image compression
      - WebP/AVIF format support
      - Background job processing
    </performance>
  </core_features>

  <database_schema>
    <tables>
      <users>
        - id (uuid, primary key)
        - email (unique)
        - password_hash
        - name
        - avatar_url
        - created_at
        - updated_at
        - last_login
        - email_verified
        - preferences (jsonb: theme, defaults, etc.)
        - credits_balance (integer)
        - subscription_tier
        - is_active
      </users>

      <sessions>
        - id (uuid, primary key)
        - user_id (references users)
        - token (unique)
        - expires_at
        - created_at
        - ip_address
        - user_agent
      </sessions>

      <projects>
        - id (uuid, primary key)
        - user_id (references users)
        - name
        - description
        - cover_image_id (references images)
        - settings (jsonb: default model, parameters)
        - tags (text array)
        - is_archived
        - is_public
        - created_at
        - updated_at
        - image_count (computed)
      </projects>

      <images>
        - id (uuid, primary key)
        - user_id (references users)
        - project_id (references projects, nullable)
        - file_path
        - file_url
        - thumbnail_url
        - width
        - height
        - file_size
        - format (png, jpg, webp)
        - prompt
        - negative_prompt
        - model_id
        - model_version
        - parameters (jsonb: seed, cfg, steps, etc.)
        - generation_time (seconds)
        - cost_credits
        - parent_image_id (for variations, references images)
        - is_favorite
        - rating (1-5)
        - tags (text array)
        - metadata (jsonb: additional info)
        - created_at
        - updated_at
        - deleted_at (soft delete)
      </images>

      <collections>
        - id (uuid, primary key)
        - user_id (references users)
        - name
        - description
        - cover_image_id (references images)
        - is_public
        - created_at
        - updated_at
      </collections>

      <collection_images>
        - id (uuid, primary key)
        - collection_id (references collections)
        - image_id (references images)
        - position (for ordering)
        - added_at
      </collection_images>

      <prompts>
        - id (uuid, primary key)
        - user_id (references users)
        - title
        - prompt_text
        - negative_prompt
        - category
        - tags (text array)
        - is_favorite
        - is_public
        - usage_count
        - created_at
        - updated_at
      </prompts>

      <generation_queue>
        - id (uuid, primary key)
        - user_id (references users)
        - project_id (references projects, nullable)
        - prompt
        - negative_prompt
        - model_id
        - parameters (jsonb)
        - status (pending, processing, completed, failed)
        - priority
        - fal_request_id
        - error_message
        - retry_count
        - created_at
        - started_at
        - completed_at
      </generation_queue>

      <models>
        - id (uuid, primary key)
        - fal_model_id
        - name
        - display_name
        - description
        - category (flux, stable-diffusion, etc.)
        - version
        - capabilities (jsonb: img2img, inpainting, etc.)
        - default_parameters (jsonb)
        - cost_per_generation
        - is_active
        - is_featured
        - created_at
        - updated_at
      </models>

      <usage_logs>
        - id (uuid, primary key)
        - user_id (references users)
        - image_id (references images, nullable)
        - action (generate, upscale, variation, etc.)
        - model_id
        - credits_used
        - generation_time
        - success
        - error_message
        - created_at
      </usage_logs>

      <shared_projects>
        - id (uuid, primary key)
        - project_id (references projects)
        - share_token (unique)
        - created_by (references users)
        - expires_at
        - view_count
        - password_hash (optional)
        - created_at
      </shared_projects>

      <shared_images>
        - id (uuid, primary key)
        - image_id (references images)
        - share_token (unique)
        - created_by (references users)
        - expires_at
        - view_count
        - created_at
      </shared_images>

      <image_comments>
        - id (uuid, primary key)
        - image_id (references images)
        - user_id (references users)
        - comment_text
        - created_at
        - updated_at
      </image_comments>

      <user_settings>
        - id (uuid, primary key)
        - user_id (references users, unique)
        - default_model_id
        - default_parameters (jsonb)
        - theme
        - gallery_view_mode
        - notifications_enabled
        - settings (jsonb: misc settings)
        - created_at
        - updated_at
      </user_settings>
    </tables>

    <indexes>
      - images(user_id, created_at DESC)
      - images(project_id)
      - images(is_favorite, created_at DESC)
      - images(tags) using GIN
      - prompts(user_id, is_favorite)
      - generation_queue(user_id, status)
      - usage_logs(user_id, created_at DESC)
      - shared_projects(share_token)
      - shared_images(share_token)
    </indexes>
  </database_schema>

  <api_endpoints>
    <authentication>
      - POST /api/auth/register
      - POST /api/auth/login
      - POST /api/auth/logout
      - GET /api/auth/me
      - POST /api/auth/verify-email
      - POST /api/auth/forgot-password
      - POST /api/auth/reset-password
      - PUT /api/auth/profile
      - PUT /api/auth/change-password
    </authentication>

    <images>
      - GET /api/images
      - GET /api/images/:id
      - POST /api/images/generate
      - POST /api/images/:id/variation
      - POST /api/images/:id/upscale
      - POST /api/images/:id/remix
      - PUT /api/images/:id
      - DELETE /api/images/:id
      - POST /api/images/:id/favorite
      - POST /api/images/:id/rate
      - GET /api/images/:id/metadata
      - POST /api/images/bulk-delete
      - POST /api/images/bulk-move
      - GET /api/images/download/:id
      - POST /api/images/:id/share
    </images>

    <projects>
      - GET /api/projects
      - POST /api/projects
      - GET /api/projects/:id
      - PUT /api/projects/:id
      - DELETE /api/projects/:id
      - GET /api/projects/:id/images
      - POST /api/projects/:id/images/add
      - DELETE /api/projects/:id/images/:imageId
      - POST /api/projects/:id/duplicate
      - POST /api/projects/:id/export
      - PUT /api/projects/:id/archive
      - POST /api/projects/:id/share
    </projects>

    <collections>
      - GET /api/collections
      - POST /api/collections
      - GET /api/collections/:id
      - PUT /api/collections/:id
      - DELETE /api/collections/:id
      - POST /api/collections/:id/images
      - DELETE /api/collections/:id/images/:imageId
      - PUT /api/collections/:id/reorder
    </collections>

    <prompts>
      - GET /api/prompts
      - POST /api/prompts
      - GET /api/prompts/:id
      - PUT /api/prompts/:id
      - DELETE /api/prompts/:id
      - GET /api/prompts/categories
      - POST /api/prompts/:id/favorite
      - GET /api/prompts/public
    </prompts>

    <generation>
      - POST /api/generate/text-to-image
      - POST /api/generate/image-to-image
      - POST /api/generate/batch
      - GET /api/generate/queue
      - GET /api/generate/queue/:id/status
      - DELETE /api/generate/queue/:id
      - POST /api/generate/queue/:id/retry
      - GET /api/generate/history
    </generation>

    <models>
      - GET /api/models
      - GET /api/models/:id
      - GET /api/models/featured
      - GET /api/models/categories
    </models>

    <usage>
      - GET /api/usage/stats
      - GET /api/usage/daily
      - GET /api/usage/monthly
      - GET /api/usage/by-model
      - GET /api/credits/balance
      - GET /api/credits/history
    </usage>

    <sharing>
      - POST /api/share/project/:id
      - GET /api/share/project/:token
      - POST /api/share/image/:id
      - GET /api/share/image/:token
      - DELETE /api/share/:token
    </sharing>

    <search>
      - GET /api/search/images?q=query
      - GET /api/search/prompts?q=query
      - GET /api/search/projects?q=query
    </search>

    <settings>
      - GET /api/settings
      - PUT /api/settings
      - GET /api/settings/defaults
      - PUT /api/settings/defaults
    </settings>

    <admin>
      - GET /api/admin/users
      - GET /api/admin/stats
      - PUT /api/admin/models/:id/toggle
      - GET /api/admin/usage-overview
    </admin>
  </api_endpoints>

  <ui_layout>
    <landing_page>
      - Navigation bar (logo, features, pricing, login, sign up)
      - Hero section with CTA buttons
      - Feature showcase grid
      - Model comparison section
      - Gallery showcase (example images)
      - Testimonials carousel
      - Pricing cards (if applicable)
      - FAQ accordion
      - Footer with links
    </landing_page>

    <dashboard_layout>
      - Top navigation bar:
        - Logo/home link
        - Quick generate button
        - Search bar
        - Notifications bell
        - Credits display
        - User menu dropdown
      - Sidebar (collapsible):
        - Dashboard link
        - Generate new image
        - My images
        - Projects
        - Collections
        - Prompts library
        - Queue status
        - Settings
        - Logout
      - Main content area:
        - Dashboard cards
        - Recent images grid
        - Quick stats
        - Activity feed
      - Responsive mobile menu
    </dashboard_layout>

    <generation_page>
      - Split layout:
        - Left panel: generation controls
          - Model selector
          - Prompt textarea
          - Negative prompt
          - Parameters accordion
          - Aspect ratio grid
          - Advanced settings
          - Generate button
          - Queue button
        - Right panel: results
          - Generated images grid
          - Image actions (favorite, download, iterate)
          - Generation info
          - History sidebar
      - Bottom toolbar: quick actions
    </generation_page>

    <gallery_page>
      - Filter sidebar (collapsible)
      - View mode toggle (grid/masonry/list)
      - Sort dropdown
      - Search bar
      - Bulk selection toolbar
      - Image grid with lazy loading
      - Lightbox modal
      - Quick actions on hover
      - Pagination or infinite scroll
    </gallery_page>

    <project_page>
      - Project header:
        - Cover image
        - Project title (editable)
        - Description
        - Settings button
        - Share button
        - Export button
      - Project toolbar:
        - Add images
        - Bulk actions
        - Filters
      - Image grid specific to project
      - Project stats sidebar
    </project_page>

    <image_detail_modal>
      - Full-size image display
      - Zoom controls
      - Image metadata panel:
        - Prompt
        - Model used
        - Parameters
        - Generation time
        - Seed
      - Action buttons:
        - Download
        - Favorite
        - Remix
        - Variation
        - Upscale
        - Share
        - Delete
      - Comments section
      - Related images carousel
    </image_detail_modal>

    <settings_page>
      - Tabbed interface:
        - Account
        - Preferences
        - Models
        - API keys
        - Billing (if applicable)
        - Privacy
        - Notifications
      - Form sections with validation
      - Save/cancel buttons
      - Danger zone (delete account)
    </settings_page>
  </ui_layout>

  <design_system>
    <color_palette>
      - Primary: Purple/violet (#8B5CF6) for main actions
      - Secondary: Pink/magenta (#EC4899) for accents
      - Success: Green (#10B981)
      - Warning: Amber (#F59E0B)
      - Error: Red (#EF4444)
      - Background Light: White (#FFFFFF)
      - Background Dark: Near black (#0F172A)
      - Surface Light: Gray 50 (#F9FAFB)
      - Surface Dark: Slate 800 (#1E293B)
      - Text Light: Gray 900 (#111827)
      - Text Dark: Gray 50 (#F9FAFB)
      - Borders Light: Gray 200 (#E5E7EB)
      - Borders Dark: Slate 700 (#334155)
    </color_palette>

    <typography>
      - Font family: Inter, system-ui, sans-serif
      - Headings: font-bold
      - Body: font-normal, text-base (16px)
      - Small: text-sm (14px)
      - Mono: JetBrains Mono, monospace (for parameters)
      - Line height: relaxed
    </typography>

    <components>
      <buttons>
        - Primary: bg-primary, rounded-lg, shadow-sm
        - Secondary: border, bg-transparent, hover:bg-surface
        - Danger: bg-red-500, text-white
        - Icon buttons: square, p-2, hover:bg-surface
        - Loading state with spinner
      </buttons>

      <cards>
        - Rounded-xl border with shadow
        - Hover elevation increase
        - Dark mode: border-slate-700
      </cards>

      <inputs>
        - Rounded-lg with focus ring
        - Textarea auto-resize
        - Label above input
        - Error states in red
        - Helper text below
      </inputs>

      <image_cards>
        - Aspect ratio preserved
        - Overlay on hover with actions
        - Favorite badge
        - Loading skeleton
        - Lazy load with blur-up
      </image_cards>

      <modals>
        - Overlay backdrop
        - Centered with max-width
        - Close button top-right
        - Smooth fade-in animation
      </modals>
    </components>

    <animations>
      - Transitions: 200-300ms ease-in-out
      - Fade in for modals
      - Slide in for sidebars
      - Scale on hover for cards
      - Skeleton loaders for images
      - Progress bars for generation
      - Smooth scroll behavior
    </animations>
  </design_system>

  <fal_ai_integration>
    <models_to_integrate>
      - fal-ai/flux/dev (Flux Dev)
      - fal-ai/flux/schnell (Flux Schnell - fast)
      - fal-ai/flux-pro (Flux Pro - highest quality)
      - fal-ai/stable-diffusion-xl (SDXL)
      - fal-ai/fast-sdxl (Fast SDXL)
      - fal-ai/flux-lora (LoRA support)
      - fal-ai/face-to-sticker (specialized)
      - fal-ai/aura-flow (if available)
    </models_to_integrate>

    <fal_features>
      - Text-to-image generation
      - Image-to-image transformation
      - Inpainting/outpainting
      - Upscaling via fal-ai/clarity-upscaler
      - Background removal via fal-ai/imageutils/rembg
      - LoRA model application
      - Queue and webhook support
      - Streaming results (if available)
    </fal_features>

    <implementation_notes>
      - Use @fal-ai/serverless-client SDK
      - Handle queue/webhook for long generations
      - Store fal request IDs for tracking
      - Implement retry logic for failures
      - Cache model metadata
      - Handle rate limits gracefully
      - Support both sync and async generation
      - Parse and store all generation parameters
    </implementation_notes>
  </fal_ai_integration>

  <docker_setup>
    <docker_compose_yml>
      services:
        postgres:
          image: postgres:16-alpine
          container_name: image_studio_db
          environment:
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
            POSTGRES_DB: image_studio
          ports:
            - "5432:5432"
          volumes:
            - postgres_data:/var/lib/postgresql/data
          healthcheck:
            test: ["CMD-SHELL", "pg_isready -U postgres"]
            interval: 10s
            timeout: 5s
            retries: 5

        pgadmin:
          image: dpage/pgadmin4
          container_name: image_studio_pgadmin
          environment:
            PGADMIN_DEFAULT_EMAIL: admin@admin.com
            PGADMIN_DEFAULT_PASSWORD: admin
          ports:
            - "5050:80"
          depends_on:
            - postgres

      volumes:
        postgres_data:
    </docker_compose_yml>

    <env_example>
      # Database
      DATABASE_URL=postgresql://postgres:postgres@localhost:5432/image_studio

      # FAL AI
      FAL_API_KEY=your_fal_api_key_here

      # Auth
      AUTH_SECRET=your_secret_key_here
      JWT_SECRET=your_jwt_secret_here

      # App
      NODE_ENV=development
      PORT=3000

      # Storage (local or S3)
      STORAGE_TYPE=local
      STORAGE_PATH=./uploads
      # S3_BUCKET=
      # S3_REGION=
      # S3_ACCESS_KEY=
      # S3_SECRET_KEY=

      # URLs
      APP_URL=http://localhost:3007
      API_URL=http://localhost:3007/api
    </env_example>

    <scripts>
      - npm run db:generate - Generate Drizzle migrations
      - npm run db:migrate - Run migrations
      - npm run db:push - Push schema to DB (dev)
      - npm run db:studio - Open Drizzle Studio
      - npm run docker:up - Start Docker services
      - npm run docker:down - Stop Docker services
      - npm run dev - Start dev server
      - npm run build - Build for production
      - npm run start - Start production server
    </scripts>
  </docker_setup>

  <implementation_steps>
    <step number="1">
      <title>Project Setup and Infrastructure</title>
      <tasks>
        - Initialize Next.js 16 project
        - Set up TypeScript configuration
        - Configure Tailwind CSS and shadcn/ui
        - Create docker-compose.yml for PostgreSQL
        - Set up Drizzle ORM with schema
        - Create database migration system
        - Set up environment variables
        - Install and configure fal-ai SDK
        - Create project folder structure
        - Set up Git repository and .gitignore
      </tasks>
    </step>

    <step number="2">
      <title>Database Schema and Migrations</title>
      <tasks>
        - Define all tables in Drizzle schema
        - Create relationships and foreign keys
        - Add indexes for performance
        - Write initial migration
        - Seed database with sample models
        - Create database utilities and helpers
        - Set up connection pooling
        - Test migrations up and down
      </tasks>
    </step>

    <step number="3">
      <title>Authentication System</title>
      <tasks>
        - Set up Better Auth
        - Create user registration endpoint
        - Implement login/logout flow
        - Add email verification
        - Create password reset flow
        - Build auth middleware
        - Create protected route wrapper
        - Add session management
        - Build user profile management
      </tasks>
    </step>

    <step number="4">
      <title>Landing Page</title>
      <tasks>
        - Create landing page layout
        - Build hero section with animations
        - Add feature showcase section
        - Create model comparison section
        - Build example gallery
        - Add FAQ accordion
        - Create footer with links
        - Implement responsive design
        - Add call-to-action buttons
        - Optimize for SEO
      </tasks>
    </step>

    <step number="5">
      <title>Dashboard Layout and Navigation</title>
      <tasks>
        - Create dashboard layout component
        - Build top navigation bar
        - Create collapsible sidebar
        - Add responsive mobile menu
        - Build dashboard overview page
        - Create quick stats cards
        - Add recent images grid
        - Implement activity feed
        - Add user menu dropdown
        - Create credits display component
      </tasks>
    </step>

    <step number="6">
      <title>FAL.AI Integration</title>
      <tasks>
        - Set up fal-ai client
        - Create model service layer
        - Implement text-to-image generation
        - Add image-to-image support
        - Create queue management system
        - Handle webhooks for async generation
        - Implement error handling
        - Add retry logic
        - Store generation metadata
        - Create model selector component
      </tasks>
    </step>

    <step number="7">
      <title>Image Generation Interface</title>
      <tasks>
        - Build generation page layout
        - Create prompt input component
        - Add model selector dropdown
        - Build parameters control panel
        - Create aspect ratio selector
        - Add advanced settings accordion
        - Implement generate button with loading
        - Create real-time progress indicator
        - Build results display grid
        - Add generation history sidebar
      </tasks>
    </step>

    <step number="8">
      <title>Image Gallery and Management</title>
      <tasks>
        - Create image gallery page
        - Build responsive image grid
        - Implement masonry layout option
        - Add image lightbox/modal
        - Create filter sidebar
        - Implement search functionality
        - Add sorting options
        - Build bulk selection UI
        - Create image detail view
        - Add download functionality
      </tasks>
    </step>

    <step number="9">
      <title>Image Iteration Features</title>
      <tasks>
        - Implement variation generation
        - Add remix/re-prompt feature
        - Create upscaling integration
        - Build image-to-image transform
        - Add inpainting support (if available)
        - Create iteration history view
        - Build comparison UI
        - Add quick iteration buttons
        - Implement seed locking
      </tasks>
    </step>

    <step number="10">
      <title>Project Management</title>
      <tasks>
        - Create projects CRUD endpoints
        - Build projects list page
        - Create project detail view
        - Add drag-and-drop image organization
        - Implement project settings
        - Build project sharing feature
        - Add project export functionality
        - Create project templates
        - Add project analytics
      </tasks>
    </step>

    <step number="11">
      <title>Collections and Organization</title>
      <tasks>
        - Create collections CRUD
        - Build collections UI
        - Add images to collections
        - Implement drag-and-drop reordering
        - Create collection sharing
        - Add favorites system
        - Build tagging interface
        - Create smart collections/filters
      </tasks>
    </step>

    <step number="12">
      <title>Prompt Library</title>
      <tasks>
        - Create prompts CRUD endpoints
        - Build prompt library UI
        - Add prompt categories
        - Implement prompt search
        - Create prompt templates
        - Add style modifiers quick-add
        - Build prompt suggestions
        - Add import/export prompts
        - Create community prompts (optional)
      </tasks>
    </step>

    <step number="13">
      <title>Batch Generation</title>
      <tasks>
        - Create batch queue system
        - Build batch input UI
        - Add CSV import for prompts
        - Implement template variables
        - Create queue management page
        - Add priority handling
        - Build progress tracking
        - Implement pause/resume
        - Add batch export
      </tasks>
    </step>

    <step number="14">
      <title>Usage Tracking and Credits</title>
      <tasks>
        - Create usage logging system
        - Build credits management
        - Add usage dashboard
        - Create cost estimation
        - Implement usage alerts
        - Build monthly reports
        - Add model cost comparison
        - Create usage optimization tips
      </tasks>
    </step>

    <step number="15">
      <title>Sharing and Collaboration</title>
      <tasks>
        - Implement project sharing links
        - Create image sharing tokens
        - Build public share views
        - Add password protection option
        - Create embed functionality
        - Add social media sharing
        - Build team workspace (optional)
        - Implement permission levels
      </tasks>
    </step>

    <step number="16">
      <title>Settings and Preferences</title>
      <tasks>
        - Create settings page layout
        - Build account settings tab
        - Add preferences management
        - Create theme switcher
        - Build default parameters settings
        - Add notification preferences
        - Create data export
        - Implement account deletion
        - Add API key management
      </tasks>
    </step>

    <step number="17">
      <title>Search and Discovery</title>
      <tasks>
        - Implement global search
        - Create search results page
        - Add search filters
        - Build command palette (Cmd+K)
        - Create quick actions menu
        - Add keyboard shortcuts
        - Implement recent searches
      </tasks>
    </step>

    <step number="18">
      <title>File Storage and CDN</title>
      <tasks>
        - Set up local file storage
        - Create thumbnail generation
        - Implement image optimization
        - Add WebP/AVIF support
        - Set up S3 integration (optional)
        - Create CDN configuration
        - Implement cleanup jobs
        - Add storage usage tracking
      </tasks>
    </step>

    <step number="19">
      <title>Performance Optimization</title>
      <tasks>
        - Add image lazy loading
        - Implement infinite scroll
        - Create skeleton loaders
        - Optimize database queries
        - Add request caching
        - Implement response compression
        - Create background jobs system
        - Add monitoring and logging
      </tasks>
    </step>

    <step number="20">
      <title>Polish and Testing</title>
      <tasks>
        - Add loading states everywhere
        - Implement error boundaries
        - Create empty states
        - Add success notifications
        - Build onboarding flow
        - Create help documentation
        - Add tooltips and hints
        - Implement analytics
        - Test responsive design
        - Fix accessibility issues
        - Cross-browser testing
        - Performance testing
      </tasks>
    </step>
  </implementation_steps>

  <success_criteria>
    <functionality>
      - Image generation works with multiple fal.ai models
      - Iteration features (variations, upscale, remix) functional
      - Project and collection organization working smoothly
      - Batch generation queue processes correctly
      - Sharing and collaboration features operational
      - All CRUD operations stable
    </functionality>

    <user_experience>
      - Beautiful, modern UI matching design system
      - Smooth animations and transitions
      - Fast image loading with lazy loading
      - Intuitive navigation and workflows
      - Clear feedback for all actions
      - Responsive on all devices
      - Accessible keyboard navigation
    </user_experience>

    <technical_quality>
      - Clean TypeScript code with types
      - Proper error handling
      - Secure authentication
      - Optimized database queries with indexes
      - Efficient image storage
      - Background job processing
      - Comprehensive logging
    </technical_quality>

    <performance>
      - Page load under 2 seconds
      - Image generation starts within 1 second
      - Gallery loads smoothly with lazy loading
      - Database queries optimized
      - Images served efficiently
      - No memory leaks
      - Handles 100+ images in gallery
    </performance>

    <design>
      - Consistent color palette and typography
      - Professional appearance
      - Dark mode fully implemented
      - Smooth animations
      - Beautiful image displays
      - Clear visual hierarchy
      - High contrast and accessibility
    </design>
  </success_criteria>

  <additional_features>
    <nice_to_have>
      - PWA support for offline viewing
      - Mobile app (React Native)
      - API for developers
      - CLI tool for batch operations
      - Webhook integrations
      - Zapier/Make integration
      - Browser extension
      - Discord bot
      - Slack integration
      - Image editing tools (crop, adjust)
      - Video generation (if fal.ai supports)
      - Animation creation
      - Style transfer advanced features
      - Custom model training integration
      - Community gallery
      - Marketplace for prompts/styles
    </nice_to_have>
  </additional_features>

  <security_considerations>
    - Secure password hashing (bcrypt/argon2)
    - JWT token expiration and refresh
    - Rate limiting on API endpoints
    - CSRF protection
    - XSS prevention
    - SQL injection protection (via Drizzle ORM)
    - File upload validation
    - Image malware scanning
    - API key encryption
    - Secure session management
    - HTTPS only in production
    - Environment variable protection
    - Database connection security
    - Input validation and sanitization
  </security_considerations>
</project_specification>