Turn a MongoDB connection string into a board, a chat, and a natural-language interface. Three layers of write protection. Works on a $0/month free-tier Atlas cluster.
Built for the 2026 MongoDB AI Hackathon.
[3-box architecture diagram — see research/08-x15-architecture-diagram.md]
Argus/
├── frontend/ Next.js 15 + Tambo React SDK + the 7 card components
├── backend/ Python FastAPI + mcp_manager + result_set_guard + 5 insight modules
├── shared/ API contract (Zod schemas) shared by both
├── research/ Audit, design decisions, specs (read these first)
├── scripts/ Utility scripts (seed demo data, etc.)
├── docker-compose.yml Local dev stack
├── .env.example Environment variable template
└── argus.txt Original brief (pre-research)
The research folder contains the source of truth for every design decision. The shared folder contains the API contract. The frontend and backend import from shared.
git clone https://github.com/your-org/argus.git
cd argus
cp .env.example .env
# Edit .env: set GEMINI_API_KEY and ARGUS_DEMO_CONNECTION_STRINGdocker compose up --buildThis starts:
- Frontend: http://localhost:3000
- Backend: http://localhost:8080
- Backend health: http://localhost:8080/api/v1/health
- Go to http://localhost:3000
- Click "Connect your MongoDB"
- Paste a connection string (e.g., the seed data connection string)
- Wait for onboarding (2-3 min)
- Explore the dashboard, ask questions in chat
python scripts/seed_demo_data.py --connection-string "$ARGUS_DEMO_CONNECTION_STRING"This creates 3 collections (users, events, orders) with 1,000 / 50,000 / 5,000 documents.
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn argus.main:app --reload --port 8080cd frontend
npm install
npm run dev┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ SSE │ │ MCP │ │
│ Vercel ├────────▶│ Cloud Run ├────────▶│ MongoDB │
│ (Next.js) │ HTTPS │ (Tambo + │ HTTP │ (user's │
│ │◀────────┤ Gemini) │◀────────┤ cluster) │
└──────────────┘ └──────────────┘ └──────────────┘
See research/08-x15-architecture-diagram.md for the 5-component version.
mongodb-mcp-serverruns in read-only mode (MDB_MCP_READ_ONLY=true).- Recommended read-only database user during onboarding.
argus-result-set-guardblocks$outand$mergeat the planner layer.
Watch the 3-min video at 0:45 to see what happens when you ask Argus to "drop the users collection."
| Module | What it does | MQL operators |
|---|---|---|
| Funnel | Conversion rates between top events. | $group, $facet |
| Cohort | Weekly retention by acquisition week. | $group, $dateTrunc, $lookup |
| RFM | Recency-Frequency-Monetary segmentation, 5×5 grid. | $bucket, $densify |
| Attribution | First-touch attribution. (Markov + Shapley in v2.) | $group, $arrayToObject |
| Anomaly | Z-score on daily metrics vs trailing 28-day mean. | $setWindowFields, $stdDevPop |
See research/13-mql-examples.md for the actual pipeline code.
- Audit findings + decisions:
research/00-audit-summary.mdthroughresearch/09-v2-plan-outline.md - Implementation specs:
research/10-readme-draft.mdthroughresearch/20-responsive.md - Backend architecture:
backend/ARCHITECTURE.md - Original brief:
argus.txt
- Frontend: Next.js 15, React 19, Tambo React SDK (
@tambo-ai/react) - Backend: Python 3.12, FastAPI, Pydantic, asyncio
- MCP: mongodb-mcp-server (HTTP transport, sidecar)
- LLM: Gemini 3 Flash (primary), with 2-level fallback
- Database: MongoDB Atlas (user's data), Memorystore for Redis (session state, v2)
- Hosting: Vercel (frontend), Cloud Run (backend)
MIT. See LICENSE (TBD).
Built in 10 days for the 2026 MongoDB AI Hackathon.