Session 49.4: Online Platform Generation Architecture

Problem Statement

The current vibe-universe generator is designed for local development:

• Code is written directly to the editor2 codebase
• Git operations happen on the local workspace
• Deployment assumes local filesystem access

For online users, this model doesn't work:

• Cannot write to our production codebase
• Users need their own repository for version control
• Deployments must be isolated per user/platform

Architecture Decision

Option 1: Database-Only Storage (Rejected)

• Store generated code in MongoDB
• No git history, no familiar tooling
• Harder for users to customize or eject

Option 2: Git-as-a-Service (Selected)

• Create GitHub/GitLab repo per user platform
• Push generated code to user's repo
• Deploy via connected CI/CD (Vercel, Netlify)
• Users can eject and customize anytime

System Design

Data Flow

┌──────────────────────────────────────────────────────────────────────┐
│                        PLATFORM GENERATION FLOW                       │
├──────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  1. USER INPUT                                                        │
│     └─→ "Create a restaurant platform with menu, orders, reservations"│
│                                                                       │
│  2. AI GENERATION (in-memory)                                         │
│     └─→ Generate module code (Angular components, services, routes)   │
│     └─→ Generate configuration (routes, navigation, layouts)          │
│     └─→ Store temporarily in Redis/memory (TTL: 1 hour)               │
│                                                                       │
│  3. VALIDATION & PREVIEW                                              │
│     └─→ TypeScript compilation check (in sandbox)                     │
│     └─→ Generate preview bundle                                       │
│     └─→ Show interactive preview to user                              │
│                                                                       │
│  4. USER CONFIRMS → CREATE REPOSITORY                                 │
│     └─→ Create GitHub repo: {username}/platform-{slug}                │
│     └─→ Initialize with README, .gitignore, package.json              │
│     └─→ Push generated code to main branch                            │
│     └─→ Create tag: v1.0.0                                            │
│                                                                       │
│  5. DEPLOYMENT SETUP                                                  │
│     └─→ Connect repo to Vercel (via OAuth)                            │
│     └─→ Configure build settings                                      │
│     └─→ Assign subdomain: {slug}.gograb.space                         │
│     └─→ Or user's custom domain                                       │
│                                                                       │
│  6. LIVE DEPLOYMENT                                                   │
│     └─→ Vercel builds from GitHub                                     │
│     └─→ CDN distribution                                              │
│     └─→ SSL certificate auto-provisioned                              │
│                                                                       │
│  7. UPDATES & VERSIONS                                                │
│     └─→ User requests changes via AI                                  │
│     └─→ New code pushed to branch: feature/update-menu                │
│     └─→ PR created for review                                         │
│     └─→ Merge → auto-deploy                                           │
│                                                                       │
└──────────────────────────────────────────────────────────────────────┘

Services Required

1. PlatformRepositoryService

Manages GitHub repositories for user platforms.

interface PlatformRepositoryService {
  // Create new repo for platform
  createRepository(userId: string, platformSlug: string): Promise<RepoInfo>;

  // Push generated code to repo
  pushCode(repoId: string, files: GeneratedFile[], message: string): Promise<CommitInfo>;

  // Create version tag
  createVersion(repoId: string, version: string): Promise<TagInfo>;

  // Create PR for updates
  createUpdatePR(repoId: string, branch: string, files: GeneratedFile[]): Promise<PRInfo>;

  // Get repo status
  getRepositoryStatus(repoId: string): Promise<RepoStatus>;
}

2. EphemeralCodeService

Handles temporary code storage during generation.

interface EphemeralCodeService {
  // Store generated code temporarily
  store(workflowId: string, files: GeneratedFile[]): Promise<void>;

  // Retrieve stored code
  retrieve(workflowId: string): Promise<GeneratedFile[]>;

  // Validate code (TypeScript check)
  validate(workflowId: string): Promise<ValidationResult>;

  // Generate preview bundle
  generatePreview(workflowId: string): Promise<PreviewBundle>;

  // Clean up expired code
  cleanup(workflowId: string): Promise<void>;
}

3. DeploymentProviderService

Manages connections to deployment platforms.

interface DeploymentProviderService {
  // Connect user's Vercel account
  connectVercel(userId: string, authCode: string): Promise<VercelConnection>;

  // Deploy from GitHub repo
  deployFromRepo(repoUrl: string, config: DeployConfig): Promise<DeploymentInfo>;

  // Configure custom domain
  configureDomain(deploymentId: string, domain: string): Promise<DomainConfig>;

  // Get deployment status
  getDeploymentStatus(deploymentId: string): Promise<DeploymentStatus>;
}

Database Schema

PlatformRepository Collection

interface PlatformRepository {
  _id: ObjectId;
  userId: string;
  platformId: string;          // Universe ID
  platformSlug: string;

  // GitHub
  githubRepoId: string;
  githubRepoUrl: string;
  githubOwner: string;
  githubRepoName: string;

  // Versions
  versions: {
    tag: string;              // v1.0.0
    commitHash: string;
    createdAt: Date;
    moduleCount: number;
    changelog: string;
  }[];
  currentVersion: string;

  // Deployment
  deploymentProvider: 'vercel' | 'netlify' | 'railway';
  deploymentId: string;
  deploymentUrl: string;
  customDomain?: string;

  // Metadata
  createdAt: Date;
  updatedAt: Date;
  lastDeployedAt: Date;
}

Environment Variables Required

# GitHub App (for creating user repos)
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=

# Vercel Integration
VERCEL_ACCESS_TOKEN=
VERCEL_TEAM_ID=

# Netlify Integration (optional)
NETLIFY_ACCESS_TOKEN=
NETLIFY_SITE_ID=

# Temporary Storage (Redis for ephemeral code)
REDIS_URL=redis://localhost:6379

# CDN for preview bundles
PREVIEW_CDN_BUCKET=gograb-previews

Security Considerations

1. OAuth Scopes: Only request minimum GitHub scopes needed

   • repo - Create repos, push code
   • read:user - Get username for repo naming

2. Repository Isolation: Each user's platform in separate repo

   • User owns their code
   • Can revoke access anytime
   • Can eject and self-host

3. Ephemeral Code TTL: Generated code expires after 1 hour

   • Prevents storage bloat
   • Forces user to commit or regenerate

4. Rate Limiting: Prevent abuse

   • Max 5 platforms per user (free tier)
   • Max 10 generations per hour

Migration Path

Phase 1: Ephemeral Storage (Week 1)

• Implement Redis-based temporary code storage
• Add validation sandbox
• Preview without deployment

Phase 2: GitHub Integration (Week 2)

• GitHub App setup
• Repository creation service
• Code push functionality

Phase 3: Deployment Integration (Week 3)

• Vercel OAuth integration
• Auto-deployment setup
• Domain configuration

Phase 4: Versioning & Updates (Week 4)

• Version tagging
• Update PRs
• Rollback capability

Comparison: Local vs Online

Next Steps

1. Create PlatformRepositoryService in backend-ai-api
2. Set up GitHub App for repository management
3. Implement ephemeral code storage with Redis
4. Add Vercel deployment integration
5. Update vibe-universe generator to support both modes