Home

Relevant source files

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

• README.md
• package.json
• DESIGN.md
• apps/api/src/index.ts
• apps/web/src/features/ai/components/video-analyzer.component.tsx
• apps/api/src/features/ai/ai.service.ts
• packages/tailwind-config/shared-styles.css
• packages/db/drizzle/0002_amused_wasp.sql
• apps/web/src/features/youtube/components/video-detail.component.tsx

This document provides a technical overview of the Adfluens (YouTube Channel Analyzer) project, a full-stack application designed to analyze YouTube channels and videos using AI to uncover viral strategies and content ideas. The project is structured as a Turborepo monorepo, encompassing a React frontend, an Express/tRPC backend, and several shared packages.

The core brand identity is built on principles of intelligence, fluidity, and trust, with a design philosophy named "The Digital Prism." This philosophy aims to refract a brand's singular identity across the spectrum of social platforms, emphasizing minimalism, precision, and a distinct "Soft Brutalism" aesthetic.

Sources: README.md, DESIGN.md

Project Architecture

The project utilizes a Turborepo monorepo structure managed with pnpm workspaces. This approach organizes the codebase into distinct applications (apps) and shared packages (packages), promoting code reuse and streamlined development.

Sources: README.md:5-39

Monorepo Structure

The diagram below illustrates the high-level organization of the monorepo.

This diagram shows the main applications and shared packages within the monorepo and their primary dependencies.

Sources: README.md:5-39, apps/web/package.json:13-15, apps/api/src/index.ts:9

Key Packages and Applications

Name	Location	Description
web	apps/web/	The frontend application built with React 19, Vite, and Tailwind CSS. It uses TanStack Query for data fetching via tRPC.
api	apps/api/	The backend server built with Express and tRPC. It handles business logic and communication with external APIs like YouTube and Google Gemini.
types	packages/types/	A shared package containing TypeScript types and Zod schemas used by both the frontend and backend.
ui	packages/ui/	A shared UI component library based on shadcn/ui, Radix UI, and Tailwind CSS.
auth	packages/auth/	A shared package for authentication configuration using the better-auth library.
db	packages/db/	A shared package for database schemas and queries using Drizzle ORM.
tailwind-config	packages/tailwind-config/	Shared Tailwind CSS configuration and base styles, implementing the project's design system.

Sources: README.md:7-39, packages/ui/README.md, packages/auth/package.json, packages/db/package.json

Tech Stack

The project is built on a modern, full-stack TypeScript foundation.

Category	Technology	Description
Monorepo	Turborepo, pnpm	For managing the monorepo and optimizing build/development tasks.
Frontend	React 19, Vite, Tailwind CSS	For building a fast and responsive user interface.
Backend	Express, tRPC, Zod	Provides a type-safe API layer between the client and server.
AI	Google Gemini 2.5 Flash	Used for video analysis, with Google Search grounding for context.
Authentication	better-auth	Handles user authentication, including email/password and social providers.
Database	Drizzle ORM, PostgreSQL	Manages database interactions and schema migrations.
Data Fetching	TanStack Query	Manages server state, caching, and data synchronization on the client.

Sources: README.md:41-46, package.json, apps/web/package.json, apps/api/src/features/ai/ai.service.ts:5

Design System: "The Digital Prism"

The project follows a strict design system detailed in DESIGN.md, named "The Digital Prism." It is characterized by "Opinionated Minimalism," "Editorial Precision," and a "Soft Brutalism" visual language.

Sources: DESIGN.md:3-29

Typography

A specific set of fonts is used to create a distinct brand voice, avoiding common choices like Inter or Roboto.

Role	Font Family	Usage
Display	Bricolage Grotesque	Headlines (H1-H3), Hero sections, key data points.
Body	Instrument Sans	UI text, paragraphs, labels, and tables.
Monospace	JetBrains Mono	Code snippets, analytics data values.

These fonts are loaded in the main index.html file.

Sources: DESIGN.md:31-48, apps/web/index.html:21-41

Color Palette

The color palette is high-contrast and is defined using CSS variables for both light and dark modes.

Light Mode ("Paper & Ink")

Role	Color Name	Hex	CSS Variable
Canvas	Alabaster	#FDFDFC	--background
Ink	Carbon	#0A0A0A	--foreground
Primary	International Orange	#FF4F00	--primary
Accent	Lime Acid	#CCFF00	--accent

Dark Mode ("Obsidian & Neon")

Role	Color Name	Hex	CSS Variable
Canvas	Obsidian	#050505	--background
Ink	Mist	#EDEDED	--foreground
Primary	International Orange	#FF4F00	--primary
Accent	Lime Acid	#CCFF00	--accent

The implementation uses OKLCH color functions for P3 display support.

Sources: DESIGN.md:52-83, packages/tailwind-config/shared-styles.css:100-155

Visual Language: "Soft Brutalism"

This aesthetic avoids common SaaS design tropes like soft drop shadows in favor of structural clarity.

• Borders: All structural elements have a 1px solid border.
• Radius: Radii are kept small and tight (2px, 4px, 8px).
• Shadows: Blurred drop shadows are strictly avoided. Instead, hard "offset" shadows or high-contrast outlines are used on hover.
• Texture: A subtle noise texture is applied to backgrounds to reduce "digital sterility."

Sources: DESIGN.md:87-101, packages/tailwind-config/shared-styles.css:302-310

Core Feature: AI Video Analysis

The central feature of the application is the AI-powered analysis of a YouTube video. This is handled by the VideoAnalyzer component on the frontend and the ai service on the backend.

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

Analysis & Chat Flow

The following diagram shows the sequence of events when a user requests a video analysis and asks a follow-up question.

This diagram illustrates the full round-trip for both the initial analysis and the interactive chat feature.

Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:71-84, 101-124, apps/api/src/features/ai/ai.service.ts:11-78, 110-136

Frontend: VideoAnalyzer.component.tsx

This React component is responsible for the entire AI interaction UI.

• State Management: Uses useState to manage loading, error, analysis results, and chat messages.
• Data Fetching: Interacts with the backend via trpcClient to trigger analysis and send chat messages.
• Caching: Caches the analysis result in localStorage using the video ID as a key to prevent redundant API calls.
• UI: Renders different states: an initial call-to-action, a loading spinner, an error message, or the full analysis report and chat interface.

Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:34-60, 71-84

Backend: ai.service.ts

This service contains the core logic for interacting with the Google Gemini AI.

• analyzeVideo function:
  • Constructs a detailed prompt including the video URL, title, description, and top comments.
  • Instructs the AI to use Google Search as a tool (tools: [{ googleSearch: {} }]) to ground its analysis on the actual video content.
  • Specifies a strict JSON output format.
  • Parses the AI's response and extracts grounding sources.
• chatAboutVideo function:
  • Initializes a chat session with a system instruction containing context about the video being discussed.
  • Manages the conversation history.

Sources: apps/api/src/features/ai/ai.service.ts:11-78, 110-136

Backend System

The backend is an Express.js server that exposes a tRPC API.

This diagram shows the middleware and request handling flow in the Express server.

Sources: apps/api/src/index.ts

Key characteristics of the backend include:

• Authentication: Handled by better-auth middleware, which intercepts all requests to /api/auth/*. This middleware is importantly placed before the express.json() parser.
• tRPC: The main API is served at the /trpc endpoint, with procedures defined in appRouter.
• Service Pattern: Business logic is separated from the API routing layer. Routers (*.router.ts) are thin and call methods in service files (*.service.ts).

Sources: apps/api/src/index.ts:25-41, README.md:73-75

Database Schema

The project uses Drizzle ORM with a PostgreSQL database. The schema includes tables for managing users, organizations, and teams, suggesting a multi-tenant or collaborative architecture provided by better-auth.

Sources: packages/db/drizzle/0002_amused_wasp.sql

Entity Relationship Diagram

The diagram below shows the relationships between the main entities in the database.

This ER diagram outlines the core tables for user and organization management.

Sources: packages/db/drizzle/0002_amused_wasp.sql

Development & Tooling

The monorepo is equipped with scripts and configurations to ensure a consistent and efficient development workflow.

Root Scripts

The root package.json defines several turbo-powered scripts that run across the entire monorepo.

Script	Command	Description
dev	turbo dev	Starts all applications (frontend and backend) in development mode.
build	turbo build	Builds all apps and packages for production.
lint	turbo lint	Runs ESLint across the entire codebase.
type-check	turbo type-check	Runs the TypeScript compiler to check for type errors.
format	prettier --write ...	Formats all code using Prettier.
db:migrate	pnpm --filter @repo/db db:migrate	Runs database migrations using Drizzle Kit.

Sources: package.json:6-18

Conclusion

The Adfluens project is a well-architected full-stack application that leverages a modern tech stack to deliver a powerful AI-driven YouTube analysis tool. Its monorepo structure promotes code sharing and maintainability, while the "Digital Prism" design system provides a strong, consistent brand identity. The core functionality is powered by a robust backend service that intelligently uses Google's Gemini AI with search grounding to provide unique and actionable insights for content creators.

Sources: README.md, DESIGN.md