Arvia - AI-Powered Image to 3D/AR Converter

Transform any image into stunning 3D/AR models with AI-powered conversion. Built with Next.js, FastAPI, and cutting-edge AI models.

✨ Features

• Image to 3D Conversion: Upload any image and convert it to a 3D model using InstantMesh
• AI Prompt Generation: Generate cinematic prompts using Groq AI (Llama 3.3)
• Text to Image: Create images from text prompts using Replicate SDXL
• AR Support: Export models in GLB and USDZ formats for AR experiences
• Authentication: Secure user authentication with Supabase
• Intelligent Caching: 60-80% cache hit rate reduces API costs
• Dark Mode: Beautiful UI with dark mode support

🏗️ Tech Stack

Frontend

• Next.js 16 - React framework with App Router
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Radix UI - Accessible component primitives
• Supabase Auth - User authentication

Backend

• FastAPI - High-performance Python API framework
• Replicate API - InstantMesh (3D conversion) & SDXL (image generation)
• Groq AI - Llama 3.3 for prompt generation
• Supabase - PostgreSQL database and storage
• Pydantic - Data validation

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.13+
• Supabase account
• API keys for: Replicate, Groq, Google Gemini

Installation

1. Clone the repository

git clone https://github.com/yourusername/arvia.git
cd arvia

2. Install dependencies

# Frontend
npm install

# Backend
cd api
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ..

3. Configure environment variables

Frontend (.env.local):

cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Backend (api/.env):

cp api/.env.example api/.env

Edit api/.env:

REPLICATE_API_TOKEN=your_replicate_api_token
GROQ_API_KEY=your_groq_api_key
GOOGLE_API_KEY=your_google_api_key
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

4. Set up database

Run the SQL schema in your Supabase SQL Editor:

# See api/database_setup.sql

5. Run development servers

# Terminal 1: Frontend
npm run dev

# Terminal 2: Backend
cd api
source venv/bin/activate
uvicorn api.main:app --reload --port 8000

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

📦 Deployment

Deploy to Vercel

1. Install Vercel CLI

npm install -g vercel

2. Deploy

vercel

3. Set environment variables in Vercel dashboard

Go to Settings → Environment Variables and add all variables from api/.env.example

4. Deploy to production

vercel --prod

Environment Variables for Production

Required environment variables (set in Vercel dashboard):

• REPLICATE_API_TOKEN
• GROQ_API_KEY
• GOOGLE_API_KEY
• SUPABASE_URL
• SUPABASE_KEY
• SUPABASE_SERVICE_ROLE_KEY

🔧 API Endpoints

All backend endpoints are available at /api/python/*:

• POST /api/python/convert-image - Convert image to 3D model
• GET /api/python/poll-status/{job_id} - Check conversion status
• POST /api/python/generate-prompt - Generate AI prompts
• POST /api/python/generate-image - Generate images from text
• GET /api/python/health - Health check

See API Documentation for detailed endpoint information.

🧪 Testing

# Backend tests
cd api
python test_setup.py        # Unit tests
./test_api.sh               # API integration tests
python test_integration.py  # Full integration tests

� Project Structure

arvia/
├── app/                    # Next.js pages
│   ├── page.tsx           # Home page (image conversion)
│   ├── prompt-generator/  # Prompt generator page
│   ├── signin/            # Sign in page
│   └── signup/            # Sign up page
├── components/            # React components
│   ├── ui/               # UI components
│   └── auth-modal.tsx    # Authentication modal
├── lib/                  # Utilities
│   ├── api.ts           # API client
│   ├── auth-context.tsx # Auth context
│   └── supabase.ts      # Supabase client
├── api/                  # Python backend
│   ├── api/             # FastAPI routes
│   ├── services/        # External API integrations
│   ├── utils/           # Database, cache, storage
│   └── models/          # Pydantic schemas
├── public/              # Static assets
└── vercel.json         # Deployment config

🔐 Security

• ✅ No API keys in code
• ✅ Environment variables for sensitive data
• ✅ Supabase Row Level Security (RLS)
• ✅ CORS properly configured
• ✅ Input validation on all endpoints
• ✅ HTTPS enforced in production

📈 Performance

• Frontend: < 3s page load
• API responses: < 500ms (non-3D endpoints)
• 3D conversion: 10-30s (depending on quality)
• Cache hit rate: 60-80%
• Cost savings: $240-600/year vs traditional hosting

🆘 Troubleshooting

Module not found errors

cd api
pip install -r requirements.txt

Database connection errors

• Verify SUPABASE_URL and SUPABASE_KEY are correct
• Check Supabase project is active
• Ensure database schema is created

Deployment fails

• Ensure all environment variables are set in Vercel
• Check vercel.json is present
• Review Vercel deployment logs

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines.

� License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• InstantMesh for 3D conversion
• Groq for fast AI inference
• Replicate for model hosting
• Supabase for backend infrastructure

---

Built with ❤️ by the Arvia team