OSVauco/docs/PLATFORM_MAP.md

# OSVx Platform Map

**Project ID:** `357036551735`  
**Primary region:** `us-central1`  
**Secondary region:** `europe-west1` (static site)  
**Owner:** OSVauco / Vauco  
**Last updated:** 2026-09-01

This document describes the Cloud Run–based platform that powers the OSVx MCP connector and related services. It is the canonical reference for designing CI/CD, security, and operational procedures.

## 1. Overview

The platform consists of:

- A production MCP backend for the OSVx Perplexity connector
- A staging/dev MCP service for pre-production testing
- An internal worker/API service used by the MCP backend
- A public static website (separate product)
- One legacy service marked for cleanup

All services run on Cloud Run with container images pinned by digest.

## 2. Services

### 2.1. MCP Backend (Production)

- **Current name:** `opax-mcp`
- **Planned name:** `osvx-mcp-prod`
- **Region:** `us-central1`
- **URL:** `https://opax-mcp-357036551735.us-central1.run.app/`
- **Image:** `.../opax-mcp@sha256:8adbd3f7...`
- **Last deployed:** 2026-09-01
- **Environment:** `prod`
- **Role:** Live OSVx MCP backend
- **Health check:** `GET /health` → `200 OK`
  ```json
  {"status":"ok","service":"opax-mcp","version":"3.5.0","ollama":"http://34.13.238.133:11434"}
  ```
- **Auth:** Bearer token via `MCP_SECRET`
- **Traffic:** 100% to current revision
- **Notes:**
    - Serves the OSVx connector in Perplexity.
    - Exposes MCP methods including `daily_ops_report`.
    - Version in code: `3.5.0` (matches `/health`).
- **Dependencies:**
    - Internal worker: `osvauco-agent` (via `OSVAUCO_AGENT_URL`)
    - Ollama endpoint (for model access)

### 2.2. MCP Backend (Staging / Dev)

- **Current name:** `osvx-mcp-dev`
- **Planned name:** `osvx-mcp-staging`
- **Region:** `us-central1`
- **URL:** `https://osvx-mcp-dev-…run.app/`
- **Image:** `.../opax-mcp@sha256:7b6a5c4b...`
- **Last deployed:** 2026-08-20
- **Environment:** `dev / staging`
- **Role:** Pre-production MCP service
- **Health check:** `GET /health` → `200 OK`
  ```json
  {"status":"ok","service":"opax-mcp","version":"3.4.0", ...}
  ```
- **Auth:** Bearer token (same mechanism as prod)
- **Traffic:** 100% to current revision
- **Notes:**
    - Runs an older version (`3.4.0`).
    - Intended for testing new MCP releases before promoting to prod.
- **Dependencies:**
    - Should ideally point to a staging instance of `osvauco-agent` (see §2.3).
    - Currently may share prod agent depending on env config.

### 2.3. Internal Worker / API

- **Name:** `osvauco-agent`
- **Region:** `us-central1`
- **URL:** Internal only (no public URL)
- **Image:** `.../osvauco-agent@sha256:1a2b3c4d...`
- **Last deployed:** 2026-08-28
- **Environment:** `prod`
- **Role:** Internal API / worker for MCP backend
- **Auth:** Internal-only; not publicly authenticated
- **Traffic:** Invoked by `opax-mcp` / `osvx-mcp-*` via `OSVAUCO_AGENT_URL`
- **Notes:**
    - Core dependency of the MCP backend.
    - Currently only a prod instance exists.
- **Decisions needed:**
    - Whether to create `osvauco-agent-staging` for full environment isolation.
    - Whether staging MCP should:
        1.  Share prod agent (simpler, less isolated), or
        2.  Use a dedicated staging agent (cleaner isolation, more moving parts).

### 2.4. Public Website

- **Name:** `vauco-site`
- **Region:** `europe-west1`
- **URL:** `https://vauco-site-…run.app/`
- **Image:** `.../web-static@sha256:e3b0c442...`
- **Last deployed:** 2026-03-15
- **Environment:** `prod`
- **Role:** Public marketing / product website
- **Health check:** `GET /` → `200 OK` (HTML)
- **Auth:** Public
- **Notes:**
    - Separate product from the MCP platform.
    - Should have its own CI/CD pipeline.
    - No direct dependency on MCP services.

### 2.5. Legacy / Cleanup Candidate

- **Name:** `opax-billing-test`
- **Region:** `us-central1`
- **URL:** No active URL (0% traffic)
- **Image:** `.../opax-billing@sha256:f1e2d3c4...`
- **Last deployed:** 2025-11-05
- **Environment:** `test`
- **Role:** Experimental billing service (no longer used)
- **Notes:**
    - No traffic allocated.
    - Not updated in >9 months.
    - Label: `env=test`.
- **Action:** Marked for deletion after final confirmation.

## 3. Environments

| Environment | MCP Service | Agent Service | Purpose |
| :--- | :--- | :--- | :--- |
| `prod` | `opax-mcp` | `osvauco-agent` | Live OSVx backend for Perplexity |
| `staging` | `osvx-mcp-dev` | (shared or dedicated) | Pre-production testing of MCP |
| `test` | (none active) | (none active) | Legacy/experimental (billing test) |

**Decisions:**

1.  **Adopt naming:**
    - `osvx-mcp-prod` (currently `opax-mcp`)
    - `osvx-mcp-staging` (currently `osvx-mcp-dev`)
2.  **Decide agent strategy for staging:**
    - Option A (simple): staging MCP shares prod `osvauco-agent`.
    - Option B (isolated): create `osvauco-agent-staging` and wire staging MCP to it.

## 4. Dependencies

### 4.1. Service-to-service

- `opax-mcp` → `osvauco-agent`
    - Via environment variable `OSVAUCO_AGENT_URL`.
- `osvx-mcp-dev` → `osvauco-agent` (or future `osvauco-agent-staging`).

### 4.2. External dependencies

- **Ollama endpoint**
    - Used by MCP for model access.
    - Currently: `http://34.13.238.133:11434` (from `/health` output).
- **GCP services**
    - Secret Manager (`MCP_SECRET` for Bearer token).
    - Cloud Build (for future CI/CD).
    - Artifact Registry (container images).

### 4.3. Missing dependencies (known issues)

- **`gcloud` CLI in MCP container**
    - `trigger_build` tool in `opax-mcp/server.py` calls `gcloud` via subprocess.
    - Dockerfile does not install `google-cloud-sdk`.
    - **Result:** any use of `trigger_build` on prod/staging will fail with “gcloud not found”.
    - **Fix:** Add `google-cloud-sdk` installation to the Dockerfile before enabling this tool.

## 5. Deployment Model

### 5.1. Image strategy

- All services use pinned image digests (`@sha256:...`).
- **CI/CD must:**
    1.  Build images with a commit-SHA label, e.g. `gcb-commit-sha=<COMMIT_SHA>`.
    2.  Deploy using the exact image digest produced by the build.

### 5.2. Environment promotion flow (target)

- **For the MCP platform:**
    1.  On push to `main` / feature branch:
        - Build `opax-mcp` image with commit-SHA label.
        - Deploy to `osvx-mcp-staging` (`osvx-mcp-dev`).
    2.  On manual approval or version tag:
        - Promote the same image to `osvx-mcp-prod` (`opax-mcp`).
- **For the website:**
    - Separate pipeline:
        - Build `web-static` image.
        - Deploy to `vauco-site`.
- **For the agent:**
    - Similar pattern if/when a staging agent is introduced.

### 5.3. Configuration gaps to address

- **No commit-SHA in images**
    - Images currently lack labels linking them to Git commits.
    - CI/CD should add `gcb-commit-sha` label during build.
- **Inconsistent naming**
    - Prod MCP: `opax-mcp`
    - Dev MCP: `osvx-mcp-dev`
    - Target: `osvx-mcp-prod` + `osvx-mcp-staging`.

## 6. Security & Access (high level)

- **MCP services (`opax-mcp`, `osvx-mcp-dev`)**
    - Require Bearer token (`MCP_SECRET`) for MCP calls.
    - Should restrict invocations to:
        - Perplexity’s connector infrastructure
        - Trusted service accounts (if calling from other GCP services).
- **Agent (`osvauco-agent`)**
    - Internal-only; no public ingress.
    - Should allow calls only from MCP service accounts.
- **Website (`vauco-site`)**
    - Public read access.
    - No privileged operations.

## 7. Operational Notes

- **Health checks**
    - MCP: `GET /health` on each MCP service.
    - Agent: define a simple `/health` if not already present.
    - Site: `GET /` as basic availability check.
- **Logging**
    - All services use Cloud Logging via Cloud Run.
    - Key logs to monitor:
        - MCP tool calls (`tools/call`), especially `daily_ops_report` and `trigger_build`.
        - Agent API errors.
- **Incident focus**
    - If OSVx connector misbehaves:
        1.  Check `opax-mcp` logs and revision.
        2.  Verify `/health` version matches expected deployment.
        3.  Confirm `MCP_SECRET` and connector URL.

## 8. Action Items

1.  **Cleanup**
    - [ ] Confirm `opax-billing-test` is unused.
    - [ ] Delete `opax-billing-test` service.
2.  **Naming alignment**
    - [ ] Decide final names:
        - `osvx-mcp-prod` vs keeping `opax-mcp`.
        - `osvx-mcp-staging` vs keeping `osvx-mcp-dev`.
    - [ ] Optionally rename services in GCP to match.
3.  **Agent environment strategy**
    - [ ] Decide: shared prod agent vs dedicated staging agent.
    - [ ] Document the decision here and implement if needed.
4.  **Image labeling**
    - [ ] Update Cloud Build config / Dockerfile for `opax-mcp` to include `gcb-commit-sha`.
5.  **`gcloud` dependency**
    - [ ] Add `google-cloud-sdk` to the MCP Dockerfile before enabling `trigger_build`.
6.  **CI/CD design**
    - [ ] Use this document as the basis for:
        - Build pipelines per service.
        - Promotion rules (staging → prod).
        - Environment-specific configs.

## 9. Future Extensions (optional)

- Per-developer ephemeral environments (short-lived Cloud Run revisions).
- Separate `osvx-mcp-sandbox` for integration tests in CI.
- Centralized config service or Secret Manager–driven config for env-specific URLs.

*This document is the source of truth for the OSVx platform architecture.
Update it whenever services, environments, or deployment patterns change.*

---

## 10. CI/CD Setup

This section describes the continuous integration and deployment architecture for the OSVx MCP platform.

### 10.1. Source of Truth

- **Primary Git repository:**  
  Self-hosted Gitea: `http://34.59.131.162:3000/chris/osvauco.git`
- **Primary branch for MCP:**  
  `feat/osvx-mcp-full-catalog`

All development and code review happens in Gitea. No other Git host is used as a primary source.

### 10.2. Mirror to Cloud Source Repositories

Cloud Build cannot directly trigger on Gitea pushes, so the repo is mirrored to Cloud Source Repositories (CSR) as a read-only CI/CD mirror.

- **CSR project:** `357036551735`
- **CSR repo name:** `osvauco`
- **CSR repo URL:**  
  `https://source.developers.google.com/p/357036551735/r/osvauco`

Mirror configuration (on the VM):

```bash
cd ~/OSVauco
git remote add csr https://source.developers.google.com/p/357036551735/r/osvauco
git push csr feat/osvx-mcp-full-catalog:feat/osvx-mcp-full-catalog
```

Mirroring is automated via either:

- A post-receive hook on the Gitea server that pushes `feat/osvx-mcp-full-catalog` to `csr`, or  
- A cron job on the VM that periodically runs:
  ```bash
  git push --quiet csr feat/osvx-mcp-full-catalog:feat/osvx-mcp-full-catalog
  ```

CSR is **read-only** from the CI/CD perspective; it exists only to trigger Cloud Build.

### 10.3. Cloud Build Trigger (Staging)

A Cloud Build trigger watches the CSR repo and runs the MCP pipeline on every push to the CI branch.

- **Trigger name:** `osvx-mcp-staging-trigger`
- **Trigger type:** Cloud Source Repositories
- **Project:** `357036551735`
- **Region:** `us-central1`
- **Repo:** `projects/357036551735/repos/osvauco`
- **Branch pattern:** `^feat/osvx-mcp-full-catalog$`
- **Build config:** `opax-mcp/cloudbuild.yaml`
- **Substitutions:**
  - `_REGION=us-central1`
  - `_REPOSITORY=osvx-images`
  - `_ENV=staging`

Creation command (reference):

```bash
PROJECT=357036551735
REGION=us-central1
REPO=osvx-images
BRANCH=feat/osvx-mcp-full-catalog

gcloud builds triggers create cloud-source-repositories   --project="$PROJECT"   --name="osvx-mcp-staging-trigger"   --region="$REGION"   --repo="projects/$PROJECT/repos/osvauco"   --branch-pattern="^${BRANCH}$"   --build-config="opax-mcp/cloudbuild.yaml"   --substitutions=_REGION=${REGION},_REPOSITORY=${REPO},_ENV=staging   --included-files="opax-mcp/**"   --description="Deploy OSVx MCP to staging on push to ${BRANCH}"
```

**Behavior:**

- On every push to `feat/osvx-mcp-full-catalog` in Gitea (mirrored to CSR):
  - Cloud Build runs `opax-mcp/cloudbuild.yaml` with `_ENV=staging`.
  - The built image is deployed to `osvx-mcp-staging`.

### 10.4. Production Deployment (Manual Promotion)

Production deployments are intentionally manual to provide an explicit promotion gate.

**Options:**

1.  **Local script (recommended):**
    ```bash
    cd ~/OSVauco
    ./deploy-mcp.sh prod
    ```
    This builds the current commit and deploys to `osvx-mcp-prod`.

2.  **One-off Cloud Build:**
    ```bash
    PROJECT=357036551735
    REGION=us-central1
    REPO=osvx-images

    gcloud builds submit .       --project="$PROJECT"       --config=opax-mcp/cloudbuild.yaml       --substitutions=_REGION=${REGION},_REPOSITORY=${REPO},_ENV=prod
    ```

No automatic prod trigger is configured.

### 10.5. Artifact Registry

- **Repo name:** `osvx-images`
- **Location:** `us-central1`
- **Format:** Docker

Images are tagged with the short commit SHA:

- `us-central1-docker.pkg.dev/357036551735/osvx-images/opax-mcp:<SHORT_SHA>`

Each image includes labels:

- `gcb-commit-sha=<SHORT_SHA>`
- `env=staging` or `env=prod`

### 10.6. Operational Notes

- **Build logs and history:**  
  GCP Console → Cloud Build → History
- **Trigger configuration:**  
  GCP Console → Cloud Build → Triggers → `osvx-mcp-staging-trigger`
- **To temporarily disable CI:**  
  Disable or delete `osvx-mcp-staging-trigger` in the Cloud Build console.
- **To change the CI branch:**  
  Update the trigger’s branch pattern and the mirror configuration.