The Video Search feature provides a global search capability within the application, allowing users to find YouTube videos based on keywords. Unlike the Channel Analyzer, which focuses on a single channel's content, Video Search queries the entirety of YouTube. The feature includes robust sorting options and presents results in a clear, grid-based layout, serving as a primary tool for content discovery and competitive analysis.

The feature is accessible via the /search route within the application, which is a protected route requiring user authentication.

Sources: apps/web/src/features/search/views/video-search.view.tsx:16-19, apps/web/src/app.tsx:50

Architecture Overview

The Video Search feature follows a standard client-server architecture, leveraging the frontend apps/web for user interaction and the backend apps/api for data fetching and processing. The frontend initiates a search request via tRPC, which the backend then uses to query the external YouTube Data API v3.

The following diagram illustrates the high-level data flow from the user to the YouTube API and back.

Generating architecture diagram...

Sources: apps/web/src/features/search/views/video-search.view.tsx, apps/api/src/features/youtube/youtube.router.ts, apps/api/src/features/youtube/youtube.service.ts

Frontend Components

The user interface for Video Search is composed of several React components that manage state, user input, and data display.

Sources: apps/web/src/features/search/views/video-search.view.tsx

`VideoSearchView`

This is the main view component for the feature, located at apps/web/src/features/search/views/video-search.view.tsx. It orchestrates the entire search process on the client side.

Key Responsibilities:

Manages component state for the search query (searchQuery), sort option (sortBy), and whether a search has been performed (hasSearched).
Uses TanStack Query's useQuery hook to call the trpc.youtube.searchVideos endpoint. The query is only enabled when searchQuery is set and hasSearched is true.
Renders the SearchInput and SortSelect components for user interaction.
Displays loading, error, and empty states based on the useQuery hook's status.
Passes the fetched video data to the VideoGrid component for rendering.
Handles navigation to the VideoDetailView when a user clicks on a video in the grid.

Sources: apps/web/src/features/search/views/video-search.view.tsx:19-46

`SearchInput`

A reusable component for capturing the user's search query. It includes a text input and a search button, and displays a loading indicator when a search is in progress.

Sources: apps/web/src/features/search/views/video-search.view.tsx:64-68, apps/web/src/features/search/components/search-input.component.tsx

`SortSelect`

A dropdown component that allows users to choose how the search results are sorted. It is populated with options defined in VIDEO_SORT_OPTIONS. When a new option is selected, it updates the sortBy state in VideoSearchView and triggers a refetch of the data if a search has already been performed.

Sources: apps/web/src/features/search/views/video-search.view.tsx:88-92, apps/web/src/features/search/components/sort-select.component.tsx, packages/types/src/youtube/video-sort-option.enum.ts

`VideoGrid`

A presentational component responsible for displaying the list of YouTubeVideo objects in a responsive grid layout. It receives the video data and an onVideoClick handler from its parent.

Sources: apps/web/src/features/search/views/video-search.view.tsx:149-151, apps/web/src/features/youtube/components/video-grid.component.tsx

Backend API

The backend logic resides in the apps/api package and is exposed via a tRPC router.

tRPC Endpoint: `youtube.searchVideos`

This is a protectedProcedure, meaning it requires user authentication. It handles incoming search requests from the client.

Path: youtube.searchVideos
File: apps/api/src/features/youtube/youtube.router.ts

The endpoint's input is validated against the videoSearchParamsSchema.

Parameter	Type	Description	Default
`query`	`string`	The search keyword(s). Must not be empty.	(none)
`sortBy`	`VideoSortOption`	The sorting criteria for the results.	`views`
`maxResults`	`number` (1-50)	The maximum number of results to return.	`20`

Sources: apps/api/src/features/youtube/youtube.router.ts:44-54, packages/types/src/youtube/video-search-params.type.ts:9-14

Service Logic: `searchVideos`

The core business logic is implemented in the searchVideos function within apps/api/src/features/youtube/youtube.service.ts. This function communicates with the official YouTube Data API v3.

The process involves two main steps:

Search for Video IDs: It first calls the YouTube /search endpoint. The order parameter for this API call is determined by the sortBy input. The YouTube API natively supports ordering by date, viewCount, and relevance.
Fetch Video Statistics: The list of video IDs from the first step is used to make a second call to the YouTube /videos endpoint. This call retrieves detailed statistics for each video, including likeCount and commentCount.
Custom Sorting: If the user requested to sort by likes or comments (which are not supported as order parameters in the YouTube Search API), the service performs a manual sort on the array of videos after all statistics have been fetched.

Sources: apps/api/src/features/youtube/youtube.service.ts:184-279

Data Flow

The following sequence diagram details the entire flow of a video search request, from the user's action to the final display of results.

Generating architecture diagram...

Sources: apps/web/src/features/search/views/video-search.view.tsx:29-36, apps/api/src/features/youtube/youtube.router.ts:44-54, apps/api/src/features/youtube/youtube.service.ts:184-279

Data Models & Types

Search Parameters

The search parameters are defined by a Zod schema to ensure type safety and validation between the client and server.

// packages/types/src/youtube/video-search-params.type.ts
export const videoSearchParamsSchema = z.object({
  query: z.string().min(1, "Search query is required"),
  sortBy: videoSortOptionSchema.default(VIDEO_SORT_OPTIONS.VIEWS),
  maxResults: z.number().min(1).max(50).default(20),
});

Sources: packages/types/src/youtube/video-search-params.type.ts:9-14

Sort Options

The available sorting options are defined in an enum-like object, with corresponding display labels for the UI.

Value	Label	Native YouTube API Support
`views`	Most Views	Yes (`viewCount`)
`likes`	Most Likes	No (Sorted in service)
`comments`	Most Comments	No (Sorted in service)
`date`	Newest First	Yes (`date`)
`relevance`	Most Relevant	Yes (`relevance`)

Sources: packages/types/src/youtube/video-sort-option.enum.ts:6-12, 24-30, apps/api/src/features/youtube/youtube.service.ts:190-199, 275-277

Resources

AI code review
Bug Bench
AI coding statistics
Coding standards
Agents
Wikis

View on GitHub

Back to directory

Repository

Monsoft-Solutions/adfluens-app

Overview

Home Getting Started Environment Variables

System Architecture

Monorepo Architecture Frontend Architecture Backend Architecture Full-Stack Data Flow

Core Features

User Authentication Video Search AI-Powered Video Analysis Channel Analyzer Video Details View

Data Management

Database Schema ORM and Migrations (Drizzle)

Frontend (apps/web)

Client State Management Theming

Frontend Components

Shared UI Library (@repo/ui)Layout Components Protected Routes

Backend (apps/api)

tRPC API Overview YouTube API Router AI API Router Server-Side Authentication (@repo/auth)

Integrations

YouTube Data API Integration Google Gemini API Integration

Developer Guides

Shared Types (@repo/types)Linting and Code Style Adding a New Feature

Deployment

Building for Production Deployment Guide

Video Search

Relevant source files

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

apps/web/src/features/search/views/video-search.view.tsx
apps/web/src/features/search/components/search-input.component.tsx
apps/web/src/features/search/components/sort-select.component.tsx
apps/web/src/features/youtube/components/video-grid.component.tsx
apps/api/src/features/youtube/youtube.router.ts
apps/api/src/features/youtube/youtube.service.ts
packages/types/src/youtube/video-search-params.type.ts
packages/types/src/youtube/video-sort-option.enum.ts
apps/web/src/app.tsx

The feature is accessible via the /search route within the application, which is a protected route requiring user authentication.

Sources: apps/web/src/features/search/views/video-search.view.tsx:16-19, apps/web/src/app.tsx:50

Architecture Overview

The following diagram illustrates the high-level data flow from the user to the YouTube API and back.

Generating architecture diagram...

Sources: apps/web/src/features/search/views/video-search.view.tsx, apps/api/src/features/youtube/youtube.router.ts, apps/api/src/features/youtube/youtube.service.ts

Frontend Components

The user interface for Video Search is composed of several React components that manage state, user input, and data display.

Sources: apps/web/src/features/search/views/video-search.view.tsx

`VideoSearchView`

This is the main view component for the feature, located at apps/web/src/features/search/views/video-search.view.tsx. It orchestrates the entire search process on the client side.

Key Responsibilities:

Manages component state for the search query (searchQuery), sort option (sortBy), and whether a search has been performed (hasSearched).
Uses TanStack Query's useQuery hook to call the trpc.youtube.searchVideos endpoint. The query is only enabled when searchQuery is set and hasSearched is true.
Renders the SearchInput and SortSelect components for user interaction.
Displays loading, error, and empty states based on the useQuery hook's status.
Passes the fetched video data to the VideoGrid component for rendering.
Handles navigation to the VideoDetailView when a user clicks on a video in the grid.

Sources: apps/web/src/features/search/views/video-search.view.tsx:19-46

`SearchInput`

A reusable component for capturing the user's search query. It includes a text input and a search button, and displays a loading indicator when a search is in progress.

Sources: apps/web/src/features/search/views/video-search.view.tsx:64-68, apps/web/src/features/search/components/search-input.component.tsx

`SortSelect`

Sources: apps/web/src/features/search/views/video-search.view.tsx:88-92, apps/web/src/features/search/components/sort-select.component.tsx, packages/types/src/youtube/video-sort-option.enum.ts

`VideoGrid`

A presentational component responsible for displaying the list of YouTubeVideo objects in a responsive grid layout. It receives the video data and an onVideoClick handler from its parent.

Sources: apps/web/src/features/search/views/video-search.view.tsx:149-151, apps/web/src/features/youtube/components/video-grid.component.tsx

Backend API

The backend logic resides in the apps/api package and is exposed via a tRPC router.

tRPC Endpoint: `youtube.searchVideos`

This is a protectedProcedure, meaning it requires user authentication. It handles incoming search requests from the client.

Path: youtube.searchVideos
File: apps/api/src/features/youtube/youtube.router.ts

The endpoint's input is validated against the videoSearchParamsSchema.

Parameter	Type	Description	Default
`query`	`string`	The search keyword(s). Must not be empty.	(none)
`sortBy`	`VideoSortOption`	The sorting criteria for the results.	`views`
`maxResults`	`number` (1-50)	The maximum number of results to return.	`20`

Sources: apps/api/src/features/youtube/youtube.router.ts:44-54, packages/types/src/youtube/video-search-params.type.ts:9-14

Service Logic: `searchVideos`

The core business logic is implemented in the searchVideos function within apps/api/src/features/youtube/youtube.service.ts. This function communicates with the official YouTube Data API v3.

The process involves two main steps:

Search for Video IDs: It first calls the YouTube /search endpoint. The order parameter for this API call is determined by the sortBy input. The YouTube API natively supports ordering by date, viewCount, and relevance.
Fetch Video Statistics: The list of video IDs from the first step is used to make a second call to the YouTube /videos endpoint. This call retrieves detailed statistics for each video, including likeCount and commentCount.
Custom Sorting: If the user requested to sort by likes or comments (which are not supported as order parameters in the YouTube Search API), the service performs a manual sort on the array of videos after all statistics have been fetched.

Sources: apps/api/src/features/youtube/youtube.service.ts:184-279

Data Flow

The following sequence diagram details the entire flow of a video search request, from the user's action to the final display of results.

Generating architecture diagram...

Sources: apps/web/src/features/search/views/video-search.view.tsx:29-36, apps/api/src/features/youtube/youtube.router.ts:44-54, apps/api/src/features/youtube/youtube.service.ts:184-279

Data Models & Types

Search Parameters

The search parameters are defined by a Zod schema to ensure type safety and validation between the client and server.

// packages/types/src/youtube/video-search-params.type.ts
export const videoSearchParamsSchema = z.object({
  query: z.string().min(1, "Search query is required"),
  sortBy: videoSortOptionSchema.default(VIDEO_SORT_OPTIONS.VIEWS),
  maxResults: z.number().min(1).max(50).default(20),
});

Sources: packages/types/src/youtube/video-search-params.type.ts:9-14

Sort Options

The available sorting options are defined in an enum-like object, with corresponding display labels for the UI.

Value	Label	Native YouTube API Support
`views`	Most Views	Yes (`viewCount`)
`likes`	Most Likes	No (Sorted in service)
`comments`	Most Comments	No (Sorted in service)
`date`	Newest First	Yes (`date`)
`relevance`	Most Relevant	Yes (`relevance`)

Sources: packages/types/src/youtube/video-sort-option.enum.ts:6-12, 24-30, apps/api/src/features/youtube/youtube.service.ts:190-199, 275-277

Resources

AI code review
Bug Bench
AI coding statistics
Coding standards
Agents
Wikis

View on GitHub

Video Search

Architecture Overview

Frontend Components

VideoSearchView

SearchInput

SortSelect

VideoGrid

Backend API

tRPC Endpoint: youtube.searchVideos

Service Logic: searchVideos

Data Flow

Data Models & Types

Search Parameters

Sort Options

Video Search

Architecture Overview

Frontend Components

VideoSearchView

SearchInput

SortSelect

VideoGrid

Backend API

tRPC Endpoint: youtube.searchVideos

Service Logic: searchVideos

Data Flow

Data Models & Types

Search Parameters

Sort Options

`VideoSearchView`

`SearchInput`

`SortSelect`

`VideoGrid`

tRPC Endpoint: `youtube.searchVideos`

Service Logic: `searchVideos`

`VideoSearchView`

`SearchInput`

`SortSelect`

`VideoGrid`

tRPC Endpoint: `youtube.searchVideos`

Service Logic: `searchVideos`