Frontend Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Adfluens frontend is a modern React 19 single-page application (SPA) built with Vite. It serves as the user-facing interface for the YouTube Channel Analyzer, providing tools for analyzing video content and strategies. The architecture emphasizes a feature-based organization, type-safety through TypeScript and tRPC, and a consistent, opinionated design system.
The application is part of a Turborepo monorepo, which allows for shared packages like UI components, types, and configuration. This structure promotes code reuse and consistency between the frontend (apps/web) and backend (apps/api). Data fetching is primarily handled by TanStack Query, which communicates with the backend via a type-safe tRPC client.
Sources: README.md:8-10, README.md:43-44, apps/web/package.json:14-22
Core Technologies & Dependencies
The frontend relies on a curated set of modern libraries to handle rendering, data fetching, styling, and routing.
| Dependency | Version | Description |
|---|---|---|
react | ^19.2.1 | The core UI library for building components. |
vite | ^7.2.6 | The build tool and development server, providing fast HMR and optimized builds. |
tailwindcss | ^4.1.17 | A utility-first CSS framework used for styling, extended by a shared config. |
@tanstack/react-query | ^5.90.12 | A library for server-state management, handling data fetching, caching, and synchronization. |
@trpc/client | ^11.7.2 | Enables type-safe API calls to the tRPC backend without code generation. |
react-router-dom|^7.10.1| Handles client-side routing, including protected routes. |
|@repo/ui|workspace:*| A shared component library based on shadcn/ui and Radix UI, providing consistent UI elements. |
|@repo/types|workspace:*| A shared package containing TypeScript types and Zod schemas used by both frontend and backend. |
|lucide-react|^0.556.0| Provides a set of simple and clean icons. |
Sources: apps/web/package.json:14-28, README.md:43, packages/ui/README.md:3
Project Structure
The apps/web application follows a feature-based directory structure. This approach co-locates related code (components, hooks, utilities) for a specific domain, improving modularity and maintainability.
This diagram illustrates the feature-based organization within the src directory.
features/: Contains self-contained modules for major application features likeyoutubeanalysis andaiinteractions.components/: Feature-specific React components.hooks/: TanStack Query hooks for data fetching related to the feature.utils/: Complex business logic and helper functions.
shared/: Holds code that is reused across multiple features, such as layout components (AppLayout) and protected route logic.lib/: Contains core library initializations and configurations, such as the tRPC client and authentication providers.
Sources: README.md:10-21, README.md:80-84, apps/web/src/shared/components/app-layout.component.tsx
Build & Development
The frontend uses Vite as its build tool and development server, configured in apps/web/vite.config.ts.
Development Server
During development, Vite runs a server on http://localhost:3000. It is configured to proxy API requests to the backend server running on http://localhost:3001. This avoids CORS issues and simplifies development.
// apps/web/vite.config.ts
export default defineConfig({
server: {
port: 3000,
host: "0.0.0.0",
proxy: {
"/trpc": {
target: "http://localhost:3001",
changeOrigin: true,
},
"/api/auth": {
target: "http://localhost:3001",
changeOrigin: true,
},
},
},
// ...
});
Sources: apps/web/vite.config.ts:6-19
Build Process
The pnpm build command, orchestrated by Turborepo, runs tsc && vite build. This first performs a TypeScript type check and then uses Vite to bundle the application for production. The output is placed in the apps/web/dist directory.
Sources: apps/web/package.json:7, apps/web/vite.config.ts:26-29, turbo.json:4-8
Application Initialization & Routing
Entrypoint
The application's entrypoint is apps/web/index.html. This file sets up the basic HTML structure, pre-connects to Google Fonts as specified by the design system, and includes a script to prevent a "flash of unstyled content" (FOUC) by setting the theme (light/dark) before the app renders. The React application is mounted into the <div id="root"></div> element.
Sources: apps/web/index.html:4-14, apps/web/index.html:45-46
Provider Hierarchy
The main App component in apps/web/src/app.tsx wraps the entire application in a series of context providers. This ensures that features like theming, data fetching, API communication, authentication, and tooltips are available throughout the component tree.
This diagram shows the nesting order of providers in the application.
Sources: apps/web/src/app.tsx:45-60
Routing
Routing is managed by react-router-dom. The configuration in app.tsx defines public routes for authentication (/sign-in, /sign-up) and a set of protected routes that require user authentication. Protected routes are rendered within the main AppLayout, which includes the shared sidebar and main content area.
- Public Routes:
/sign-in,/sign-up - Protected Routes:
/(ChannelAnalyzerView)/search(VideoSearchView)/video/:id(VideoDetailView)
Sources: apps/web/src/app.tsx:62-72
Data Fetching with tRPC and TanStack Query
The frontend communicates with the backend using tRPC for type-safe API calls. TanStack Query is used to manage the server state, providing caching, request deduplication, and background refetching.
The QueryClient is configured with a default staleTime of 5 minutes, meaning fetched data will be considered fresh for this duration, preventing unnecessary refetches.
// apps/web/src/app.tsx:25-32
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 5 * 60 * 1000, // 5 minutes
retry: 1,
},
},
});
The following diagram shows the sequence of a component fetching data using a tRPC mutation.
This flow is exemplified in the VideoAnalyzer component, which calls trpcClient.ai.analyze.mutate to get AI insights for a video.
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:78-81, apps/web/src/app.tsx:25-32, README.md:43
Design System: "The Digital Prism"
The project follows a highly opinionated design system named "The Digital Prism," documented in DESIGN.md. The aesthetic is described as "Soft Brutalism," which merges modern SaaS usability with the edge of brutalism.
Core Principles
- Opinionated Minimalism: Remove noise, not features.
- Editorial Precision: Information-dense layouts with strong hierarchy.
- Tactile Digitalism: Responsive controls with distinct borders and high-contrast states.
- No Drop Shadows: Depth is achieved with hard "offset" borders or high-contrast outlines instead of blurred shadows.
Sources: DESIGN.md:17-23, DESIGN.md:90-94
Typography
The application uses a specific font pairing to establish a unique brand voice, avoiding common choices like Inter or Roboto.
| Role | Font Family | Usage |
|---|---|---|
| Display | Bricolage Grotesque | Headlines (H1-H3), key data points |
| Body | Instrument Sans | UI text, paragraphs, labels, tables |
| Monospace | JetBrains Mono | Code snippets, technical identifiers |
These fonts are loaded via Google Fonts in index.html.
Sources: DESIGN.md:27-43, apps/web/index.html:29-42, packages/tailwind-config/shared-styles.css:15-17
Color Palette
The color palette is high-contrast and bold, with distinct themes for 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 |
| Secondary | Deep Forest | #004D40 | --secondary |
| 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 |
| Secondary | Emerald | #10B981 | --secondary |
| Accent | Lime Acid | #CCFF00 | --accent |
These colors are defined as CSS variables in packages/tailwind-config/shared-styles.css and are used throughout the @repo/ui component library.
Sources: DESIGN.md:50-76, packages/tailwind-config/shared-styles.css:201-264
Shared UI Library (@repo/ui)
The @repo/ui package provides a set of shared, accessible, and customizable React components. It is built using shadcn/ui, Radix UI, and Tailwind CSS. This ensures a consistent look and feel across the entire application. Components are exported from the package and consumed directly in the apps/web application.
Sources: packages/ui/README.md:3-9, packages/ui/README.md:20-32