610 lines
8.4 KiB
Markdown
610 lines
8.4 KiB
Markdown
Google Cloud Product OS
|
||
Technical Specification
|
||
|
||
Product-Centric IDE + SaaS Autopilot Platform
|
||
|
||
1. Purpose
|
||
|
||
This document defines the technical architecture, components, interfaces, and implementation plan for building a:
|
||
|
||
Google Cloud–native, Gemini-powered Product Operating System (Product OS)
|
||
|
||
The platform unifies:
|
||
|
||
Code development
|
||
|
||
Product launch
|
||
|
||
Marketing automation
|
||
|
||
Analytics and causality
|
||
|
||
Growth optimization
|
||
|
||
Support automation
|
||
|
||
Experimentation
|
||
|
||
Infrastructure management
|
||
|
||
into a single product-centric IDE and automation system.
|
||
|
||
This is not a general-purpose IDE.
|
||
It is a Product OS for launching and operating SaaS products on Google Cloud.
|
||
|
||
2. Core Design Principles
|
||
2.1 Product-Centric Orientation
|
||
|
||
The platform optimizes for:
|
||
|
||
Shipping products
|
||
|
||
Launching features
|
||
|
||
Running marketing
|
||
|
||
Optimizing growth
|
||
|
||
Operating infrastructure
|
||
|
||
Automating decisions
|
||
|
||
Not for:
|
||
|
||
Arbitrary coding workflows
|
||
|
||
Multi-cloud portability
|
||
|
||
Framework experimentation
|
||
|
||
2.2 Opinionated for Google Cloud
|
||
|
||
The platform is single-cloud and deeply integrated with:
|
||
|
||
Cloud Run
|
||
|
||
Cloud Build
|
||
|
||
Artifact Registry
|
||
|
||
Firestore
|
||
|
||
Cloud SQL
|
||
|
||
BigQuery
|
||
|
||
Pub/Sub
|
||
|
||
Vertex AI (Gemini)
|
||
|
||
No AWS or Azure abstraction layers are supported.
|
||
|
||
2.3 Backend Tool Execution (Security Model)
|
||
|
||
All automation executes on the backend.
|
||
|
||
The IDE:
|
||
|
||
Never runs gcloud
|
||
|
||
Never runs Terraform
|
||
|
||
Never holds GCP credentials
|
||
|
||
Never touches databases directly
|
||
|
||
Instead:
|
||
|
||
IDE / Supervisor AI
|
||
↓
|
||
Control Plane API
|
||
↓
|
||
Executors
|
||
↓
|
||
GCP Services
|
||
|
||
2.4 AI as a Product Operator
|
||
|
||
The AI is not a coding assistant.
|
||
|
||
It is a:
|
||
|
||
Product Operator AI
|
||
|
||
Responsibilities:
|
||
|
||
Interpret product goals
|
||
|
||
Read analytics and insights
|
||
|
||
Decide actions
|
||
|
||
Dispatch tools
|
||
|
||
Enforce policies
|
||
|
||
Learn from outcomes
|
||
|
||
3. High-Level Architecture
|
||
┌─────────────────────────────┐
|
||
│ VSCodium IDE Client │
|
||
│ (Product-Centric UI Shell) │
|
||
└──────────────┬──────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────┐
|
||
│ Control Plane API │
|
||
│ (Tool Router + Policy) │
|
||
└──────────────┬───────────┘
|
||
│
|
||
┌──────────────┬───────────┼─────────────┬──────────────┐
|
||
▼ ▼ ▼ ▼ ▼
|
||
Deploy Executor Analytics Exec Firestore Exec SQL Exec Missinglettr Exec
|
||
Cloud Build+Run BigQuery Firestore Cloud SQL Social Posting
|
||
|
||
│
|
||
┌──────▼───────┐
|
||
│ GCS Store │
|
||
│ Artifacts │
|
||
└──────────────┘
|
||
|
||
4. IDE Client Architecture
|
||
4.1 Base Editor
|
||
|
||
VSCodium distribution
|
||
|
||
OpenVSX marketplace
|
||
|
||
Preinstalled extensions
|
||
|
||
Preconfigured settings
|
||
|
||
Custom UI panels
|
||
|
||
4.2 Product-Centric Navigation
|
||
|
||
The IDE must expose:
|
||
|
||
Product OS
|
||
├── Code
|
||
├── Marketing
|
||
├── Analytics
|
||
├── Growth
|
||
├── Support
|
||
├── Experiments
|
||
└── Infrastructure
|
||
|
||
|
||
Each section is:
|
||
|
||
First-class
|
||
|
||
AI-assisted
|
||
|
||
Connected to backend tools
|
||
|
||
4.3 IDE Responsibilities
|
||
|
||
The IDE handles:
|
||
|
||
File editing
|
||
|
||
Patch preview & application
|
||
|
||
Project context collection
|
||
|
||
Tool invocation UI
|
||
|
||
Artifact viewing
|
||
|
||
Logs & traces display
|
||
|
||
The IDE does NOT:
|
||
|
||
Execute cloud commands
|
||
|
||
Store secrets
|
||
|
||
Perform deployments
|
||
|
||
Perform database queries
|
||
|
||
5. Control Plane API
|
||
5.1 Purpose
|
||
|
||
The Control Plane is the central orchestration backend.
|
||
|
||
Responsibilities:
|
||
|
||
Auth
|
||
|
||
Tool registry
|
||
|
||
Tool invocation routing
|
||
|
||
Policy enforcement
|
||
|
||
Run tracking
|
||
|
||
Artifact storage (GCS)
|
||
|
||
Gemini proxy
|
||
|
||
5.2 Core Endpoints
|
||
POST /tools/invoke
|
||
GET /runs/{run_id}
|
||
GET /runs/{run_id}/logs
|
||
GET /tools
|
||
GET /artifacts/{run_id}
|
||
|
||
5.3 Tool Invocation Contract
|
||
Request
|
||
{
|
||
"tool": "cloudrun.deploy_service",
|
||
"tenant_id": "t_123",
|
||
"workspace_id": "w_456",
|
||
"input": {
|
||
"service_name": "marketing-gateway",
|
||
"repo": "github.com/org/repo",
|
||
"ref": "main",
|
||
"env": "prod"
|
||
},
|
||
"dry_run": false
|
||
}
|
||
|
||
Response
|
||
{
|
||
"run_id": "run_20260119_abc",
|
||
"status": "queued"
|
||
}
|
||
|
||
6. Tool Registry
|
||
|
||
All executable actions are declared as tools.
|
||
|
||
6.1 Tool Schema
|
||
tools:
|
||
cloudrun.deploy_service:
|
||
description: Deploy a Cloud Run service
|
||
input_schema:
|
||
service_name: string
|
||
repo: string
|
||
ref: string
|
||
env: string
|
||
output_schema:
|
||
service_url: string
|
||
risk: medium
|
||
executor: deploy-executor
|
||
|
||
6.2 Registry Responsibilities
|
||
|
||
Input validation
|
||
|
||
Output validation
|
||
|
||
Risk classification
|
||
|
||
Executor routing
|
||
|
||
Used by:
|
||
|
||
IDE
|
||
|
||
Supervisor AI
|
||
|
||
Web dashboard
|
||
|
||
7. Executors (Domain Services)
|
||
|
||
Each executor is a Cloud Run service with its own service account.
|
||
|
||
7.1 Deploy Executor
|
||
|
||
Purpose:
|
||
|
||
Build and deploy services
|
||
|
||
Tools:
|
||
|
||
cloudrun.deploy_service
|
||
|
||
cloudrun.tail_logs
|
||
|
||
cloudrun.rollback
|
||
|
||
GCP APIs:
|
||
|
||
Cloud Build
|
||
|
||
Cloud Run
|
||
|
||
Artifact Registry
|
||
|
||
IAM:
|
||
|
||
roles/cloudbuild.builds.editor
|
||
|
||
roles/run.admin (scoped)
|
||
|
||
roles/artifactregistry.writer
|
||
|
||
7.2 Analytics Executor (OpsOS)
|
||
|
||
Purpose:
|
||
|
||
Product intelligence and causality
|
||
|
||
Tools:
|
||
|
||
analytics.get_funnel_summary
|
||
|
||
analytics.get_top_drivers
|
||
|
||
analytics.get_anomalies
|
||
|
||
GCP APIs:
|
||
|
||
BigQuery
|
||
|
||
BigQuery ML
|
||
|
||
IAM:
|
||
|
||
roles/bigquery.dataViewer
|
||
|
||
roles/bigquery.jobUser
|
||
|
||
7.3 Firestore Executor
|
||
|
||
Purpose:
|
||
|
||
Company Brain + configs
|
||
|
||
Tools:
|
||
|
||
firestore.get_company_brain
|
||
|
||
firestore.update_company_brain
|
||
|
||
GCP APIs:
|
||
|
||
Firestore
|
||
|
||
IAM:
|
||
|
||
roles/datastore.user
|
||
|
||
7.4 SQL Executor
|
||
|
||
Purpose:
|
||
|
||
Transactional summaries
|
||
|
||
Tools:
|
||
|
||
sql.get_subscription_summary
|
||
|
||
sql.get_user_metrics
|
||
|
||
GCP APIs:
|
||
|
||
Cloud SQL
|
||
|
||
IAM:
|
||
|
||
roles/cloudsql.client
|
||
|
||
DB-level users
|
||
|
||
7.5 Missinglettr Executor
|
||
|
||
Purpose:
|
||
|
||
Social publishing
|
||
|
||
Tools:
|
||
|
||
missinglettr.publish_campaign
|
||
|
||
missinglettr.get_campaign_status
|
||
|
||
Secrets:
|
||
|
||
Missinglettr API tokens
|
||
|
||
IAM:
|
||
|
||
roles/secretmanager.secretAccessor
|
||
|
||
8. Data Storage
|
||
8.1 Firestore
|
||
|
||
Used for:
|
||
|
||
Company Brain
|
||
|
||
Tool registry
|
||
|
||
Policy configs
|
||
|
||
Style profiles
|
||
|
||
Run metadata
|
||
|
||
8.2 GCS
|
||
|
||
Used for:
|
||
|
||
Logs
|
||
|
||
AI outputs
|
||
|
||
Generated patches
|
||
|
||
Deployment artifacts
|
||
|
||
Prompt snapshots
|
||
|
||
8.3 BigQuery
|
||
|
||
Used for:
|
||
|
||
Event warehouse
|
||
|
||
Funnels
|
||
|
||
Causality models
|
||
|
||
Experiment results
|
||
|
||
9. AI Integration
|
||
9.1 Gemini Proxy
|
||
|
||
All AI calls go through Control Plane.
|
||
|
||
Responsibilities:
|
||
|
||
Auth
|
||
|
||
Rate limiting
|
||
|
||
Prompt registry
|
||
|
||
Logging
|
||
|
||
Cost controls
|
||
|
||
9.2 AI Patch Contract
|
||
|
||
Gemini must return:
|
||
|
||
{
|
||
"files": [
|
||
{
|
||
"path": "src/main.ts",
|
||
"diff": "@@ -1,3 +1,6 @@ ..."
|
||
}
|
||
],
|
||
"commands": [
|
||
"npm test"
|
||
],
|
||
"summary": "Add logging middleware"
|
||
}
|
||
|
||
10. IAM Strategy
|
||
10.1 Users
|
||
|
||
OAuth only
|
||
|
||
No GCP IAM
|
||
|
||
No key files
|
||
|
||
10.2 Backend
|
||
|
||
Workload identity
|
||
|
||
No long-lived keys
|
||
|
||
Least privilege
|
||
|
||
Per-executor roles
|
||
|
||
11. Supported Languages
|
||
|
||
TypeScript / Node
|
||
|
||
Python
|
||
|
||
No additional languages in v1.
|
||
|
||
12. SaaS Autopilot Layer
|
||
|
||
A Supervisor AI Agent runs in Vertex AI Agent Designer.
|
||
|
||
It calls the same tools as the IDE.
|
||
|
||
Supervisor AI → Control Plane → Executors
|
||
|
||
13. Non-Goals
|
||
|
||
The platform does NOT:
|
||
|
||
Replace VS Code generically
|
||
|
||
Support all frameworks
|
||
|
||
Support multi-cloud
|
||
|
||
Allow raw IAM editing
|
||
|
||
Execute cloud commands locally
|
||
|
||
14. Repository Structure
|
||
/platform
|
||
/client-ide
|
||
/vscodium
|
||
/extensions
|
||
/backend
|
||
/control-plane
|
||
/executors
|
||
/contracts
|
||
/infra
|
||
/docs
|
||
|
||
15. Implementation Phases
|
||
Phase 1 – Core
|
||
|
||
Control Plane API
|
||
|
||
Deploy Executor
|
||
|
||
Gemini Proxy
|
||
|
||
IDE Deploy UI
|
||
|
||
Phase 2 – Intelligence
|
||
|
||
Firestore Executor
|
||
|
||
Analytics Executor
|
||
|
||
Funnel + driver tools
|
||
|
||
Phase 3 – Automation
|
||
|
||
Missinglettr Executor
|
||
|
||
Growth + Experiments
|
||
|
||
Supervisor AI
|
||
|
||
16. Final Statement
|
||
|
||
This system is a:
|
||
|
||
Google Cloud–native Product Operating System
|
||
for launching, growing, and automating SaaS products
|
||
using Gemini and backend-controlled automation.
|
||
|
||
Optional Next Steps
|
||
|
||
Generate Control Plane API scaffold
|
||
|
||
Generate Tool Registry schema
|
||
|
||
Generate VSCodium extension skeleton
|
||
|
||
Generate Terraform base
|
||
|
||
If you want, I can next generate:
|
||
|
||
The Control Plane API OpenAPI spec
|
||
|
||
The Tool Registry schema file
|
||
|
||
The First Executor service skeleton
|
||
|
||
The VSCodium extension skeleton
|
||
|
||
Tell me which one you want first. |