master-ai/platform/docs/GETTING_STARTED.md

Product OS - Getting Started

Project Structure

platform/
├── backend/
│   └── control-plane/       # Fastify API server
├── client-ide/
│   └── extensions/
│       └── gcp-productos/   # VSCodium/VS Code extension
├── contracts/               # Tool registry schemas
├── infra/
│   └── terraform/           # GCP infrastructure
├── docs/                    # Documentation
└── docker-compose.yml       # Local development

Quick Start (Local Development)

Prerequisites

• Node.js 22+
• Docker & Docker Compose
• (Optional) VS Code or VSCodium for extension development

1. Start Local Services

cd platform
docker-compose up -d

This starts:

• Firestore emulator on port 8081
• GCS emulator on port 4443
• Control Plane API on port 8080

2. Run Control Plane in Dev Mode

For faster iteration without Docker:

cd platform/backend/control-plane
cp env.example .env
npm install
npm run dev

3. Test the API

# Health check
curl http://localhost:8080/healthz

# List tools (empty initially)
curl http://localhost:8080/tools

# Invoke a tool (dry run)
curl -X POST http://localhost:8080/tools/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "cloudrun.deploy_service",
    "tenant_id": "t_dev",
    "input": {"service_name": "test"},
    "dry_run": true
  }'

4. Build & Install the Extension

cd platform/client-ide/extensions/gcp-productos
npm install
npm run build

Then in VS Code / VSCodium:

1. Open Command Palette (Cmd+Shift+P)
2. Run "Developer: Install Extension from Location..."
3. Select the gcp-productos folder

Or use the VSIX package:

npx vsce package
code --install-extension gcp-productos-0.0.1.vsix

Extension Usage

Once installed, use the Command Palette:

• Product OS: Configure Backend - Set the Control Plane URL
• Product OS: List Tools - View available tools
• Product OS: Invoke Tool - Execute a tool
• Product OS: Open Run - View run details

Deploying to GCP

1. Configure Terraform

cd platform/infra/terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your project details

2. Build & Push Container

cd platform/backend/control-plane

# Build
docker build -t us-central1-docker.pkg.dev/YOUR_PROJECT/productos/control-plane:latest .

# Push (requires gcloud auth)
docker push us-central1-docker.pkg.dev/YOUR_PROJECT/productos/control-plane:latest

3. Apply Terraform

cd platform/infra/terraform
terraform init
terraform plan
terraform apply

Seeding Tools

To add tools to the registry, you can:

1. Use the Firestore console to add documents to the tools collection
2. Create a seed script that loads contracts/tool-registry.yaml
3. Build an admin endpoint (coming in v2)

Next Steps

• Build Deploy Executor
• Build Analytics Executor
• Add Gemini integration
• Add OAuth/IAP authentication
• Create Product-Centric UI panels