OpenNoodl/dev-docs/tasks/phase-3/TASK-005-deployment-automation/DEPLOY-overview.md

DEPLOY Series: Deployment Automation

Overview

The DEPLOY series transforms Noodl's deployment from manual folder exports into a modern, automated deployment pipeline. Users can deploy to popular hosting platforms with one click, get automatic preview URLs for each branch, and manage environment variables and domains directly from the editor.

Target Environment

• Editor: React 19 version only
• Platforms: Netlify, Vercel, GitHub Pages, Cloudflare Pages
• Backwards Compatibility: Existing deploy-to-folder continues to work

Task Dependency Graph

DEPLOY-001 (One-Click Deploy)
    │
    ├─────────────────────┐
    ↓                     ↓
DEPLOY-002 (Previews)  DEPLOY-003 (Settings)

Task Summary

Task ID	Name	Est. Hours	Priority
DEPLOY-001	One-Click Deploy Integrations	30-37	Critical
DEPLOY-002	Preview Deployments	24-31	High
DEPLOY-003	Deploy Settings & Environment Variables	28-36	High

Total Estimated: 82-104 hours

Implementation Order

Phase 1: Core Deployment (Weeks 1-2)

1. DEPLOY-001 - One-click deploy to platforms
   • Establishes provider architecture
   • OAuth flows for each platform
   • Core deployment functionality

Phase 2: Preview & Settings (Weeks 3-4)

2. DEPLOY-002 - Preview deployments

   • Branch-based previews
   • PR integration
   • Sharing features

3. DEPLOY-003 - Deploy settings

   • Environment variables
   • Custom domains
   • Deploy rules

Existing Infrastructure

Deployer

// packages/noodl-editor/src/editor/src/utils/compilation/build/deployer.ts
export async function deployToFolder({
  project,
  direntry,
  environment,
  baseUrl,
  envVariables,
  runtimeType = 'deploy'
}: DeployToFolderOptions)

Compilation

// packages/noodl-editor/src/editor/src/utils/compilation/compilation.ts
class Compilation {
  deployToFolder(direntry, options): Promise<void>;
  // Build scripts system for pre/post deploy
}

Deploy UI

// Current deploy popup with folder selection
DeployToFolderTab.tsx
DeployPopup.tsx

Cloud Services

// packages/noodl-editor/src/editor/src/models/CloudServices.ts
interface Environment {
  id: string;
  name: string;
  url: string;
  appId: string;
  masterKey?: string;
}

New Architecture

Service Layer

packages/noodl-editor/src/editor/src/services/
├── DeployService.ts              # Central deployment service
├── PreviewDeployService.ts       # Preview management
├── EnvironmentConfigService.ts   # Env vars & profiles
├── DomainService.ts              # Custom domain management
├── DeployRulesService.ts         # Automation rules
└── deploy/
    ├── DeployProvider.ts         # Provider interface
    └── providers/
        ├── NetlifyProvider.ts
        ├── VercelProvider.ts
        ├── GitHubPagesProvider.ts
        └── CloudflareProvider.ts

Provider Interface

interface DeployProvider {
  readonly platform: DeployPlatform;
  readonly name: string;
  
  // Authentication
  authenticate(): Promise<AuthResult>;
  isAuthenticated(): boolean;
  
  // Sites
  listSites(): Promise<Site[]>;
  createSite(name: string): Promise<Site>;
  
  // Deployment
  deploy(siteId: string, files: DeployFiles): Promise<DeployResult>;
  getDeployStatus(deployId: string): Promise<DeployStatus>;
  
  // Configuration
  getEnvVariables(siteId: string): Promise<Record<string, string>>;
  setEnvVariables(siteId: string, vars: Record<string, string>): Promise<void>;
}

Platform Comparison

Feature	Netlify	Vercel	GitHub Pages	Cloudflare
OAuth	✓	✓	Via GitHub	✓
Preview Deploys	✓	✓	Manual	✓
Custom Domains	✓	✓	✓	✓
Env Variables	✓	✓	Secrets only	✓
Deploy Hooks	✓	✓	Actions	✓
Free Tier	100GB/mo	100GB/mo	Unlimited*	100K/day

*GitHub Pages: Free for public repos, requires Pro for private

Key User Flows

1. First-Time Deploy

User clicks "Deploy"
    ↓
Select platform (Netlify, Vercel, etc.)
    ↓
Authenticate with platform (OAuth)
    ↓
Create new site or select existing
    ↓
Configure environment variables
    ↓
Deploy → Get live URL

2. Subsequent Deploys

User clicks "Deploy"
    ↓
Site already linked
    ↓
One-click deploy
    ↓
Progress indicator
    ↓
Success → Link to site

3. Preview Workflow

User pushes feature branch
    ↓
Auto-deploy preview
    ↓
Comment on PR with preview URL
    ↓
Stakeholder reviews
    ↓
Merge → Production deploy
    ↓
Preview auto-cleaned

UI Components to Create

Component	Package	Purpose
DeployPanel	noodl-core-ui	Main deploy interface
PlatformSelector	noodl-core-ui	Platform choice
SiteSelector	noodl-core-ui	Site choice
DeployProgress	noodl-core-ui	Progress indicator
PreviewManager	noodl-core-ui	Preview list
EnvironmentVariables	noodl-core-ui	Var management
CustomDomains	noodl-core-ui	Domain setup
DeployRules	noodl-core-ui	Automation rules

Data Models

Deploy Target

interface DeployTarget {
  id: string;
  name: string;
  platform: DeployPlatform;
  siteId: string;
  siteName: string;
  url: string;
  customDomain?: string;
  lastDeployedAt?: string;
}

Preview Deployment

interface PreviewDeployment {
  id: string;
  projectId: string;
  branch: string;
  commitSha: string;
  url: string;
  status: PreviewStatus;
  createdAt: string;
  expiresAt?: string;
}

Environment Profile

interface EnvironmentProfile {
  id: string;
  name: string;
  variables: EnvironmentVariable[];
  isDefault: boolean;
}

interface EnvironmentVariable {
  key: string;
  value: string;
  sensitive: boolean;
}

Security Considerations

Token Storage

• OAuth tokens stored in electron safeStorage
• Never logged or displayed
• Cleared on disconnect

Sensitive Variables

• Encrypted at rest
• Masked in UI (•••••)
• Never exported to .env without warning

Platform Security

• Minimum OAuth scopes
• Token refresh handling
• Secure redirect handling

Testing Strategy

Unit Tests

• Provider method isolation
• Token handling
• File preparation

Integration Tests

• OAuth flow mocking
• Deploy API mocking
• Full deploy cycle

Manual Testing

• Real deployments to each platform
• Custom domain setup
• Preview workflow

Cline Usage Notes

Before Starting Each Task

1. Review existing deployment infrastructure:

   • deployer.ts
   • compilation.ts
   • DeployPopup/

2. Understand build output:

   • How project.json is exported
   • How bundles are created
   • How index.html is generated

Key Integration Points

1. Compilation: Use existing deployToFolder for file preparation
2. Cloud Services: Existing environment model can inform design
3. Git Integration: Leverage GIT series for branch awareness

Platform API Notes

• Netlify: Uses digest-based upload (SHA1 hashes)
• Vercel: File-based deployment API
• GitHub Pages: Git-based via GitHub API
• Cloudflare: Similar to Netlify/Vercel

Success Criteria (Series Complete)

1. ✅ One-click deploy to 4 platforms
2. ✅ OAuth authentication flow works
3. ✅ Site creation from editor works
4. ✅ Preview deploys auto-generated
5. ✅ PR comments posted automatically
6. ✅ Environment variables managed
7. ✅ Custom domains configurable
8. ✅ Deploy rules automate workflow

Future Work (Post-DEPLOY)

The DEPLOY series enables:

• CI/CD Integration: Connect to GitHub Actions, GitLab CI
• Performance Monitoring: Lighthouse scores per deploy
• A/B Testing: Deploy variants to subsets
• Rollback: One-click rollback to previous deploy
• Multi-Region: Deploy to multiple regions

Files in This Series

• DEPLOY-001-one-click-deploy.md
• DEPLOY-002-preview-deployments.md
• DEPLOY-003-deploy-settings.md
• DEPLOY-OVERVIEW.md (this file)

External Dependencies

Platform OAuth

Platform	OAuth Type	Client ID Required
Netlify	OAuth 2.0	Yes
Vercel	OAuth 2.0	Yes
GitHub	OAuth 2.0	From GIT-001
Cloudflare	OAuth 2.0	Yes

API Endpoints

• Netlify: api.netlify.com/api/v1
• Vercel: api.vercel.com/v13
• GitHub: api.github.com
• Cloudflare: api.cloudflare.com/client/v4

Complete Roadmap Summary

With the DEPLOY series complete, the full OpenNoodl modernization roadmap includes:

Series	Tasks	Hours	Focus
DASH	4 tasks	43-63	Dashboard UX
GIT	5 tasks	68-96	Git integration
COMP	6 tasks	117-155	Shared components
AI	4 tasks	121-154	AI assistance
DEPLOY	3 tasks	82-104	Deployment

Grand Total: 22 tasks, 431-572 hours