FlytBase Hackathon — Customer & Product Intelligence Workspace

Internal tool built for the "Knowledge Base Over Customer Data" problem statement (Solutions Engineer track). It lets a Solutions Engineer query customer data — accounts, issues, feature requests, tasks, meeting notes — and live FlytBase docs together, in one conversational interface, with every answer grounded in a specific record or doc page (no hallucinated answers).

About

Solutions Engineers constantly bounce between CRM notes, support tickets, feature-request trackers, and product docs to answer a single customer question. This tool collapses that into one search bar:

• Ask a natural-language question and get an answer synthesized from whichever mix of structured customer data, semantic search, and live FlytBase documentation is relevant — never a free-form guess.
• Auto-syncing dataset — a background worker pulls the latest customer dataset on an interval, diffs it, and soft-deletes stale records.
• Live doc fetching — pulls and caches relevant pages straight from docs.flytbase.com / releases.flytbase.com instead of relying on a stale embedded copy.
• Contradiction detector — flags open feature requests that closely match something already shipped in recent release notes (cosine similarity on embeddings).
• Evidence-first UI — every answer in the Ask view comes with an evidence rail showing exactly which records/doc pages it was grounded in.

Tech Stack

Layer	Tech
Backend	Node.js, Express (TypeScript), tsx
Database	MongoDB Atlas + Atlas Vector Search
AI	Google Gemini API (@google/generative-ai) — classification, embeddings, grounded synthesis
Frontend	React + Vite + Tailwind
Scheduling	node-cron (interval sync + hourly safety-net cron)
Utilities	adm-zip (dataset unpacking), node-fetch (live doc fetching)

Project Structure

app/
├── backend/         # Express + TS API
│   └── src/
│       ├── ingest/       # markdown parsers, Mongo upsert, embeddings
│       ├── sync/         # dataset sync worker (diff + soft-delete)
│       ├── docs/         # live FlytBase doc fetcher (10 min cache)
│       └── query/        # router, grounded synthesis, contradiction detector, query log
├── frontend/        # React/Vite/Tailwind UI
└── data/raw/        # sample markdown dataset for local dev

Getting Started

1. MongoDB Atlas

• Create a free cluster and grab the connection string.
• Collections auto-create on first upsert: accounts, issues, feature_requests, tasks, meetings, doc_cache, query_log, sync_status, contradictions.
• After running npm run ingest once, go to Atlas Search → Create Search Index → Vector Search and create one index per entity collection, named <collection>_vector_index, on field embedding, dimensions 3072, similarity cosine.

2. Gemini API key

Get one from Google AI Studio and add it to backend/.env as GEMINI_API_KEY.

3. Run locally

# backend
cd app/backend
npm install
cp .env.example .env   # fill in MONGODB_URI + GEMINI_API_KEY
npm run ingest          # loads data/raw/*.md into Mongo + generates embeddings
npm run dev              # API on :8787

# frontend (separate terminal)
cd app/frontend
npm install
npm run dev              # Vite on :5173, proxies /api -> :8787

Open http://localhost:5173.

To trigger a sync manually: npm run sync:once in backend/, or POST /api/sync-now.

Known Gaps (worth flagging in a demo)

• Live doc fetcher's link discovery is a generic sitemap + keyword crawler — should be validated against the real docs.flytbase.com structure.
• DATASET_URL zip layout assumptions (findDataDir in sync/worker.ts) should be double-checked against the real dataset.
• Contradiction confidence threshold (0.82 cosine similarity) is an untuned starting point.
• No deployment config yet (Vercel/Render/Railway) — this is a local-first scaffold for now.

License

Built for the FlytBase Hackathon. No license specified yet.