brainy/docs/deployment/gcp-deployment.md

# Google Cloud Platform Deployment Guide for Brainy

## Overview
Deploy Brainy on GCP with automatic scaling, global distribution, and zero-config dynamic adaptation. Brainy automatically detects and optimizes for GCP services.

## Quick Start (Zero-Config)

### Option 1: Cloud Run (Serverless Containers)

```bash
# Build and deploy with one command
gcloud run deploy brainy \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

# Brainy auto-detects Cloud Run and configures:
# - Memory-optimized caching
# - GCS for storage (if available)
# - Cloud SQL for metadata (if available)
```

### Option 2: Cloud Functions (Serverless)

```javascript
// index.js
const { Brainy } = require('@soulcraft/brainy')

let brain

exports.brainyHandler = async (req, res) => {
  // Zero-config - auto-adapts to Cloud Functions
  if (!brain) {
    brain = new Brainy() // Detects GCP environment automatically
    await brain.init()
  }
  
  const { method, ...params } = req.body
  
  try {
    let result
    switch(method) {
      case 'add':
        result = await brain.add(params)
        break
      case 'find':
        result = await brain.find(params)
        break
      case 'relate':
        result = await brain.relate(params)
        break
      default:
        return res.status(400).json({ error: 'Unknown method' })
    }
    res.json({ result })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
}
```

Deploy:
```bash
gcloud functions deploy brainy \
  --runtime nodejs20 \
  --trigger-http \
  --entry-point brainyHandler \
  --memory 512MB \
  --timeout 60s
```

### Option 3: Google Kubernetes Engine (GKE)

```bash
# Create autopilot cluster (fully managed, zero-config)
gcloud container clusters create-auto brainy-cluster \
  --region us-central1

# Deploy using Cloud Build
gcloud builds submit --tag gcr.io/$PROJECT_ID/brainy

# Apply Kubernetes manifest
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: brainy
spec:
  replicas: 3
  selector:
    matchLabels:
      app: brainy
  template:
    metadata:
      labels:
        app: brainy
    spec:
      containers:
      - name: brainy
        image: gcr.io/$PROJECT_ID/brainy
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
        env:
        - name: NODE_ENV
          value: production
---
apiVersion: v1
kind: Service
metadata:
  name: brainy-service
spec:
  type: LoadBalancer
  selector:
    app: brainy
  ports:
  - port: 80
    targetPort: 3000
EOF
```

## Zero-Config Storage (Automatic)

Brainy automatically detects and uses the best GCP storage:

```javascript
const brain = new Brainy()
// Auto-detection priority:
// 1. Firestore (if available)
// 2. Cloud Storage (GCS)
// 3. Cloud SQL
// 4. Persistent Disk
// 5. Memory (fallback)
```

### Cloud Storage Configuration (Optional)

```javascript
const brain = new Brainy({
  storage: {
    type: 's3', // GCS is S3-compatible
    options: {
      endpoint: 'https://storage.googleapis.com',
      bucket: process.env.GCS_BUCKET || 'auto', // Auto-creates bucket
      // Uses Application Default Credentials automatically
    }
  }
})
```

### Firestore Integration (Optional)

```javascript
const brain = new Brainy({
  storage: {
    type: 'firestore',
    options: {
      projectId: process.env.GCP_PROJECT || 'auto',
      collection: 'brainy-data'
    }
  }
})
```

## Scaling Strategies

### 1. Cloud Run Auto-scaling

```yaml
# service.yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: brainy
  annotations:
    run.googleapis.com/execution-environment: gen2
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: "1"
        autoscaling.knative.dev/maxScale: "1000"
        autoscaling.knative.dev/target: "80"
    spec:
      containerConcurrency: 100
      containers:
      - image: gcr.io/PROJECT_ID/brainy
        resources:
          limits:
            cpu: "2"
            memory: "2Gi"
```

### 2. GKE Horizontal Pod Autoscaling

```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: brainy-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: brainy
  minReplicas: 3
  maxReplicas: 100
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
```

## Global Distribution

### Multi-Region Setup

```javascript
// Brainy automatically handles multi-region with GCS
const brain = new Brainy({
  distributed: {
    enabled: true,
    regions: ['us-central1', 'europe-west1', 'asia-northeast1'],
    replication: 'auto' // Automatic cross-region replication
  }
})
```

### Traffic Director Configuration

```bash
# Global load balancing with Traffic Director
gcloud compute backend-services create brainy-global \
  --global \
  --load-balancing-scheme=INTERNAL_SELF_MANAGED \
  --protocol=HTTP2

gcloud compute backend-services add-backend brainy-global \
  --global \
  --network-endpoint-group=brainy-neg \
  --network-endpoint-group-region=us-central1
```

## Monitoring & Observability

### Cloud Monitoring (Automatic)

Brainy automatically sends metrics to Cloud Monitoring:

```javascript
// No configuration needed - automatic when running on GCP
const brain = new Brainy()

// Automatic metrics:
// - Request latency
// - Error rate
// - Storage operations
// - Cache hit rate
// - Memory usage
```

### Custom Metrics

```javascript
const { Monitoring } = require('@google-cloud/monitoring')
const monitoring = new Monitoring.MetricServiceClient()

const brain = new Brainy({
  onMetric: async (metric) => {
    // Send custom metrics to Cloud Monitoring
    await monitoring.createTimeSeries({
      name: monitoring.projectPath(projectId),
      timeSeries: [{
        metric: {
          type: `custom.googleapis.com/brainy/${metric.name}`,
          labels: metric.labels
        },
        points: [{
          interval: { endTime: { seconds: Date.now() / 1000 } },
          value: { doubleValue: metric.value }
        }]
      }]
    })
  }
})
```

### Cloud Trace Integration

```javascript
const brain = new Brainy({
  tracing: {
    enabled: true,
    sampleRate: 0.1 // Sample 10% of requests
  }
})
```

## Security Best Practices

### 1. Workload Identity (GKE)

```yaml
# Enable Workload Identity
apiVersion: v1
kind: ServiceAccount
metadata:
  name: brainy-sa
  annotations:
    iam.gke.io/gcp-service-account: brainy@PROJECT_ID.iam.gserviceaccount.com
```

### 2. Binary Authorization

```yaml
# Ensure only signed container images
apiVersion: binaryauthorization.grafeas.io/v1beta1
kind: Policy
metadata:
  name: brainy-policy
spec:
  defaultAdmissionRule:
    requireAttestationsBy:
    - projects/PROJECT_ID/attestors/prod-attestor
```

### 3. VPC Service Controls

```bash
# Create VPC Service Perimeter
gcloud access-context-manager perimeters create brainy_perimeter \
  --resources=projects/PROJECT_NUMBER \
  --restricted-services=storage.googleapis.com \
  --title="Brainy Security Perimeter"
```

## Cost Optimization

### 1. Preemptible VMs (80% savings)

```yaml
# GKE node pool with preemptible VMs
apiVersion: container.cnrm.cloud.google.com/v1beta1
kind: ContainerNodePool
metadata:
  name: brainy-preemptible-pool
spec:
  clusterRef:
    name: brainy-cluster
  config:
    preemptible: true
    machineType: n2-standard-2
  autoscaling:
    minNodeCount: 1
    maxNodeCount: 10
```

### 2. Cloud CDN for Static Assets

```bash
# Enable Cloud CDN for frequently accessed data
gcloud compute backend-buckets create brainy-assets \
  --gcs-bucket-name=brainy-static

gcloud compute backend-buckets update brainy-assets \
  --enable-cdn \
  --cache-mode=CACHE_ALL_STATIC
```

### 3. Committed Use Discounts

```bash
# Purchase committed use for predictable workloads
gcloud compute commitments create brainy-commitment \
  --plan=TWELVE_MONTH \
  --resources=vcpu=100,memory=400
```

## Deployment Automation

### Cloud Build CI/CD

```yaml
# cloudbuild.yaml
steps:
  # Build container
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/brainy:$SHORT_SHA', '.']
  
  # Push to registry
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/brainy:$SHORT_SHA']
  
  # Deploy to Cloud Run
  - name: 'gcr.io/cloud-builders/gcloud'
    args:
    - 'run'
    - 'deploy'
    - 'brainy'
    - '--image=gcr.io/$PROJECT_ID/brainy:$SHORT_SHA'
    - '--region=us-central1'
    - '--platform=managed'

# Trigger on push to main
trigger:
  branch:
    name: main
```

### Terraform Infrastructure

```hcl
# main.tf
resource "google_cloud_run_service" "brainy" {
  name     = "brainy"
  location = "us-central1"

  template {
    spec {
      containers {
        image = "gcr.io/${var.project_id}/brainy"
        
        resources {
          limits = {
            cpu    = "2"
            memory = "2Gi"
          }
        }
        
        env {
          name  = "NODE_ENV"
          value = "production"
        }
      }
    }
  }

  traffic {
    percent         = 100
    latest_revision = true
  }
}

resource "google_cloud_run_service_iam_member" "public" {
  service  = google_cloud_run_service.brainy.name
  location = google_cloud_run_service.brainy.location
  role     = "roles/run.invoker"
  member   = "allUsers"
}
```

## Performance Optimization

### 1. Memory Store (Redis Compatible)

```javascript
// Brainy can use Memorystore for caching
const brain = new Brainy({
  cache: {
    type: 'redis',
    options: {
      host: process.env.REDIS_HOST || 'auto-detect',
      port: 6379
    }
  }
})
```

### 2. Cloud Spanner for Global Consistency

```javascript
const brain = new Brainy({
  metadata: {
    type: 'spanner',
    options: {
      instance: 'brainy-instance',
      database: 'brainy-db'
    }
  }
})
```

## Troubleshooting

### Common Issues

1. **Quota Exceeded**
   ```bash
   # Check quotas
   gcloud compute project-info describe --project=$PROJECT_ID
   
   # Request increase
   gcloud compute project-info add-metadata \
     --metadata google-compute-default-region=us-central1
   ```

2. **Cold Starts**

   **v7.3.0+ Progressive Initialization (Zero-Config)**

   Brainy automatically detects Cloud Run and Cloud Functions environments
   and uses progressive initialization for <200ms cold starts:

   ```javascript
   // Zero-config - Brainy auto-detects Cloud Run (K_SERVICE env var)
   const brain = new Brainy({
     storage: {
       type: 'gcs',
       gcsNativeStorage: { bucketName: 'my-bucket' }
     }
   })
   await brain.init() // Returns in <200ms

   // First write validates bucket (lazy validation)
   await brain.add('noun', { name: 'test' }) // Validates here
   ```

   **Manual Override (if needed)**
   ```javascript
   const brain = new Brainy({
     storage: {
       type: 'gcs',
       gcsNativeStorage: {
         bucketName: 'my-bucket',
         // Force specific mode
         initMode: 'progressive' // 'auto' | 'progressive' | 'strict'
       }
     }
   })
   ```

   | Mode | Cold Start | Best For |
   |------|------------|----------|
   | `auto` (default) | <200ms in cloud | Zero-config, auto-detects |
   | `progressive` | <200ms always | Force fast init everywhere |
   | `strict` | 100-500ms+ | Local dev, tests, debugging |

   **Keep Warm (Alternative)**
   ```javascript
   // Keep minimum instances warm
   const brain = new Brainy({
     warmup: {
       enabled: true,
       interval: 60000 // Ping every minute
     }
   })
   ```

   **Readiness Detection (v7.3.0+)**

   Use the `brain.ready` Promise to ensure Brainy is initialized before handling requests:

   ```javascript
   let brain

   async function handleRequest(req, res) {
     if (!brain) {
       brain = new Brainy({ storage: { type: 'gcs', ... } })
       brain.init()  // Fire and forget
     }

     // Wait for initialization to complete
     await brain.ready

     // Now safe to use brain methods
     const results = await brain.find({ query: req.query.q })
     res.json(results)
   }
   ```

   For Cloud Run health checks, use `isFullyInitialized()` to verify all background tasks are complete:

   ```javascript
   // Health check endpoint for Cloud Run
   app.get('/health', async (req, res) => {
     try {
       await brain.ready
       res.json({
         status: 'ready',
         fullyInitialized: brain.isFullyInitialized()
       })
     } catch (error) {
       res.status(503).json({ status: 'initializing' })
     }
   })
   ```

3. **Memory Pressure**
   ```javascript
   // Optimize for GCP memory constraints
   const brain = new Brainy({
     memory: {
       mode: 'aggressive', // Aggressive garbage collection
       maxHeap: 0.8        // Use 80% of available memory
     }
   })
   ```

## Production Checklist

- [ ] Enable Workload Identity for secure access
- [ ] Configure Cloud Armor for DDoS protection
- [ ] Set up Cloud KMS for encryption keys
- [ ] Enable VPC Service Controls
- [ ] Configure Cloud IAP for authentication
- [ ] Set up Cloud Monitoring dashboards
- [ ] Configure Error Reporting
- [ ] Enable Cloud Trace
- [ ] Set up budget alerts
- [ ] Configure backup and disaster recovery

## Support

- Documentation: https://brainy.soulcraft.ai/docs
- Issues: https://github.com/soulcraft/brainy/issues
- GCP Marketplace: https://console.cloud.google.com/marketplace/product/brainy