Frontend API Routes

Relevant source files

The following files were used as context for generating this wiki page:

• dashboard-next/app/api/comments/route.ts
• dashboard-next/app/api/live-comments/route.ts
• dashboard-next/app/api/gemini-sentiment/route.ts
• dashboard-next/app/api/stats/route.ts
• dashboard-next/app/api/analytics/targets/route.ts

The Next.js API routes serve as the backend-for-frontend (BFF) for the sentiment analysis dashboard. They are responsible for fetching, processing, and serving all data required by the UI components. These routes handle two primary types of data: static, pre-processed data read from local CSV files, and live data fetched from external services like the YouTube API and a backend Python AI service.

A key feature across these routes is performance optimization through in-memory caching for static data and a robust fallback system for live data analysis, ensuring the dashboard remains responsive and reliable. The routes encapsulate the logic for data retrieval, transformation, and analysis, providing clean, ready-to-use JSON payloads to the frontend.

Sources: dashboard-next/app/api/stats/route.ts, dashboard-next/app/api/live-comments/route.ts

System Architecture

The API routes act as an intermediary layer between the frontend client and various data sources. Static routes directly access the file system to read CSV data, while live routes orchestrate calls to the YouTube API and a separate backend AI service for sentiment analysis.

The following diagram illustrates the high-level data flow within the system.

API Endpoint Summary

Endpoint	Method	Description	Data Source	Caching
/api/stats	GET	Provides high-level statistics for the dashboard overview.	comments_fixed_labels.csv	5-min in-memory
/api/comments	GET	Fetches a list of comments, with optional search filtering.	comments_cleaned_readme_spec.csv	5-min in-memory
/api/analytics/targets	GET	Aggregates comment data by criticism target.	comments_fixed_labels.csv	None
/api/live-comments	GET	Fetches live comments from a YouTube video, with optional filtering and AI sentiment analysis.	YouTube API & Backend AI	None
/api/gemini-sentiment	POST	Proxies sentiment analysis requests (single or batch) to the backend AI service.	Backend AI Service	None

Sources: dashboard-next/app/api/stats/route.ts, dashboard-next/app/api/comments/route.ts, dashboard-next/app/api/analytics/targets/route.ts, dashboard-next/app/api/live-comments/route.ts, dashboard-next/app/api/gemini-sentiment/route.ts

Detailed Endpoint Analysis

Static Data Endpoints

These endpoints serve data from pre-processed CSV files stored in the project. They employ an in-memory caching strategy to enhance performance by avoiding repeated file I/O and parsing.

GET /api/stats

This route is responsible for calculating and serving the main statistics displayed on the dashboard, such as total comments, sentiment distribution, and emotion breakdowns. It reads from comments_fixed_labels.csv.

Caching Mechanism:
To prevent re-reading and processing the large CSV file on every request, this endpoint uses a 5-minute in-memory cache.

The diagram below shows the caching logic.

GET /api/comments

This endpoint provides a list of comments from the comments_cleaned_readme_spec.csv file. It supports a search query parameter to filter comments based on a keyword.

• Data Source: ../data/processed/comments_cleaned_readme_spec.csv
• Optimization: It parses only the first 1000 rows for performance.
• Caching: Implements the same 5-minute in-memory cache as /api/stats to store the full list of 1000 comments. The search filter is applied to the cached data.
• Response Headers: Sets Cache-Control: public, s-maxage=300, stale-while-revalidate=600 to enable client-side and CDN caching.

Sources: dashboard-next/app/api/comments/route.ts:8-10, dashboard-next/app/api/comments/route.ts:31, dashboard-next/app/api/comments/route.ts:63-65

GET /api/analytics/targets

This route provides aggregated data based on the target_kritik column in the comments_fixed_labels.csv file. It can return either a summary of all targets or detailed statistics for a specific target.

• Functionality:
  1. If no target query parameter is provided, it groups all comments by their target, calculates sentiment percentages for each, and returns a sorted list of the top 8 targets.
  2. If a target is specified, it filters for comments matching that target and returns its total count, sentiment breakdown, and a sample of 5 comments.
• Data Transformation: It maps internal target names (e.g., coaching_staff) to display-friendly names (e.g., Pelatih).

Sources: dashboard-next/app/api/analytics/targets/route.ts:14-23, dashboard-next/app/api/analytics/targets/route.ts:26-44

Live Data & AI Endpoints

These routes interact with external services to provide real-time data and AI-powered analysis.

GET /api/live-comments

This is a complex endpoint that orchestrates fetching and analyzing live YouTube comments.

Request Flow:
The following sequence diagram details the interaction between the client, the API route, and external services.

Key Features:

• Pagination: Fetches multiple pages from the YouTube API to gather up to maxResults comments (default 200).
• Relevance Filtering: If filter is not false, it uses an advanced filterRelevantComments function to score and select comments based on football-related keywords, opinion indicators, and quality checks (e.g., length, spam detection).
• Sentiment Analysis: If sentiment=true, it calls the backend AI service at http://localhost:8000/predict for each comment.
• Fallback Logic: If the backend AI service fails, it uses a local analyzeSentimentFallback function, which performs a lexicon-based sentiment analysis to ensure a response is always provided.

Sources: dashboard-next/app/api/live-comments/route.ts:182-187, dashboard-next/app/api/live-comments/route.ts:70-136, dashboard-next/app/api/live-comments/route.ts:150-178, dashboard-next/app/api/live-comments/route.ts:8-68

POST /api/gemini-sentiment

This route acts as a dedicated proxy to the "Unified Sentiment Scorer" backend service running at http://localhost:8000. It simplifies frontend interaction with the AI model.

• Functionality:
  • Accepts a JSON body with either a single text or an array of texts.
  • If texts is provided, it calls the /predict-batch endpoint on the backend service.
  • Otherwise, it calls the /predict endpoint for a single text.
  • It forwards the model_type parameter, which can be static, realtime, or unified, to control the backend model's behavior.
• Fallback Logic: Similar to /api/live-comments, if the call to the backend service fails, this route executes an internal, lexicon-based fallback analysis to provide a result.

Sources: dashboard-next/app/api/gemini-sentiment/route.ts:6-25, dashboard-next/app/api/gemini-sentiment/route.ts:33-118

Conclusion

The frontend API routes are a critical component of the application's architecture, effectively decoupling the frontend from the complexities of data sourcing and processing. The system demonstrates a thoughtful design by combining high-performance serving of static, cached data with a robust, fault-tolerant system for handling live data analysis. The inclusion of in-memory caching, relevance filtering, and fallback mechanisms ensures a fast, reliable, and intelligent user experience.