Plain-English Buyer Guide

This guide explains InsightPilot in simple language. It is written for buyers, business owners, admins, and support teams who want to install the app, connect a database, ask questions, review documents, and share reports without reading the source code.

Who This Guide Is For

The Simple Idea

Most companies already have useful data in a database and important rules inside documents. The problem is that owners and managers usually cannot easily ask that data questions like "Which products sold best this month?" or "Does customer X violate rule 7 of this contract?" InsightPilot gives them a controlled admin panel for that work.

The app does not replace the customer's existing business system. It connects to it safely, reads approved data, and helps users understand what is happening.

Why Not Just ChatGPT?

ChatGPT can explain a piece of data when someone manually pastes it into a chat. InsightPilot is different because it controls the workflow around the answer: approved database connections, schema discovery, SQL safety checks, certified metric versions, document citations, review decisions, governance records, exportable evidence, and private-by-default team sharing.

BI Companion, Not Enterprise BI Suite Replacement

InsightPilot is best understood as a trust-first BI companion for Laravel products. It strengthens safe SQL analytics, certified metric proof, document citations, collaboration reviews, governance evidence, and exportable proof. It does not try to replace dedicated enterprise BI suites such as Power BI or Tableau.

Updated audit ratings: Semantic metric maturity 9.0/10, Collaboration maturity 8.8/10, Enterprise BI replacement strength 6.8/10, and Enterprise BI companion strength 8.7/10. Direct guarded SQL supports MySQL/MariaDB, PostgreSQL, SQL Server, Redshift, Snowflake, and BigQuery; managed sync supports CSV, Google Sheets, Stripe, HubSpot, and GA4.

Who Usually Benefits Most?

• Agencies: create a client analytics portal with demo data, branded reports, and safe database access.
• SaaS founders: answer MRR, ARR, churn, expansion, and customer-success questions without exposing raw SQL.
• Finance ops: monitor revenue, refunds, margin, receivables, anomalies, and executive reports from certified metric definitions.
• Compliance-heavy teams: connect contract citations, approval trails, governance evidence, and exports for review.

Important Terms In Simple Words

First 30 Minutes After Buying

1. Upload the project to hosting or a VPS.
2. Point the website to the public folder.
3. Create a blank MySQL database for InsightPilot.
4. Open /install.
5. Complete the installer and create the admin account.
6. Choose demo data if you want to see the product immediately.
7. Log in as admin.
8. Open Settings -> OpenAI and enter the API key and model.
9. Open Settings -> Mail and send a test email.
10. Open Data Connections and connect the first external MySQL/MariaDB, PostgreSQL, or SQL Server database.
11. Open Schema Explorer, refresh schema, hide sensitive tables, and enable safe business tables.
12. Open Ask Data and ask a simple question.

Installation, Explained Simply

Before Upload

• Ask hosting support if PHP 8.2+, MySQL, Composer, and required PHP extensions are available.
• Make sure the domain can point to the public folder.
• Create a new empty database for the app.
• Keep the database name, username, password, and host ready.

Installer Steps

Settings You Should Configure First

Connect A Business Database

Open Data Connections. Add the external database details:

• Connection name: a friendly name like "Main POS Database".
• Database type: MySQL/MariaDB, PostgreSQL, or SQL Server.
• Host: usually an IP address, domain, or localhost.
• Port: usually 3306 for MySQL, 5432 for PostgreSQL, or 1433 for SQL Server.
• Database name: the exact database name.
• Username: recommended read-only database user.
• Password: stored encrypted.

PostgreSQL uses the public schema by default and can opt into configured schema lists. SQL Server requires the server to have the Microsoft PHP drivers and pdo_sqlsrv extension installed.

Click Test Connection. If it passes, save and activate the connection.

If The Test Fails

• Check the host and port.
• Confirm the username and password.
• Ask hosting support if remote database access or the SQL Server PHP driver is blocked.
• Confirm the database user has SELECT permission.
• Make sure the external database server allows this app server to connect.

Schema Explorer, Explained Simply

After connecting a database, InsightPilot needs to understand the structure. That means it reads table names, column names, primary keys, and relationships.

1. Open Schema Explorer.
2. Select the connection.
3. Click Refresh Schema.
4. Hide system tables, auth tables, logs, tokens, password tables, and private tables.
5. Give business-friendly labels to useful tables.
6. Enable only useful non-sensitive columns for AI.

Ask Data, Step By Step

1. Open Ask Data.
2. Select the database connection.
3. Type a business question like "What were my top selling products this month?"
4. Click Generate.
5. Review the SQL preview and explanation.
6. Check the safety status. Run only if it is safe.
7. View the result table, chart, explanation, and recommended actions.
8. Save useful questions as Saved Queries.
9. Add important saved queries to a dashboard.

Good Questions To Ask

• What were my top selling products this month?
• Which customers bought the most?
• Show revenue by category for this week.
• Which branch had the highest refunds?
• Which products are trending down?
• Compare this month revenue with last month.

Questions That Need More Detail

• "Show everything." This is too broad.
• "Why is business bad?" The app needs a specific metric, time period, or table.
• "Delete old records." InsightPilot blocks write actions and only allows safe read-only queries.

How SQL Safety Works

InsightPilot does not blindly run AI-generated SQL. It checks the SQL before execution.

Results, Charts, And Actions

After a safe query runs, InsightPilot shows the result in several useful ways.

• Result table: sortable, searchable, paginated rows.
• Chart: bar, line, pie, donut, area, KPI, or table chart based on result shape.
• Explanation: simple business-language summary of what the result means.
• Actions: recommendations, risks, opportunities, and priority labels.
• Presentation pack: chart explanation, export checklist, source timestamp, and caveat reminder.

Saved Queries And Dashboards

If users ask the same question often, save it. A saved query stores the question, SQL, chart setup, explanation, metadata, and favorite/report-widget status. Saved queries are private by default inside the active organization and can be shared internally with organization, role, or direct-user visibility.

1. Ask a question in Ask Data.
2. Review SQL and run it safely.
3. Save the query.
4. Rename it to something business-friendly.
5. Mark it favorite if it is important.
6. Add it as a dashboard widget.

Dashboards let users combine KPI widgets, chart widgets, table widgets, saved queries, risk summaries, and anomaly cards. Dashboards and exports are private by default inside the active organization and can be shared internally; public report links remain separate protected links.

Executive Briefs

Executive briefs are scheduled reports for owners and managers. They can be daily, weekly, or monthly.

• Pick a dashboard or widgets.
• Select the frequency.
• Let the app generate a summary with KPIs, changes, risks, opportunities, and actions.
• Email the report with a PDF attachment.
• Review the run history later.

Documents And Contract Compliance

InsightPilot can also work with business documents such as contracts, policies, subdocuments, rules, and obligations.

1. Open Documents.
2. Upload or paste a contract, policy, or rule document.
3. Create links between documents when one document depends on another.
4. Open the document graph to see relationships.
5. Ask a question about a rule, clause, or obligation.
6. Review citations and caveats.
7. Export an evidence report if needed.

Example question: "Document Contract Subdoc is linked with this doc. Rule 7 of linked docs is to be explained."

The app should answer using linked documents, show which document and rule were used, and provide source snippets.

Data Plus Document Questions

One standout workflow is combining database results with document rules.

Risks, Anomalies, And Monitoring

InsightPilot can alert users before they ask a question.

• Anomalies: sudden sales drop, refund spike, low stock trend, customer drop.
• Risk Center: missing documents, clause conflicts, automated risk scores.
• Scheduled Monitoring: recurring checks that run through cron.
• Insight Actions: tasks created from risks, opportunities, anomalies, and findings.

Collaboration

Teams can use InsightPilot to review findings together. For this marketplace release, dashboards, saved queries, and exports are private by default with organization, role, and direct-user internal visibility modes.

• Assign insight actions to users.
• Mark actions as open, assigned, in progress, done, or dismissed.
• Comment on dashboards, saved queries, report exports, anomalies, and actions.
• Mention a teammate so they see the item in their mention inbox.
• Request approvals, record decisions like approved, needs changes, or rejected, and transfer ownership inside the active organization.

Recommended Roles

Security Checklist

• Use HTTPS on the live domain.
• Use a strong admin password.
• Enable 2FA for admin users.
• Use read-only credentials for external databases.
• Hide sensitive tables in Schema Explorer.
• Disable AI access for sensitive columns.
• Configure sensitive column masking.
• Review query audit logs and failed query logs.
• Keep the installer locked after setup.
• Back up the app database regularly.
• Do not paste secrets into document content or user questions.

OpenAI And Data Safety

InsightPilot is designed to send controlled context to AI, not the whole database.

• It sends allowed schema details, not full database rows.
• It sends only selected tables and useful columns.
• It can hide sensitive tables and columns.
• It can summarize results using limited aggregates or sample rows.
• It checks documents and questions for prompt-injection style risks.
• It shows confidence, caveats, and sources where applicable.

Exports And Sharing

• Export result tables as Excel-compatible files.
• Export reports and evidence packs as PDF.
• Print report views.
• Create share links with optional password and expiry.
• Include sources, SQL, row samples, timestamps, citations, and audit trail in evidence reports.

Demo Mode For CodeCanyon Preview

Demo mode helps buyers understand the product quickly.

1. Run php artisan insightpilot:demo-install for a locked local or live-preview demo.
2. Log in with admin@ovion.tech and Demo@12345.
3. Keep OpenAI disabled if you do not want public demo token usage.
4. Show seeded dashboards, saved queries, reports, anomaly alerts, actions, documents, and presets.
5. Use demo fallback screens to explain that live AI requires the buyer's own OpenAI API key.
6. Reset demo data with php artisan insightpilot:demo-reset before recording screenshots or videos if needed.
7. Open Launch Checklist, Marketplace Readiness, and Module Readiness before publishing the preview.

Cron, Explained Simply

Cron is a server timer. It tells Laravel to check whether scheduled jobs need to run.

* * * * * php /path/to/insightpilot/artisan schedule:run >> /dev/null 2>&1

Without cron, users can still use manual pages, but automatic monitors, executive briefs, anomaly checks, freshness checks, data quality checks, data contracts, and schema drift checks may not run on time.

Common Problems And Plain Fixes

What To Send Support

If you need support, send clear details. This saves time.

• Website URL.
• Hosting type: shared hosting, VPS, local XAMPP, cPanel, Plesk, etc.
• PHP version.
• Database type and version.
• Exact page where the problem happens.
• Exact error message or screenshot.
• Recent steps you performed before the issue.
• Relevant log lines from storage/logs, with passwords and API keys removed.

Simple Demo Script For Sellers

1. Open dashboard and show KPI widgets.
2. Open Data Connections and explain encrypted credentials.
3. Open Schema Explorer and show table/column controls.
4. Open Ask Data and show a generated SQL preview.
5. Show SQL safety status before running the query.
6. Show result table, chart, explanation, and action recommendation.
7. Save the query and add it to a dashboard.
8. Open Documents and show citations plus linked document graph.
9. Open Risk Center or Anomalies and show proactive alerts.
10. Open Executive Briefs and show PDF/report history.
11. Open Evidence Lineage and show reproducibility/audit trail.
12. Open Launch Checklist and Module Readiness to show buyer-confidence checks.

Go-Live Checklist

• Installer locked.
• HTTPS enabled.
• Admin password changed from any demo value.
• OpenAI key and model configured.
• Mail test passed.
• Cron configured.
• External database uses read-only credentials.
• Sensitive tables hidden.
• Sensitive columns masked or disabled for AI.
• Roles and permissions reviewed.
• Backup plan confirmed.
• Demo data removed or clearly labeled if not needed.