Sogni Vibe - AI Image Ideation Tool

🎨 Overview

Sogni Vibe is a mobile-first web application for iterative AI image generation, helping users evolve from a loose concept to their master vision through three intuitive phases:

1. Intent Wizard - Dynamic Q&A to capture your creative vision
2. Studio Loop - Generate and refine 16 images per round (4 batches of 4)
3. Finalization Gallery - Celebrate your final image with confetti and download

🚀 Getting Started

Prerequisites

• Node.js 20+
• npm 10+

1. Install Dependencies

git clone https://github.com/sogni-ai/sogni-vibe.git
cd sogni-vibe
npm run install:all

2. Configure Environment Files

Copy the provided templates and fill in the required values.

# Frontend (Vite) env vars live at the project root
cp src/.env.example .env

# Backend env vars live under ./server
cp server/.env.example server/.env

• The frontend template lives at src/.env.example; copy it to .env before editing.
• Update .env with the API URL you want the SPA to call (see ENV_CONFIG.md for staging/production notes).
• Update server/.env with your Sogni/OpenRouter credentials and port overrides (see the configuration table below).

3. Run the App Locally

Backend (Terminal 1):

cd server
npm run dev

The API listens on http://localhost:3000 by default.

Frontend (Terminal 2):

npm run dev

The Vite dev server starts on http://localhost:5173 and proxies /api to the backend.

🌟 Features

• Dynamic Wizard: Intelligent Q&A that only asks for missing details
• Batch Generation: 4 batches × 4 images = 16 images per round
• Smart Refinement: Single-select for refinement, multi-select for concept merging
• Batch Weighting: Multiple selections from same batch weight that prompt more heavily
• Infinite Iterations: No limits on creative exploration
• Branching: Automatic branch creation when going back and generating
• Mobile-First: Responsive design with hot pink accent color
• Final Gallery: Museum-style presentation with confetti and download button

🏗️ Architecture

Frontend (Svelte 5)

• State Management: Svelte 5 Runes ($state, $derived)
• Components:
  • IntentWizard.svelte - Phase 1 dynamic Q&A
  • Studio.svelte - Phase 2 image generation grid
  • Gallery.svelte - Phase 3 finalization view
• Styling: Mobile-first CSS with hot pink (#FF1B8D) accent

Backend (Node.js/Express)

• API Endpoints:
  • POST /api/wizard-questions - Generate dynamic wizard questions
  • POST /api/refine - LLM prompt refinement via OpenRouter
  • POST /api/generate - Image generation via Sogni SDK
  • GET /api/balance - Fetch Sogni credit balance and available models (returns mock fallback without credentials)
  • GET /health - Lightweight health check used by the Svelte app on boot
• Security: API keys stored server-side only

🔧 Configuration

Environment Variables

| File | Purpose | Default / Example | | --- | --- | --- | | .env | Frontend API target used by Vite during dev & build | VITE_API_URL=http://localhost:3000 | | server/.env | Credentials & model config for the Express API | SOGNI_USERNAME=your_usernameSOGNI_PASSWORD=your_passwordOPENROUTER_API_KEY=your_api_keyLLM_MODEL=qwen/qwen3-32bIMG_MODEL=flux.1-schnellPORT=3000 |

When deploying, mirror any changes in ENV_CONFIG.md so the team stays aligned across environments.

📱 User Journey

1. Start: Enter your creative vision in "What will you dream?"
2. Refine: Answer dynamic questions to add missing details
3. Generate: View 16 images in a 4×4 grid (4 batches of 4)
4. Select: Choose one or more images to refine or merge
5. Iterate: Continue generating until you find perfection
6. Finalize: Select your masterpiece and download

🎯 Key Interactions

• Single Selection: Generates 4 refined variations
• Multi-Selection: Merges concepts with batch weighting
• Manual Editing: Edit prompts directly in the textarea
• Navigation: Back/Forward through iteration history
• Branching: Automatic when going back then generating

📊 Statistics Tracked

• Total time (12-hour format)
• Duration (formatted as Xh Ym or Xm Ys)
• Total iterations
• Branches explored
• Images generated (iterations × 16)

🎨 Design System

• Primary Color: Hot Pink (#FF1B8D)
• Typography: System fonts, responsive sizing
• Layout: Mobile-first, 4×4 grid on desktop/tablet
• Animations: Confetti, fade-in, loading spinners

🛠️ Development

Build for Production

# Frontend
npm run build

# Backend
cd server
npm start

Project Structure

sogni-vibe/
├── src/                    # Frontend source
│   ├── lib/
│   │   ├── components/    # Svelte components
│   │   ├── state/        # State management
│   │   └── utils/        # Utilities
│   └── styles/           # CSS files
├── server/               # Backend API
│   ├── api/             # API endpoints
│   └── lib/             # Server utilities
└── dist/                # Production build

📝 Notes

• Mock Implementation: Currently uses placeholder images for demo
• Rate Limiting: Implemented but configurable
• No Authentication: MVP version - no user accounts
• Session Storage: Volatile (lost on refresh)

🚧 Future Enhancements

• Real Sogni.ai API integration
• User authentication & credit system
• Persistent storage & shareable links
• Social media sharing
• Advanced model selection
• ControlNet & LoRA support

📄 License

Private - MVP Development

Built with ❤️ for creative exploration