Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Adfluens project is structured as a full-stack monorepo, managed by Turborepo and pnpm workspaces. This architecture facilitates code sharing, streamlined dependency management, and consistent tooling across the entire application stack, which includes a React frontend, an Express/tRPC backend, and several shared libraries. The core principle is to maintain a single source of truth for shared logic, types, and UI components, enhancing development velocity and maintainability.
The architecture is designed with a clear separation of concerns, grouping code into apps (deployable units) and packages (sharable modules). This approach allows for independent development and testing of features while ensuring that the entire system remains cohesive and integrated.
Sources: README.md:5-7, README.md:65-67
Core Tooling
The monorepo's foundation is built on two key technologies: pnpm for package management and Turborepo for build orchestration.
- pnpm Workspaces: Manages dependencies and links local packages within the monorepo. It ensures that
appscan consumepackagesas if they were standard npm dependencies, using theworkspace:*protocol. - Turborepo: A high-performance build system that optimizes running tasks across the monorepo. It understands the dependencies between packages and uses caching to avoid re-running computations, significantly speeding up development and CI/CD pipelines.
Sources: README.md:61-62, package.json:28-30
Project Structure
The repository is organized into two primary directories: apps and packages, a standard convention for Turborepo projects.
youtube-channel-analyzer/
├── apps/
│ ├── web/
│ └── api/
├── packages/
│ ├── types/
│ ├── ui/
│ ├── auth/
│ ├── db/
│ └── tailwind-config/
├── turbo.json
├── pnpm-workspace.yaml
└── package.json
Sources: README.md:7-39
This diagram illustrates the high-level folder structure of the monorepo.
Sources: README.md:7-39
Applications (apps)
The apps directory contains the deployable applications of the project. Each sub-directory is a standalone application that consumes shared code from the packages directory.
| Application | Description | Key Technologies |
|---|---|---|
web | The main frontend application built with React. | React 19, Vite, tRPC |
api | The backend server built with Express and tRPC. | Express, tRPC, Gemini AI |
Sources: README.md:9, README.md:20, apps/web/package.json, apps/api/package.json
Shared Packages (packages)
The packages directory contains modules shared across different applications in the monorepo. This is where the majority of the code reuse happens.
| Package | Description |
|---|---|
@repo/types | Shared TypeScript types and Zod schemas for type-safe API communication. |
@repo/ui | A shared UI component library based on shadcn/ui and Radix UI. |
@repo/auth | Authentication configuration and utilities using better-auth. |
@repo/db | Database schema (Drizzle ORM) and query client. |
@repo/tailwind-config | Shared Tailwind CSS configuration and styles. |
@repo/eslint-config | Shared ESLint configurations for consistent linting rules. |
Sources: README.md:33-39, packages/types/package.json, packages/ui/README.md:3, packages/auth/package.json, packages/db/package.json, eslint.config.js
Dependency Management
Dependencies are managed by pnpm workspaces. Applications and packages declare their dependencies in their respective package.json files. Shared local packages are linked using the workspace:* protocol.
This diagram shows the dependency flow between the applications and the shared packages.
For example, the @repo/web application depends on several shared packages:
// apps/web/package.json
{
"dependencies": {
"@repo/auth": "workspace:*",
"@repo/types": "workspace:*",
"@repo/ui": "workspace:*",
"@tanstack/react-query": "^5.90.12",
"@trpc/client": "^11.7.2",
...
}
}
Sources: apps/web/package.json:12-18
Data Flow: tRPC and Shared Types
The monorepo leverages tRPC for end-to-end typesafe API communication between the frontend and backend. The @repo/types package is crucial for this, as it defines the data structures (e.g., YouTubeVideo, ViralAnalysisResult) and Zod schemas used by both the client and server.
This sequence diagram illustrates a typical data flow when the frontend requests an AI analysis from the backend.
Scripts and Orchestration
The root package.json defines scripts that are run across the entire monorepo using turbo. These scripts delegate tasks to the individual workspaces.
| Script | Description |
|---|---|
dev | Runs all dev scripts in parallel (e.g., starts web and api). |
build | Builds all apps and packages in the correct order. |
lint | Lints all workspaces. |
type-check | Runs TypeScript compiler to check types across the repo. |
db:* | A set of scripts to manage the database schema via drizzle-kit. |
Sources: package.json:6-15
Turborepo's pipeline configuration in turbo.json defines the dependency graph between these tasks, enabling caching and parallel execution. For instance, build depends on the build task of its internal package dependencies (^build).
Sources: README.md:85-89
Design System and Theming
The project employs a centralized design system, documented in DESIGN.md and implemented within the @repo/ui and @repo/tailwind-config packages.
DESIGN.md: The "Digital Prism" design philosophy document that specifies typography, color palettes ("Paper & Ink" for light, "Obsidian & Neon" for dark), and visual language ("Soft Brutalism").@repo/tailwind-config: A shared package containingshared-styles.csswhich implements the design system's CSS variables, fonts, and custom utilities.@repo/ui: A library of React components built with shadcn/ui that consume the shared Tailwind config, providing a consistent look and feel.
This structure ensures that the web application can import and use styled, accessible components with minimal effort, and that the visual identity of the application is consistent and easy to update from a single source of truth.
Sources: DESIGN.md, packages/tailwind-config/shared-styles.css, packages/ui/README.md:3-5
Conclusion
The monorepo architecture of the Adfluens app provides a robust and scalable foundation for a full-stack application. By leveraging Turborepo and pnpm workspaces, it achieves efficient code sharing, consistent development workflows, and end-to-end type safety with tRPC. This structure significantly reduces boilerplate, simplifies dependency management, and allows developers to build and iterate on features across the entire stack with confidence and speed.
Sources: README.md:5-7, README.md:61-62