> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcm.game/llms.txt
> Use this file to discover all available pages before exploring further.

# IV. System Architecture & Infrastructure

> The serverless GCP topology, Cloud Run Engine Room, and Next.js frontend.

## 4.1 The Google-Native Tech Stack (Serverless & Zero-Trust)

PCMTG is engineered on a fully serverless, event-driven topology within the Google Cloud Platform (GCP). The primary directive is to eliminate operational overhead (NoOps) while ensuring instantaneous elasticity.

* **Compute:** Cloud Run handles high-frequency game logic and real-time state without provisioning virtual machines.
* **Frontend:** Vercel-like Next.js deployments are handled natively within GCP via Firebase App Hosting. This allows the frontend to communicate with Cloud Run microservices via internal VPC peering.
* **Security & IAM:** The ecosystem operates on a "Least Privilege" Service Account model. For example, the Next.js frontend has no permission to directly trigger the Vertex AI generation pipeline.

## 4.2 The Control Plane (Orchestration & Automation)

The Control Plane manages the flow of time, secret management, and code delivery.

* **Cloud Scheduler & Pub/Sub:** Cloud Scheduler acts as the metronome, emitting events to Pub/Sub topics. It fires a "Matchmaker Tick" every 60s to resolve tables, and an "Economist Tick" to execute GIP decay math.
* **Fault Tolerance:** Pub/Sub retains messages in a dead-letter queue if a Cloud Run service cold-starts or fails, ensuring no game state resolutions are dropped.
* **Secret Manager:** Hardcoded API keys are strictly forbidden. Sensitive strings are stored in Google Secret Manager and injected into Cloud Run instances only at runtime.

## 4.3 The Engine Room

The Engine Room handles the secure execution of game rules, ensuring no math is trusted to the client.

* **Cloud Run Concurrency:** Configured for high concurrency (up to 80 requests per container) rather than spinning up one instance per request. A single container can process batches of "Based" button presses simultaneously, saving massive compute costs.
* **Language Split:** Data engineering and AI pipelines use Python (FastAPI). Core game logic and matchmaking use Node.js (Express or NestJS).

## 4.4 Client-Side Rendering (The PWA)

* **Next.js (App Router):** Hosted via Firebase App Hosting. Uses Server-Side Rendering (SSR) for dynamic Open Graph (OG) tags when memes are shared on social media.
* **Real-Time Streaming:** Bypasses resource-heavy short-polling. The client leverages the Firebase Client SDK to establish an `onSnapshot` listener to their specific `ActiveTable` document. Firestore pushes state updates (like flipping cards at zero) to the React client in single-digit milliseconds.

## 4.5 The AI-Native Dev Environment

* **Primary IDE:** Google Antigravity acts as the central AI-first IDE, integrating with the GCP project to read logs and execute deployments.
* **Heavyweight Models:** Claude 3.5 Sonnet handles complex UI generation and React scaffolding. Gemini 1.5 Pro handles holistic architectural reasoning and Cloud Run logic generation.
* **Pipeline Models:** Gemini 3.1 Lite is explicitly routed for the News Stub analysis pipeline due to its high speed and cost efficiency.
* **Local LLM Fallback:** An automated try-catch block routes Vertex AI safety filter rejections via SSH tunnel to a local Ubuntu machine running open-weight models (Llama 3 8B or Gemma 2 9B via Ollama) to generate uncensored satirical text.