Giraph

An AI-powered business intelligence platform for importing datasets, generating insights, and creating interactive visualizations and dashboards.

Overview

Giraph is a full-stack monorepo with:

• frontend/: Next.js 15 + TypeScript app (dashboard, auth flows, data connect UI, visualizations)
• backend/: Express + MongoDB API (import, analysis, query, insights, dashboards, Google integrations)

Core capabilities include:

• CSV/Excel file ingestion
• Google Sheets import and analysis
• AI-assisted schema analysis and insight generation (Gemini)
• Visualization recommendation and generation
• Dashboard persistence and retrieval
• JWT + cookie-based authentication, including Google OAuth

Tech Stack

• Frontend: Next.js, React 19, TypeScript, Tailwind CSS, Radix UI, Axios, ECharts/Recharts
• Backend: Node.js, Express, MongoDB/Mongoose, Passport, JWT, Multer, Google APIs, Nodemailer, Winston
• AI: Google Gemini (@google/generative-ai)

Repository Structure

Giraph/
├── frontend/                  # Next.js frontend
│   ├── app/                   # App Router pages and API route handlers
│   ├── components/            # UI + feature components
│   ├── context/               # Auth context
│   └── lib/                   # API client, hooks, chart utilities
├── backend/                   # Express backend
│   ├── src/api/               # Routes, controllers, middleware
│   ├── src/services/          # Domain/service layer
│   ├── src/models/            # Mongoose models
│   ├── src/config/            # App/bootstrap/database/passport config
│   └── src/utils/             # Utility modules (Gemini, logging, mail, file/db helpers)
└── README.md

Prerequisites

• Node.js 18+ recommended
• npm 9+ recommended
• MongoDB running locally or accessible remotely
• Google Gemini API key
• (Optional) Google OAuth credentials for Google login/Sheets workflows

Quick Start

1. Install dependencies

Install per app:

npm install
npm install --prefix backend
npm install --prefix frontend

2. Configure environment

Create backend/.env with:

# Core
PORT=3000
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/giraph
FRONTEND_URL=http://localhost:3001
BACKEND_APP_URL=http://localhost:3000

# AI
GEMINI_API_KEY=your_gemini_key

# Auth
JWT_SECRET=replace_with_strong_secret
JWT_EXPIRATION=7d
JWT_COOKIE_NAME=jwt_token

# Google OAuth / Sheets (optional but required for Google features)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

# Email (optional)
EMAIL_SERVICE_PROVIDER=gmail
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_SECURE=true
EMAIL_USER=your_email
EMAIL_PASS=your_app_password
EMAIL_FROM="Giraph Platform <no-reply@giraph.ai>"

# Ethereal fallback (optional)
ETHEREAL_HOST=
ETHEREAL_PORT=587
ETHEREAL_USER=
ETHEREAL_PASS=

Create frontend/.env.local with:

NEXT_PUBLIC_API_URL=http://localhost:3000/api

3. Run backend

npm run dev --prefix backend

4. Run frontend

In a second terminal:

npm run dev --prefix frontend -- --port 3001

Then open http://localhost:3001.

Available Scripts

Backend (backend/package.json)

• npm run dev --prefix backend - Run with nodemon
• npm start --prefix backend - Run with Node

Frontend (frontend/package.json)

• npm run dev --prefix frontend
• npm run build --prefix frontend
• npm start --prefix frontend
• npm run lint --prefix frontend

API Surface (High-Level)

Mounted under /api by the backend:

• /auth - signup/login/logout/me, email verification, Google OAuth callbacks
• /datasources - file upload/list/delete, data source listing
• /collections - collection listing, retrieval, deletion
• /import - file import, Google import, analyze and iteration flows
• /analysis - schema analysis
• /query - natural-language/data query processing
• /insights - insights, forecast, anomalies
• /visualizations - recommendations, generation, regeneration, dashboard save/get
• /dashboards - dashboard CRUD
• /google - Google auth, sheets listing/tabs/data, import/analyze, logout

Authentication Model

• Backend issues JWTs and stores them in HttpOnly cookies (JWT_COOKIE_NAME)
• Frontend Axios client sends cookies with withCredentials: true
• Protected endpoints are guarded by token middleware

Common Development Notes

• Backend default port: 3000
• Frontend recommended dev port: 3001
• CORS uses FRONTEND_URL from backend env
• Next.js rewrites /api/:path* to http://localhost:3000/api/:path*
• Uploaded files are handled via Multer under backend upload handling

Troubleshooting

• 401 Unauthorized on frontend requests:
  • Confirm backend is running and NEXT_PUBLIC_API_URL is correct
  • Confirm cookie domain/port alignment and FRONTEND_URL in backend .env
• GEMINI_API_KEY not found:
  • Add GEMINI_API_KEY to backend/.env and restart backend
• Mongo connection issues:
  • Verify MONGODB_URI and ensure MongoDB is reachable
• Google login/sheets not working:
  • Verify Google credentials and callback URL consistency

Security Notes

• Replace default/dev secrets before production
• Set secure cookie behavior and HTTPS in production
• Restrict CORS origin to trusted frontend domains
• Keep API keys and OAuth secrets in environment variables only

Existing Backend README

A backend-focused README also exists at backend/README.md.

License

No license file is currently present in this repository.