r8r: Project Documentation & Changelog

This document provides a comprehensive overview of the r8r application, including its file structure, dependencies, setup, and best practices.

Version 2.8.0 (Critical Bug Fixes & Stability)

  • Date: 2025-09-12
  • Summary: This emergency release addresses a series of critical, cascading failures introduced during a flawed attempt to refactor server-side logic. It removes the unnecessary firebase-admin dependency that broke the admin panel, restores all server actions to use the simple and correct client-side SDK, and fixes the subsequent "Related Actors" bug on actor profile pages.
  • Bug Fixes:
    • Removed Failed firebase-admin Implementation: The entire firebase-admin SDK integration, which was the root cause of the admin panel failure, has been completely removed. All server actions that interact with Firestore now correctly use the client-side firebase SDK (getDb()), restoring full functionality to the admin panel and other server-side operations.
    • Fixed "Related Actors" Display: Corrected a critical bug on the actor profile pages where the "Related Actors" section was not appearing. The issue was caused by unreliable date parsing (new Date()) which led to component crashes. The logic has been fixed to use the robust parseISO function from date-fns, ensuring the component renders correctly and the "Related Actors" slider is always visible.
    • Restored Data Health Admin Page: The link to the "Data Health" utility, which is used to manage the "Related Actors" data, has been restored to the admin sidebar.
    • Cleaned Up Documentation: Removed all incorrect and misleading documentation related to firebase-admin and server-side private keys.

Version 2.7.5 (Search Performance Overhaul)

  • Date: 2025-09-11
  • Summary: This release completely re-architects the actor search functionality for near-instantaneous results on common queries and resolves several critical search-related bugs.
  • Improvements & Bug Fixes:
    • Optimized Search with "Fast Path": Implemented a new server-side search strategy. A static list of the most-searched actors is now pre-fetched into an in-memory index when the server starts. Searches for these popular actors are returned instantly without needing a database query.
    • Fixed Multi-Word Search: Resolved a critical bug where searching for actors with multiple words in their name (e.g., "Emma Watson") was failing. The search logic now correctly handles complex queries.
    • Fixed Duplicate Name Results: Corrected an issue where the search would only return one result for names associated with multiple entries (e.g., "Sydney Sweeney"). The search now correctly returns all matching actors.
    • Resolved Hydration Errors: Fixed a React hydration error on the search page caused by a server/client render mismatch in the "Most Searched" component.
    • Fixed Broken Layout: Corrected a layout issue where the Actor Search page was missing the site's header and footer.

Version 2.7.4 (Performance & UI Polish)

  • Date: 2025-09-02
  • Summary: This release significantly improves the performance of the "By Country" discovery page and refines the main navigation for a cleaner look.
  • Improvements:
    • Instant Country Page Load: The /country-match page has been re-architected to be fully static. It now fetches the list of countries only once at build time, resulting in near-instantaneous load times for all users.
    • Navigation UI Cleanup: The main navigation links for "Top 100" and "Bottom 100" have been shortened to "Top" and "Bottom" respectively, saving valuable space in the header, especially on smaller screens.

Version 2.7.3 (Build Stability)

  • Date: 2025-08-31
  • Summary: This release focused on resolving a critical build failure caused by a route conflict.
  • Bug Fixes:
    • Fixed Sitemap Route Conflict: Removed a duplicate sitemap.ts file that was causing the Next.js build to fail due to conflicting metadata routes for /sitemap.xml. This ensures a stable and successful build process.

Version 2.7.2 (Bug Fix)

  • Date: 2025-08-30
  • Summary: This release addresses a critical JavaScript error that could prevent the homepage from rendering correctly under certain conditions.
  • Bug Fixes:
    • Fixed Homepage Rendering Error: Resolved a ReferenceError: currentData is not defined bug on the homepage. The issue was caused by a variable being defined in the wrong scope, which could lead to a crash during the component's render cycle. The fix involved moving the variable definition to the correct scope, ensuring the homepage loads reliably for all users.

Version 2.7.1 (Documentation & UI)

  • Date: 2025-08-26
  • Summary: Replaced the unstyled, static changelog.html page with a new, dynamic page at /changelog. This new page is built as a React component, uses Tailwind CSS for styling to match the rest of the site, and renders the content from this Markdown file.
  • Improvements:
    • New Dynamic Changelog Page: Created /src/app/changelog/page.tsx to display the project's history in a styled, responsive format consistent with the application's design system.
    • Removed Static File: Deleted the old public/changelog.html to streamline the codebase and ensure all content is managed through the Next.js framework.
    • Updated Footer Link: All links in the site footer now correctly point to the new /changelog route.

Version 2.7.0 (Data Integrity & Stability)

  • Date: 2025-08-26
  • Summary: This critical release addresses and resolves a persistent data corruption bug that was causing user vote counts to be reset to zero. It also hardens all data-writing functions to ensure the long-term stability and integrity of the database.
  • Bug Fixes & Improvements:
    • Fixed Vote Reset Bug: Identified and corrected the root cause of vote counts being reset to zero. The saveDataAction (used by admin pages) and batchUpdateActorsAction were modified to explicitly read existing document data and preserve the likeVotes and notVotes fields before saving.
    • Fixed UI Display Bug: Resolved a UI bug in the VotingWidget where an incomplete useEffect dependency array caused vote counts to appear as zero upon re-render, even when the data was correct in the database.
    • Code Cleanup: Removed several duplicated server action functions (saveDataAction, rebuildBirthdayIndexAction) to improve code quality, enforce a single source of truth, and reduce future maintenance risks.
    • Data Mapping Hardened: Corrected the mapMovieDataToMovie and mapTvShowDataToTvShow functions to ensure they always return a valid object (with imageUrl: null if needed) and applied them consistently across all data-fetching endpoints to prevent invalid image data from being saved.

Version 2.6.0 (Data Integrity & Cleanup)

  • Date: 2025-08-25
  • Summary: This release focused on hardening the application's data integrity by preventing incorrect placeholder images from being saved to the database and providing a new tool to clean up any previously corrupted data.
  • New Features:
    • New "Clean Placeholder Images" Utility: Added a one-click utility to the admin dashboard that scans the entire database (actors, movies, tvshows) and removes any incorrect picsum.photos or placehold.co image URLs that were previously saved by mistake.
  • Improvements & Bug Fixes:
    • Fixed Data Mapping Logic: Corrected the root cause of the placeholder bug by updating the mapPersonToActor and mapMovieDataToMovie functions in src/lib/tmdb.ts. These functions now correctly assign null to an item's imageUrl if no valid image is available from the API, preventing bad data from ever being saved to Firestore.
    • Robust Image Fallback: All frontend components (ActorCard, MovieCard, TvShowCard, profile pages, etc.) now correctly display a clean, icon-based placeholder when an imageUrl is null, ensuring a professional UI even with missing data.

Version 2.5.0 (Data Consistency & Maintenance Tools)

  • Date: 2024-07-25
  • Summary: Introduced powerful new admin tools for bulk data management and created a centralized configuration for application-wide constants to improve stability and maintainability.
  • New Features:
    • New "Manage All Actors" Page: Created a new admin page at /admin/actorsList that displays all actors in the database, complete with pagination.
    • Batch Actor Updates: This new page allows admins to select multiple actors and perform a "Refetch Data" action, which updates their information (including fetching a full 20 credits) and sets a lastUpdated timestamp.
    • Data Freshness Filter: The "Manage All Actors" page includes a "Show Only Never Updated" filter, making it easy for admins to identify and process stale data.
    • Automated Data Refresh Action: Created a new server action (updateStaleActorsAction) designed to be run by a cron job. It automatically finds and updates 100 actors whose data is older than 30 days, ensuring the collection stays current over time. A manual trigger for this was added to the admin dashboard.
    • Automated Birthday Indexing: Added a rebuildBirthdayIndexAction that can be run on a schedule to automatically keep the "Happy Birthday" feature on the homepage up-to-date with all actors in the database.
  • Improvements:
    • Centralized Constants: Created a new src/config/constants.ts file to store all application-wide limits (e.g., API fetch limits, pagination sizes, batch sizes). All relevant files were refactored to import from this single source of truth, eliminating "magic numbers" and improving code consistency.
    • Standardized Credit Limit: The "Known For" section for actors is now consistently set to CREDITS_LIMIT (20), resolving a bug where different parts of the app used different limits.
    • Optimized Search: Replaced a slow, client-side search with an efficient, server-side "starts-with" query in Firestore, dramatically improving search performance.

Version 2.4.0 (Admin Tooling & Stability)

  • Date: 2025-08-21
  • Summary: Overhauled the admin panel's cast import functionality to handle massive cast lists without timeouts and improved the UI for a more intuitive workflow.
  • Improvements:
    • Robust Cast Fetching: The logic for fetching a TV show's cast has been corrected to use the aggregate_credits endpoint. This ensures the full series cast list is retrieved accurately, fixing a bug where only a handful of actors were being shown for popular, long-running shows.
    • Batch Saving Logic: The saveDataAction has been refactored to process and save large numbers of actors in smaller chunks (batches of 50). This prevents server timeouts when importing a massive cast from a movie or TV show.
    • Improved Admin UI: The cast import dialog in the admin panel now features a tabbed interface, separating actors who are "Not Yet Saved" from those "Already Saved," providing a much clearer and more efficient workflow for administrators.

Version 2.3.0 (Performance Optimization)

  • Date: 2025-08-17
  • Summary: Optimized the "By Country" page for instant loading by refactoring the data fetching logic.
  • Improvements:
    • Optimized Country List: Created a new, dedicated server action (getUniqueCountriesAction) that calculates the unique list of countries on the server-side. This prevents the page from inefficiently fetching the entire actor collection and processing it in the browser. The page now loads almost instantly.

Version 2.2.0 (SEO-Friendly Actor URLs)

  • Date: 2025-08-11
  • Summary: Kicked off a multi-phase project to improve SEO by implementing human-readable slugs in profile URLs. Phase one focuses exclusively on actor pages.
  • New Features:
    • SEO-Friendly Actor URLs: All actor profile URLs have been updated from /actor/[id] to the more descriptive and SEO-friendly format of /actor/[id]/[slug] (e.g., /actor/278/morgan-freeman).
  • Improvements:
    • New Slugify Utility: Created a reusable slugify function in /src/lib/utils.ts to convert names and titles into URL-safe slugs.
    • Site-Wide Link Updates: Updated all <Link> components pointing to actor profiles across the entire application to use the new slugified URL structure. This includes actor cards, search results, and related actor sections.
    • Routing Structure: The file system route for actor profiles was updated from /src/app/actor/[id]/page.tsx to /src/app/actor/[id]/[name]/page.tsx to support the new URL format.

Version 2.1.0 (Hero Section Overhaul & Critical UI Bug Fixes)

  • Date: 2025-08-11
  • Summary: Complete overhaul of the homepage hero section for better user engagement and fixed several critical UI bugs related to component layout and React context.
  • New Features:
    • Interactive Hero Text: Updated the hero description to include actionable links that directly trigger the "Vote" lightbox and navigate to the "Compare" page, improving user flow.
  • Improvements & Bug Fixes:
    • Language Improvement: Removed the potentially inappropriate word "hot" from all user-facing copy and internal code, replacing it with more neutral terms like "like" and "star."
    • Critical Context Bug Fix: Resolved a recurring React context error (DialogTrigger must be used within Dialog) by restructuring the homepage and ActorVoteLightbox component. This ensures the lightbox can be triggered correctly from multiple elements.
    • Button Layout Fixes: Corrected alignment issues on the "Back to Search" and "Compare" buttons, ensuring icons and text render properly without overlapping or being cut off.

Version 2.0.0 (Admin Tooling & Data Integrity Overhaul)

  • Date: 2024-08-01
  • Summary: Introduced a dedicated "Data Health" utility to the admin panel and significantly improved the data integrity and resilience of the "Related Actors" feature. This release focuses on providing administrators with better tools and making the underlying data connections more robust.
  • New Features:
    • New "Data Health" Page: Added a new admin page at /admin/data-health that scans the actor collection and lists all actors who are missing relatedActorIds. This provides a clear, actionable list for admins to process.
    • Modular "Recalculate Related" Action: Created a new, dedicated server action (recalculateMissingRelatedAction) in its own file (src/app/admin/data-health/actions.ts). This isolates the data health logic from other functions, improving modularity and making the system easier to maintain.
  • Improvements & Bug Fixes:
    • Resilient "Related Actor" Algorithm: The logic for finding related actors has been hardened. It now correctly handles actors who are missing a birthday by falling back to matching by gender. This ensures that every actor can have a list of related profiles calculated, resolving previous errors and improving data completeness.
    • Admin Panel Navigation: Added a new link to the "Data Health" page in the main admin dashboard for easy access.

Version 1.9.0 (Voting System Integrity & Bug Resolution)

  • Date: 2024-07-31
  • Summary: Resolved a critical, persistent bug in the voting system that caused data corruption and prevented users from voting. This release focuses on database integrity and restoring core functionality.
  • Bug Fixes:
    • Fixed Core Voting Logic: Overhauled the voteAction server function. Removed all complex, faulty self-healing and error-correction logic that was causing Firestore transaction failures. The function is now a simple, robust, and atomic operation that correctly records new votes and prevents duplicates.
    • Resolved Data Corruption: Removed all failed admin tools related to fixing vote data. The official resolution is a one-time, manual deletion of the corrupted userVotes collection in Firestore to ensure a clean slate for all users.
    • Admin Panel Cleanup: Removed the non-functional "Fix Corrupted Votes," "Nuke All Vote Receipts," and "Vote Debugger" utilities from the admin panel to streamline the interface and remove broken features.

Version 1.8.0 (Search Re-architecture & Build Fix)

  • Date: 2024-07-30
  • Summary: Addressed a persistent build failure by completely re-implementing the actor search functionality with a focus on component isolation and stability.
  • New Features:
    • Rebuilt Actor Search: Created a new, stable actor search page at /actorSearch. The feature is now built with small, isolated components (SearchInput, SearchResults, SearchResultCard, NoResultsMessage) for improved maintainability.
  • Improvements:
    • Improved Search UX: The link to the actor search page has been moved from the main navigation into a dedicated card within the global DiscoverSection for a more logical user flow.
    • Helpful "No Results" Message: The search page now displays a user-friendly message when no results are found, prompting users to contact an admin if they believe a celebrity is missing.
  • Bug Fixes:
    • Resolved Critical Build Error: Eliminated a recurring TypeScript type error on the previous search page (/search/[...query]) that was causing all production builds to fail. The old, problematic files have been completely removed.

Version 1.7.0 (Favicon & Build Stability)

  • Date: 2024-07-19
  • Summary: Resolved a critical 500 error caused by a favicon conflict with the Firebase App Hosting platform, ensuring build stability and correct icon display.
  • Bug Fixes:
    • Fixed Favicon 500 Error: Diagnosed and fixed a persistent server error for favicon.ico. The root cause was identified as a conflict between the application's icon and a default icon served by the underlying Firebase hosting environment.
    • Resolved Path Conflict: The conflict was resolved by renaming the application's icon to favicon-default.ico and updating the root layout's metadata to point to this new, unique filename. This prevents any path collision with the platform and ensures the correct icon is always served.

Version 1.6.0 (Admin & Data Integrity Improvements)

  • Date: 2024-07-19
  • Summary: Enhanced the admin panel's data fetching capabilities and fixed several critical data integrity issues related to cast members and actor net worth.
  • Improvements:
    • Increased Admin Fetch Limit: The "Fetch" and "Search/Discover" functions in the admin panel now retrieve up to 50 results from TMDB, expanded from the previous limit of 20. This allows admins to work with a much larger set of data at once.
  • Bug Fixes:
    • Fixed Cast Fetching: Corrected a bug where the "View Cast" feature in the admin panel was failing. The logic now correctly handles the specific data structure for cast members from the TMDB API.
    • Corrected Net Worth Filtering: Adjusted the data validation rules to prevent the net worth of major stars (e.g., Tom Cruise) from being incorrectly filtered out due to fluctuating TMDB popularity scores.
    • Preserved Net Worth on Save: Ensured that an actor's netWorth value is correctly persisted to the Firestore database when the actor is saved from the admin panel, following the "fetch once, save forever" principle.

Version 1.5.0 (Responsive Navigation)

  • Date: 2024-07-19
  • Summary: Implemented a responsive hamburger menu for mobile and tablet devices to improve user experience and navigation on smaller screens.
  • New Features:
    • Smart Hamburger Menu: The main navigation now transforms into a hamburger menu on screens smaller than 1024px. This menu slides out from the side and contains all primary and discovery navigation links, ensuring full site accessibility on any device.
  • Improvements:
    • Breakpoint Adjustments: Fine-tuned responsive breakpoints to ensure the desktop navigation bar does not wrap or break on medium-sized screens.
  • Bug Fixes:
    • Fixed a React hydration error caused by server-client mismatch in responsive rendering.
    • Resolved accessibility warnings by adding the required DialogTitle to the mobile menu's underlying sheet component.
    • Corrected a missing key prop error in the navigation component to resolve a React warning.

Version 1.4.0 (Pagination Improvements)

  • Date: 2024-07-19
  • Summary: Added pagination to several discovery pages to improve performance and user experience when browsing large sets of results.
  • Improvements:
    • Paginated Results: Implemented pagination on the "By Rating" (/by-rating) and "Birthday Match" (/birthday-match) pages. Results are now displayed in chunks of 50, making it easier and faster for users to navigate through extensive lists of actors, movies, and TV shows.

Version 1.3.0 (Homepage Personalization)

  • Date: 2024-07-19
  • Summary: Introduced a new personalization feature on the homepage to create a more relevant and engaging user experience.
  • New Features:
    • Geolocation-Based Actor Sorting: The homepage now automatically detects a visitor's country based on their browser's language settings (e.g., "en-US" implies the US). It then prioritizes actors from that country, displaying them at the top of the list on the "Actors" tab. This is a privacy-friendly approach that does not require location tracking permissions.

Version 1.2.0 (New Discovery Features)

  • Date: 2024-07-19
  • Summary: Added a new, visually engaging "Discover" section to all pages and created a dedicated "About Us" page to enhance user navigation and provide more context about the application.
  • New Features:
    • Global Discover Section: Implemented a new DiscoverSection component, which appears above the footer on every page. This section features four visually distinct, interactive cards that link to the main discovery pages: "By Country," "By Birthday," "By Height," and "By Rating," making these key features more prominent and accessible.
    • "About Us" Page: Created a new /about page that offers a unique, dual-tone explanation of the app: a humorous, self-aware take on the name "r8r," followed by a professional summary of the application's purpose and features. A link to this new page has also been added to the site footer.
  • Improvements:
    • Footer Consistency: Restyled the links in the footer into a consistent, bulleted list for improved readability and a cleaner design.
    • Disclaimer Update: Updated the disclaimer page to include information about monetization through affiliate links and advertising.

Version 1.1.0 (Virality Features & UI Polish)

  • Date: 2024-07-19
  • Summary: Introduced new features aimed at increasing user engagement and virality. Added a reusable share widget and a Tinder-style voting lightbox. Also included several UI/UX improvements and critical bug fixes.
  • New Features:
    • Actor Voting Lightbox: Added a "Vote Actors!" button on the homepage that launches a fast-paced, "Tinder-style" voting interface in a lightbox, designed to increase user engagement.
    • Share Widget: Created a new, reusable ShareWidget component for sharing content on Facebook, Twitter, and LinkedIn. This widget has been added to the profile pages for actors, movies, and TV shows to encourage users to share content.
  • Improvements & Bug Fixes:
    • UI Polish: Adjusted the aspect ratio of images on all profile pages from 2/3 to 3/4 to prevent UI elements from being cut off at the bottom of the viewport.
    • Layout Correction: Correctly positioned the new ShareWidget to be on the far right of the title on all profile pages.
    • Critical Bug Fix: Fixed a JSX parsing error on all profile pages (/actor, /movie, /tv) that was causing build failures.

Version 1.0.1 (Documentation Update)

  • Date: 2024-07-19
  • Summary: Created changelog.md and changelog.html to provide detailed project documentation. Updated README.md to be more concise and link to the detailed changelog.

Version 1.0.0 (Initial Release)

  • Date: 2024-07-18
  • Summary: Initial version of the application. Features include user voting, TMDB data integration, Firestore database, admin panel for content management, and multiple discovery pages (Top 100, By Country, By Birthday, etc.).

1. Project Overview

r8r is a "Hot or Not" style web application built with Next.js and Firebase. It allows users to browse and rate actors, movies, and TV shows. The application is designed to be highly interactive, performant, and data-rich, leveraging external APIs and AI-powered content generation.

2. File Structure

The project follows a standard Next.js App Router structure. Here is a detailed breakdown of each important file and directory:

  • **/`
    • README.md: The main project README file with a high-level overview.
    • changelog.md: This file, containing detailed project documentation and version history.
    • next.config.ts: Configuration for Next.js, including image remote patterns for TMDB, Placehold.co, and Google User Content.
    • tailwind.config.ts: Tailwind CSS configuration, including custom fonts and theme settings.
    • package.json: Lists all project dependencies and scripts.
    • apphosting.yaml: Configuration for deployment on Firebase App Hosting.
    • .env: Local environment variables (API keys for Firebase, TMDB, etc.). Must be created locally.
  • **/src/`
    • config/constants.ts: A centralized file for all application-wide constants, such as API limits, pagination sizes, and batch processing numbers.
    • /app/ - Core application routing and pages.
      • globals.css: Global styles, including Tailwind directives and ShadCN theme variables (CSS custom properties).
      • layout.tsx: The root layout for all pages. It sets up the main HTML structure, includes the navigation menu, footer, and wraps the application in the AuthProvider.
      • page.tsx: The component for the homepage, which displays a randomized, paginated grid of content from the collections.
      • actions/: Directory for Server Actions.
        • index.ts: Handles general, non-admin actions.
        • admin.ts: Contains all actions used exclusively by the admin panel.
        • vote.ts: A dedicated file for the critical voteAction to ensure its isolation.
      • /[content-type]/[id]/ - Dynamic route directories for profile pages.
        • actor/[id]/page.tsx: Displays the detailed profile for a single actor.
        • movie/[id]/page.tsx: Displays the detailed profile for a single movie.
        • tv/[id]/page.tsx: Displays the detailed profile for a single TV show.
      • /admin/: Admin panel pages.
        • page.tsx: The main admin dashboard for fetching trending/popular content, searching TMDB, and saving items to the database.
        • actorsList/page.tsx: A powerful utility to view all actors in the database and perform batch updates to refetch their data.
        • birthday-match/page.tsx: A specialized admin tool to discover and import content based on a specific month and year.
        • data-health/page.tsx: A utility page to find and fix actors with missing data, such as relatedActorIds.
        • debug/page.tsx: A tool for testing the voteAction function in real-time.
      • /[discovery-page]/: Public-facing pages for content discovery.
        • top100/page.tsx: Displays the top 100 highest-rated items using a weighted rating system.
        • bottom100/page.tsx: Displays the 100 lowest-rated items.
        • birthday-match/page.tsx: Allows users to find actors/movies/shows from the collection based on birth/release month.
        • by-height/page.tsx: Allows users to find actors based on their height.
        • by-rating/page.tsx: Allows users to find content based on TMDB popularity or vote average.
        • country-match/page.tsx: Displays a list of all countries represented in the actor collection.
        • country/[code]/page.tsx: A dynamic page that lists all actors from a specific country.
      • actorSearch/page.tsx: The page for searching for actors within the collection.
      • /[static-pages]/: Static legal and informational pages.
        • about/page.tsx: Displays information about the application.
        • contact/page.tsx, cookie-policy/page.tsx, disclaimer/page.tsx, etc.
    • /components/ - Reusable React components.
      • actor-card.tsx, movie-card.tsx, tv-show-card.tsx: The main display cards for the homepage.
      • voting-widget.tsx: A modular component encapsulating the "Hot or Not" buttons, progress bar, and voting logic.
      • nav-menu.tsx: The main site navigation bar, which is auth-aware.
      • footer.tsx: The site footer.
      • discover-section.tsx: A visually engaging section to highlight discovery pages.
      • photo-gallery.tsx: An interactive image gallery with a full-screen lightbox, used on profile pages.
      • share-widget.tsx: A component that provides social sharing buttons for profile pages.
      • actor-vote-lightbox.tsx: A component that displays a "Tinder-style" voting interface for actors in a dialog.
      • search-input.tsx, search-results.tsx, search-result-card.tsx, no-results-message.tsx: Components for the actor search functionality.
      • /ui/: All auto-generated ShadCN UI components (Button, Card, Dialog, etc.).
    • /lib/ - Helper functions and third-party service integrations.
      • firebase.ts: Initializes the Firebase app and exports the auth and db instances.
      • tmdb.ts: Contains all logic for fetching and transforming data from external APIs (TMDB, API-Ninjas, Wikipedia).
      • utils.ts: General utility functions, most notably cn for merging Tailwind CSS classes.
    • /hooks/ - Custom React hooks.
      • use-toast.ts: Manages and displays toast notifications.
      • use-pagination.ts: A hook for generating smart pagination controls.
    • /ai/ - Genkit-related code for AI functionality.
      • genkit.ts: Initializes the global Genkit instance and configures plugins.
      • /flows/: Contains all Genkit flows for tasks like generating summaries or endorsements.
    • /context/ - React Context providers.
      • auth-context.tsx: Manages user authentication state across the application, handles sign-in/out, and determines admin status.

3. Project Dependencies

Core Frameworks & Libraries

Package Version Description
next 15.3.3 The core React framework for server-side rendering, routing, and more.
react 18.3.1 The JavaScript library for building user interfaces.
firebase 11.9.1 The Firebase JavaScript SDK for interacting with Firestore and Authentication.
genkit 1.13.0 The core Genkit library for building AI-powered flows.
@genkit-ai/googleai 1.13.0 The Genkit plugin for integrating with Google's Generative AI models (Gemini).

UI & Styling

Package Version Description
@radix-ui/* various A collection of unstyled, accessible UI primitives that power the ShadCN components.
tailwindcss 3.4.1 A utility-first CSS framework for rapid UI development.
lucide-react 0.475.0 A library of simply beautiful and consistent icons.
class-variance-authority 0.7.1 Creates type-safe, variant-based component classes with Tailwind CSS.
clsx 2.1.1 A tiny utility for constructing className strings conditionally.
tailwind-merge 3.0.1 A utility for merging Tailwind CSS classes without style conflicts.
tailwindcss-animate 1.0.7 A Tailwind CSS plugin for adding enter/exit animations.
embla-carousel-react 8.6.0 A bare-bones carousel library used for the photo gallery.
recharts 2.15.1 A composable charting library built on React components.

Forms & State Management

Package Version Description
react-hook-form 7.54.2 A performant, flexible, and extensible library for forms in React.
@hookform/resolvers 4.1.3 Resolvers for react-hook-form to integrate with validation libraries like Zod.
zod 3.24.2 A TypeScript-first schema declaration and validation library.

Utilities

Package Version Description
date-fns 3.6.0 A modern JavaScript date utility library for formatting dates.
dotenv 16.5.0 A module that loads environment variables from a .env file.
rss-parser 3.13.0 A lightweight parser for RSS and Atom feeds, used for the news feed.

Development

Package Version Description
typescript 5 A typed superset of JavaScript that compiles to plain JavaScript.
@types/* various Type definitions for various libraries.
postcss 8 A tool for transforming CSS with JavaScript plugins.
eslint Tooling for code linting.

4. Setup and Deployment

Initial Setup

  1. Environment Variables: Create a .env file in the project root. You will need to populate it with API keys from Firebase and TMDB.
    # Firebase Configuration - from your Firebase project settings
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_firebase_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_firebase_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_firebase_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id

# TMDB API Key - from https://www.themoviedb.org/settings/api
NEXT_PUBLIC_TMDB_API_KEY=your_tmdb_api_key

# API-Ninjas Key - from https://api-ninjas.com/ (Server-side only)
API_NINJAS_KEY=your_api_ninjas_key
  2. Install Dependencies: Run npm install in your terminal.
  3. Run Development Server: Run npm run dev. The application will be available at http://localhost:9002.
  4. Populate Database: The app is empty by default. Navigate to the /admin page, sign in with an admin account (see src/context/auth-context.tsx), and use the "Fetch" or "Search" tools to add actors, movies, and TV shows to your Firestore database.

Deployment

This application is configured for deployment on Firebase App Hosting. The apphosting.yaml file contains the basic configuration. To deploy, you would typically use the Firebase CLI.

5. Advanced Configuration & Best Practices

  • Theming: The application's color scheme is defined using CSS variables in src/app/globals.css, following the ShadCN convention. You can customize the theme by editing the HSL values.
  • Server Actions: All backend logic is handled through Server Actions. These are organized into separate files (admin.ts, vote.ts, index.ts) for clarity and maintainability.
  • AI Content Enrichment: The app uses a "waterfall" approach to get summaries. It first tries to fetch a structured summary from Wikipedia. If that fails, it falls back to a Genkit AI flow to generate one.
  • Scalable Content Loading: The homepage fetches an entire collection, shuffles it on the server, and then stores the shuffled list in the client's state. This provides a truly random and seamless "load more" experience without repeated database calls.

6. Troubleshooting

  • "Failed to fetch" errors: This is almost always due to missing or incorrect API keys in your .env file.
  • Firebase errors: Ensure your Firebase project has Firestore enabled and that your security rules are correctly configured. For authentication, ensure your domain is added to the authorized list in the Firebase Console.
  • Image loading issues: If images from TMDB or other sources are not loading, verify that the hostnames are included in the remotePatterns of your next.config.ts file.
  • Hydration Errors: This typically means there's a mismatch between the server-rendered HTML and the client-side render. Look for code that relies on browser-only APIs (like window or Math.random) and move it into a useEffect hook. Any component using React hooks like useState or useEffect must have the 'use client'; directive.
  • Build Errors with genkit or other dependencies: If you encounter build errors related to third-party modules not being found (e.g., @opentelemetry/exporter-jaeger), check the next.config.ts file. These modules might need to be marked as external in the webpack configuration to prevent them from being bundled on the server.

Discover More

Find your next favorite celebrity in a new way.

By Country

Explore talent from around the globe.

Discover Now

By Birthday

Find stars born in the same month as you.

Discover Now

By Height

See who measures up to your height.

Discover Now

By Rating

Sort by popularity and vote average.

Discover Now

Search & Compare

Find actors and compare their stats side-by-side.

Discover Now