Vercel Deployment Architecture

Overview

The Next.js monorepo deployment architecture leverages a tri-platform integration between Charles Schwab's development infrastructure, GitHub Enterprise for source control, and Vercel for hosting and deployment. This architecture enables continuous deployment, preview environments, and global content delivery while maintaining security and compliance requirements.

System Architecture

The deployment ecosystem consists of three primary platforms working in concert to deliver applications from code commit to production.

Platform Integration

Schwab Development Environment

The development environment runs within Schwab's secure network infrastructure:

Infrastructure Components:

Component	Technology	Purpose
Development Container	Docker on RHEL 9.5	Consistent development environment
Node.js Runtime	v20.18 LTS	JavaScript/TypeScript execution
Build System	Turborepo v2.4 + pnpm v9.1	Monorepo build orchestration
Version Control	Git	Source code management

Security & Access:

All development occurs within Schwab's secure network
VPN required for external access
SSO authentication for GitHub Enterprise
Containerized environment ensures consistency

GitHub Enterprise Integration

GitHub Enterprise serves as the central hub for source control and CI/CD orchestration:

Repository Structure:

GitHub Actions Workflows:

Workflow	Trigger	Purpose	Output
CI (Continuous Integration)	Push to branch	Lint, test, type-check, build	Validation status
Vercel Deploy	Push to feature branch	Build and deploy preview	Preview URL
Deployment Status	Vercel webhook	Monitor deployment state	E2E test trigger
Security Scans	Pull request	Veracode, Blackduck scanning	Security report
E2E Testing	Deployment success	Mabl automated tests	Test results

CI Workflow Example

The CI workflow implements pre-checks and validation before deployment:

# .github/workflows/CI.yml
name: CI
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
   branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

permissions: write-all

jobs:
  build:
    name: Build
    runs-on:
      group: schwab-cloud-base
      labels: [ linux ]
    permissions:
      checks: write
      contents: write
      statuses: write
    steps:
      - name: Setup PNPM
        id: setup
        uses: charlesschwab/setup-action/npm@v2
        with:
          package-manager: pnpm
          packages-token: ${{ secrets.PACKAGES_AUTH_TOKEN }}
          node-version: ${{ vars.NODEJS_VERSION }}
          on-prem-artifact-registry-username: ${{ secrets.ONPREM_ARTIFACT_REGISTRY_AUTH_USER }}
          on-prem-artifact-registry-token: ${{ secrets.ONPREM_ARTIFACT_REGISTRY_AUTH_TOKEN }}
      - name: Install Dependencies
        run: pnpm install
      - name: Run Lint
        run: pnpm lint
      - name: Build
        run: pnpm ${{ vars.NPM_BUILD_COMMAND }}
    outputs:
      version: ${{ steps.setup.outputs.project-version }}

Workflow Features:

Concurrency Control: Cancels in-progress runs for the same branch
Multiple Triggers: Push to main, pull requests, manual dispatch
Schwab Runners: Uses schwab-cloud-base runner group
Reusable Actions: Leverages Schwab's setup-action for standardized setup
Artifact Registry: Integrates with on-prem artifact registry for packages
Version Output: Exports project version for downstream workflows

Branch Protection:

Require 2 trusted committer approvals
Require passing status checks (lint, tests, type-check)
Require up-to-date branches
No force pushes to main branch
Automatic deletion of feature branches after merge

Vercel Platform Integration

Vercel provides the hosting, build, and deployment infrastructure:

Build Architecture:

Deployment Types:

Type	Trigger	URL Pattern	Purpose
Preview	Feature branch push	`app-branch-charles-schwab.vercel.app`	Development testing
Staging (SIT)	Manual/workflow	`app-sit02.charles-schwab.vercel.app`	Integration testing
Pre-Production	Manual/workflow	`app-pre01.charles-schwab.vercel.app`	Final validation
Production	Main branch merge	`www.schwab.com`	Live application

Vercel Configuration:

Team: charles-schwab
Build Command: turbo run build
Install Command: pnpm install
Framework Preset: Next.js
Node Version: 20.x
Root Directory: Application-specific

Deployment Flow

Feature Development Workflow

The complete lifecycle from development to production:

Preview Deployment Process

Preview deployments are created automatically for every push to a feature branch:

Process Flow:

Push Detection: GitHub webhook notifies Vercel of push
Build Initiation: Vercel clones repository at specific commit
Dependency Installation: pnpm install with cache restoration
Monorepo Build: Turborepo builds affected applications
Asset Optimization: Next.js optimizes images, fonts, scripts
Edge Deployment: Deploy to global edge network
URL Generation: Unique preview URL created
Status Notification: Vercel bot comments on PR with URL

Preview URL Structure:

https://[app-name]-[branch-name]-charles-schwab.vercel.app
                   └─ sanitized branch name

Preview Features:

Automatic HTTPS with SSL certificate
Environment variables from Vercel project
Edge Config integration for feature flags
Analytics and real user monitoring
Build logs and deployment history

Production Deployment Process

Production deployments require QA approval and follow a controlled process:

Deployment Stages:

Production Safeguards:

Main branch protection requires PR
Two trusted committer approvals required
All automated checks must pass
QA manual approval required
Deployment can be rolled back instantly

Implementation Notes & Observations

Monorepo Considerations

Infrastructure:

Aspect	Technology	Impact
Monorepo Pattern	Turborepo	Holds source code for multiple projects in single repository
Build Acceleration	Turbo caching	Turbocharges local setup and speeds up CI
Delivery Pipeline Support	Limited OOTB actions	Building blocks available but require customization for monorepo

Key Observations:

Current Delivery Pipeline support for monorepo-based applications has limitations
Required building blocks (reusable actions) exist but need customization
Support ticket raised for guidance on CI/CD implementation
Epic created by Delivery Pipeline team to address multi-version monorepo support

Mabl E2E Integration

Preview URL Handling:

Every Vercel deployment creates a new preview URL that must be passed to Mabl for E2E testing:

Preview action workflow deploys to Vercel
After deployment, workflow extracts preview URL
Preview URL output passed to Mabl action by caller workflow
Mabl executes E2E tests against preview environment

Integration Flow:

Security Scan Integration

Challenges Encountered:

When reusing OOTB application-security action from Delivery Pipeline:

PNPM Support: Blackduck and Veracode have limited pnpm package manager support
Dependency Review: Comment posting fails due to memory overflow when analyzing large dependency trees
Workarounds: Custom implementations required for monorepo security scanning

Vercel Preview Deployment Implementation

Approach:

Preview action workflow implements Vercel build and deployment using steps from Vercel documentation:

Build artifacts locally using Turborepo
Upload pre-built artifacts to Vercel
Vercel deploys artifacts to edge network
Extract and output preview URL for downstream workflows

Benefits:

Full control over build process
Integration with security scans before deployment
Ability to pass preview URL to E2E testing

Considerations:

Potential duplicate deployments when GitHub App also enabled
Additional complexity compared to GitHub App automatic deployments

Environment Management

Environment Aliases

Vercel supports multiple environment aliases for different testing stages:

Environment	Alias Pattern	Purpose	Deployment
Development	`*-dev01.charles-schwab.vercel.app`	Development testing	Manual
SIT (System Integration)	`*-sit02.charles-schwab.vercel.app`	Integration testing	Manual
SIT Extended	`*-sit03.charles-schwab.vercel.app`	Extended integration	Manual
Pre-Production	`*-pre01.charles-schwab.vercel.app`	Pre-prod validation	Manual
Pre-Production Extended	`*-pre02/03/04.charles-schwab.vercel.app`	Additional staging	Manual
PTE (Pre-Production Testing)	`*-pte01.charles-schwab.vercel.app`	Final validation	Manual
Production	`www.schwab.com`	Live environment	Automatic from main

Environment Variables

Environment variables are managed at the Vercel project level:

Variable Scopes:

Scope	Description	Use Case
Production	Values for production deployments	API keys, prod URLs
Preview	Values for preview deployments	Dev/staging endpoints
Development	Values for local development	Local testing

Critical Variables:

VERCEL_ENV: Deployment environment (production/preview/development)
VERCEL_URL: Deployment URL
VERCEL_GIT_COMMIT_SHA: Git commit hash
VERCEL_GIT_COMMIT_REF: Git branch name
LAUNCHDARKLY_SDK_KEY: Feature flag integration
EDGE_CONFIG_FLAGS: Edge config connection string

Domain Configuration

Production domains are configured through Vercel and Akamai:

Domain Flow:

Domain Mapping:

www.schwab.com → Production deployment
client.schwab.com → Client portal production
Preview domains automatically provisioned by Vercel

Integration Points

GitHub to Vercel Integration

Integration Methods:

The repository uses a hybrid approach combining both Vercel's GitHub App and custom GitHub Actions workflows:

Method	Implementation	Purpose
GitHub App	Vercel GitHub App installed	Automatic preview deployments
API Integration	GitHub Actions + Vercel API	Controlled deployments
Webhooks	Vercel deployment webhooks	Status notifications

GitHub App for Vercel

The GitHub Apps for Vercel is enabled on the nextjs-web repository, providing:

Automatic Deployments:

Preview build deployment triggered automatically when code is pushed (commit) or a Pull Request is created
Separate deployments for each Vercel project (nextjs-web-www, nextjs-web-client, storybook, sanity-studio, etc.)
Vercel Bot adds comments and updates status of preview deployments for each project

GitHub App Benefits:

Automatic preview deployment on push
PR comments with deployment URLs
Deployment status checks
Build logs visible in PR
One-time setup with minimal configuration
Faster to production with zero-config deployments

GitHub App Limitations:

Less control over pre-deployment validation
Cannot easily integrate custom security scans
Difficult to control automatic preview deployments
Limited ability to run pre-checks (linting, testing) before deployment

API Integration with GitHub Actions

Custom GitHub Actions workflows provide additional control and quality gates:

API Integration Benefits:

Full control over deployment process
Custom pre-deployment checks (linting, testing, security scans)
Conditional deployment logic
Integration with additional tools (Mabl, Veracode)
Shift-left approach for automation and accessibility
Higher quality confidence with comprehensive checks

API Integration Challenges:

Additional effort required to add PR comments with preview URLs
Requires script updates when new projects are added
Slower deployment due to additional validation steps
Potential for duplicate deployments when used alongside GitHub App

Integration Strategy Comparison

GitHub Apps for Vercel	GitHub Actions
Auto deployment enabled by default; preview build triggers automatically	Allows pre-checks (linting, unit tests, security scans) before deployment; provides more control
Vercel bot adds comment of preview deployment status for each project	Additional effort required to add comment with preview URLs after deployment
Release to production is partially automated	Can fully automate using GitHub release tags
One-time initial project setup configuration	Requires script updates when new projects are added
Deployment hook/webhook setup required to trigger Mabl GitHub Actions	Mabl E2E automation integrated directly into CI/CD orchestration
Faster to production but comes with risk as quality may be compromised	Slower due to additional checks but compensated with higher quality confidence and lower risk

Current Implementation

The current v1.0 implementation follows this flow:

CI/CD Orchestration:

Code push → Lint → Test → Build → Security Scans → 
Trigger Preview Deployment → Wait for deployment URL → 
Trigger Mabl E2E Automation + Accessibility Scan

Deployment Duplication Consideration:

With both GitHub App and GitHub Actions enabled, preview deployments may be created twice:

Automatic deployment via GitHub App for Vercel
Manual deployment via GitHub Actions workflow for Mabl E2E integration

Resolution Approaches:

Phase 1: Limit GitHub Actions to pre-checks only (linting, security scans); continue using GitHub App for deployments
Phase 2: Create deployment initialization workflows with reusable build/deployment actions for independent project control
Phase 3: Implement path-based deployment control to build specific projects based on file changes

Vercel to External Services

Service Integrations:

Integration Details:

LaunchDarkly: Edge Config sync for feature flags
Mabl: Webhook triggers for E2E test execution
Akamai: DNS and CDN for global distribution
Sanity CMS: Content delivery via API
Harbor: Container image storage and distribution

Performance Optimization

Build Caching Strategy

Vercel integrates with Turborepo's remote caching for optimal build performance:

Cache Layers:

Layer	Technology	Benefit
Dependency Cache	pnpm store	Fast dependency installation
Build Cache	Turbo Remote Cache	Skip unchanged package builds
Next.js Cache	Incremental builds	Faster Next.js compilation
Asset Cache	Vercel CDN	Cached static assets

Build Performance:

Full build (cold cache): ~8-12 minutes
Incremental build (warm cache): ~2-4 minutes
Deployment to edge: ~30-60 seconds

Edge Network Distribution

Vercel's edge network provides global distribution:

Edge Locations:

North America: 40+ locations
Europe: 30+ locations
Asia Pacific: 20+ locations
South America: 5+ locations

Edge Features:

Automatic HTTPS/TLS
HTTP/2 and HTTP/3 support
Brotli compression
Smart CDN caching
Edge middleware execution
Image optimization at edge

Monitoring & Observability

Deployment Monitoring

Metrics Tracked:

Metric	Source	Purpose
Build Duration	Vercel	Track build performance
Deployment Success Rate	Vercel + GitHub Actions	Reliability monitoring
Preview URL Generation	Vercel API	Preview availability
Error Rate	Vercel Analytics	Application health

Application Monitoring

Monitoring Tools:

Vercel Analytics: Core web vitals, page views
Splunk: Log aggregation and analysis
Browser DevTools: Network and console monitoring
Lighthouse: Performance scoring

Alerting

Alert Types:

Build failures (GitHub Actions + Vercel)
Deployment errors (Vercel webhooks)
Security vulnerabilities (Veracode)
Test failures (Mabl)

Security & Compliance

Access Control

Role-Based Access:

Role	Permissions	Scope
Owner	Full access	Vercel team, all projects
Member	Deploy, view	Specific projects
Viewer	Read-only	Deployment history, logs

Authentication:

Vercel SSO with Schwab credentials
GitHub Enterprise SSO
API tokens for CI/CD

Security Scanning

Scan Types:

Security Measures:

HTTPS-only deployments
Encrypted environment variables
No sensitive data in build logs
Regular dependency updates
Security audit trail

Compliance

Requirements:

All deployments logged and traceable
Code review required for production
Security scans mandatory
Data encryption in transit and at rest
Access logs retained

Rollback Capabilities

Instant Rollback:

Vercel maintains deployment history allowing instant rollback:

Navigate to Vercel dashboard
Select previous deployment
Promote to production
Live in <30 seconds

Rollback Methods:

Method	Speed	Scope
Vercel Dashboard	Instant (<30s)	Single project
Vercel API	Instant (<30s)	Automated rollback
Git Revert	Normal build time	All projects

Backup Strategy

Deployment Artifacts:

All deployments retained for 90 days
Build logs available for 30 days
Source code in GitHub (permanent)
Environment variables backed up in Vercel

Cost Optimization

Resource Management

Vercel Plan:

Enterprise plan for charles-schwab team
Unlimited bandwidth
Unlimited deployments
Advanced analytics included

Cost Optimization Strategies:

Turbo cache reduces build time
Incremental Static Regeneration minimizes rebuilds
Image optimization reduces bandwidth
Edge caching reduces origin requests

Overview​

System Architecture​

Platform Integration​

Schwab Development Environment​

GitHub Enterprise Integration​

CI Workflow Example​

Vercel Platform Integration​

Deployment Flow​

Feature Development Workflow​

Preview Deployment Process​

Production Deployment Process​

Implementation Notes & Observations​

Monorepo Considerations​

Mabl E2E Integration​

Security Scan Integration​

Vercel Preview Deployment Implementation​

Environment Management​

Environment Aliases​

Environment Variables​

Domain Configuration​

Integration Points​

GitHub to Vercel Integration​

GitHub App for Vercel​

API Integration with GitHub Actions​

Integration Strategy Comparison​

Current Implementation​

Vercel to External Services​

Performance Optimization​

Build Caching Strategy​

Edge Network Distribution​

Monitoring & Observability​

Deployment Monitoring​

Application Monitoring​

Alerting​

Security & Compliance​

Access Control​

Security Scanning​

Compliance​

Rollback Capabilities​

Backup Strategy​

Cost Optimization​

Resource Management​

See Also​