🌹 ROSE — Personal AI Assistant & Interactive Website Builder

---

📖 Overview

ROSE is a personal AI assistant, research companion, and interactive web application workspace created by Surya. Inspired by the refined typography, clean negative space, and responsive interfaces of modern AI tools like Claude and ChatGPT, ROSE combines fluid conversational intelligence with an in-browser Website Builder and live sandbox, an autonomous Deep Web Research engine, and Supabase Cloud Sync with Google OAuth.

---

✨ Features

• 💬 Conversational AI Streaming: Real-time Server-Sent Events (SSE) streaming powered by the official @google/genai SDK with full markdown formatting, syntax highlighting, and conversational context retention.
• 🌐 In-Browser Website Builder & Sandbox:
  • Ask ROSE to build web apps, landing pages, interactive calculators, or portfolios in natural language.
  • Automatically compiles standalone HTML/CSS/JavaScript bundles.
  • Live split-screen sandbox preview with viewport toggles (Desktop, Tablet, Mobile) and 1-click HTML bundle export.
• 🔍 Autonomous Deep Web Research:
  • Multi-step research mode with real-time progress indicators, search query traces, and cited sources.
  • Generates comprehensive synthesis reports with key takeaways.
• 🔐 Supabase Cloud Sync & Google OAuth:
  • Multi-device chat history and user preferences synchronization.
  • Google Sign-In with Row Level Security (RLS) policies.
  • Frictionless Local Guest Mode: Start chatting immediately with local browser storage even without logging in.
• 📎 Multimodal File Reasoning:
  • Upload images (PNG, JPEG, WebP), PDFs, spreadsheets, and source code files.
  • In-browser file parsing and base64 inline visual transmission directly to Gemini vision.
• 🎙️ Voice Interaction: Built-in speech-to-text dictation and natural speech synthesis audio playback.
• 🎨 Deep Aesthetic Customization:
  • System, Light, and Dark modes with eye-safe contrast.
  • Custom desktop and mobile wallpaper uploads with blur and opacity controls.
  • Typography engine (Plus Jakarta Sans, Newsreader Serif, JetBrains Mono) with font size scaling.
  • Custom accent colors and persona prompts.
• 🛡️ Full-Stack Security Proxy:
  • API keys remain strictly server-side inside Express /api routes and are never leaked to the client browser.

---

🛠️ Tech Stack

Layer	Technologies
Frontend Framework	React 19, TypeScript 5.8, Vite 6
Styling & Animation	Tailwind CSS v4, Motion (motion/react), Lucide React icons
Backend & Proxy	Express 4, Node.js, tsx, esbuild
AI Integration	Official Google Gen AI SDK (@google/genai), OpenRouter API fallback
Authentication & DB	Supabase (@supabase/supabase-js), PostgreSQL, Row Level Security (RLS)
Typography	Plus Jakarta Sans, Newsreader, JetBrains Mono

---

🚀 Getting Started

1. Prerequisites

• Node.js: v18.0.0 or higher (v20+ recommended)
• npm (v9+) or pnpm / yarn
• Git

2. Clone the Repository

git clone https://github.com/imsurya26/rose-ai.git
cd rose-ai

3. Install Dependencies

npm install

4. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Open .env and provide your API keys:

# Required: Free API key from Google AI Studio (https://aistudio.google.com/)
GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"

# Optional: Host URL (default: http://localhost:3000)
APP_URL="http://localhost:3000"

# Optional: Supabase credentials for cloud sync & Google OAuth
VITE_SUPABASE_URL="https://your-project.supabase.co"
VITE_SUPABASE_ANON_KEY="your-anon-public-key"

# Optional: OpenRouter key for alternative open-source models
OPENROUTER_API_KEY=""

5. Run Development Server

npm run dev

Open your browser at 👉 http://localhost:3000.

---

🗄️ Supabase Cloud Sync Setup (Optional)

To enable cross-device conversation sync and Google Sign-In:

1. Create a free project at supabase.com.
2. In your Supabase Dashboard, open the SQL Editor → New Query.
3. Copy the contents of supabase/schema.sql and click Run. This provisions:
   • profiles: User account metadata
   • user_settings: Synchronized themes, fonts, and wallpapers
   • conversations: Chat sessions with tags and pinned status
   • messages: Full conversation histories with attachments and research traces
   • Row Level Security (RLS) policies guaranteeing strict data privacy.
4. Set up Google OAuth:
   • In Supabase, go to Authentication → Providers → Google.
   • Enable Google Sign-In and copy the Callback URL.
   • Create a Web OAuth Client ID in Google Cloud Console and add the callback URL.
   • Paste the Google Client ID & Secret back into Supabase.
   • Under URL Configuration, add your app domain to Redirect URLs.
5. Add VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY to your .env file.

---

📜 Available Scripts

Command	Description
npm run dev	Starts local Express server and Vite development server on port 3000.
npm run build	Compiles client assets (vite build) and bundles server.ts into dist/server.cjs via esbuild.
npm run start	Boots the compiled standalone production server (node dist/server.cjs).
npm run lint	Runs TypeScript type checking (tsc --noEmit).
npm run clean	Removes compiled dist/ directory.

---

📂 Project Architecture

rose-ai/
├── index.html                 # Entry HTML template with fonts and metadata
├── package.json               # Dependencies and build scripts
├── server.ts                  # Express backend proxy (SSE streaming, Gemini SDK)
├── .env.example               # Template environment configuration
├── .gitignore                 # Excluded directories and secret files
├── LICENSE                    # MIT License
├── supabase/
│   └── schema.sql             # Complete PostgreSQL DDL & RLS policies
└── src/
    ├── main.tsx               # Client React DOM entry point
    ├── App.tsx                # Primary state engine, workspace layout, router
    ├── index.css              # Tailwind CSS styles and theme variables
    ├── types.ts               # Shared TypeScript interfaces
    ├── context/
    │   └── AuthContext.tsx    # Supabase authentication provider & session listener
    ├── components/
    │   ├── Aura.tsx           # Ambient status and audio visualizer
    │   ├── ChatInput.tsx      # Text input, file uploads, mode selector
    │   ├── ChatMessage.tsx    # Message bubble, markdown parser, code syntax highlighter
    │   ├── LivePreview.tsx    # Interactive sandbox preview & responsive frame
    │   ├── LoginPage.tsx      # Google OAuth login & guest mode gateway
    │   ├── ModelSelector.tsx  # Multi-model switcher dropdown
    │   ├── ResearchPanel.tsx  # Deep web research progress & citation cards
    │   ├── SettingsModal.tsx  # Appearance, wallpaper, typography, and account settings
    │   ├── Sidebar.tsx        # Conversation archive, search, and session manager
    │   └── WelcomeScreen.tsx  # Hero landing with quick action prompts
    └── lib/
        ├── ai-router.ts       # AI model dispatch engine
        ├── storage.ts         # LocalStorage manager with cloud synchronization
        ├── attachments/       # Document, image, and PDF parser
        ├── preview/           # Live sandbox HTML generator & code extractor
        ├── research/          # Autonomous web exploration engine
        └── supabase/          # Supabase client factory & CRUD operations

---

📤 Pushing to GitHub

To push this codebase to your GitHub repository:

# 1. Initialize git (if not already initialized)
git init

# 2. Stage all files (safe: .env is automatically excluded by .gitignore)
git add .

# 3. Create initial commit
git commit -m "feat: complete release of ROSE AI assistant and website builder"

# 4. Set main branch
git branch -M main

# 5. Link remote repository
git remote add origin https://github.com/imsurya26/rose-ai.git

# 6. Push to GitHub
git push -u origin main

(You can also use the Export to GitHub feature directly from Google AI Studio settings menu).

---

👤 Author

• Surya — @imsurya26

---

📄 License

This project is licensed under the MIT License.