InsightOS

InsightOS is an AI-powered analytics platform that lets users:

• Sign in before accessing protected workflows.
• Upload SQL schemas and initialize temporary SQLite databases.
• Enforce strict per-user ownership over uploaded databases.
• Ask questions in natural language and generate SQL.
• Run safe read-only queries.
• Generate CFO-style financial summaries.
• Run long-running upload and CFO tasks as background jobs with polling status.
• Draft a warehouse schema from business context.

The project is split into:

• frontend/: Next.js app (UI, charts, flows).
• backend/: FastAPI service (auth session flow, NL to SQL, query execution, CFO and warehouse engines).

Project Structure

insight-os/
	backend/
		main.py
		requirements.txt
		services/
	frontend/
		app/
		components/
		convex/
	docs/
		run-project.md
			testing-and-ci.md
		deploy-vercel-single-instance.md

Quick Start

1. Install backend dependencies.
2. Install frontend dependencies.
3. Optionally configure frontend environment variables.
4. Start backend on port 8000.
5. Start frontend on port 3000.
6. Open the sign-in page, create a local session, then upload the sample SQL file from http://localhost:3000/sample_ecommerce.sql.

Detailed instructions are in:

• docs/run-project.md
• docs/testing-and-ci.md

Deployment

For deploying both frontend and backend under a single Vercel project/domain, see:

• docs/deploy-vercel-single-instance.md

Current API Endpoints (Backend)

• GET /health
• GET /auth/me
• POST /auth/sign-in
• GET /jobs
• GET /jobs/{job_id}
• POST /preview-sql
• POST /upload-sql
• POST /jobs/upload-sql
• POST /generate-sql
• POST /query
• POST /query-plan
• POST /cfo-report
• POST /jobs/cfo-report
• POST /create-warehouse

Current Runtime Model

• Backend persists auth sessions and background job metadata to local JSON files for single-instance deployments.
• Uploaded SQL dumps are converted into temporary SQLite databases stored under backend/temp_dbs.
• Database ownership is enforced per signed-in user via backend ownership metadata.
• Background jobs are suitable for local development, demos, and single-instance deployments, but not durable enough for distributed workers or serverless scale-out.

Notes

• Backend currently uses mocked AI logic for NL to SQL, CFO insights, and warehouse design.
• Frontend defaults to http://localhost:8000 in development and same-origin /api in production, while auth state and API base override are stored in browser localStorage.
• Frontend Convex integration is optional; the provider is enabled only when NEXT_PUBLIC_CONVEX_URL is configured.
• For production on a single Vercel domain, use same-origin API calls and rewrites as described in the deployment guide, but review the serverless caveats before relying on local-disk sessions, jobs, or temporary database files.