Deployment

Relevant source files

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

• vercel.json
• package.json
• requirements.txt
• tests/youtubeService.test.ts
• App.tsx
• README.md

The youtube_notes application is deployed on the Vercel platform as a hybrid application. This architecture combines a static single-page application (SPA) frontend built with React and Vite, and a serverless Python backend that handles API requests. Vercel orchestrates the build process for both parts and routes incoming traffic appropriately.

This deployment strategy allows for a fast, globally distributed frontend, while leveraging Python for specific backend tasks like fetching YouTube transcripts. The entire configuration for this process is defined within the vercel.json file at the root of the repository.

Deployment Architecture

The project is structured as a monorepo where both the frontend and backend code reside. Vercel is configured to handle this structure by defining separate build processes for the Node.js-based frontend and the Python-based backend.

The following diagram illustrates the high-level deployment architecture on Vercel.

This diagram shows that Vercel uses two distinct builders: @vercel/static-build for the React frontend and @vercel/python for the FastAPI backend. All traffic is routed through Vercel's Edge Network, which serves static content or invokes the serverless function based on the request path.

Sources: vercel.json, package.json:10, requirements.txt

Build Process

The build process is defined in vercel.json and triggered by a push to the connected Git repository. Vercel executes two main build steps in parallel.

Sources: vercel.json:2-13

Frontend Build

The frontend is a React application built using Vite. The build configuration in vercel.json instructs Vercel to use the @vercel/static-build builder.

{
  "src": "package.json",
  "use": "@vercel/static-build",
  "config": {
    "distDir": "dist"
  }
}

Sources: vercel.json:8-13

This configuration triggers the vercel-build script defined in package.json, which in turn executes vite build. The output is a set of static files (HTML, CSS, JS) placed in the dist directory, which Vercel then deploys to its edge network.

Script	Command	Description
build	vite build	Standard Vite build command for production.
vercel-build	vite build	The specific script Vercel is configured to run for the frontend build.

Sources: package.json:10-11

Backend Build

The backend is a Python serverless function. Vercel uses the @vercel/python builder for any files located in the api/ directory.

{
  "src": "api/index.py",
  "use": "@vercel/python"
}

Sources: vercel.json:3-6

During the build, Vercel creates a serverless function environment and installs the Python dependencies listed in requirements.txt.

Python Dependencies:

Package	Description
youtube-transcript-api	Fetches transcripts from YouTube.
fastapi	The web framework used to build the API.
uvicorn	ASGI server, used for local development.
pytest	Testing framework for Python code.
httpx	An HTTP client, likely for testing.

Sources: requirements.txt

Routing

Vercel's routing rules direct incoming requests to either the static frontend or the serverless backend function. These rules are defined in the routes array in vercel.json.

This flow shows how Vercel acts as a reverse proxy, directing API traffic to the Python function and all other traffic to the static assets.

Sources: vercel.json:14-22

The specific routing rules are as follows:

Source Path (src)	Destination (dest)	Description
/api/(.*)	/api/index.py	Any request starting with /api/ is rewritten and handled by the Python serverless function.
/(.*)	/$1	All other requests are served from the static build output (the dist directory).

Sources: vercel.json:15-21

This is confirmed by frontend service calls, which target the /api/transcript endpoint to fetch data.

Sources: tests/youtubeService.test.ts:25

Local Development vs. Production

The deployment environment differs significantly from the local development setup.

Local Development

For local development, the package.json provides a dev script that uses concurrently to run the frontend and backend servers simultaneously.

• Frontend: The dev:frontend script runs vite, which starts a hot-reloading development server.
• Backend: The dev:backend script runs python -m uvicorn api.index:app --reload --port 3001, starting a local Python server on port 3001.

The dev:vercel script (vercel dev) can be used to more closely simulate the Vercel production environment locally.

Sources: package.json:6-9

Production

In production, there are no long-running servers.

• The frontend consists of static files served directly from Vercel's CDN.
• The backend is a serverless function that is instantiated on-demand to handle incoming API requests. This is a more scalable and cost-effective approach for handling intermittent traffic.

Sources: vercel.json