# joaquinmayer/youtube-channel-search architecture

> Architecture diagram of the GitHub repository joaquinmayer/youtube-channel-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joaquinmayer/youtube-channel-search
- Repository: https://github.com/joaquinmayer/youtube-channel-search

## Overview

A continuación se presenta una guía detallada para crear un diagrama de arquitectura que refleje con precisión la estructura y funcionalidad de este proyecto, orientado a una aplicación web de búsqueda y exploración de canales de YouTube.

##### Proyecto y propósito
- Tipo de proyecto: Una aplicación web full-stack (basada en Next.js) que permite buscar canales de YouTube, explorar canales relacionados y generar keywords usando IA.
- Propósito: Facilitar la búsqueda de canales especializados en temas específicos, integrando la YouTube Data API v3 para la búsqueda y la API de Google Gemini para generar sugerencias y keywords.

##### Análisis de la estructura de archivos
- Directorio "app": Contiene la configuración del layout (layout.tsx), páginas principales (page.tsx), archivos globales (globals.css) y endpoints de API (dentro de app/api). Esto sugiere el uso del nuevo “app directory” de Next.js.
- Subdirectorios en "app/api": Cada endpoint (youtube-search, related-channels, generate-keywords) se encarga de una funcionalidad específica de la API.
- Directorio "components": Incluye componentes UI (carpetas y archivos en components/ui) que probablemente se usan para construir la interfaz de usuario moderna y responsiva. Muchos de los componentes están basados o se integran con Radix UI.
- Otros directorios: "hooks" para lógica reutilizable, "lib" para utilidades comunes, "public" para imágenes (incluyendo capturas de pantalla) y "styles" para estilos adicionales.

##### Información extraída del README
- Se detallan las funciones clave, como la búsqueda por palabra clave, la búsqueda de canales relacionados, generación de keywords impulsada por IA, historial de búsquedas, y funcionalidades de exportación a CSV.
- Tecnologías: Next.js, TypeScript, Tailwind CSS, Radix UI, React Hook Form, Zod, YouTube Data API v3 y Google Gemini.
- Integraciones externas: Las llaves API para YouTube y Gemini indican que la aplicación se comunica con servicios externos para obtener y procesar datos.

##### Creando el diagrama – Pasos e Instrucciones
a. Componentes principales:
- Cliente / Frontend: Representa la interfaz de usuario creada con Next.js, compuesta por páginas (ej. page.tsx, layout.tsx) y componentes UI (en components/ui).
- API Layer (Backend): Los endpoints de Next.js ubicados en app/api – cada uno dedicado a una función (búsqueda, canales relacionados, generación de keywords).
- Servicios Externos:
- YouTube Data API v3: Usado en el endpoint de búsqueda.
- Google Gemini API: Usado para la generación de keywords con IA.
- Utilidades y Hooks: Componentes reutilizables en "hooks" y lógica de utilidades en "lib", que ayudan en el procesamiento y validación (con ayuda de herramientas como Zod).

b. Relaciones e Interacciones:
- El usuario interactúa con el Frontend (páginas e interfaces de usuario).
- El Frontend realiza solicitudes HTTP (fetch/axios) a los endpoints API internos (app/api/youtube-search, app/api/related-channels, app/api/generate-keywords).
- Cada endpoint actúa como un puente para consumir servicios externos, haciendo llamadas a la YouTube Data API v3 y Google Gemini API.
- Los datos retornados se transforman y se muestran en la interfaz, utilizando componentes UI para representar información (por ejemplo, resultados de búsqueda, sugerencias de keywords, historial).
- Ambos, el Frontend y los endpoints, utilizan utilidades y hooks para gestionar lógica, validaciones y estilos.

c. Patrones y principios arquitectónicos:
- Separación de preocupaciones: Se tiene una clara división entre frontend (interfaz, layout y componentes UI) y backend (API routes).
- API-First: Los endpoints están diseñados para manejar la lógica de negocio, interactuar con servicios externos y procesar los datos.
- Modularidad y reusabilidad: Los componentes UI, hooks y utilidades permiten una arquitectura modular.
- Uso de frameworks modernos: Aprovecha el enrutamiento y renderizado del nuevo “app directory” de Next.js junto con tipado y estilos modernas con TypeScript y Tailwind CSS.

d. Tecnologías relevantes:
- Next.js for rendering y enrutamiento.
- TypeScript para tipado estático y robustez.
- Tailwind CSS para estilos.
- Radix UI para componentes accesibles.
- React Hook Form y Zod para manejo y validación de formularios.
- APIs externas: YouTube Data API v3 y Google Gemini API.

##### Directrices para adaptar el diagrama al proyecto
- Dado que es una aplicación full-stack, destaque la separación entre el cliente (frontend) y el backend (endpoints de API) junto con las integraciones hacia servicios externos.
- Resalte cómo la arquitectura maneja la búsqueda de datos, el procesamiento con IA, y la presentación a través de componentes de la UI.

##### Elementos que el diagrama debe incluir
- Etiquetas claras para cada componente:
- "Frontend (Next.js UI)", "API Endpoints (youtube-search, related-channels, generate-keywords)", "YouTube Data API v3", "Google Gemini API", "Hooks & Utilidades", "Componentes UI (Radix, Tailwind CSS)".
- Flechas direccionales que indiquen:
- flujo de datos desde el usuario hacia el frontend.
- solicitudes de API del frontend a los endpoints.
- conexiones y llamadas salientes de cada endpoint a los servicios externos.
- Componentes UI y frontend (por ejemplo, cajas azules).
- API backend (cajas verdes o naranjas).
- Servicios externos (por ejemplo, cajas grises o con borde punteado).
- Elementos de infraestructura y utilidades (colores neutrales).

##### Resumen gráfico sugerido
- El diagrama debe comenzar con el usuario (navegador) en la parte superior.
- Del usuario, flechas deben apuntar hacia la “Interfaz de usuario de Next.js”, representada con un bloque que incluye "layout.tsx", "page.tsx" y componentes UI.
- Desde este bloque, dibuje líneas que conecten a un bloque “API Endpoints” (dividiendo en tres subcomponentes: youtube-search, related-channels, generate-keywords).
- De cada uno de estos bloques de API, se deben trazar flechas hacia y desde “YouTube Data API v3” y “Google Gemini API”, donde corresponda.
- Finalmente, incluya bloques adicionales etiquetados como “Hooks & Utilidades” y “Static Assets / Estilos” para dejar claro el uso de componentes adicionales como CSS, Tailwind y lógica de utilidades.

Esta estructura modular y claramente etiquetada ayudará a visualizar tanto la arquitectura de la aplicación web como la forma en la que se integran los distintos servicios y tecnologías. Preste especial atención a la relacionalidad y flujo de datos, utilizando flechas y código de colores para una mejor comprensión del rol de cada componente dentro del sistema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User (Browser)"]:::client

    subgraph "Frontend (Next.js UI)"
        nLP["Layout & Pages"]:::client
        nUI["UI Components"]:::client
    end

    subgraph "API Endpoints (Backend)"
        nYT["YouTube Search Endpoint"]:::api
        nRC["Related Channels Endpoint"]:::api
        nGK["Generate Keywords Endpoint"]:::api
    end

    nYTD["YouTube Data API v3"]:::external
    nGGA["Google Gemini API"]:::external

    nHooks["React Hooks & Utilities"]:::util
    nStatic["Static Assets & Styles"]:::static

    U -->|"uses"| nLP
    U -->|"uses"| nUI
    nUI -->|"fetches"| nYT
    nUI -->|"fetches"| nRC
    nUI -->|"fetches"| nGK
    nYT -->|"calls"| nYTD
    nRC -->|"calls"| nYTD
    nGK -->|"calls"| nGGA

    nLP ---|"integrates"| nHooks
    nLP ---|"applies"| nStatic
    nUI ---|"integrates"| nHooks
    nUI ---|"applies"| nStatic

    %% Click Events
    click nLP "https://github.com/joaquinmayer/youtube-channel-search/blob/main/app/layout.tsx"
    click nUI "https://github.com/joaquinmayer/youtube-channel-search/tree/main/components/ui"
    click nYT "https://github.com/joaquinmayer/youtube-channel-search/blob/main/app/api/youtube-search/route.ts"
    click nRC "https://github.com/joaquinmayer/youtube-channel-search/blob/main/app/api/related-channels/route.ts"
    click nGK "https://github.com/joaquinmayer/youtube-channel-search/blob/main/app/api/generate-keywords/route.ts"
    click nHooks "https://github.com/joaquinmayer/youtube-channel-search/tree/main/hooks"
    click nStatic "https://github.com/joaquinmayer/youtube-channel-search/blob/main/styles/globals.css"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-dasharray:5,stroke-width:2px;
    classDef util fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef static fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
