nano-pro/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Nano Banana Pro is a PHP web application for AI image generation and iterative editing using Google's Gemini 3 Pro Image Preview API. It features Microsoft Azure AD SSO authentication and a "Cinematography Prompt Studio" that enhances user prompts with real camera and lens physics.

Development Commands

# Start development server
php -S localhost:8000

# Install dependencies (for JWT validation)
composer install

Architecture

Request Flow

1. index.php - Main SPA entry point, renders UI and handles client-side state
2. api.php - Backend API endpoint for image generation/editing operations
3. enhance_prompt.php - AI-powered prompt enhancement using Gemini text model

Core Components

Authentication Layer:

• AuthMiddleware.php - Central auth orchestrator, handles SSO flow and login UI
• JWTValidator.php - Validates Azure AD JWT tokens using JWKS
• auth.php - Login/logout endpoint for MSAL token exchange
• SSO can be disabled via SSO_ENABLED=false in .env for local development

Session & Storage:

• SessionManager class in session_manager.php - Handles per-user isolated sessions
• Images stored on disk at uploads/sessions/{session_id}/images/
• Metadata files (.meta) track expiration for auto-cleanup (24 hours)
• Session history limited to last 10 images, 50 conversation items

API Integration:

• NanoBananaProAPI class in api.php wraps Google's Generative Language API
• Uses model gemini-3-pro-image-preview for image generation
• Uses model gemini-3-flash-preview for prompt enhancement
• Supports both text-to-image generation and image editing with input images

Configuration

Copy .env.example to .env and config.example.php to config.php:

• GEMINI_API_KEY - Google Gemini API key (required)
• SSO_ENABLED - Enable/disable Azure AD authentication
• SSO_TENANT_ID, SSO_CLIENT_ID - Azure AD app registration values

Key Data Flows

Image Generation:

1. Client submits prompt to api.php with action=generate
2. If editing, SessionManager retrieves current image from disk
3. NanoBananaProAPI sends request to Gemini with optional input image
4. Response image saved to disk, session updated, webhook logged

Prompt Enhancement:

1. Client submits scene + camera/lens settings to enhance_prompt.php
2. Server builds structured prompt with camera physics and lens characteristics
3. Gemini text model returns enhanced cinematography description
4. Result transferred to main image generation form

Webhook Logging

webhook_logger.php logs user actions (image generation, prompt enhancement) to external webhook endpoint for analytics.