# ReelStack — Complete Documentation for AI Systems

> ReelStack is a free AI-powered web application that extracts recipes, grocery lists, and interactive travel maps from short-form videos on Instagram Reels, YouTube Shorts, and TikTok.

## Product Overview

ReelStack solves a common problem: people discover recipes, restaurants, and travel destinations through short-form video platforms (Instagram Reels, YouTube Shorts, TikTok) but have no easy way to act on that content. ReelStack bridges the gap between "watching a video" and "doing something useful with the information."

### Core Value Proposition

- **For food videos**: Paste a cooking reel URL → get a complete recipe with dish name, ingredients (with quantities and units), and cooking instructions. The extracted ingredients form a grocery shopping list.
- **For travel videos**: Paste a travel reel URL → get all places mentioned or shown, plotted on an interactive map with descriptions, ratings, and directions.

## Technical Architecture

### Frontend
- **Framework**: Flutter Web (Dart 3.6+, Flutter 3.38+)
- **State Management**: Provider
- **Navigation**: go_router
- **Authentication**: Firebase Auth
- **Deployment**: Vercel

### Backend
- **Framework**: FastAPI (Python)
- **Database**: PostgreSQL via SQLAlchemy + Alembic
- **AI/ML**: Google Gemini (multimodal analysis of video frames and audio)
- **Video Processing**: yt-dlp (download), OpenCV (frame extraction), Pillow (image processing)
- **Authentication**: Firebase Admin SDK
- **Deployment**: Docker

### AI Pipeline
1. Video is downloaded using yt-dlp
2. Key frames are extracted with OpenCV
3. Google Gemini classifies content as "food" or "travel"
4. Gemini performs structured extraction based on content type
5. Results are geocoded (travel) or normalized into ingredient quantities (food)
6. Structured data is persisted and returned to the user

## Detailed Feature List

### Video Extraction
- Accepts URLs from Instagram Reels, YouTube Shorts, and TikTok
- Automatic platform detection and video download
- Background processing with real-time status polling
- Supports both public and (where platform-supported) private video URLs

### Food / Recipe Extraction
- Extracts dish names, descriptions, and cuisine type
- Identifies all ingredients with quantities and units
- Normalizes ingredient measurements for grocery list compatibility
- Generates structured recipe data from video analysis
- Supports multiple dishes per video

### Travel / Places Extraction
- Identifies all places, landmarks, and locations mentioned or shown
- Geocodes extracted places to latitude/longitude coordinates
- Displays results on an interactive map
- Generates place cards with names, descriptions, and ratings
- Provides directions and navigation links

### User Features
- Firebase authentication (Google sign-in)
- Save and organize extracted reels, places, and dishes
- View extraction history
- Profile management with delivery address

## API Reference

### Public Endpoints
- `POST /api/extract` — Submit a video URL for extraction
- `GET /api/extract/{job_id}` — Poll extraction status and get results
- `GET /health` — Health check

### Authenticated Endpoints
- `GET /api/users/me` — Get user profile
- `POST /api/users/me` — Create/sync user
- `PUT /api/users/me` — Update user profile
- `GET /api/users/me/reels` — List saved reels
- `POST /api/users/me/reels` — Save a reel
- `DELETE /api/users/me/reels/{job_id}` — Remove a saved reel
- `GET /api/users/me/reels/{job_id}/items` — Get items from a saved reel
- `GET /api/users/me/items` — List saved items (places/dishes)
- `POST /api/users/me/items` — Save an item
- `PUT /api/users/me/items/{item_id}` — Update a saved item
- `DELETE /api/users/me/items/{item_id}` — Remove a saved item
- `GET /api/users/me/history` — View extraction history
- `POST /api/feedback` — Submit feedback

## Use Cases and Examples

### Use Case 1: Cooking Reel to Grocery List
A user sees a butter chicken recipe on Instagram Reels. They copy the reel URL, paste it into ReelStack, and receive:
- Dish: "Butter Chicken"
- Ingredients: chicken thighs (500g), butter (3 tbsp), tomato puree (200ml), cream (100ml), garam masala (1 tsp), ...
- This list can be used directly for grocery shopping.

### Use Case 2: Travel Vlog to Itinerary
A user watches a "3 Days in Bali" YouTube Short. They paste the URL and receive:
- Places: Tegallalang Rice Terraces, Uluwatu Temple, Seminyak Beach, Tanah Lot Temple
- Each place pinned on an interactive map with descriptions and directions
- Effectively creates a travel itinerary from a 60-second video.

### Use Case 3: TikTok Recipe Collection
A food blogger saves multiple TikTok cooking videos. Each one is extracted into structured recipe data with ingredients, making it easy to catalog and reference later.

## Competitive Differentiation

ReelStack is unique in that it:
1. Works across all three major short-form video platforms (Instagram, YouTube, TikTok)
2. Uses multimodal AI (video frames + audio) for extraction, not just text/caption analysis
3. Provides structured, actionable output (not just summaries)
4. Supports both food AND travel content types
5. Offers grocery-list-ready ingredient extraction with quantities
6. Is free to use with no signup required to try

## Contact and Links

- Website: https://reel-stack.vercel.app
- Summary: https://reel-stack.vercel.app/llms.txt