surge-agent

Tagline: A Multi-Tenant Geospatial ad server, programmatic Vickrey auction engine, and dynamic yield governor for high-velocity physical retail zones.

🛠️ The Architecture (How it Works)

surge-agent converts physical location zones (West Wing, Fan Plaza, Stadium Snacks) into digital ad inventory slots. During high-traffic events (like the 2026 World Cup), the engine consumes raw Wi-Fi telemetry, calculates crowd density, runs programmatic ad auctions, and dynamically modulates consumer pricing in real time.

                  [Telemetry Pings]
                          │
                          ▼
             ┌─────────────────────────┐
             │  Edge Aggregator Buffer │ (Memory-pooled 10s window)
             └────────────┬────────────┘
                          ▼
             ┌─────────────────────────┐
             │ Time-Series Collections │ (raw_spatial_logs, TTL indices)
             └────────────┬────────────┘
                          ▼
             ┌─────────────────────────┐
             │  Geospatial Resolver   │ (MongoDB 2dsphere / $geoWithin)
             └────────────┬────────────┘
                          ▼
┌──────────────────────────────────────────────────┐
│             Programmatic RTB Engine              │
├──────────────────────────────────────────────────┤
│ 1. Dynamic Quality Score (Stock-dependent QS)    │
│ 2. Foot-Traffic Surge Adjusters (1.5x Multiplier)│
│ 3. Vickrey Second-Price Settlement Auction Loop  │
└────────────────────────┬─────────────────────────┘
                         ▼
             ┌─────────────────────────┐
             │  Dynamic Yield Governor │ (Search Scarcity vs. Stimulation)
             └─────────────────────────┘

1. Programmatic Real-Time Bidding (RTB) & Vickrey Settlement

When a search or location ping occurs, surge-agent triggers an ad-matching pipeline:

• Ad Ranking: Evaluates candidates targeting the active zone: $$\text{Ad Rank} = \text{Max CPC Bid} \times \text{Quality Score (QS)} \times \text{Surge Multiplier}$$
• Stock-Dependent QS: QS scales based on inventory context. If stock hits the safety buffer threshold, the QS drops to $0$ instantly, stripping the campaign from the auction to prevent over-selling.
• Second-Price Pricing: Billed CPC is settled using Vickrey mechanics: $$\text{Billed CPC} = \frac{\text{Runner-Up Ad Rank}}{\text{Winner } QS \times \text{Surge Multiplier}} + \$0.01$$
• Atomic Cost-Splitting: Supports Co-Opetition Joint Bundles. If a joint campaign wins the auction (e.g., Nike x Red Bull), the settled Vickrey CPC is split 50/50 and atomically deducted from both partner merchant budgets simultaneously.

2. Pedestrian Density Surge Adjusters

Wi-Fi beacon logs are digested to track active devices inside Zone polygons. When visitor count inside the geofence crosses $\ge 5$, a 1.5x Ad Rank Multiplier is applied to bids targeting that region, raising bid values dynamically in crowded zones.

3. Dynamic Yield & Search-Driven Discounts

The engine tracks search velocity and cart additions to adjust product pricing on the fly:

• Scarcity Rule: High searches ($\ge 10$) + low stock $\implies$ Flash discount drops to 5% to preserve margin.
• Stimulation Rule: High searches ($\ge 5$) + zero cart additions $\implies$ Price is cut by 30% to stimulate immediate purchase conversion.
• Asynchronous Telemetry Buffer: Rather than hitting the database directly for every search/cart event, events are buffered in memory and flushed in batches every 5 seconds to eliminate write bottlenecks.

🎛️ System Design & Tech Stack

• Database (MongoDB Atlas):
  • 2dsphere Geospatial Indexing: Resolves coordinate telemetry pings against polygon geofences via $geoWithin and $geoIntersects queries.
  • Time-Series Collections: Raw pings are collected using a 24h TTL index, and consolidated hourly into a historical_trends collection via a background rollup daemon.
  • CSFLE Fallback: Transparent Field-Level Encryption utilizing Fernet keys to secure sensitive fields (wholesale pricing, merchant profit margins) at rest.
  • Multi-Tenant Wrapper Layer: All database reads, writes, and aggregation pipelines are run through a tenanted collection proxy that automatically injects {"tenantId": active_tenant_id} filters.
• Backend API (FastAPI + Python 3.12): Provides high-throughput async endpoints, running a decoupled telemetry flush loop and orchestrating the programmatic RTB auctions.
• Frontend Dashboard (Next.js 16 + React 19): Responsive glassmorphic dark-mode UI containing three active tabs: Map Operations, Shopping Simulator, and the Merchant Campaign Management Deck.

⚡ The Hard Parts (Challenges & Workarounds)

• ACID Transactions vs. Geospatial Queries: MongoDB does not allow $near geospatial operations inside active transaction sessions. We solved this by separating the geospatial warehouse matching stage outside the session, compiling target coordinates, and then executing the final B2B inventory transfer atomically inside the ACID transaction.
• JSX Tree Mismatch Under High Density: Managing the state loops for real-time SSE auction logs, traffic controls, and joint campaigns led to unclosed tags during layout nesting. We resolved the compilation errors by auditing the JSX structure and adding missing layout wrapper closures.
• Vickrey Settlement Edge Cases: If an auction only has one qualified bidder, the Vickrey formula divider drops. We implemented a fallback flat-minimum threshold ($0.05) to ensure campaigns are not served for free while maintaining math integrity.

🧪 Verification & Dev Pipeline

• Backend Unit Tests: Verified via pytest backend/test_upgrades.py with 100% pass rate (7/7 tests passing). Covers atomic transaction splits, multi-tenant isolation, telemetry flushes, and Vickrey calculations.
• Type Check: Clean npx tsc --noEmit validation.
• Production Build: Success on Next.js optimization pipeline (npm run build).

Built With

• css
• fastapi
• mongodb
• next.js
• python
• typescript
• uvicorn