Dream Frame - AI Image Generation Platform

Dream Frame is a full-stack web application that allows users to generate high-quality images using AI (Fal.ai), manage their generated images, and explore a community feed of shared creations.

🚀 Key Features

• AI Image Generation: Leverages Fal.ai's powerful models (likely Flux Pro or Stable Diffusion XL) to generate images from text prompts.
• User Accounts: Secure authentication and user profiles powered by Supabase.
• Image Gallery: Personal gallery to view and manage generated images.
• Community Explore: A public feed to discover images created by other users.
• Usage Limits: System to track and limit free image generations per user.
• Responsive UI: Modern, responsive interface built with React and Tailwind CSS.

🛠 Tech Stack

Frontend

• Framework: React (v19) with Vite
• Styling: Tailwind CSS (v4)
• UI Components: Radix UI primitives (likely via shadcn/ui)
• Icons: Lucide React
• Animations: Framer Motion
• Routing: React Router (v7)
• Runtime: Node.js / Bun

Backend

• Runtime: Bun
• Framework: Express.js
• Database: Supabase (PostgreSQL)
• Storage: Supabase Storage (for hosting generated images)
• AI Service: Fal.ai
• Authentication: Custom implementation using Supabase Auth

📋 Prerequisites

Before running the project, ensure you have the following installed:

• Bun (Recommended runtime) or Node.js
• A Supabase account
• A Fal.ai account with an API key

⚙️ Environment Setup

You need to configure environment variables for the backend. Create a .env file in the backend/ directory:

# Server Configuration
PORT=3000

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Fal.ai Configuration
FAL_API_KEY=your_fal_api_key
FAL_MODEL=fal-ai/flux-pro/v1.1-ultra  # or your preferred model endpoint

🚀 Installation & Running

Backend

1. Navigate to the backend directory:

   cd backend

2. Install dependencies:

   bun install

3. Start the development server:

   bun dev

   The server will start on http://localhost:3000.

Frontend

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   bun install
   # or npm install

3. Start the development server:

   bun dev
   # or npm run dev

   The frontend will be available at the URL shown in the terminal (usually http://localhost:5173).

   Note: Ensure the frontend is configured to point to your local backend. Check frontend/src/services/images.service.js if you need to change API_BASE_URL.

📚 API Documentation

Authentication (/api/auth)

Method	Endpoint	Description
POST	/signup	Create a new user account.
POST	/login	Authenticate an existing user.
POST	/logout	Log out the current user.
POST	/refresh	Refresh the authentication token.

User Profile (/api/profile)

Method	Endpoint	Description
POST	/	Create a profile for the user.
GET	/me	Get the authenticated user's profile.
GET	/usage/me	Get the user's current usage stats (images generated vs limit).
GET	/:id	Get a specific user's profile by ID.
PUT	/:id	Update a user's profile.

Images (/api/images)

Method	Endpoint	Description
POST	/generate	Generate a new image. Requires prompt and optionally image_size.
GET	/explore	Get a list of public images for the explore feed. Supports pagination (limit, offset).
GET	/my	Get the authenticated user's generated images.

🗄️ Database Schema (Supabase)

The project relies on the following tables in Supabase:

• profiles: Stores user information (linked to auth.users).
  • id (UUID, PK)
  • username (Text)
  • avatar_url (Text)
• images: Stores metadata for generated images.
  • id (UUID, PK)
  • user_id (UUID, FK)
  • image_url (Text)
  • prompt (Text)
  • model (Text)
  • is_public (Boolean)
  • created_at (Timestamp)
• user_usage: Tracks usage limits.
  • user_id (UUID, PK, FK)
  • images_generated (Integer)
  • free_limit (Integer)

Storage Bucket: generated-images (Public access or signed URLs required).

📂 Project Structure

.
├── backend/                # Express + Bun backend
│   ├── src/
│   │   ├── config/         # Environment & Service configs
│   │   ├── middlewares/    # Auth & Error handling
│   │   ├── modules/        # Feature-based modules (Auth, Images, Profile)
│   │   │   ├── auth/
│   │   │   ├── images/
│   │   │   └── profile/
│   │   ├── app.js          # App entry point
│   │   └── server.js       # Server startup
│   └── package.json
│
└── frontend/               # React + Vite frontend
    ├── src/
    │   ├── components/     # Reusable UI components
    │   ├── hooks/          # Custom React hooks
    │   ├── pages/          # Application routes/pages
    │   ├── services/       # API integration services
    │   └── ...
    ├── vite.config.js
    └── package.json