Querify

Ask questions about your Firestore database in plain English — no SQL, no code, no back-and-forth with your developer.

Querify is a natural language query tool for Firebase Firestore. It lets non-technical users explore their company's data by typing questions the way they'd say them out loud. The backend translates those questions into Firestore queries via Groq (LLaMA 3.3 70B), executes them read-only, and returns clean results in a table.

---

How it works

1. Upload your database key — Your developer gives you a Firebase service account JSON. You upload it once; it's AES-256-GCM encrypted in your browser before it ever leaves your device.
2. Pick your dataset — Querify auto-discovers all collections in your Firestore and shows them as selectable cards.
3. Ask your question — Type anything: "Show me orders placed in the last 7 days" or "Find products under $50 that are in stock, sorted by price."
4. See your data — Results appear in a clean, readable table. Querify is read-only, always — it can never modify or delete anything.

---

Project structure

/
├── backend/       # Node.js + Express REST API
└── frontend/      # Vite + React SPA

---

Backend

TypeScript/Node.js REST API that accepts a natural language query and an encrypted Firestore service account, translates the query into a structured Firestore operation via Groq, and executes it.

Stack

• Runtime: Node.js + Express
• AI: Groq SDK (LLaMA 3.3 70B)
• Database: Firebase Admin SDK (Firestore)
• Validation: Zod
• Upload handling: Multer (memory storage)
• Encryption: Node.js built-in crypto (AES-256-GCM)

Setup

cd backend
npm install
cp .env.example .env

Fill in .env:

GROQ_API_KEY=your_groq_api_key
PORT=3000

# 32-byte key, hex-encoded (64 chars). Generate with:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=your_64_char_hex_key_here

The same ENCRYPTION_KEY value must be set as VITE_ENCRYPTION_KEY in the frontend.

Running

npm run dev      # development (ts-node-dev, hot reload)
npm run build    # compile TypeScript
npm start        # run compiled output

API

Method	Path	Description
POST	/connect	Upload encrypted service account, auto-discover all collections, return session token
POST	/query	Translate a natural language query and execute it against Firestore
GET	/schema	Return the stored schema for an active session

See backend/PLAN.md for full request/response contracts.

---

Frontend

Vite + React + TypeScript SPA targeting non-technical business users.

Stack

• Framework: React 18 + React Router v6
• Build: Vite 5
• Encryption: Web Crypto API (no npm dependency)
• Styling: Plain CSS — no component library

Setup

cd frontend
npm install
cp .env.example .env

Fill in .env:

VITE_API_BASE_URL=http://localhost:3000

# Must match ENCRYPTION_KEY in backend .env exactly
VITE_ENCRYPTION_KEY=your_64_char_hex_key_here

Running

npm run dev      # development server (Vite HMR)
npm run build    # production build → dist/
npm run preview  # preview production build locally

App flow

/                    Landing page
/app/connect         Upload database key (Step 1)
/app/collections     Pick a dataset (Step 2)
/app/query           Ask questions, see results (Step 3)

---

Security notes

• Encryption in transit: The service account JSON is AES-256-GCM encrypted client-side before upload. The server decrypts it using the shared ENCRYPTION_KEY and never persists it to disk.
• Read-only: Two-layer guardrail blocks all mutating operations — a keyword deny-list on the raw query, plus an intent field that Groq self-declares. Any non-read intent is rejected with a 403 before touching Firestore.
• Session TTL: Sessions expire after 2 hours, both client-side (localStorage check) and server-side (lazy expiry on each /query request).
• POC note: The shared encryption key is intentionally hardcoded in both .env files for this prototype. In production, this would be fetched from a key management service (e.g. AWS KMS, GCP Secret Manager).

---

For developers: giving a teammate access

1. Go to Google Cloud Console → IAM & Admin → Service Accounts
2. Create a service account with the roles/datastore.user role (read-only)
3. Generate a JSON key
4. Hand the .json file to your teammate — they upload it through the Querify UI

That's it. The file is encrypted automatically on upload.

---

Built with

• Groq — LLM inference (LLaMA 3.3 70B)
• Firebase Admin SDK — Firestore access
• Vite + React