Backend: FastAPI Server

Relevant source files

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

• src/api/aggressive_api.py
• src/api/inference_api.py
• src/api/sensitive_api.py
• dashboard-next/app/api/gemini-sentiment/route.ts
• dashboard-next/app/api/live-comments/route.ts
• UNIFIED_SCORING_SYSTEM.md
• README.md

The backend of the Garuda Sentiment Analysis project is built using FastAPI, a modern, high-performance Python web framework. It serves as the analytical engine, exposing various sentiment analysis models through a RESTful API. The primary consumer of this API is the Next.js frontend dashboard. The architecture has evolved to a "Unified Scoring System" to ensure consistent sentiment results across different parts of the application, such as static historical analysis and live comment monitoring.

The backend is composed of several distinct FastAPI applications, with aggressive_api.py representing the most current and comprehensive implementation, known as the "Unified Sentiment Analysis API". This API is designed to be the central point for all sentiment predictions, offering different scoring behaviors (static, realtime, unified) to suit various use cases.

Sources: README.md, UNIFIED_SCORING_SYSTEM.md, src/api/aggressive_api.py

Architecture Overview

The backend consists of a Python-based FastAPI server that listens for requests, processes text data through sentiment analysis models, and returns structured JSON responses. The Next.js frontend does not directly call the FastAPI server from the browser; instead, it uses its own API routes as a Backend-for-Frontend (BFF) layer. These Next.js routes proxy requests to the FastAPI server, which typically runs on http://localhost:8000.

This diagram illustrates the high-level communication flow between the frontend and backend components.

All FastAPI applications are configured with CORSMiddleware to allow requests from any origin (allow_origins=["*"]), which is crucial for development and flexible deployment scenarios.

Sources: src/api/aggressive_api.py:13-19, src/api/sensitive_api.py:13-19, src/api/inference_api.py:16-22

Unified Sentiment Analysis API

The core of the modern backend is the "Unified Sentiment Analysis API" defined in aggressive_api.py. This API centralizes the sentiment analysis logic using a UnifiedSentimentScorer. It is designed to provide consistent yet adaptable scoring based on the context (model_type).

Sources: src/api/aggressive_api.py, UNIFIED_SCORING_SYSTEM.md

API Endpoints

The API exposes several endpoints for health checks, prediction, and model introspection.

Method	Endpoint	Description
GET	/health	Checks the health of the API and returns its status and version.
POST	/predict	Analyzes a single text input and returns its sentiment.
POST	/predict-batch	Analyzes a list of texts in a single request for efficiency.
GET	/model-info	Retrieves information about the loaded UnifiedSentimentScorer model.
GET	/test	Runs a predefined set of test comments through the analyzer for all model types (static, realtime, unified).
GET	/compare-models	Provides a comparison of how different model types score the same set of texts.

Sources: src/api/aggressive_api.py:40-128

Data Models (Pydantic)

The API uses Pydantic models for robust data validation and serialization. These models define the expected structure for API requests and responses.

This class diagram shows the relationships between the Pydantic models used in the API.

Request and Response Flow

When a client sends a request to the /predict endpoint, the FastAPI server receives the TextInput, passes it to the UnifiedSentimentScorer, and formats the result into a SentimentResponse.

The following sequence diagram details the process for a single prediction request.

Client-Side Integration and Fallback

The Next.js frontend communicates with the FastAPI backend via its own API routes, which act as a proxy. This pattern is visible in files like gemini-sentiment/route.ts and live-comments/route.ts. These routes forward requests to http://localhost:8000.

A key feature of this integration is the robust fallback mechanism. If the FastAPI server is unavailable or returns an error, the Next.js API route executes its own local, rule-based sentiment analysis function (analyzeSentimentFallback). This ensures that the application remains functional even if the primary backend fails, providing graceful degradation.

This diagram shows the end-to-end flow, including the fallback path.

The fallback logic uses a weighted lexicon to calculate sentiment scores, providing a reasonably accurate analysis without relying on the external service.

Sources: dashboard-next/app/api/gemini-sentiment/route.ts:32-96, dashboard-next/app/api/live-comments/route.ts:7-60

Other API Modules

The repository contains other FastAPI files, such as sensitive_api.py and inference_api.py. These appear to be earlier or more specialized versions of the sentiment analysis service.

• sensitive_api.py: Implements a SensitiveSentimentAnalyzer.
• inference_api.py: Implements a SmartFallbackAnalyzer.

The aggressive_api.py with its UnifiedSentimentScorer represents the latest architectural direction, aiming to consolidate these different models under a single, configurable system.

Sources: src/api/sensitive_api.py, src/api/inference_api.py

Summary

The FastAPI backend is a critical component of the sentiment analysis system, providing the core analytical power through a well-defined REST API. Its architecture has evolved to a sophisticated "Unified Scoring System" that ensures consistency while allowing for context-specific behavior. The integration with the Next.js frontend is robust, featuring a proxy layer and a crucial fallback mechanism that guarantees service availability and a seamless user experience. This design makes the backend scalable, maintainable, and resilient.