Channel Analyzer

Relevant source files

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

• apps/web/src/features/youtube/views/channel-analyzer.view.tsx
• apps/api/src/features/youtube/youtube.router.ts
• apps/api/src/features/youtube/youtube.service.ts
• apps/web/src/features/youtube/components/analyzer-input.component.tsx
• apps/web/src/features/ai/components/video-analyzer.component.tsx
• apps/api/src/features/ai/ai.service.ts
• packages/db/drizzle/meta/0000_snapshot.json

The Channel Analyzer is a core feature of the Adfluens application that allows users to fetch and display the top-performing videos from a specific YouTube channel. By entering a channel's handle (e.g., @username) or its unique ID, the system retrieves a list of the most viewed videos, serving as the entry point for more detailed, AI-powered analysis on individual videos.

This feature bridges the user interface with the backend data-fetching services, which in turn communicate with the YouTube Data API. The primary goal is to provide users with a quick overview of a channel's most successful content, enabling them to select specific videos for deeper strategic analysis.

Architecture Overview

The Channel Analyzer follows a standard full-stack architecture, with a React frontend communicating with a tRPC backend. The backend service layer is responsible for all interactions with the external YouTube Data API.

The following diagram illustrates the high-level component interactions.

This diagram shows the flow from the user interacting with the ChannelAnalyzerView to the backend YouTube Service fetching data from the YouTube API and returning it to the frontend for display.
Sources: apps/web/src/features/youtube/views/channel-analyzer.view.tsx, apps/api/src/features/youtube/youtube.router.ts, apps/api/src/features/youtube/youtube.service.ts

Frontend Components

The user-facing portion of the Channel Analyzer is composed of several React components that manage state, user input, and data display.

Sources: apps/web/src/features/youtube/views/channel-analyzer.view.tsx, apps/web/src/features/youtube/components/analyzer-input.component.tsx

ChannelAnalyzerView

This is the main view component for the feature, located at the root path /. It orchestrates the data fetching and display logic.

• State Management: It manages the loading status, error messages, and the list of fetched videos using useState.
  • videos: YouTubeVideo[]
  • loading: boolean
  • error: string | null
• Core Logic: The handleAnalyze function is triggered by the AnalyzerInput component. It sets the loading state and calls the fetchChannelVideos utility to initiate the data fetching process from the backend.
• Navigation: Upon clicking a video in the VideoGrid, it uses react-router-dom's navigate function to redirect the user to the detailed video analysis page (/video/:id).

Sources: apps/web/src/features/youtube/views/channel-analyzer.view.tsx:15-18, 20-44, 46-48

AnalyzerInput

A reusable form component for capturing the user's input.

• Props:
  • onAnalyze: (channelId: string) => void: A callback function that is invoked when the form is submitted.
  • isLoading: boolean: A flag to disable the input and show a loading indicator on the button.
• Functionality: It contains a text input for the channel handle/ID and a submit button. The input is styled with an @ sign icon to guide the user.

Sources: apps/web/src/features/youtube/components/analyzer-input.component.tsx

Backend API

The backend exposes tRPC procedures that the frontend consumes to get channel and video data.

Sources: apps/api/src/features/youtube/youtube.router.ts, apps/api/src/features/youtube/youtube.service.ts

API Endpoints

The youtubeRouter defines the endpoints related to YouTube data. The Channel Analyzer feature primarily uses resolveChannel and getVideos.

Procedure	Type	Input Schema	Description
resolveChannel	mutation	z.object({ identifier: z.string().min(1) })	Resolves a channel handle or name to a unique channel ID.
getVideos	query	z.object({ channelId: z.string().min(1) })	Fetches a list of top videos for a given channel ID.
getComments	query	z.object({ videoId: z.string().min(1) })	Fetches comments for a specific video. Used in the subsequent analysis step.
searchVideos	query	videoSearchParamsSchema	Searches for videos globally on YouTube.

Sources: apps/api/src/features/youtube/youtube.router.ts:12-49

Service Logic

The business logic for interacting with the YouTube API resides in youtube.service.ts.

resolveChannelId(identifier)

This function is responsible for converting a user-provided string (handle, name, or ID) into a canonical YouTube Channel ID (UC...).

1. It first checks if the identifier is already a valid channel ID format.
2. If not, it attempts to resolve it as a channel handle (e.g., @handle) via the /channels endpoint of the YouTube API.
3. If that fails, it falls back to using the /search endpoint to find a channel matching the identifier.

Sources: apps/api/src/features/youtube/youtube.service.ts:9-56

fetchChannelVideos(channelId)

This function retrieves the top 20 videos for a given channel ID.

1. It calls the YouTube API's /search endpoint, filtering by channelId and ordering the results by viewCount.
2. It extracts the video IDs from the search results.
3. It makes a second API call to the /videos endpoint with the collected IDs to get detailed statistics for each video (views, likes, comments).
4. Finally, it formats the data into the YouTubeVideo[] type and returns it.

Sources: apps/api/src/features/youtube/youtube.service.ts:61-125

Data Flow

The end-to-end process, from user input to displaying videos, involves a two-step API interaction coordinated by the frontend.

The sequence diagram below details this flow.

AI Analysis Integration

While the Channel Analyzer's primary job is to list videos, its purpose is to feed the AI analysis engine. When a user clicks a video, they are taken to a detail view that uses the VideoAnalyzer component. This component triggers the ai.analyze tRPC mutation, which executes the analyzeVideo service function. This service uses the Google Gemini AI model with Google Search grounding to perform a "viral analysis" of the selected video, its title, description, and comments.

Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:71-84, apps/api/src/features/ai/ai.service.ts:12-47

Database Schema

The project includes a database schema for a channels table, defined using Drizzle ORM. While the provided files for the channel analysis flow do not show direct interaction with this table (data is fetched live from the YouTube API), it is likely intended for caching or storing channel metadata for future use.

The diagram below shows the schema for the channels table.

channels Table Columns

Column	Type	Constraints	Description
id	varchar(255)	Primary Key, Not Null	The unique YouTube channel ID (e.g., UC...).
title	varchar(255)	Not Null	The display title of the channel.
description	text	Nullable	The channel's description.
thumbnail_url	text	Nullable	URL for the channel's thumbnail image.
subscriber_count	integer	Nullable	The number of subscribers.
video_count	integer	Nullable	The total number of videos on the channel.
view_count	integer	Nullable	The total number of views for the channel.
created_at	timestamp	Not Null, Default now()	Timestamp of when the record was created.
updated_at	timestamp	Not Null, Default now()	Timestamp of when the record was last updated.

Sources: packages/db/drizzle/meta/0000_snapshot.json

Summary

The Channel Analyzer is a foundational feature that initiates the user's journey in the application. It combines a simple user interface with a robust backend service to resolve channel identifiers and fetch top-performing video content directly from the YouTube API. This flow efficiently gathers the necessary data for the subsequent, more advanced AI-driven analysis of video strategies, making it a critical component of the overall system.