Frameo

AI-powered movie recommendations — decide what to watch next with taste matching, social reviews, and charts.

Frameo is a free, public open-source project. Anyone can use, copy, modify, and build on it under the MIT License — no paid license required.

Tech stack

• Framework: Next.js (App Router)
• Language: TypeScript
• UI: Tailwind CSS + Framer Motion + GSAP
• API: tRPC + TanStack Query
• Auth: Better Auth (email + Google OAuth)
• Database: Supabase Postgres + Drizzle ORM + pgvector
• Cache: Redis (ioredis)
• AI: Google Gemini
• Movies: TMDB (+ OMDB for external ratings)
• Email: Resend
• Media: Cloudinary
• Monitoring: Sentry (optional)
• Deploy: Vercel + Supabase + Redis

Getting started

1. Clone the repo
2. Create a Supabase project and enable pgvector (create extension if not exists vector;)
3. Copy .env.example → .env.local and fill in values (use the Supabase Transaction pooler for DATABASE_URL)
4. npm install
5. Push schema: npm run db:push
6. Create HNSW indexes: run drizzle/0001_hnsw_indexes.sql in the Supabase SQL editor
7. Optional: npm run db:seed-embeddings
8. npm run dev → http://localhost:3000

Scripts

Command	Purpose
npm run dev	Local development
npm run build / start	Production build
npm run db:generate	Generate Drizzle migrations
npm run db:push	Push schema to Supabase
npm run db:migrate	Run migrations
npm run db:studio	Drizzle Studio
npm run db:seed-embeddings	Embed popular/trending TMDB movies

Environment variables

All keys are listed in .env.example. You will need accounts for:

• Supabase — Postgres + pgvector
• TMDB API
• OMDB — optional external ratings
• Google AI Studio — Gemini
• Google Cloud Console — OAuth
• Resend — transactional email
• Cloudinary — avatars
• Redis (local, Upstash, or similar)
• Sentry — optional

Generate BETTER_AUTH_SECRET with a long random string (32+ characters).

Recommendations

Personalized picks use pgvector cosine similarity over movie + user taste embeddings, then Gemini for natural-language reasons. Redis caches results for 30 minutes.

Security

See SECURITY.md for how to report vulnerabilities. Never commit .env.local or real API keys.

Contributing

Issues, ideas, and pull requests are welcome. Fork the repo, make your changes, and open a PR.

License

MIT — free for everyone. See LICENSE.

You may use Frameo for personal or commercial projects, modify it, and redistribute it, as long as you include the copyright and license notice.

Movie data courtesy of TMDB. This product uses the TMDB API but is not endorsed or certified by TMDB.