Shared Types (@repo/types)
Relevant source files
The following files were used as context for generating this wiki page:The @repo/types package is a crucial component of the youtube-channel-analyzer monorepo. It serves as the single source of truth for TypeScript type definitions and interfaces shared between the frontend (apps/web) and backend (apps/api) applications. This centralization ensures type safety, prevents data contract mismatches, and facilitates consistent data handling across the entire stack.
The package contains data structures related to the core domains of the application: YouTube data (videos, comments) and AI-generated analysis results. By defining these types in a shared location, both the tRPC backend and the React frontend can rely on the same models for API requests, responses, and internal state management.
Sources: README.md:29-33, packages/types/package.json
Package Architecture
The @repo/types package is designed to be a dependency for other workspaces within the monorepo, primarily the api and web applications. It does not contain any runtime logic, only type definitions.
Sources: apps/api/package.json:18, apps/web/package.json:14
This diagram illustrates the dependency relationship, where both the frontend and backend consume types from the shared package.
Exports
Types are exported individually from the package, allowing consumers to import only the specific types they need. The exports field in package.json maps import paths to the corresponding TypeScript source files.
| Export Path | Source File | Description |
|---|---|---|
./youtube/youtube-video.type | src/youtube/youtube-video.type.ts | Defines the structure for a YouTube video object. |
./youtube/youtube-comment.type | src/youtube/youtube-comment.type.ts | Defines the structure for a YouTube comment object. |
./ai/viral-analysis-result.type | src/ai/viral-analysis-result.type.ts | Defines the shape of the AI analysis report. |
./ai/chat-message.type | src/ai/chat-message.type.ts | Defines the structure for a single chat message. |
| (...and other YouTube types) | src/youtube/*.ts | Additional types for API responses and search params. |
Sources: packages/types/package.json:5-41
Core Data Structures
The types are organized into two main categories: youtube and ai.
YouTube Data Types
These types model the data retrieved from the YouTube Data API.
This diagram shows the main YouTube data entities and their relationship. The properties are inferred from their usage in consumer packages.
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:12-13, apps/api/src/features/ai/ai.service.ts:14-22
YouTubeVideo
Represents a single YouTube video. This type is used as input for the AI analysis.
| Field | Type | Description |
|---|---|---|
id | string | The unique identifier of the video. |
title | string | The title of the video. |
channelTitle | string | The name of the channel that posted the video. |
description | string | The video's description text. |
Sources: apps/api/src/features/ai/ai.service.ts:20-22, apps/web/src/features/ai/components/video-analyzer.component.tsx:12
YouTubeComment
Represents a comment on a YouTube video. A slice of comments is used to provide audience sentiment context to the AI.
| Field | Type | Description |
|---|---|---|
textDisplay | string | The formatted text content of the comment. |
likeCount | number | The number of likes the comment has received. |
Sources: apps/api/src/features/ai/ai.service.ts:16-18, apps/web/src/features/ai/components/video-analyzer.component.tsx:13
AI & Analysis Types
These types define the data structures for interacting with the AI service and for storing the results of the analysis.
This diagram shows the structure of the AI-generated analysis and the chat message format.
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:14-15, apps/api/src/features/ai/ai.service.ts:5-7, 68-78
ViralAnalysisResult
This is the primary data structure for the AI-powered video analysis report. The backend AI service generates this object, and the frontend consumes it for display.
| Field | Type | Description |
|---|---|---|
summary | string | An executive summary of the video's content and strategy. |
hooks | string[] | A list of attention-grabbing elements from the video. |
viralReasons | string[] | An analysis of the psychological reasons the video performed well. |
contentIdeas | string[] | A list of actionable content ideas inspired by the video. |
sources | Source[] | (Optional) A list of web sources used by the AI for grounding its analysis. |
Sources: apps/api/src/features/ai/ai.service.ts:33-39, apps/web/src/features/ai/components/video-analyzer.component.tsx:14, 219-250
ChatMessage
Represents a single message in the interactive chat feature, which allows users to ask follow-up questions about the video analysis.
| Field | Type | Description |
|---|---|---|
role | "user" | "model" | Indicates whether the message is from the user or the AI. |
text | string | The text content of the message. |
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:15, 96
Data Flow: Video Analysis
The shared types are fundamental to the video analysis feature, ensuring data integrity as information flows from the client, through the API, to the external AI service, and back.
This sequence diagram shows how the types are used in the analyze tRPC mutation.
Usage Example
The frontend component VideoAnalyzer demonstrates how these types are imported and used to manage state.
// Source: apps/web/src/features/ai/components/video-analyzer.component.tsx
import type { YouTubeVideo } from "@repo/types/youtube/youtube-video.type";
import type { YouTubeComment } from "@repo/types/youtube/youtube-comment.type";
import type { ViralAnalysisResult } from "@repo/types/ai/viral-analysis-result.type";
import type { ChatMessage } from "@repo/types/ai/chat-message.type";
// ...
export const VideoAnalyzer: React.FC<VideoAnalyzerProps> = ({
video,
comments,
}) => {
const [analysis, setAnalysis] = useState<ViralAnalysisResult | null>(null);
// ...
const [chatMessages, setChatMessages] = useState<ChatMessage[]>([]);
// ...
};
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:2-5, 34, 40
Conclusion
The @repo/types package is a foundational element of the application's architecture. By providing a centralized, strictly-typed set of data contracts, it enhances developer experience, reduces bugs, and ensures that the frontend and backend components can communicate seamlessly and reliably. This approach is key to maintaining a scalable and robust system in a monorepo environment.
Sources: README.md:29-33