ByteCanvas

ByteCanvas is a full-stack text-to-image app.

• Frontend: React + Vite + Tailwind + shadcn/ui + Zustand
• Backend: FastAPI + Bytez SDK
• Persistence: Supabase REST API (Storage bucket + images table)

Features

• Generate images from prompts using Bytez.
• Save generated image metadata in Supabase.
• Browse recent creations on Home.
• Full History page with:
  • search by prompt
  • date range filters
  • pagination
  • delete image
• Image details page with download and delete.

Project Structure

bytecanvas/
  client/   # React app
  server/   # FastAPI API

Prerequisites

• Node.js 20+
• pnpm
• Python 3.12 recommended
  • Python 3.14 may cause dependency/runtime issues with some third-party libs.

Environment Variables

Server

Copy server/.env.example to server/.env and fill values.

Required:

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• BYTEZ_API_KEY

Important:

• SUPABASE_SERVICE_ROLE_KEY must be the Supabase service_role secret key.
• Do not use sb_publishable_* or sb_anon_* for backend server operations.

Optional defaults:

• SUPABASE_BUCKET=generated-images
• BYTEZ_MODEL=stabilityai/stable-diffusion-xl-base-1.0

Client

By default, the frontend can use Vite proxy in client/vite.config.js, so API requests to /api/* are forwarded to backend on http://127.0.0.1:8000.

If you want explicit backend URL, create client/.env:

VITE_API_BASE_URL=http://127.0.0.1:8000

Supabase Setup

Create storage bucket:

• Name: generated-images
• Public bucket recommended for direct browser image URLs.

Create table: images

• id text primary key (or uuid stored as text)
• prompt text not null
• image_url text not null
• storage_path text not null
• created_at timestamptz not null
• metadata jsonb not null

Quick SQL (Supabase SQL Editor):

CREATE TABLE IF NOT EXISTS public.images (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  prompt TEXT NOT NULL,
  image_url TEXT NOT NULL,
  storage_path TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  model VARCHAR(255)
);

ALTER TABLE public.images ADD COLUMN metadata JSONB;

Install & Run

1) Backend

cd server
python -m venv venv
venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Health check:

• http://127.0.0.1:8000/health

2) Frontend

cd client
pnpm install
pnpm dev

Open:

• http://localhost:5173

API Endpoints

Base prefix: /api/v1

• POST /generate

  • Body: { "prompt": "A cat in a wizard hat" }
  • Returns generated image record.

• GET /history?page=1&page_size=12&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

  • Returns paginated image history.

• GET /history/{image_id}

  • Returns one image record.

• DELETE /history/{image_id}

  • Deletes image metadata + storage object.

• GET /search?q=cat&page=1&page_size=12&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

  • Returns paginated filtered records.

Frontend Routes

• / home
• /history history view
• /image/:id image details

See route setup in client/src/routes/AppRoutes.jsx.

Build

Frontend production build:

cd client
pnpm build

Backend compile sanity check:

cd server
venv\Scripts\python.exe -m compileall app

Troubleshooting

500 on /api/v1/history or /api/v1/generate

• Verify backend terminal logs.
• Confirm server/.env has valid values.
• Ensure SUPABASE_SERVICE_ROLE_KEY is service role, not publishable/anon.

Images appear as broken icon

• Check whether image_url is accessible in browser.
• Ensure bucket is public if using /storage/v1/object/public/... URLs.
• Ensure uploaded object exists at stored storage_path.

ERR_CONNECTION_REFUSED from frontend

• Backend is not running on 127.0.0.1:8000.
• Start backend first, then refresh frontend.