README.md
High-level overview of the project, architecture, and repository guide.
Turn a folder of ordinary images into an AI-powered search application using MongoDB Search, MongoDB Vector Search, Ollama, Voyage AI, and Next.js.
Most operating systems still rely heavily on filenames when searching images. Once your collection grows into hundreds or thousands of photos, finding exactly what you're looking for becomes surprisingly difficult.
This project explores a different approach.
Instead of searching filenames, we use a vision model to understand each image, generate structured metadata, store everything in MongoDB, and layer increasingly capable search techniques on top of that data.
By the end, we'll have an application that can search both literal words and meaning, all while keeping the architecture surprisingly simple.
If you'd rather click around before looking at the code, start with the live example. Then come back and we'll build it together.
This repository accompanies the MongoDB tutorial:
Building an AI-Powered Image Search Application with MongoDB
https://www.youtube.com/watch?v=yYoxQLufWYw
https://github.com/learnmongo/ai-image-viewer
This project is intended for developers interested in modern search applications and practical AI techniques.
You'll probably enjoy it if you're interested in:
The application itself intentionally stays fairly small so we can focus on understanding the architecture behind it.
Starting with nothing more than a folder of images, you'll build a complete search application capable of understanding what's actually inside each image.
We'll build the search experience one layer at a time.
Search for:
beachMongoDB Search looks across titles, descriptions, summaries, tags, and other metadata to quickly find documents containing those keywords.
Now search for:
oceanEven if the word ocean never appears anywhere in a document, MongoDB Vector Search can still return relevant images because it compares meaning instead of exact words.
Finally, combine both approaches.
wild flying animalsMongoDB Search contributes precise keyword matches.
MongoDB Vector Search contributes semantic understanding.
Using MongoDB's $rankFusion stage, we combine both approaches into a single search experience that feels much more natural.
One of the goals of this project was to keep the overall architecture simple.
Everything revolves around a single MongoDB document.
Images
│
▼
Vision Model (Ollama)
│
▼
Structured Metadata
│
▼
MongoDB Documents
├── MongoDB Search
└── Vector Embeddings
│
▼
Hybrid Search
│
▼
Next.js ApplicationRather than introducing multiple databases or external search systems, MongoDB becomes the central source of truth for the application.
Metadata.
Embeddings.
Search indexes.
Everything lives together.
That simplicity is one of my favorite parts of this architecture.
As the project grew, a few design decisions ended up making a big difference.
Rather than asking a vision model to produce the final MongoDB document directly, the project separates those responsibilities.
The vision model focuses on understanding the image.
A second instruction model transforms that understanding into structured JSON.
This makes prompts easier to iterate on and produces much more consistent MongoDB documents.
Embeddings are generated in their own processing step.
That means they can be regenerated later without analyzing every image again.
It also makes experimenting with different embedding models much easier.
Each image becomes a single MongoDB document containing:
As the application grows, the document grows with it.
Keyword search is incredibly precise.
Vector search understands meaning.
Hybrid search combines both.
For many real-world applications, that's the experience users are actually looking for.
If you're exploring the code after watching the video, these are the best places to start.
| Location | Purpose |
|---|---|
tools/process/ | Image processing pipeline, Ollama integration, metadata generation, and embedding tools. |
lib/image/queries/ | MongoDB aggregation pipelines for MongoDB Search, Vector Search, and Hybrid Search. |
app/api/ | API routes connecting the frontend to MongoDB. |
app/ | Next.js application and user interface. |
The README gives you the high-level overview. The documents below take a deeper look at individual parts of the project.
| Guide | Description |
|---|---|
| 📖 ARCHITECTURE.md | Understand the overall system, the processing pipeline, and why the project is structured this way. |
| 🧭 CODE-GUIDE.md | A guided tour of the repository and where to find the code shown in the tutorial. |
| 🔍 SEARCH.md | Learn how MongoDB Search, MongoDB Vector Search, and Hybrid Search are implemented. |
| 🤖 OLLAMA.md | Learn how Ollama fits into the processing pipeline and how to swap in other providers. |
| 💬 PROMPTS.md | Read about the prompt engineering decisions and lessons learned while building the project. |
If you're following along with the tutorial, these sections map directly to the repository.
| Video Section | Repository |
|---|---|
| System Architecture | ARCHITECTURE.md |
| Image Processing | tools/process/ |
| MongoDB Search | SEARCH.md |
| MongoDB Vector Search | generate-embeddings.js |
| Hybrid Search | lib/image/queries/ |
Image search is really just the beginning.
The same architecture can be applied to:
Once your data has been enriched with AI and stored in MongoDB, you can continue building on top of it without introducing additional systems.
That's what makes this pattern so powerful.
If you build something based on this project, or take it in a different direction, I'd genuinely love to see it.