49.5 Online Platform Deployment

Documentation for Sessions

Session 49.5: Online Platform Deployment Architecture

Overview

This session implements the complete infrastructure for online platform generation where:

Generated platforms are frontend-only Angular apps
Code is stored in GitLab (with Gitea fallback option)
Drafts system uses git branches for work-in-progress changes
Multi-tenant isolation maps tenants to GitLab groups
Build pipeline leverages GitLab CI/CD

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      ONLINE PLATFORM GENERATION SYSTEM                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  USER LAYER                                                                  │
│  └── Platform Builder UI → Configure modules, layouts, branding              │
│                                                                              │
│  GENERATION LAYER (backend-ai-api)                                           │
│  ├── Vibe Universe Generator → Creates Angular code                          │
│  └── PlatformApiClientService → Calls backend-api to store code              │
│                                                                              │
│  STORAGE LAYER (backend-api + GitLab)                                        │
│  ├── MongoDB: Universe config, drafts metadata, deployment records           │
│  ├── GitLab: Generated source code                                           │
│  │   ├── Group per tenant: {tenant_slug}/                                    │
│  │   ├── Project per universe: {tenant_slug}/{universe_slug}                 │
│  │   └── Branches: main, draft/*, preview/*                                  │
│  └── Tags: v1.0.0, v1.1.0 (versioned releases)                               │
│                                                                              │
│  BUILD LAYER (GitLab CI/CD)                                                  │
│  ├── Pipeline triggered on push/tag                                          │
│  ├── Builds Angular app → Callbacks to backend-api                           │
│  └── Deploys to CDN                                                          │
│                                                                              │
│  RUNTIME LAYER                                                               │
│  ├── Generated frontend → https://{slug}.gograb.space                        │
│  ├── API calls → backend-api.gograb.io (shared)                              │
│  └── AI features → backend-ai-api.gograb.io (shared)                         │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Key Decisions

Decision	Choice	Rationale
Git Provider	GitLab Premium	Unlimited users, built-in CI/CD, groups/projects model
Code Storage	Git (not MongoDB)	Version control, branching, proper tooling
Abstraction Layer	GitProviderService	Easy migration to other providers if needed
Drafts	Git branches	main=production, draft/*=work-in-progress
Builds	GitLab CI/CD	10,000 compute minutes/month included
Multi-tenant	Tenant→Group, Universe→Project	Natural isolation

Components

1. Core Interfaces (`libs/libs-foundational/core-models`)

git-provider.interface.ts - Abstraction for git operations
git-provider.types.ts - Git entity types (repo, branch, commit, etc.)
draft.types.ts - Draft entity and operations
platform-deployment.types.ts - Deployment pipeline types

2. Git Provider (`apis/backend-api/src/app/git-provider/`)

GitLabProviderService - Full GitLab API v4 implementation
GiteaProviderService - Gitea fallback implementation
git-provider.module.ts - Factory-based provider selection

Configuration:

GIT_PROVIDER=gitlab           # or 'gitea'
GITLAB_URL=https://gitlab.com
GITLAB_API_TOKEN=glpat-xxx

3. Drafts Service (`apis/backend-api/src/app/drafts/`)

REST API for draft management:

POST /drafts - Create draft (creates git branch)
GET /drafts/:id - Get draft
PUT /drafts/:id - Update draft metadata
POST /drafts/:id/preview - Create preview deployment
POST /drafts/:id/publish - Merge to main and deploy
DELETE /drafts/:id - Discard draft

4. Build Pipeline (`apis/backend-api/src/app/build-pipeline/`)

BuildPipelineService - Deployment orchestration
WebhookController - GitLab webhook handler

Endpoints:

POST /deployments - Trigger deployment
GET /deployments/:id - Get deployment status
GET /deployments/current/:universeId - Current deployment
POST /deployments/:id/cancel - Cancel deployment
POST /deployments/rollback - Rollback to version

5. Platform Code (`apis/backend-api/src/app/platform-code/`)

High-level orchestration:

POST /platforms/initialize - Create repo for universe
POST /platforms/code - Push generated code
POST /platforms/versions - Create version tag
GET /platforms/:id - Platform info
GET /platforms/:id/files - Get files from repo

6. Tenant Sync (`apis/backend-api/src/app/tenant-sync/`)

Keeps GitLab groups in sync with tenant changes:

onTenantCreated() - Create GitLab group
onTenantDeleted() - Archive/delete group
onTeamMemberAdded() - Add to GitLab group
onTeamMemberRemoved() - Remove from group

RBAC to GitLab role mapping:

owner → Owner (50)
admin → Maintainer (40)
editor → Developer (30)
viewer → Reporter (20)

7. Platform API Client (`apis/backend-ai-api/src/app/platform-api-client/`)

HTTP client for backend-ai-api to call backend-api:

pushCode() - Push generated files
createDraft() - Create draft for changes
publishDraft() - Merge and deploy
triggerDeployment() - Deploy to environment

Workflow: Generate and Deploy

1. User creates universe in Platform Builder
   └── backend-api creates GitLab project via PlatformCodeService

2. AI generates platform code
   └── backend-ai-api sends to backend-api via PlatformApiClientService

3. backend-api pushes to GitLab
   └── GitProviderService.pushFiles()

4. GitLab CI/CD runs automatically
   └── .gitlab-ci.yml builds Angular app

5. Pipeline callbacks to backend-api
   └── WebhookController updates deployment status

6. Platform goes live
   └── https://{universe-slug}.gograb.space

Workflow: Draft Changes

1. User creates draft "menu-redesign"
   └── DraftsService creates branch draft/menu-redesign

2. AI makes changes
   └── Code pushed to draft branch

3. User previews draft
   └── Preview deployment at preview-xxx.gograb.space

4. User publishes draft
   └── Branch merged to main, tag created, production deployed

Files Created

Core Models

libs/libs-foundational/core-models/src/lib/interfaces/git-provider.interface.ts
libs/libs-foundational/core-models/src/lib/interfaces/git-provider.types.ts
libs/libs-foundational/core-models/src/lib/interfaces/draft.types.ts
libs/libs-foundational/core-models/src/lib/interfaces/platform-deployment.types.ts

Backend API

apis/backend-api/src/app/git-provider/ (module, gitea-provider, gitlab-provider)
apis/backend-api/src/app/drafts/ (module, schema, service, controller)
apis/backend-api/src/app/build-pipeline/ (module, schema, service, controller, webhook)
apis/backend-api/src/app/platform-code/ (module, service, controller)
apis/backend-api/src/app/tenant-sync/ (module, service)

Backend AI API

apis/backend-ai-api/src/app/platform-api-client/ (module, service)

Infrastructure

docker/gitea/docker-compose.yml (Gitea alternative)
apis/backend-api/.env.gitlab.example
apis/backend-ai-api/.env.platform.example

Configuration

GitLab Setup

Create GitLab Premium account (or use self-hosted)
Create API token with scopes: api, read_repository, write_repository
Configure webhook secret for callbacks

Environment Variables (backend-api)

# Git Provider
GIT_PROVIDER=gitlab
GITLAB_URL=https://gitlab.com
GITLAB_API_TOKEN=glpat-xxx
GITLAB_WEBHOOK_SECRET=xxx

# Cloudflare Pages (for hosting deployed platforms)
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

# Deployment URLs (API_BASE_URL also used for GitLab webhook callbacks)
DOMAIN_SUFFIX=gograb.space
API_BASE_URL=https://backend-api-production-97c0.up.railway.app
AI_API_BASE_URL=https://backend-ai-api-production.up.railway.app

Environment Variables (backend-ai-api)

BACKEND_API_URL=http://localhost:3000
BACKEND_API_INTERNAL_TOKEN=xxx

Cloudflare Pages Setup

Create Cloudflare account at https://dash.cloudflare.com/
Go to Workers & Pages → Create application → Pages
Create an API token:
- Go to My Profile → API Tokens → Create Token
- Use template: "Edit Cloudflare Workers"
- Or custom permissions: Account:Cloudflare Pages:Edit
Copy Account ID from the right sidebar of any Cloudflare page

Add to .env.local:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token

GitLab CI/CD Variables

When a platform project is created, set these CI/CD variables in GitLab:

CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID
CLOUDFLARE_API_TOKEN - Cloudflare API token with Pages edit permissions
GOGRAB_WEBHOOK_SECRET - Same as GITLAB_WEBHOOK_SECRET
GOGRAB_UNIVERSE_ID - The universe ID for callbacks

Deployment Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    DEPLOYMENT FLOW                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Code Push to GitLab                                         │
│     └── User creates draft → AI generates code → Push to GitLab │
│                                                                  │
│  2. GitLab CI/CD Pipeline                                       │
│     └── .gitlab-ci.yml triggers on push/tag                     │
│     └── Build stage: npm ci → ng build --prod                   │
│     └── Deploy stage: wrangler pages deploy                     │
│                                                                  │
│  3. Cloudflare Pages                                            │
│     └── Production: https://{slug}.pages.dev                    │
│     └── Preview: https://{branch}.{slug}.pages.dev              │
│     └── Custom domain: https://{slug}.gograb.space (future)     │
│                                                                  │
│  4. Callback to backend-api                                     │
│     └── POST /webhooks/gitlab/pipeline                          │
│     └── Updates deployment status in MongoDB                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Completed vs Pending

✅ Completed

GitProviderService interface + GitLab/Gitea implementations
DraftsModule (branch-based drafts workflow)
BuildPipelineModule (deployment tracking)
PlatformCodeModule (code push orchestration)
TenantSyncModule (tenant → GitLab group sync)
CloudflareModule (Pages project management)
GitLab CI/CD template with Cloudflare Pages deployment
Webhook controller for pipeline callbacks

🔲 Next Steps

Cloudflare Setup - Get API credentials and configure
End-to-end test - Create project, push code, verify deployment
Custom domains - DNS management for gograb.space subdomains
Monitoring - Deployment metrics and alerts