Personal AI Image Studio

Local-first web application for managing AI-assisted image generation projects. The stack pairs a FastAPI backend (SQLite + Google Gemini 2.5 Flash integration) with a Vite/React frontend styled via Tailwind and shadcn-inspired components.

Project structure

Img_New_Gen/
├── backend/      # FastAPI application, SQLAlchemy models, Gemini integration
├── frontend/     # Vite + React client, Tailwind UI
├── assets/       # Drop screenshots or design artifacts here
├── docs/         # Additional documentation (status, roadmap, etc.)
├── Makefile      # Helper commands for combined workflows
└── README.md     # This document

Prerequisites

• Python 3.10+
• Node.js 20+ (with npm)
• Google Gemini API key (set as GOOGLE_API_KEY for backend)

Initial setup

1. Backend virtualenv & dependencies

   cd backend
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -U pip
   pip install -e .[dev,test]
   cp .env.example .env
   # add GOOGLE_API_KEY and any custom paths

2. Database migration

   cd backend
   source .venv/bin/activate
   alembic upgrade head

3. Frontend dependencies

   cd frontend
   npm install

Alternatively, you can rely on the Makefile shortcuts described below after the first install.

Running the app

Development servers

From the repo root:

make dev

• Spins up the FastAPI backend on http://localhost:8000
• Boots the Vite dev server on http://localhost:5173

If you prefer separate terminals:

make backend   # FastAPI (reload enabled)
make frontend  # Vite dev server

The backend serves generated files from the /data mount; by default files live under backend/data/.

Key workflows

• Generate images from the Project Chat view. You can attach reference images (PNG/JPEG/WebP) and the UI now provides live thumbnails before submission. Submitting multiple times will reuse your existing conversation unless you start a “New Chat”.
• Browse the Global Gallery via the sidebar or the “View Gallery” button in the chat header. The gallery uses Apple Photos–style cards with hover overlays, and metadata is available in the optional info pane.
• View & download assets from either the chat history or gallery. All image tiles fall back to the full-size file if a thumbnail has not been generated yet, avoiding broken placeholders.

Production build preview

make build     # runs `npm run build` inside frontend/

Deploy the backend with any ASGI server (uvicorn, gunicorn, etc.) pointing at app.main:app and serve the built frontend from frontend/dist/ (or configure a reverse proxy).

Quality checks & tests

Use Make targets to run linting and tests across both stacks:

make lint      # Ruff for backend, TypeScript check for frontend
make format    # Autofix with Ruff & Prettier
make test      # Pytest + Vitest

You can also run suites individually:

# Backend
cd backend
source .venv/bin/activate
pytest

# Frontend
cd frontend
npm run lint
npm test

Vitest is configured with JSDOM and the backend includes a smoke test for /healthz. Extend coverage as features grow (e.g., add component tests, API route tests).

Troubleshooting

• Images appear “broken”: Confirm the backend is running so /data/** routes resolve. Thumbnails are generated asynchronously; if a thumb is missing the frontend will automatically fall back to the full-size image.
• Prompt submissions stall: Check the backend logs for Gemini or attachment errors. Each upload is stored under data/attachments/{message_id} to avoid checksum collisions—clearing the data/attachments directory can resolve corrupted files (keep a backup first).
• Gallery not updating: The frontend invalidates the images query after each generation. If the gallery still shows stale data, force a reload or clear the browser cache to refresh query state.

Release notes (2025-10-27)

• Fixed Gemini integration so prompts and edits reliably return images.
• Added gallery redesign with hover overlays, dedicated info pane, and quick access to “Open in Preview” / “Download”.
• Introduced attachment thumbnails in the chat composer with safe URL cleanup.
• Hardened backend attachment storage to prevent duplicate checksum errors that previously blocked prompt submission.
• Ensured all image renders fall back from thumbnail to full-size asset to eliminate broken tiles in chat and gallery views.

Configuration & environment

Key environment variables (backend/.env):

• GOOGLE_API_KEY: Gemini authentication (required for image generation)
• DATA_DIR: Override default storage directory (backend/data)
• DATABASE_URL: SQLite path (defaults to sqlite+aiosqlite:///./data/app.db)

Frontend preferences (default format, aspect ratio, etc.) persist locally via zustand under the image-studio-settings key and can be adjusted in the Settings page.

Useful directories

• backend/app/services/: Gemini client wrapper and image storage pipeline
• backend/app/api/routes/: FastAPI routers for projects, conversations, chat, tags, images
• frontend/src/pages/: React routes (Projects, Project Chat, Gallery, Settings)
• frontend/src/components/: Shared UI primitives (buttons, inputs, quick switcher)

Roadmap ideas

Documentation index

• Project status & next steps

• Add toast notifications for gallery bulk actions and settings updates

• Expand test coverage (API regression tests, component interactions)

• Capture demo GIFs/screenshots and place them under assets/

• Introduce user authentication & per-user data segregation if required

Enjoy building with the Personal AI Image Studio!