Banana Weather: AI-Powered Atmospheric Art

Banana Weather is a GenMedia web application that visualizes the current "vibe" and atmospheric essence of a location using Generative AI.

It combines precise Geolocation with the creative power of Google Gemini 3.1 Flash Image (Nano Banana 2, now GA) and Google Veo 3.1 to generate high-fidelity, vertical (9:16) 3D isometric art and looping videos representing the weather, architecture, and mood of your city in real-time.

Model note: The default image model is gemini-3.1-flash-image (GA). You can opt into the higher-fidelity gemini-3-pro-image (Nano Banana Pro) or the lower-cost gemini-3.1-flash-lite-image via the GEMINI_IMAGE env var. Video defaults to veo-3.1-lite-generate-001, which is a Preview-stage model (Pre-GA Offerings Terms, no retirement SLA) retained intentionally for cost; override via VEO_MODEL (e.g. veo-3.1-generate-001 or veo-3.1-fast-generate-001 for GA tiers).

Features

• AI-Generated Atmospheric Art: Unique, non-deterministic visuals for every request.
• Cinematic Video Loops: Transitions from static image to a "Parallax" animation using Veo 3.1 Lite.
• Smart Caching: Reuses generated content for 3 hours to improve performance and reduce costs.
• Video Download: Download your generated animations as MP4 files with timestamped filenames.
• Fictional Locations: Supports generating scenes for fictional worlds (e.g., Arrakis, Middle-earth) via the Presets system.
• Presets Gallery: A curated list of pre-generated scenes categorized by theme, backed by Firestore.
• Responsive Flutter Web UI: Mobile-first design with a clean, "Digital Picture Frame" aesthetic.

What to Expect

1. Instant Immersion: Upon opening the app, it attempts to detect your location and immediately conjures an atmospheric portrait of your current weather and surroundings.
2. The "Dreaming" Phase: When you request a new city, the AI takes a moment (typically 10-20 seconds) to "dream" up the visuals. You'll see a status indicator as it writes the prompt, paints the image, and finally animates the scene.
3. Explore the Impossible: Use the "Presets" drawer to visit fictional locations like Arrakis, Winterfell, or Coruscant, rendered with the same realistic fidelity as real-world cities.

Architecture

The system follows a Client-Server architecture:

1. The Backend (Go 1.25):

   • Orchestrator: Handles API requests, validating inputs.
   • Geocoding: Interacts with Google Maps Platform.
   • Generative AI: Gemini 3.1 Flash Image & Veo 3.1.
   • Persistence: Uses Firestore for metadata/caching and Cloud Storage for assets.
   • Server: Serves the compiled Flutter Web application.

2. The Frontend (Flutter Web):

   • UI: Single-page app using Provider.
   • Video: video_player integration with seamless transition.
   • Theme: Light/Dark mode with dynamic "Glassmorphism" overlays.

Setup & Deployment

1. Prerequisites

• Google Cloud Project: Create a project and enable billing.
• APIs Enabled:
  • Vertex AI API (for Gemini & Veo).
  • Google Maps Platform (Places API, Geocoding API).
  • Cloud Run.
• Firestore Database: Provisioned in Native Mode. Quickstart Guide.
• GCS Bucket: A Standard storage bucket for hosting generated media. Create Bucket Guide.

2. Service Account Setup

Run the helper script to create the identity and grant permissions (Vertex AI, Logging, Firestore):

./setup_sa.sh

3. Environment Configuration

Create a .env file:

GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
IMAGE_LOCATION="global"      # Vertex location for Gemini 3 image models (global/us/eu). Veo does NOT use this.
VEO_LOCATION="us-central1"   # Vertex region for Veo (a region, never global).
GOOGLE_MAPS_API_KEY="your-maps-api-key"
GEMINI_IMAGE="gemini-3.1-flash-image" # Optional: Override the image model (e.g. gemini-3-pro-image for Nano Banana Pro, or gemini-3.1-flash-lite-image for lower cost)
VEO_MODEL="veo-3.1-lite-generate-001" # Optional: Override the video model (e.g. veo-3.1-generate-001, veo-3.1-fast-generate-001)
GENMEDIA_BUCKET="your-gcs-bucket-name"
FIRESTORE_DATABASE="banana-weather"
PORT=8080

Locations differ per service. Gemini 3 image models are served at global (also us/eu), while Veo requires a region (default us-central1) and does not run at global. These are configured separately via IMAGE_LOCATION and VEO_LOCATION; the Cloud Run deploy region (default us-central1) is independent. For backward compatibility, GOOGLE_CLOUD_LOCATION is still honored as the image location fallback if IMAGE_LOCATION is unset.

Migration warning: any deploy that previously set GOOGLE_CLOUD_LOCATION to a non-default region specifically to drive Veo must now set VEO_LOCATION instead, because GOOGLE_CLOUD_LOCATION now routes to the image location only and no longer affects video.

3. Development

• Run Local: ./dev.sh
• Deploy: ./deploy.sh

4. Utility Tools

We have a unified CLI (banana) for admin tasks, content generation, and maintenance.

See the CLI Documentation for full usage details.

cd backend
go build -o banana ./cmd/banana
./banana --help

Migration: Move from JSON to Firestore (One-time).

./banana migrate

Admin Console: View stats and manage locations.

./banana admin stats