INSIGHTIQ

InsightIQ — Ask your database questions in plain English. Get instant charts, anomaly alerts & PDF reports. Business intelligence for non-technical managers, powered by Grok API.

Comment

InsightIQ — Our Story

💡 Inspiration

Every business runs on data, but most of that data is locked behind a wall that only engineers and analysts can climb. I've seen managers wait days for a simple report — "How did we perform last quarter?" — only to receive a spreadsheet they can barely interpret.

That frustration became the spark. What if a business manager could just ask their database a question, the same way they'd ask a colleague? No SQL. No waiting. No intermediaries.

The hackathon problem statement confirmed exactly that need — an intelligent analytics platform that connects to data, finds patterns, and communicates insights in human language. InsightIQ was born from the belief that data fluency shouldn't be a prerequisite for making good decisions.

🔨 How I Built It

InsightIQ is built entirely with HTML, CSS, and Vanilla JavaScript — no frameworks, no bloat. Every layer of the system was wired together manually, which made the architecture both lean and deeply intentional.

The core pipeline works like this:

$$\text{Natural Language Query} \xrightarrow{\text{Grok API}} \text{SQL} \xrightarrow{\text{DB Proxy}} \text{Result Set} \xrightarrow{\text{Chart.js}} \text{Visual Insight}$$

The key components:

  • Grok API serves as the brain — it takes the user's plain-English question, understands the database schema context injected into the prompt, and generates valid SQL.
  • A lightweight JS serverless proxy sits between the browser and the database, forwarding parameterized queries securely to MySQL/PostgreSQL without ever exposing credentials client-side.
  • Chart.js handles all visualizations. The chart type is chosen algorithmically — time-series data gets a line chart, categorical comparisons get bar charts, and proportional data gets pie charts.
  • jsPDF + html2canvas renders the session's insights into a downloadable PDF report, complete with AI-generated commentary.
  • Session memory is maintained in a JavaScript state object, enabling genuine multi-turn conversations where follow-up questions carry full context.

The anomaly detection runs a simple but effective z-score calculation in-browser:

$$z = \frac{x - \mu}{\sigma}$$

Any data point where $|z| > 2.5$ is flagged as an anomaly and surfaced to the user at session start — proactively, without them having to ask.

📚 What I Learned

Building InsightIQ taught me more than I expected, especially about the invisible complexity in systems that appear simple on the surface.

  • Prompt engineering is architecture. Getting Grok API to reliably generate correct SQL required carefully structured prompts that inject schema context, enforce output format, and constrain hallucination. A badly written prompt is as broken as a badly written function.

  • Browsers are sandboxes. The moment I tried to connect directly to a PostgreSQL database from JavaScript, I hit a wall. Databases don't speak HTTP, and browsers can't speak TCP. Designing around this constraint taught me a lot about the separation between client-side and server-side responsibilities.

  • Vanilla JS is underrated. Without React or any framework, I had to manage state, DOM updates, and async flows manually. It was harder — but I came out understanding the web platform at a much deeper level.

  • UX for non-technical users is its own discipline. Every design decision — from error messages to chart labels — had to assume the user knows nothing about data. That constraint made the product sharper.

🚧 Challenges I Faced

1. CORS & API Security Calling the Grok API directly from the browser exposes the API key in client-side code. Solving this without a full backend meant building a minimal serverless proxy — a constraint that turned into a valuable architecture lesson.

2. NL-to-SQL Reliability LLMs are creative, which is a problem when you need deterministic SQL. I tackled this by grounding every prompt with the full database schema and enforcing strict output formatting. Even then, edge cases required building a validation layer that checks generated SQL for syntax errors before execution.

3. Dynamic Chart Selection Deciding the right chart type automatically — without user input — required building a classification heuristic based on column data types, cardinality, and whether a date column was present. Getting this to feel "obviously correct" to a non-technical user took several iterations.

4. Stateless LLM, Stateful Conversation Grok API has no memory between calls. Simulating a multi-turn conversation meant manually constructing a growing message history and injecting it into every subsequent API call — while keeping token usage from blowing up on long sessions.

5. PDF Rendering Consistency html2canvas captures the DOM as a canvas image, but Chart.js charts rendered on <canvas> elements don't always serialize cleanly. Getting charts to appear crisply in the exported PDF required careful timing and forced canvas redraws before capture.

🏁 Closing Thought

InsightIQ is proof that you don't need a complex stack to build something meaningful. A clear problem, a powerful API, and a commitment to simplicity can go a long way.

Data should answer to people — not the other way around.

Built With

Share this project:

Updates