---
title: "Sprint 20: The Shadow Logger & Diagnostic Observability"
description: "Comprehensive backend HTTP boundary logging, full Prisma database query hooking, a robust asynchronous BigQuery diagnostic sink, and an admin-only God Mode interactive overlay."
---
# Sprint 20: The Shadow Logger & Diagnostic Observability
With our core game loop and economic mechanics locked down, Sprint 20 establishes a robust, enterprise-grade telemetry, audit, and diagnostic observability layer. This ensures absolute visibility into our high-velocity, serverless-deployed digital economy without introducing runtime latency.
## 🛠 Context & Required Skills for AI Agents
When working inside this context:
1. **Zero-Trust Administrative Claims**: Administrative actions, such as fetching unredacted solution vectors, must never expose client-side Firestore rules bypasses. Rely on secure Express APIs that verify session-based administrative claims.
2. **Non-Blocking Observability**: Diagnostic operations must execute asynchronously in the background. Never let telemetry operations delay or block the HTTP boundary handshake.
---
## 🗺 Sprint 20 Roadmap
### [x] Phase 0: Database & Schema Provisioning
- **Objective**: Set up necessary database schema modifications to support admin flags and verbose log collection.
- **Tasks**:
- Added the `is_admin` boolean column to the `PlayerAccount` Postgres model.
- Programmatically provisioned the `VerboseDebugLogs` table inside the Google Cloud BigQuery data warehouse.
### [x] Phase 1: The HTTP Boundary (Shadow Middleware)
- **Objective**: Establish global route request and response payload capturing.
- **Tasks**:
- Created global Express middleware `shadowLogger` to intercept `req.body` and hook `res.json` payloads.
- Calculated exact route execution latencies using `process.hrtime()` and emitted flat Newline Delimited JSON (NDJSON) with appropriate GCP severities.
### [x] Phase 2: The Database Boundary (Prisma Hooking)
- **Objective**: Globally trace database query execution timings and queries.
- **Tasks**:
- Enforced a central Prisma client configuration with strict connection pool limits (`max: 1`) suitable for serverless scale.
- Built a global `$extends` query hook to audit query timings and emit structured logs to `stdout`.
### [x] Phase 3: The BigQuery Debug Sink
- **Objective**: Construct an asynchronous, non-blocking telemetry log pipeline.
- **Tasks**:
- Built background-scheduled `TelemetryQueue` utilizing the BigQuery Storage Write API.
- Added coordinate clamping breach checks that trigger `severity: "WARNING"` anomaly logs.
- Hooked unhandled route exceptions to stream error call-stacks with `severity: "ERROR"` to BigQuery.
### [x] Phase 4: Client-Side "God Mode" Overlay
- **Objective**: Provide administrative visual tools in the Arena while preserving zero-trust security.
- **Tasks**:
- Refactored `bouncer.js` session resolution to inject `req.isAdmin` claims on authenticated request sessions.
- Implemented secure API endpoint `GET /debate/admin-vectors` to fetch active News Stub solution coordinate shifts.
- Developed and conditionally rendered the glassmorphic `<AdminDebugPanel />` diagnostics overlay for authenticated administrators.
---
## 🏁 Retrospective & Conclusion
Sprint 20 successfully delivered absolute system-wide observability to the PCMTG monorepo. Through global HTTP shadow logging and Prisma client query extensions, we capture all boundary actions and database transaction speeds with minimal overhead. Our asynchronous BigQuery telemetry queue guarantees background shipping of diagnostic data, while our glassmorphic God Mode UI gives administrators precise interactive vector diagnostics safely wrapped inside a Zero-Trust claims architecture.
