This README helps developers understand the purpose, structure, and deployment process of this Demo App.
|
This demo showcases the Leafy Store Associate App, built on MongoDB to streamline product discovery and inventory visibility as part of a unified commerce strategy. Unified commerce brings all channels and systems together into a single, real-time platform—an approach you can implement in siloed environments using an Operational Data Layer (ODL) with MongoDB. The app highlights how advanced search can run directly on operational data, with performance and simplicity. Inventory data is simulated but kept fresh with Atlas Triggers, showing how product and store stock can update in real time with minimal effort. By combining search, freshness, and flexible modeling in one platform, MongoDB makes AI-ready commerce experiences simple to build and easy to scale. |
-
Intelligent product discovery at scale
Unified search on operational data using Regex, Full-Text (fuzzy + boosting), Vector (semantic), and Hybrid (RRF with configurable weights).
Includes geospatial queries to instantly locate nearby inventory—showing how MongoDB enables advanced search directly on live operational data, critical for unified commerce. -
Fast, enriched search results
Product cards display SKU, aisle, shelf, stock, image, and relevance score.
Thanks to MongoDB’s flexible data model, results return instantly from a unified product catalog with embedded store-level inventory. -
Continuously fresh inventory data
A 12-hour simulation trigger updates ~500 products with realistic stock movements, while an inventory-sync trigger keeps each product’sinventorySummarycurrent. -
Clean architecture for the advanced search microservice
The search logic lives in a dedicated, modular FastAPI service that separates API, use-case, and infrastructure layers.- Swappable AI providers (e.g., Voyage AI → Bedrock) via an embedding interface
- Extensible logic to add new re-rankers, personalization, or filters without touching orchestration code
- Multi-channel reuse across REST, GraphQL, or event-driven consumers
| Component | Description |
|---|---|
| Main App (Next.js) | Full-stack frontend that delivers the UI and runs basic MongoDB queries. It handles geospatial logic —finding nearby stores with available stock—and delegates advanced product search to the microservice. |
| Advanced Search Microservice (Python) | Cleanly architected FastAPI service that performs 4 types of search and coordinates query embeddings with Voyage AI. |
| MongoDB Atlas | Core operational data layer with 3 collections: products, inventory, and stores. Stores text and image embeddings used for semantic and image-based search.• Each product embeds a store-level inventorySummary. One Atlas Trigger listens for key inventory changes and syncs product documents. A second scheduled trigger simulates daily inventory updates to maintain realism and consistency. |
| Embeddings & AI Integration | Embeddings were generated using Voyage AI and stored in MongoDB. The same model is used for query embedding generation to ensure consistency. The architecture also supports swapping in alternative providers. |
👉 For technical deep dives, see the Frontend README and Advanced Search Microservice README.
🗄️ Database & Modeling -> See docs/setup/collections/README.md for setup instructions and insights into our data modeling strategy.
🗒️ Tip: Check the ADR documentaion folder for architectural rationales and design choices.
retail-unified-commerce/
├── frontend/ # Next.js app
├── backend/
│ └── advanced-search-ms/ # FastAPI-based search service
├── docs/ # ADRs, helper scripts, setup docs and more.
├── docker-compose.yml # Orchestrates services
└── Makefile # Dev commands- MongoDB Atlas account (Free Tier)
- Demo dataset - we provide JSON files for the 3 required collections:
- Index definitions in:
- Atlas Triggers – Not required to run the app, but we include two triggers to keep inventory data fresh and simulate real-world updates:
- Environment configuration files (.env) for each app, using .env.example files as a template:
- Installed tools:
- Docker + Docker Compose
- Node.js v20 (if running frontend separately)
- Python 3.11 + Poetry (if running backend separately)
git clone https://github.com/mongodb-industry-solutions/retail-unified-commerce.git
cd retail-unified-commerce
make build📝 Note: Once the apps are running, go to http://localhost:3000 to use the frontend app.
To view the API documentation for the Advanced Search microservice, visit http://localhost:8000/docs.
| Action | Command |
|---|---|
| Build & start | make build |
| Start (no rebuild) | make start |
| Stop all containers | make stop |
| Clean containers/images | make clean |
| View all logs | make logs |
| Action | Command |
|---|---|
| Build frontend | make front-build |
| Start frontend | make front-up |
| Stop frontend | make front-stop |
| View logs | make front-logs |
| Action | Command |
|---|---|
| Build backend | make back-build |
| Start backend | make back-up |
| Stop backend | make back-stop |
| View logs | make back-logs |
Now that the app is running, you can start exploring. Use the available helpers to guide your journey:
- Talk tracks that explain key concepts per page
- Document summaries and full JSON views of products and more...
MongoDB Atlas is a powerful Operational Data Layer (ODL) for unified commerce. It simplifies how retailers consolidate, serve, and act on critical data across channels.
-
Flexible document model
Easily model rich, complex retail data—such as products with per-store inventory, pricing, or media assets—in a single document. No rigid schemas or painful joins. -
Built-in advanced search
With Atlas Search and Vector Search, retailers can implement full-text, semantic, hybrid, and even image-based product discovery directly on operational data—without needing separate search or vector databases. -
Support for modern AI-driven apps
Store and query multimodal embeddings, trigger real-time updates, and support smart recommendations with minimal complexity. Atlas is built to support AI-native experiences with operational-grade performance. -
Simplified architecture
Reduce ETL complexity, avoid data duplication, and enable real-time updates with features like Atlas Triggers, Change Streams, and Online Archive. Run analytics or AI workloads on dedicated nodes without affecting core performance. -
🌟 What’s Next: Native AI Simplicity
MongoDB will soon offer native support for automatic embedding generation and reranking—making intelligent search and recommendations even easier to build.
👉 _Read more in this blog post
This project was made possible through a close collaboration between domain experts and technical implementers:
- Prashant Juttukonda – Principal
- Angie Guemes – Developer & Maintainer
- Florencia Arin – Developer & Maintainer
- 🎥 YouTube Video 1– coming soon
- 🎥 YouTube Video 2– coming soon
- 📚 Solution Library
- 📝 Blog
⭐ If you found this useful, consider giving the repo a star!
Copyright (c) 2025 MongoDB
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.