Tip
Live Production Deployments:
- Frontend Site (Render): https://query-ai-1.onrender.com
- Backend API Server (Render): https://query-ai-gwj8.onrender.com
- Database & Auth Integration: Hosted PostgreSQL & GitHub OAuth + Credentials via Supabase
Query AI is a high-fidelity, premium dark-mode Perplexity clone built using the Bun runtime, React, Express, Prisma ORM, and Google Gemini LLM. It delivers a real-time, cited search experience that crawls the web, aggregates reliable sources, structures answers in markdown grids, and suggests context-aware follow-up questions.
Query AI is architected with a decoupled frontend and backend, using Supabase for user authentication and user profile database synchronization.
graph TD
Client[React SPA Frontend] -->|1. Auth: GitHub OAuth or Email/Password| Supabase[Supabase Auth]
Supabase -->|2. SQL Trigger / Sync Middleware| DB[(PostgreSQL Database)]
Client -->|3. Upgrade Plan / Buy Credits| Upgrade[Upgrade Checkout Page]
Upgrade -->|4a. Test/Live Payment| Razorpay[Razorpay Checkout SDK]
Upgrade -->|4b. Mock Fallback| Sandbox[Sandbox Simulator Modal]
Razorpay -->|5a. Callback Token| Webhook[POST /payments/webhook]
Sandbox -->|5b. Mock Trigger| Webhook
Webhook -->|6. Transaction Verification| DB
Client -->|7. Search Query + JWT| Billing[Billing Rate Limiter Middleware]
Billing -->|8. Deduct Credit / Check PRO| DB
Billing -->|9. Authorized Search Request| API[Express API Server]
API -->|10. Web Crawling Context| Tavily[Tavily Search API]
API -->|11. Prompt Context Engineering| Gemini[Google Gemini 1.5]
API -->|12. Save History| Prisma[Prisma ORM]
Prisma -->|13. Persist Messages| DB
API -->|14. Chunked SSE Stream| Client
- Frontend App: Responsive React SPA styled with Tailwind CSS, utilizing Radix-UI components and Lucide icons for micro-interactions and transitions.
- Backend Engine: Express server running on the ultra-fast Bun runtime. It handles authentication middleware, query history caching, Tavily web searching, and server-sent stream completions.
- Database Layer: PostgreSQL managed via Supabase. Schema migrations and database interactions are performed using the Prisma v7 ORM.
Query AI integrates a hybrid monetization flow that allows users to purchase subscriptions (Query AI Pro) or pay-as-you-go refills (Search Credits). The system handles off-site gateway completions asynchronously using a cryptographically verified webhook channel.
sequenceDiagram
participant User as React Client (Frontend)
participant Server as Express Server (Backend)
participant RZP as Razorpay Gateway / Sandbox
participant DB as Postgres Database (Prisma)
User->>Server: 1. POST /payments/create-order { productType: "SUBSCRIPTION" | "TOPUP" }
Server->>DB: 2. Record Payment attempt in ledger (PENDING status)
Server-->>User: 3. Return local orderId and transaction info
alt Real Payment Path (Razorpay SDK)
User->>RZP: 4. Launch Razorpay Standard Checkout overlay
User->>RZP: 5. Authenticate payment (UPI / Card / Netbanking)
RZP-->>User: 6. Return payment_id, order_id, & signature
User->>Server: 7. POST /payments/webhook { signature, payment_id, orderId }
else Test Sandbox Path (Simulator fallback)
User->>Server: 4. POST /payments/webhook { orderId, mock_success: true }
end
alt Signature Check
Server->>Server: 8. Verify HMAC-SHA256 signature
end
Server->>DB: 9. Fetch and verify local order status
Server->>DB: 10. Update local payment to SUCCESS & grant user credits/Pro status
Server-->>User: 11. Respond with 200 OK (Payment completed)
User->>User: 12. Refresh credentials & redirect back to Workspace
- Instant Web Synthesis: Crawls the web dynamically using the Tavily Search API and structures answers using Vercel AI SDK and Google Gemini (
gemini-1.5-flash). - Interactive Workspace Tabs:
- Answer: Displays real-time streaming completions formatted in clean Markdown, citations, tables, and related questions.
- Links: Renders a clean, deduplicated grid of every single domain reference crawled during the active thread session.
- Hybrid Monetization (Subscriptions vs. Credits): Let users purchase
Query AI Prosubscriptions (unlimited searches) or top up usage credits in their wallets (+50search credits packages). - Pre-flight Billing Rate Limiter: Express check middleware intercepting search queries, dynamically decrementing active credits or letting PRO users pass, preventing API cost overrun.
- Secure Cryptographic Webhook Handler: Asynchronous verification using HMAC-SHA256 signatures, ensuring user upgrades happen only after off-site gateway success events.
- Self-Healing Account Integration: Auth syncing that merges Supabase ID changes if email credentials and OAuth methods collide.
- Smart XML-Like Response Parser: Automatically decodes and parses
`<ANSWER>`and`<FOLLOW_UPS>`suggestions in real-time, allowing users to click follow-up questions to query further in history context. - OAuth Security: User registration, login, and sessions are securely managed via Supabase GitHub OAuth.
- Secure JWT Middleware: Private backend routes require a valid Supabase JWT in the
Authorizationheader. The middleware lazily syncs verified users into the Postgres database, preventing constraint collisions. - Side-Docked Navigation: Fast access to conversation histories (loaded via
GET /conversations) with individual item deletion support (DELETE /conversation/:id). - Dedicated Account Page: An elegant
/profileinterface displaying user credentials, avatar initials, and logout options.
Ensure you have the Bun runtime installed on your machine.
Navigate to the Backend directory and install dependencies:
cd Backend
bun installCreate a .env file based on .env.example and fill out the required variables:
DATABASE_URL="postgresql://..." # Your PostgreSQL Database URL
DIRECT_URL="postgresql://..." # Direct connection URL (for migrations)
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_SECRET_KEY="your-supabase-service-role-key"
GEMINI_API_KEY="your-google-gemini-key"
TAVILY_API_KEY="your-tavily-search-key"
GITHUB_OAUTH_CLIENT_ID="your-github-client-id"
GITHUB_OAUTH_SECRET="your-github-client-secret"
VITE_RAZORPAY_KEY_ID="rzp_test_xxxxxx" # Your Razorpay Test Key IDStart the index server in hot-reload mode:
bun --hot index.tsThe backend API server will listen on http://localhost:3000.
Navigate to the Frontend directory and install dependencies:
cd ../Frontend
bun installCreate a .env file based on .env.example:
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-supabase-anon-key"
VITE_RAZORPAY_KEY_ID="rzp_test_xxxxxx"Start the client development server:
bun devOpen http://localhost:5173 (or the printed port) in your browser.
Note
Dynamic URL Resolution (No Code Changes Needed!):
The frontend automatically detects where it is running. If it runs on localhost or 127.0.0.1, it directs API calls to the local backend http://localhost:3000. In production, it targets the live Render backend (https://query-ai-gwj8.onrender.com). You do not need to change any URLs before pushing to GitHub!
For testing how the frontend builds, minifies, and serves assets under production conditions (NODE_ENV=production) using Bun's static serving and SPA client fallback logic, see the Production Verification Test Script (production/verify_production.ts) (kept local/untracked).
- You can run the production test suite locally using:
bun run production/verify_production.ts
For production-grade authentication, we configure Postgres database triggers in the Supabase console. This syncs profile additions and removals from auth.users directly to the public.User schema managed by Prisma:
-- Trigger Function for User Creation
create or replace function public.handle_new_user()
returns trigger as $$
begin
insert into public."User" (id, email, name, provider, "supabaseId")
values (
gen_random_uuid(),
new.email,
coalesce(new.raw_user_meta_data->>'full_name', new.raw_user_meta_data->>'name', split_part(new.email, '@', 1)),
case when new.raw_app_meta_data->>'provider' = 'google' then 'Google'::"Authprovider" else 'Github'::"Authprovider" end,
new.id
);
return new;
end;
$$ language plpgsql security definer;
-- Bind Trigger
create trigger on_auth_user_created
after insert on auth.users
for each row execute procedure public.handle_new_user();The following screenshots showcase the premium dark-mode interface and rich features of Query AI:
