🚀 Winner of the Google Cloud Rapid Agent Hackathon — MongoDB Track 🚀
MallPulse is an enterprise-grade brick-and-mortar mall inventory intelligence and fulfillment platform.
In physical retail malls, individual tenants operate inside separate, disconnected informational silos. When an in-store shopper complains that an item variant (color, or size) is out of stock, they leave frustrated, even if the exact SKU is available at a sibling store merely yards away under the same mall roof.
MallPulse acts as a geospatial-to-semantic inventory bridge that integrates independent store databases, enabling conversational search, multi-tenant inventory lookups, indoor walking route calculation, and ACID-compliant stock reservations with automated 15-minute TTL expirations.
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│ │ React PWA │ │ SVG Map │ │ WebSockets │ │ Offline │ │
│ │ (Shopper) │ │ (Indoor Navigation) │ (Sync) │ │ Shell │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └────┬────┘ │
└────────┼───────────────┼───────────────┼─────────────┼──────┘
│ │ │ │ HTTPS
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ GOOGLE CLOUD RUN (BACKEND) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ API GATEWAY (HTTPS) │ │
│ └──────────────────────────┬──────────────────────────┘ │
│ │ │
│ ┌──────────────────────────┴──────────────────────────┐ │
│ │ SUPERVISOR AGENT (Gemini) │ │
│ └──────┬───────────────────┬───────────────────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Shopper Intel│ │ Inventory │ │ Fulfillment │ │
│ │ Agent │ │ Locator Agent│ │ Coordinator │ │
│ └──────────────┘ └──────┬───────┘ └──────┬───────┘ │
└──────────────────────────────┼───────────────────┼──────────┘
│ │ TCP /
▼ ▼ SCRAM-SHA-256
┌─────────────────────────────────────────────────────────────┐
│ MONGODB ATLAS (DATA ENGINE LAYER) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ - Tenants Collection (2dsphere geospatial search index) │ │
│ │ - Inventory Collection (Atlas Vector Search & Indexing) │ │
│ │ - Reservations Collection (15-min TTL automated index) │ │
│ │ - sessions_and_memory (Atomic conversational checkpoints)│ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
- Move Beyond Chat: The agent goes beyond simple conversational assistance; it handles atomic business logic: querying databases, performing spatial and rating lookups, executing strict ACID reservation transactions, and outputting physical navigation routes.
- Sequential Tool Chaining Density: The Supervisor Agent interprets intent via a parsing loop, triggers spatial queries in response, coordinates stock-locking transactions, and prints map layouts sequentially.
- Deep MongoDB Track Integration:
- 2dsphere Indexing: Powering proximity matching coordinates within decimal degrees inside specific boundaries.
- TTL Automation: The reservations are bound to an expiration parameter which MongoDB's background thread cleans atomically.
- Change Streams: Stock changes are dynamically tracked and synchronized back to active user browsers, avoiding race conditions.
- Production Readiness Grade: Fully prepared with secure multi-stage Dockerfiles, Terraform provisioning coordinates, Cloud Build actions, and unified structured JSON logs.
The complete production source tree is formatted exactly as follows:
mallpulse/
├── .github/
│ └── workflows/
│ ├── ci.yml # Automated test checks on pull requests
│ └── deploy.yml # Automated deployment workflows to Cloud Run
├── backend/
│ ├── src/
│ │ ├── agents/
│ │ │ ├── supervisor.py # Orchestrates routing
│ │ │ ├── shopper_intelligence.py # Extracts search schemas
│ │ │ ├── inventory_locator.py # Aggregates location lists
│ │ │ └── fulfillment_coordinator.py# Runs ACID holds & lock operations
│ │ ├── api/
│ │ │ └── routes/routes.py # FastAPI application router
│ │ ├── core/
│ │ │ ├── config.py # Configuration loader and env parser
│ │ │ └── logger.py # Google-compliant JSON Structured Logger
│ │ ├── db/
│ │ │ └── mongodb.py # Motor async MongoDB connector client
│ │ ├── mcp_server/
│ │ │ └── server.py # Model Context Protocol microservice
│ │ └── main.py # FastAPI primary entry point
│ ├── tests/
│ │ ├── test_search.py # Tests search matching pipeline
│ │ └── test_reservation.py # Tests atomic reservation holds locks
│ ├── pyproject.toml # Poetry/UV dependency manifest
│ ├── Dockerfile # Multi-stage production container build
│ └── requirements.txt # Python production pip package list
├── frontend/src/ # Complete PWA React workspace
├── infrastructure/
│ ├── terraform/
│ │ └── main.tf # Auto-scaling GCP cloud architecture coordinates
│ └── cloudbuild.yaml # Automated Google Cloud Build triggers pipeline
├── scripts/
│ ├── seed_data.py # Seeds mock tenants & inventory
│ └── generate_qr.py # Produces secure verification barcodes base64
├── docker-compose.yml # Offline orchestration testing pipeline
├── README.md # Production document guide
└── LICENSE # Apache 2.0 open-source permission file
Setup a .env file containing the following variables:
# MongoDB Atlas parameters
MONGODB_URL="mongodb+srv://admin:secure_pwd@cluster0.mongodb.net/mallpulse?retryWrites=true&w=majority"
DATABASE_NAME="mallpulse"
# Gemini API secrets
GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"
# Server ports (local)
PORT=8000
MCP_PORT=8080To provision and populate your local MongoDB development instance with tenants and initial inventories catalog, run the python script:
docker-compose up -d mongodb
python scripts/seed_data.pyLaunch the API gateways, FastMCP microservices, and databases simultaneously:
docker-compose up --buildAccess the API server at http://localhost:8000/api/v1/health.
Compile and launch the reactive shopper panel:
cd frontend
npm install
npm run devThe mall interface will be loaded on http://localhost:3000.
Execute this simple gcloud command to automate compiling both container architectures, pushing the results to GCR, and setting up the auto-scaling invokers on Cloud Run:
gcloud builds submit --config infrastructure/cloudbuild.yaml --project YOUR_PROJECT_ID .- The Shopper Query: The shopper types: "Find me a navy blue blazer under $200."
- Cognitive Parsing: The Shopper Intelligence Agent extracts matching criteria: color
navy, categoryblazer, price limit$200. - Proximity Search: The Inventory Locator Agent runs a
$geoNearlookup on the 2dsphere tenants collection and Atlas Vector search on the inventory arrays. - The Resolution: The terminal displays that the product is available at Zara Elegant Wear (Floor 1, Unit A-10) for
$189.00(within budget). - The Hold: The shopper click Reserve Now. The Fulfillment Coordinator Agent executes an ACID transaction, decrements the active stock, inserts a reservation record, and displays a secure pickup QR pass with an active 15-minute TTL countdown timer.
- Navigation: A beautiful glowing route is drawn dynamically on the canvas map guiding the shopper from the entrance to unit A-10.
Licensed under the Apache License, version 2.0. See LICENSE for the full terms and conditions.