The Shows - Movie & TV Show Tracker

A Next.js application for discovering, tracking, and rating movies and TV shows. Built with TypeScript, Tailwind CSS, and Prisma.

Features

• Search & Discovery: Search for movies and TV shows, browse trending and popular content
• Personal Collections: Maintain watchlist, track watched shows, and rate your favorites
• Show Details: View comprehensive information including overview, genres, ratings, and runtime
• Caching: Optimized TMDB API responses with intelligent caching
• Session Management: Simple session-based user management (no auth required for MVP)

Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Database: SQLite (dev) via Prisma ORM
• Styling: Tailwind CSS with custom theme tokens
• UI Components: shadcn/ui components
• API: TMDB (The Movie Database)

Project Structure

Follows the "Always Rules" architecture:

/app                    # Next.js app router pages
  /api                 # API routes
  /[page-name]         # Page directories
    /features          # Page-specific components
    /hooks            # Page-specific hooks
    /utils            # Page-specific utilities
/components            # Reusable components
/lib                   # Global utilities and services
  /api                # API clients
  /cache              # Caching layer
  /db                 # Database client
  /utils              # Utility functions
/theme                 # Design tokens
/prisma               # Database schema

Getting Started

Prerequisites

• Node.js 18+ and npm
• TMDB API key (get one at https://www.themoviedb.org/settings/api)

Installation

1. Clone the repository

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env.local

   Edit .env.local and add your TMDB API key:

   TMDB_API_KEY=your_actual_tmdb_api_key_here
   

4. Initialize the database:

   npx prisma db push

5. Run the development server:

   npm run dev

6. Open http://localhost:5001

Development

Database Management

# Generate Prisma client
npx prisma generate

# Push schema changes to database
npx prisma db push

# Open Prisma Studio
npx prisma studio

Building for Production

npm run build
npm start

Environment Variables

Variable	Description	Required
DATABASE_URL	SQLite database path	Yes
TMDB_API_KEY	TMDB API key	Yes
TMDB_API_BASE_URL	TMDB API base URL	No
REDIS_URL	Redis URL (optional)	No
NEXT_PUBLIC_APP_URL	App URL	No

API Routes

• POST /api/auth/session - Initialize user session
• GET /api/shows/[id]/status - Get show status for user
• POST /api/shows/watchlist - Add/remove from watchlist
• POST /api/shows/watched - Mark as watched/unwatched
• POST /api/shows/rating - Rate a show
• GET /api/user/shows - Get user's shows

Pages

• / - Home page with trending and popular shows
• /search - Search for movies and TV shows
• /show-details/[type]/[id] - Show details page
• /watchlist - User's watchlist
• /history - Watched shows
• /ratings - Rated shows

Performance

• LCP < 2.5s on 4G networks
• API responses cached with TTL
• Optimized image loading with Next.js Image component
• Server-side rendering for initial page loads

Testing

npm test

License

MIT