A premium movie tracking and social platform inspired by the magic of cinema — built with a cinematic design language that treats every screen like a dark theater illuminated by a projector beam.
- Browse & Search — explore trending, popular, and top-rated movies powered by the TMDB API
- Detailed Movie Pages — full cast & crew, OTT availability, ratings, and recommendations
- Smart Recommendations — personalized movie suggestions based on your watch history
- Watch Diary — log every film you watch with dates, ratings, and personal notes
- Star Ratings — rate movies on a granular scale
- Curated Lists — create, manage, and share custom movie collections
- List Discovery — explore lists created by other users in the community
- Viewing Analytics — charts and stats on your watching habits (genres, ratings distribution, watch frequency)
- Year in Review — a cinematic, scroll-driven recap of your year in film (powered by GSAP + ScrollTrigger)
- Achievements — unlock badges and milestones as you track your journey
- Activity Feed — see what friends are watching, rating, and adding to lists
- User Profiles — public profiles showcasing watch stats, favorites, and activity
- Follow System — follow other cinephiles and build your community
- Comments & Likes — discuss films and engage with diary entries and lists
- Cinematic UI — warm near-black palette with tungsten & daylight accent lighting
- 3D Poster Wall — interactive Three.js landing hero with floating movie posters
- Film Grain Overlay — subtle SVG noise for a celluloid texture
- Smooth Animations — Framer Motion page transitions, Lenis smooth scrolling
- Accessible — full
prefers-reduced-motionsupport with opacity-only fallbacks
| Technology | Purpose |
|---|---|
| React 19 + TypeScript | UI framework |
| Vite 7 | Build tool & dev server |
| Tailwind CSS v4 | Styling (CSS-first @theme) |
| Framer Motion | Page transitions & micro-animations |
| React Three Fiber + Three.js | 3D poster wall on landing page |
| Lenis | Smooth scroll |
| Chart.js | Analytics visualizations |
| React Router v7 | Client-side routing |
| Technology | Purpose |
|---|---|
| FastAPI | REST API framework |
| SQLAlchemy | ORM & database modeling |
| PostgreSQL 15 | Primary database |
| Redis 7 | Caching layer |
| PyJWT | Authentication tokens |
| Uvicorn | ASGI server |
| Technology | Purpose |
|---|---|
| Docker Compose | Container orchestration (Postgres + Redis) |
| TMDB API | Movie metadata, posters, and discovery |
- Node.js ≥ 18
- Python ≥ 3.10
- Docker (for PostgreSQL & Redis)
- TMDB API Key — get one free here
git clone https://github.com/Ayush971/CineGraph.git
cd CineGraphdocker-compose up -dThis spins up PostgreSQL (port 5432) and Redis (port 6379).
cd backend
# Create and activate a virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtCreate a .env file in backend/ with:
TMDB_API_READ_ACCESS_TOKEN=your_tmdb_read_access_token
TMDB_API_KEY=your_tmdb_api_key
TMDB_BASE_URL=https://api.themoviedb.org/3
TMDB_IMAGE_BASE_URL=https://image.tmdb.org/t/pStart the server:
python app/main.pyThe API will be live at http://localhost:8000 — interactive docs at /docs.
cd frontend
# Install dependencies
npm install
# Start the dev server
npm run devThe app will be live at http://localhost:5173.
The backend exposes a RESTful API at http://localhost:8000. Key endpoint groups:
| Endpoint | Description |
|---|---|
/auth |
Registration, login, JWT token management |
/movies |
Search, trending, popular, movie details (via TMDB) |
/diary |
Log, edit, and retrieve personal watch diary entries |
/lists |
Create, manage, and discover curated movie lists |
/comments |
Add and retrieve comments on diary entries and lists |
/social |
Follow/unfollow users, activity feed |
/likes |
Like/unlike diary entries, lists, and comments |
/achievements |
User milestones and badges |
/analytics |
Watch statistics, genre breakdowns, rating distributions |
/recommendations |
Personalized movie suggestions |
📖 Full interactive API docs available at
http://localhost:8000/docs(Swagger UI)
CineGraph/
├── frontend/ # React + Vite frontend
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ │ ├── landing/ # 3D poster wall hero
│ │ │ └── ui/ # Design system primitives
│ │ ├── pages/ # Route-level page components
│ │ ├── context/ # React context (Auth, etc.)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── services/ # API client & service layer
│ │ ├── types/ # TypeScript type definitions
│ │ └── utils/ # Utility functions
│ └── package.json
│
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── routes/ # API route handlers
│ │ ├── models/ # SQLAlchemy database models
│ │ ├── schemas/ # Pydantic request/response schemas
│ │ ├── services/ # Business logic layer
│ │ ├── config/ # Database & app configuration
│ │ ├── utils/ # Helper utilities
│ │ └── main.py # Application entry point
│ └── requirements.txt
│
├── docker-compose.yml # PostgreSQL + Redis containers
├── DESIGN_LANGUAGE.md # "PROJECTION" design system spec
└── README.md
CineGraph follows the "PROJECTION" design language — the UI is a dark auditorium, and content is the light:
- Posters are the light source — the UI recedes so imagery can project
- Tungsten acts, Daylight navigates — two accent colors with strict roles (warm gold for actions, cool blue for wayfinding)
- Motion is projection — elements fade up from dark and settle like a film reel stopping, no bouncy cartoon springs
Read the full design spec in DESIGN_LANGUAGE.md
Contributions are welcome! Feel free to open issues or submit pull requests.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source and available under the MIT License.
- Movie data provided by The Movie Database (TMDB)
- Typography: Bricolage Grotesque, Instrument Sans, Spline Sans Mono
Built with 🍿 and a love for cinema