Production AI Architecture Blueprints

# System Architecture & Topology

1. Ingress Layer:
   Client (Web/Mobile) ──[App Check Token]──> Cloud Run Ingress Gateway
   
2. State & Session Coordination:
   Cloud Run ──[Single Source of Truth]──> Cloud Firestore (Transaction Lock)
   
3. Inference Execution:
   Gateway ──[Streaming SSE]──> Gemini 3.7 Flash ──[Tool Call Schema]──> MCP Server

"tok-keyword">import { getFirestore, "tok-type">FieldValue } "tok-keyword">from "firebase-admin/firestore";

"tok-keyword">interface "tok-type">SessionLock {
  lockedBy: "tok-type">string;
  lockedAt: "tok-type">number;
  status: "ACQUIRED" | "RELEASED";
  turnCount: "tok-type">number;
}

"tok-comment">/**
 * Acquires a leased lock on the agent session in a Firestore transaction before tool execution.
 * Server SDKs lock the documents a transaction reads, so contending workers retry.
 * Throws an error "tok-keyword">if another worker holds an active lock.
 */
"tok-keyword">export "tok-keyword">async "tok-keyword">function acquireSessionLock(
  sessionId: "tok-type">string,
  workerId: "tok-type">string
): "tok-type">Promise<"tok-type">void> {
  "tok-keyword">const db = getFirestore();
  "tok-keyword">const sessionRef = db.collection("agent_sessions").doc(sessionId);

  "tok-keyword">await db.runTransaction("tok-keyword">async (transaction) => {
    "tok-keyword">const snap = "tok-keyword">await transaction.get(sessionRef);
    "tok-keyword">const data = snap.data() "tok-keyword">as "tok-type">SessionLock | "tok-type">undefined;

    "tok-keyword">const now = Date.now();
    "tok-keyword">const isLocked = data?.status === "ACQUIRED" && (now - data.lockedAt < 30_000);

    "tok-keyword">if (isLocked && data?.lockedBy !== workerId) {
      "tok-keyword">throw "tok-keyword">new Error(`Concurrent mutation blocked: Session ${sessionId} is locked by worker ${data.lockedBy}.`);
    }

    transaction.set(sessionRef, {
      lockedBy: workerId,
      lockedAt: now,
      status: "ACQUIRED",
      turnCount: "tok-type">FieldValue.increment(1)
    }, { merge: true });
  });
}

"tok-keyword">import { getFirestore, "tok-type">FieldValue } "tok-keyword">from "firebase-admin/firestore";

"tok-keyword">const DAILY_TOKEN_BUDGET = 250_000;

"tok-keyword">export "tok-keyword">async "tok-keyword">function verifyTokenBudget(
  userId: "tok-type">string,
  estimatedTokens: "tok-type">number
): "tok-type">Promise<{ allowed: "tok-type">boolean; remainingTokens: "tok-type">number }> {
  "tok-keyword">const db = getFirestore();
  "tok-comment">// One document per user per UTC day, so the daily budget refills at midnight UTC
  "tok-keyword">const quotaRef = db.collection("token_quotas").doc(userId + "_" + "tok-keyword">new Date().toISOString().slice(0, 10));

  "tok-keyword">return "tok-keyword">await db.runTransaction("tok-keyword">async (tx) => {
    "tok-keyword">const snap = "tok-keyword">await tx.get(quotaRef);
    "tok-keyword">const used = snap.data()?.usedTokens ?? 0;

    "tok-keyword">if (used + estimatedTokens > DAILY_TOKEN_BUDGET) {
      "tok-keyword">return { allowed: false, remainingTokens: Math.max(0, DAILY_TOKEN_BUDGET - used) };
    }

    tx.set(quotaRef, {
      usedTokens: "tok-type">FieldValue.increment(estimatedTokens),
      lastUpdated: Date.now()
    }, { merge: true });

    "tok-keyword">return { allowed: true, remainingTokens: DAILY_TOKEN_BUDGET - (used + estimatedTokens) };
  });
}

# Backend API & Tool Handshake Contracts

- Endpoint: POST /api/v1/agent/deliberate
- Headers:
  - X-Firebase-AppCheck: <JWT>
  - Authorization: Bearer <ID_TOKEN>
- Error Handling Contract:
  - 401: Invalid App Check Attestation (Abort immediately)
  - 429: Token Burn Ceiling reached (Return cached summary)
  - 503: Model temporarily overloaded (Retry with exponential backoff)

"tok-keyword">version: "1.0"
"tok-keyword">pipeline: "deterministic-agent-runtime"
"tok-keyword">verification_gates:
  - stage: "01_syntax"
"tok-keyword">    command: "node --check dist/server.js"
"tok-keyword">    required: true
  - stage: "02_contracts"
"tok-keyword">    command: "npm run test:contracts"
"tok-keyword">    required: true
  - stage: "03_attestation"
"tok-keyword">    command: "curl -H &"tok-comment">#039;X-Firebase-AppCheck: token' https://SERVICE-PROJECT_NUMBER.REGION.run.app/health"
"tok-keyword">    required: true
  - stage: "04_tokenomics_audit"
"tok-keyword">    command: "node scripts/verify-token-caps.mjs"
"tok-keyword">    required: true