Overall System Architecture

Relevant source files

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

• README.md
• dashboard-next/README.md
• CHANGELOG.md
• dashboard-next/app/api/live-comments/route.ts
• dashboard-next/app/api/stats/route.ts
• dashboard-next/DASHBOARD_STRUCTURE.md
• PERFORMANCE_OPTIMIZATION_REPORT.md
• UNIFIED_SCORING_SYSTEM.md
• config/sentiment_config_v2_optimized.py

The Garuda Sentiment Analysis project is an advanced system designed for real-time and historical sentiment analysis of YouTube comments, with a specific focus on Indonesian football. The architecture is centered around a unique Dual Model System that leverages two different machine learning models to serve distinct use cases: a pre-trained SVM model for analyzing a static, historical dataset, and a powerful Gemini AI model for contextual, real-time analysis of live comments.

This dual approach allows the system to provide fast, consistent, and cost-effective historical insights while also offering highly accurate, context-aware analysis for live social listening. The frontend is a modern Next.js 14 application that provides interactive visualizations, and the backend consists of API routes that handle data fetching, processing, and analysis.

Sources: README.md:3-5, dashboard-next/README.md:3-17, CHANGELOG.md:7-22

High-Level Component Diagram

The system is composed of a Next.js frontend, a set of backend API routes, and multiple data sources. The backend logic is split to handle static data and live data separately, reflecting the dual-model architecture.

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

Dual Model Architecture

The core of the project is its dual-model system, which was introduced in version 5.0.0. This design provides specialized models for historical and real-time data, optimizing for speed, cost, and accuracy depending on the context.

Sources: README.md:7-10, CHANGELOG.md:7-22

Static vs. Live Analysis Flow

The data flow differs significantly between the static and live analysis paths.

Sources: README.md:11-26, dashboard-next/README.md:5-17, dashboard-next/app/api/stats/route.ts:8-20, dashboard-next/app/api/live-comments/route.ts:205-256

Model Comparison

The two models are chosen for their complementary strengths.

Feature	SVM Model	Gemini AI
Data Source	Pre-labeled & cleaned CSV	Real-time & raw YouTube comments
Accuracy	87.5% (domain-specific)	95%+ (general context)
Speed	<1ms per comment	1-2s per comment
Context	Limited	Excellent
Cost	Free (offline)	API quota-based
Reasoning	No	Yes

Sources: README.md:29-37, CHANGELOG.md:12-22

Frontend Architecture

The frontend is a modern, responsive dashboard built with Next.js 14 and the App Router.

Sources: dashboard-next/README.md:21-28

Technology Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Animations: Framer Motion
• Visualizations: Recharts
• Icons: Lucide React

Sources: dashboard-next/README.md:21-28

Page & Navigation Structure

The dashboard is organized into logical sections to facilitate "Progressive Disclosure," where users can move from a high-level overview to deep-dive analysis.

Menu Group	Page	Route	Purpose
ANALYSIS	Dashboard	/	High-level overview of key metrics and sentiment distribution.
	Sentiment Analysis	/sentiment	Detailed analysis of sentiment by target (PSSI, players, etc.).
	Emotion Insights	/emotions	In-depth analysis of emotions found in comments.
	Comments Explorer	/comments	Tool to browse, search, and filter all 19K+ comments.
	Model Performance	/model	Displays technical metrics for the static SVM model.
TOOLS	Live Analyzer	/analytics	Real-time sentiment prediction for a single piece of text.
	Dataset	/dataset	Dataset management and statistics.
	Documentation	/docs	Project documentation.

Sources: dashboard-next/DASHBOARD_STRUCTURE.md:5-100

Design System

The UI is built on a custom design system that emphasizes elegance and performance. Key features include:

• Glassmorphism: Blurred, semi-transparent card backgrounds (bg-slate-900/20 backdrop-blur-xl).
• Gradient Effects: Used for text and backgrounds to create a modern feel.
• CSS-Only Animations: Lightweight animations for fades, slides, and scaling, powered by Framer Motion.
• Responsive Layouts: Mobile-first grid systems ensure usability across devices.

Sources: dashboard-next/DESIGN_SYSTEM.md:3-10, dashboard-next/README.md:92-101

Backend and API Architecture

The backend logic is contained within Next.js API routes, which serve data to the frontend.

Static Data API (/api/stats)

This endpoint is responsible for serving aggregated statistics from the pre-processed CSV file. To optimize performance, it uses a multi-layer caching strategy.

Sources: PERFORMANCE_OPTIMIZATION_REPORT.md:83-96, dashboard-next/app/api/stats/route.ts:8-20

The caching is implemented directly in the route handler:

// dashboard-next/app/api/stats/route.ts

// In-memory cache
let cachedStats: any = null;
let cacheTimestamp = 0;
const CACHE_DURATION = 30 * 1000; // 30 seconds

export async function GET() {
  // ...
  const now = Date.now();
  if (cachedStats && (now - cacheTimestamp) < CACHE_DURATION) {
    return NextResponse.json(cachedStats);
  }
  // ... read file, process data, and cache it
  cachedStats = result;
  cacheTimestamp = Date.now();

  return NextResponse.json(result, {
    headers: {
      'Cache-Control': 'public, s-maxage=300, stale-while-revalidate=600',
    },
  });
}

Sources: dashboard-next/app/api/stats/route.ts:8-20, 68-77, PERFORMANCE_OPTIMIZATION_REPORT.md:15-22

Live Comments API (/api/live-comments)

This endpoint orchestrates the entire real-time analysis pipeline, from fetching comments to filtering and sentiment analysis.

Sources: dashboard-next/app/api/live-comments/route.ts:205-289, README.md:104-116

Data and Scoring System

Data Sources

The system relies on two primary data sources:

1. comments_cleaned_readme_spec.csv: A static, pre-processed file containing over 19,000 labeled comments. This is the foundation for the historical dashboard and SVM model metrics.
2. YouTube Data API v3: Used to fetch live comments in real-time for immediate analysis.

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

Unified Scoring System

To ensure consistency between the different models, a Unified Scoring System is implemented. This system uses a shared lexicon and thresholds for determining sentiment. Even when the Gemini AI is unavailable, the fallback mechanism uses this unified system to provide consistent results.

Key components of the unified system include:

• Consistent Lexicon: A shared dictionary of positive and negative words with assigned weights.
• Unified Thresholds: Standardized ratios (positive_threshold: 0.35) to classify sentiment.
• Model-Specific Adjustments: Minor adjustments are applied to scores to mimic the behavior of different models (e.g., "conservative" for static, "aggressive" for real-time).

Sources: UNIFIED_SCORING_SYSTEM.md:6-34, dashboard-next/app/api/live-comments/route.ts:6-59

The fallback logic demonstrates this unified approach:

// dashboard-next/app/api/live-comments/route.ts
function analyzeSentimentFallback(text: string) {
  // Unified lexicon for consistent fallback scoring
  const sentimentLexicon = { /* ... */ };
  
  // ... calculate scores based on lexicon ...
  
  // Apply unified thresholds
  const totalScore = positiveScore + negativeScore;
  // ...
  const posRatio = positiveScore / totalScore;

  // Unified decision thresholds
  if (posRatio >= 0.35 && posRatio > negRatio) {
    return { sentiment: 'positive', /* ... */ };
  } 
  // ...
}

Sources: dashboard-next/app/api/live-comments/route.ts:6-59

Sentiment Schema

The analysis is based on a multi-layered sentiment framework designed to produce actionable insights. The schema includes layers such as:

• Layer 1: Core Sentiment: positive, negative, neutral.
• Layer 2: Target Kritik: pssi_management, coaching_staff, players.
• Layer 3: Root Cause Analysis: tactical_strategic, technical_skill, mental_psychological.
• Layer 4: Time Perspective: immediate, short_term, long_term.
• Layer 5: Constructiveness: constructive, destructive, hopeful.

Sources: config/sentiment_config_v2_optimized.py:11-205

Performance & Optimization

The system incorporates several key optimizations to ensure a fast and smooth user experience.

Metric	Before	After	Improvement
API Response (cached)	~200ms	<5ms	🚀 97.5% faster
Network Requests	High	-90%	📉 90% reduction
Bundle Size	~450KB	~300KB	📦 33% smaller
Startup Time	~500ms	172ms	⚡ 65% faster

Sources: PERFORMANCE_OPTIMIZATION_REPORT.md:111-118

Key optimization strategies include:

1. Server-Side Caching: In-memory caching on API routes to prevent re-processing of static data.
2. Client-Side Data Fetching (SWR): Optimized SWR configuration to reduce network requests and prevent UI flashing.
3. Code Splitting: Heavy components like charts and AI insights are lazy-loaded using next/dynamic.
4. React Memoization: Components and data are memoized with React.memo and useMemo to prevent unnecessary re-renders.
5. Build Configuration: Next.js build is optimized with swcMinify and package import optimization.

Sources: PERFORMANCE_OPTIMIZATION_REPORT.md:13-77, dashboard-next/OPTIMIZATION_SUMMARY.md:5-32

Conclusion

The architecture of the Garuda Sentiment Analysis project is a well-considered blend of technologies designed to meet two distinct needs: deep historical analysis and immediate real-time monitoring. The Dual Model System is the cornerstone of this design, allowing for an optimal balance of performance, cost, and accuracy. Complemented by a modern frontend, a robust API layer with multi-level caching, and a unified scoring system, the architecture provides a powerful, scalable, and insightful platform for analyzing public sentiment in Indonesian football.

Sources: README.md, dashboard-next/README.md