SupplyPulse

Inspiration

Supply chain disruptions are not abstract problems in Nigeria they are what the average Nigerian SME business go through almost daily. Imagine a supplier for a business goes silent, WhatsApp messages go unanswered, and a warehouse manager is suddenly staring at ₦2.6 million worth of unfulfilled orders with a Friday deadline. The solution is usually frantic phone calls, personal contacts, and gut instinct. I kept asking myself: why is this still manual? Every piece of information needed to resolve a disruption already exists on the internet, the orders, the suppliers, the contacts. The problem is that nobody has built a system that connects them and acts on them in real time. That gap is what SupplyPulse is built to close.

What it does

SupplyPulse is an AI supply chain crisis agent for Nigerian SMEs. When a disruption hits, you describe it in plain English, no forms, no dropdowns. The agent does the rest: SENSE — classifies the disruption type (stockout, late delivery, price spike, supplier unavailability) DIAGNOSE — queries MongoDB and surfaces every affected order, SKU, and naira value at risk MATCH-DB — runs a $vectorSearch on 768-dimensional supplier embeddings to find semantically similar alternatives from your own database MATCH-MAPS — if your database has fewer than 3 results, Google Maps Places API fires automatically, returning real open businesses nearby labelled [MAPS LIVE] PLAN — merges both sources into a ranked recovery plan: Option A, B, C — each with lead time, price tier, reliability score, and a plain-English rationale EXECUTE — on your approval, updates all order records in MongoDB, sends a professional vendor email via Gmail, and writes a full decision log VERIFY — shows a resolution summary: time-to-resolve, cost delta, supplier chosen, source, audit trail stored The whole loop runs in under 3-5 minutes. The average manual resolution is about 4–6 hours.

How we built it

Next.js 16 (App Router, TypeScript) — frontend and API routes in one codebase MongoDB Atlas — $vectorSearch on supplier embeddings is the core intelligence engine. Orders, audit logs, and decision records all live here too Google text-embedding-004 — generates 768-dimensional embeddings for each supplier profile, enabling semantic search ("TV remotes" matches "consumer electronics accessories") Gemini 2.0 Flash — primary LLM agent with 7 real function calls per disruption. Google Maps Places API — Text Search fires when the database has fewer than 3 good matches, solving the cold-start problem on day one Nodemailer + Gmail SMTP — vendor emails sent via App Password auth, no third-party email service needed

The agent loop is the hardest part architecturally. Each turn can call multiple tools, receive results, reason again, and call more tools up to 8 iterations before producing a final response. Getting that to work reliably with function calling across both Gemini and Groq required careful message format normalization

Challenges we ran into

The first challenge we ran into was supplier coverage. If your business is in Kano, Onitsha, or Port Harcourt — not just Lagos — a hardcoded supplier database fails you immediately. We needed a way to surface relevant, real businesses anywhere in Nigeria without manually seeding every city.

That is exactly why we integrated Google Maps Places API as an automatic fallback. When the agent finds fewer than 3 matching suppliers in your database, it fires a live Maps search scoped to the operator's location — returning real, open businesses with Google ratings, review counts, and addresses. A procurement officer in Abuja gets results in Abuja. One in Aba gets results in Aba. The system adapts to where you are, not where we assumed you'd be.

Peer dependency conflicts. next-auth@4 expects nodemailer@^7 but we were on nodemailer@8. Vercel's default npm install fails without --legacy-peer-deps. Fixed with a single .npmrc file. The command I user from my terminal was `

git add .npmrc
git commit -m "fix: add .npmrc for legacy-peer-deps (next-auth + nodemailer conflict)" git push `

Free tier constraints. gemini-2.0-flash has a $0 limit in some regions for the free tier.

Keeping the AI output clean. Gemini default to markdown formatting (bold, ## headers). Our chat UI renders plain text so the asterisks showed up literally. We solved it by writing explicit formatting rules into the system prompt: CAPS for labels, ─── dividers, • bullets. No markdown syntax.

Accomplishments that we're proud of

The dual-source supplier matching is the thing we're most proud of. No other tool we've seen merges your private supplier database with live Google Maps results in a single ranked list each result clearly labelled [YOUR DB] or [MAPS LIVE] so you always know where a recommendation came from.

The audit trail is the second. Every single agent decision is written to MongoDB with timestamp, rationale, match score, source, cost delta, and operator approval status. Over time this becomes a genuine operational intelligence layer not just a chatbot.

And the 7-step agent loop actually works end-to-end. It's not a demo that simulates tool calls — it queries real MongoDB collections, runs real vector search, calls real Google Maps, sends real emails, and writes real records. The whole chain.

What we learned

I learnt how to fix Peer dependency conflicts on vercel I also learned that human-in-the-loop is a feature, not a limitation. Every demo we showed, the moment we said nothing happens until you type approve, people visibly relaxed. Autonomy is very scary in supply chain. The agent is doing the thinking and the human doing the deciding is the right split.

What's next for SupplyPulse

Re-enable authentication — Because it was a demo I removed the authentication but the next step would be for users to create live accounts, per-company supplier databases, and chat history are built; just need MongoDB consistently available to turn the middleware back on WhatsApp integration — most Nigerian SME procurement happens over WhatsApp. A Twilio-powered WhatsApp interface for the agent is the most-requested feature Supplier onboarding flow — let suppliers register directly, verify their own data, and appear in the [YOUR DB] results Predictive disruption alerts — instead of waiting for a crisis, monitor order lead times and supplier activity and flag risks before they become emergencies Multi-language support — Yoruba, Igbo, Hausa intake for operators outside Lagos who don't default to English

Built With

• gemini
• google-maps
• mongodb
• next.js
• nodemailer
• typescript
• vercel