Deployment Model

NearSync deploys through Vercel's Git integration with no external CI/CD system. Each of the three applications maps to a separate Vercel project, and Turborepo's turbo-ignore command prevents unnecessary rebuilds when only one application changes.

Architecture Overview

Developer pushes to GitHub
    |
    +-- Push to main branch (production)
    |   |
    |   +-- Vercel detects change
    |       |
    |       +-- Run turbo-ignore for each project
    |       |   |
    |       |   +-- admin-dashboard: files changed? -> rebuild or skip
    |       |   +-- client-portal: files changed? -> rebuild or skip
    |       |   +-- marketing-website: files changed? -> rebuild or skip
    |       |
    |       +-- Build only affected projects
    |       |   |
    |       |   +-- Install dependencies (Turborepo caching)
    |       |   +-- Run turbo build with project filter
    |       |   +-- Generate static artifacts
    |       |
    |       +-- Deploy to production domains
    |           +-- admin.nearsync.tech
    |           +-- portal.nearsync.tech
    |           +-- nearsync.tech
    |
    +-- Push to stage branch (staging)
    |   |
    |   +-- Preview deployments for testing
    |
    +-- Pull request opened
        |
        +-- Preview deployment generated for review

Branch Strategy

NearSync uses a two-branch model:

Branch	Environment	Purpose
main	Production	Serves production domains. All merges to main trigger production deployments.
stage	Staging/Preview	Pre-production testing environment. Preview URLs generated for each push.

Pull requests generate their own preview deployments automatically, enabling reviewers to test changes in isolation before merging.

Vercel Project Mapping

Each application deploys as a separate Vercel project with its own root directory and build command.

Application	Root Directory	Build Command	Production Domain
Admin Dashboard	apps/admin-dashboard	cd ../.. && npx turbo run build --filter=@nearsync/admin-dashboard	admin.nearsync.tech
Client Portal	apps/client-portal	cd ../.. && npx turbo run build --filter=@nearsync/client-portal	portal.nearsync.tech
Marketing Website	apps/marketing-website	cd ../.. && npx turbo run build --filter=@nearsync/marketing-website	nearsync.tech

All three projects point to the same Git repository. The rootDirectory setting tells Vercel where each application's source lives, while the build command uses Turborepo's --filter flag to build only the target application and its package dependencies.

Alongside these three apps, NearSync runs a small Vercel edge project that proxies the public API and MCP server at api.nearsync.tech, and serves developer documentation at docs.nearsync.ai. The platform's business logic itself runs on Supabase edge functions (see Edge Functions below), which deploy independently of the Vercel pipeline.

Intelligent Builds with turbo-ignore

Each Vercel project uses npx turbo-ignore as its Ignored Build Step. This command compares the current commit against the last successful deployment and determines whether any files relevant to the project have changed.

How It Works

1. Vercel receives a push event for the repository.
2. For each project, Vercel runs npx turbo-ignore <package-name> before starting the build.
3. turbo-ignore checks whether the application or any of its package dependencies have changed since the last deployment commit.
4. If nothing relevant changed, the build is skipped entirely (exit code 0).
5. If changes are detected, the full build proceeds.

Example Scenarios

Scenario: Only apps/client-portal files changed

• admin-dashboard project: turbo-ignore detects no relevant changes, build skipped
• client-portal project: turbo-ignore detects changes, build proceeds
• marketing-website project: turbo-ignore detects no relevant changes, build skipped

Scenario: A shared package (@nearsync/ui-system) changed

• All three projects depend on @nearsync/ui-system, so turbo-ignore triggers rebuilds for all three

Scenario: Only @nearsync/tsconfig changed

• All projects transitively depend on tsconfig, so all three rebuild

This approach keeps deployment times short and avoids wasting build minutes on unchanged projects.

Build Pipeline

When a build proceeds, Turborepo handles dependency resolution and caching:

npx turbo run build --filter=@nearsync/admin-dashboard

  1. Resolve dependency graph
     @nearsync/types -> @nearsync/supabase-client -> @nearsync/ui-system -> admin-dashboard

  2. Build packages in topological order
     - Check Turborepo cache for each package
     - If cache hit (content hash matches): reuse cached output
     - If cache miss: run build, store result in cache

  3. Build target application
     - Vite bundles the React SPA
     - Static assets generated in dist/

  4. Vercel deploys the dist/ output

Turborepo's content-hash-based caching means unchanged packages are never rebuilt, even across different Vercel projects in the same push.

Edge Functions

Supabase Edge Functions deploy separately from the frontend applications, using the Supabase CLI:

supabase functions deploy <function-name>

Edge functions include:

• hyper-worker - Central request router for all backend business logic (15 service modules)
• OAuth callbacks - Handlers for third-party OAuth flows (Canva, CRM providers, integrations)
• Cron jobs - Scheduled tasks for reminders, data syncing, and enrichment

These functions run on Deno and are deployed to Supabase's edge infrastructure, independent of the Vercel deployment pipeline.

Secrets Management

Secrets are managed through two channels, never committed to Git:

Scope	Storage	Access Pattern
Frontend environment variables	Vercel project settings	Injected at build time via VITE_* prefix
Edge function secrets	Supabase dashboard (Settings > Secrets)	Accessed at runtime via Deno.env.get()

Frontend environment variables include the Supabase project URL, anonymous key, and Sentry DSN. Edge function secrets include service role keys, third-party API keys, and webhook signing secrets.

BYOK Client Deployments

For BYOK (Bring Your Own Keys) clients who opt for NearSync-managed hosting, a separate Vercel project is created pointing to the same repository but configured with the client's own Supabase environment variables.

When NearSync pushes to main, all Vercel projects (including BYOK client projects) auto-rebuild from the same codebase. Every client receives updates simultaneously with no manual propagation.

For self-hosted BYOK clients, NearSync provides static build artifacts and migration scripts per release. Clients deploy to their own infrastructure and pull updates at their discretion.

See Multi-Tenancy for details on how managed and BYOK deployments differ at the data layer.

Rollback

Vercel maintains deployment history for each project. If a production deployment introduces issues:

1. Instant rollback via Vercel dashboard to the previous successful deployment
2. DNS remains stable throughout - no DNS propagation delays
3. Database safety - all data persists in Supabase regardless of which frontend version is deployed
4. Supabase Edge Functions can be rolled back independently via the Supabase CLI