Getting Started

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/index.html
• packages/ui/README.md
• packages/tailwind-config/shared-styles.css
• apps/web/package.json
• apps/api/src/features/ai/ai.service.ts

This document provides instructions for setting up and running the Adfluens (YouTube Channel Analyzer) project. The application is a full-stack platform designed to analyze YouTube channels and videos using AI to uncover viral strategies and content ideas. It is built as a monorepo using Turborepo and pnpm workspaces.

The tech stack includes React (Vite) for the frontend, Express and tRPC for the backend, and Google Gemini for AI analysis. The project follows a feature-based architecture to keep code organized and maintainable.

Sources: README.md:1-5, README.md:28-32

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js: Version 20 or higher.
• pnpm: Version 9 or higher.

You can install pnpm globally via npm if you do not have it.

npm install -g pnpm

Sources: README.md:35-38, package.json:29-31

Installation and Setup

Follow these steps to get the project running locally.

1. Install Dependencies

Clone the repository and install all dependencies from the root directory using pnpm. This will install dependencies for all workspaces (apps and packages).

pnpm install

Sources: README.md:43-46

2. Configure Environment Variables

Create a .env file in the root of the project. This file will hold your API keys required for the application to function.

YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here

• YOUTUBE_API_KEY: Required for fetching data from the YouTube Data API v3.
• GEMINI_API_KEY: Required for the AI analysis features powered by Google Gemini.

Sources: README.md:48-56, apps/api/src/features/ai/ai.service.ts:16

3. Include Fonts

The project uses custom fonts from Google Fonts as defined in the design system. The main web application's index.html already includes the necessary links to preload these fonts.

<!-- Preconnect to Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />

<!-- Display font: Bricolage Grotesque -->
<link
  href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,200..800&display=swap"
  rel="stylesheet"
/>

<!-- Body font: Instrument Sans -->
<link
  href="https://fonts.googleapis.com/css2?family=Instrument+Sans:ital,wght@0,400..700;1,400..700&display=swap"
  rel="stylesheet"
/>

<!-- Monospace font: JetBrains Mono -->
<link
  href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap"
  rel="stylesheet"
/>

Sources: apps/web/index.html:23-47, DESIGN.md:28-44

Running the Application

To start the application for development, run the dev script from the root directory.

pnpm dev

This command, managed by Turborepo, will concurrently start:

• The React frontend at http://localhost:3000
• The Express backend API at http://localhost:3001

The backend exposes a tRPC API at http://localhost:3001/trpc and an authentication endpoint at http://localhost:3001/api/auth.

Sources: README.md:58-67, apps/api/src/index.ts:14, apps/api/src/index.ts:70-73

Project Structure

The project is a Turborepo monorepo, which organizes the codebase into apps and packages.

This diagram shows the high-level structure of the monorepo and the dependencies between the applications and packages.

Sources: README.md:7-27

Applications (apps)

• web: The frontend application built with React, Vite, and Tailwind CSS. It uses TanStack Query and a tRPC client to communicate with the backend.
• api: The backend server built with Express. It provides a tRPC API for business logic and uses Better Auth for handling authentication.

Sources: README.md:9-10, README.md:15-16, apps/web/package.json, apps/api/src/index.ts

Shared Packages (packages)

• @repo/ui: A shared React component library based on shadcn/ui and Radix UI. It provides consistent, accessible, and customizable components like Button, Card, and Input.
• @repo/types: Contains shared TypeScript types and Zod schemas used by both the frontend and backend to ensure type safety across the stack.
• @repo/auth: Manages authentication logic using the better-auth library.
• @repo/db: Handles database interactions, schemas, and migrations using Drizzle ORM.
• @repo/tailwind-config: A shared Tailwind CSS configuration that implements the project's design system, "The Digital Prism".

Sources: README.md:23-26, packages/ui/README.md:3-9, DESIGN.md:5-10

Core Scripts

The root package.json contains several scripts for managing the monorepo.

Script	Description
pnpm dev	Starts all apps in development mode.
pnpm build	Builds all apps and packages for production.
pnpm lint	Lints all code in the monorepo.
pnpm type-check	Runs TypeScript type checking across all packages.
pnpm db:generate	Generates Drizzle ORM migration files.
pnpm db:migrate	Applies pending database migrations.
pnpm db:studio	Opens the Drizzle Studio to view and manage data.

Sources: package.json:6-19

Design System: "The Digital Prism"

The project's visual identity is defined by a design system named "The Digital Prism," which emphasizes "Opinionated Minimalism" and "Soft Brutalism."

• Typography: Uses Bricolage Grotesque for display text and Instrument Sans for body text to create a distinct look.
• Color Palette: A high-contrast palette with "International Orange" (#FF4F00) as the primary action color and "Lime Acid" (#CCFF00) as an accent.
• Visual Language: Avoids drop shadows in favor of 1px solid borders and tight corner radii (2px - 8px) to create a "tactile" feel.

This system is implemented via a shared Tailwind CSS configuration and a set of global CSS variables.

Sources: DESIGN.md:5-26, DESIGN.md:46-70, DESIGN.md:72-81, packages/tailwind-config/shared-styles.css:11-13