🧠 MindMap AI

Turn documents into interactive 3D knowledge graphs — then study them with AI.

AI-powered 3D knowledge mapping & collaborative study platform

🌐 Live Demo · 📱 Download APK · Features · Tech Stack · Architecture · Getting Started · Structure · API · Deployment

✦ Live now


🌐 Web app	mindmap-ai.xyz — deployed on Vercel
📱 Mobile app	Download the Android APK → — built with EAS (Expo SDK 54)

📥 Download the Android App

Grab the latest Android build from the Releases page.

To install:

Download the .apk from the latest release
On your Android device, open it — you may be prompted to allow installs from unknown sources (Settings → Apps → Special access → Install unknown apps)
Tap Install, then open MindMap AI

Requires Android 6.0+. The APK is an EAS-built package signed for direct install — no Play Store account needed.

Overview

MindMap AI turns passive studying into active, visual, AI-assisted learning.

Students upload PDFs or Word documents, paste a YouTube link, or drop in raw notes — and Gemini extracts the concepts and builds an interactive 3D knowledge graph. From there, they can study with an AI tutor, collaborate in real time, take AI-generated active-recall quizzes with AI-graded answers, and track their progress over time.

The repository is a monorepo with two apps:

mindmap-web — the Next.js 16 web app (deployed to Vercel at mindmap-ai.xyz)
mindmap-mobile — the React Native (Expo) mobile app (Android build via EAS)

Built as a senior graduation project — a full end-to-end product spanning 3D rendering, real-time collaboration, generative AI, and cross-platform delivery.

✨ Features

🗺️ 3D Knowledge Maps Interactive WebGL graph rendered with Three.js Nodes as glowing 3D spheres, edges as living connections GSAP camera fly-ins and node pop-in transitions Click any node to inspect, summarize, or ask the AI Drag to orbit · scroll to zoom · animated energy pulses	🤖 AI Features — Gemini PDF / DOCX / YouTube → Map — upload a document or paste a YouTube link, Gemini auto-builds the graph AI Tutor — streaming chat aware of your map & selected node Active-recall quizzes — MCQ + short-answer, generated from your nodes AI answer grading — typed answers graded for partial credit, not string-match Node summarizer — one-click AI summary for any concept Semantic search — find nodes by meaning via pgvector embeddings
👥 Real-time Collaboration — Firebase Live node-position sync across editors (<50 ms via RTDB) Presence bar — see who's online with colored avatars Per-user cursor tracking Invite by email with Editor / Viewer roles In-session threaded comments via Firestore	📊 Analytics & Progress 30-day activity bar chart Per-map mastery rings (SVG donut charts) Quiz session history with score trends Weekly study report card Streaks — tracked, never shamed
🌐 Public Explore Browse community knowledge maps Search by title or description Sort by popular / recent / most-forked One-click fork — deep-clones all nodes & edges to your account 5-star rating system	📱 Mobile App — React Native + Expo Supabase auth with session persistence + Google OAuth Browse, search & open any map Concepts · Graph · People · Notes tabs per map Orbital + network graph views with node focus Dedicated AI Tutor screen — streaming chat, multi-thread history per map 3D flip flashcards (Reanimated) · offline review · FCM push

🧰 Tech Stack

Layer	Technology
Frontend	Next.js 16 App Router · shadcn/ui · Tailwind CSS
Animations	Framer Motion (UI) · GSAP (3D canvas + timelines)
3D Rendering	Three.js + custom raycasting
Backend	Next.js API Routes + Server Actions
Auth	Supabase Auth — email + Google OAuth
Database	Supabase PostgreSQL + Prisma ORM
Vector Search	pgvector — 1536-dim embeddings, cosine similarity
File Storage	Supabase Storage
Realtime / Presence	Firebase RTDB + `onDisconnect()`
Push Notifications	Firebase Cloud Messaging (FCM)
In-session data	Firestore
Mobile	React Native (Expo SDK 54) · Expo Router
Mobile animations	Reanimated + Gesture Handler
Mobile graphics	react-native-svg · expo-linear-gradient
AI	Google AI Studio — Gemini (gemini-2.5-flash)
State	Zustand
Validation	React Hook Form + Zod
Deployment	Vercel (web) · EAS (mobile)

🏗️ Architecture

The system is organized into four layers — a client layer (Next.js web + React Native mobile), a Next.js API layer exposing REST routes and server actions, a services layer spanning Supabase, Firebase, and Google AI Studio, with Prisma providing type-safe database access. Content enters as PDF, DOCX, or a YouTube link, and Gemini turns it into a knowledge graph.

Data split — why Supabase and Firebase?

Concern	Provider	Why
Users, maps, nodes, edges	Supabase PostgreSQL	Relational, consistent, SQL
Auth sessions	Supabase Auth	RLS enforces per-user access
PDF/DOCX uploads, avatars	Supabase Storage	Integrated with RLS
Vector embeddings	pgvector (Supabase)	Same DB, cosine similarity
Live node positions	Firebase RTDB	Sub-50 ms sync, ephemeral
Presence / cursors	Firebase RTDB	`onDisconnect()` auto-cleanup
In-session comments	Firestore	Nested document model
Push notifications	FCM	Native mobile push

🚀 Getting Started

Prerequisites

Node.js 20+
A Supabase project
A Firebase project
A Google AI Studio API key

1 · Clone

git clone https://github.com/Mazennaji/mindmap-ai.git
cd mindmap-ai/mindmap-web

2 · Install

npm install

3 · Environment variables

cp .env.local.example .env.local

Full .env.local reference (click to expand)

# ── Supabase ──────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# ── Firebase (client) ─────────────────────
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_DATABASE_URL=

# ── Firebase (admin — server only) ────────
FIREBASE_PROJECT_ID=
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=

# ── AI ────────────────────────────────────
GEMINI_API_KEY=

# ── Database ──────────────────────────────
DATABASE_URL=      # pooled connection (pgBouncer, :6543)
DIRECT_URL=        # direct connection (:5432) — used by Prisma

# ── App ───────────────────────────────────
NEXT_PUBLIC_APP_URL=http://localhost:3000

⚠️ NEXT_PUBLIC_* values are baked in at build time and exposed to the browser — never put secrets behind that prefix. Everything without it stays server-only.

4 · Database setup

npx prisma generate         # generate the Prisma client
npx prisma db push          # push schema to Supabase (dev)

# Then, in the Supabase SQL editor, run:
#   supabase/setup.sql      → pgvector, RLS policies, buckets
#   supabase/storage.sql    → storage bucket rules

5 · shadcn/ui components

npx shadcn@latest init
npx shadcn@latest add button card dialog input badge avatar tabs tooltip

6 · Run

npm run dev

Open http://localhost:3000 🎉

📁 Project Structure

mindmap-ai/
├── mindmap-web/                   # Next.js web app → Vercel (mindmap-ai.xyz)
│   ├── prisma/
│   │   └── schema.prisma          # maps, nodes, edges, users, ratings…
│   ├── src/
│   │   ├── app/
│   │   │   ├── (auth)/            # login · register
│   │   │   ├── (dashboard)/       # protected app pages
│   │   │   │   ├── dashboard/     # stats + recent maps
│   │   │   │   ├── maps/          # map list + 3D editor ([id])
│   │   │   │   ├── study/         # flashcard + quiz review
│   │   │   │   ├── explore/       # public discovery + [id] detail
│   │   │   │   ├── analytics/     # progress charts
│   │   │   │   └── settings/      # profile · security · danger
│   │   │   ├── api/
│   │   │   │   ├── maps/          # CRUD + fork + rate
│   │   │   │   ├── nodes/  flashcards/  quiz-sessions/
│   │   │   │   ├── upload/  explore/  analytics/  collaborators/
│   │   │   │   ├── ai/            # generate-map · quiz · grade · summarize · chat
│   │   │   │   └── user/          # profile · export · delete
│   │   │   └── auth/callback/     # Supabase OAuth callback
│   │   ├── components/            # ui · map · ai · flashcards · collab · analytics · explore
│   │   ├── hooks/                 # useAuth · useMap · useCollaboration…
│   │   ├── lib/                   # supabase · firebase · prisma · ai clients
│   │   ├── store/                 # Zustand stores
│   │   └── types/                 # map.ts · analytics.ts · explore.ts
│   ├── next.config.ts
│   └── middleware.ts             # Supabase auth session refresh
│
└── mindmap-mobile/                # React Native (Expo) app → EAS
    ├── assets/                    # icons + splash
    ├── google-services.json       # Firebase Android config (FCM)
    ├── lib/                       # api · supabase · firebase · googleAuth · comments…
    ├── components/                # maps · auth · settings…
    ├── store/                     # Zustand stores
    └── app/                       # Expo Router
        ├── _layout.tsx            # root layout + notifications
        ├── auth/callback.tsx      # Google OAuth redirect handler
        ├── (auth)/                # login · register · forgot-password
        ├── (tabs)/                # dashboard · maps · study · progress · settings
        └── map/[id]/
            ├── index.tsx          # Concepts / Graph / People / Notes + Tutor FAB
            └── tutor.tsx          # full-screen AI Tutor chat

🔌 API Routes

Method	Route	Description
`GET`	`/api/maps`	List all maps for current user
`POST`	`/api/maps`	Create a new map
`GET`	`/api/maps/:id`	Get single map with nodes + edges
`PATCH`	`/api/maps/:id`	Update title / description / visibility
`DELETE`	`/api/maps/:id`	Delete map
`POST`	`/api/maps/:id/fork`	Deep-clone a public map
`POST` `GET`	`/api/maps/:id/rate`	Rate a map (1–5) · read rating summary
`POST`	`/api/nodes`	Create a node
`GET`	`/api/flashcards?mapId=`	Get flashcards for a map
`POST`	`/api/quiz-sessions`	Save a completed quiz session
`POST`	`/api/upload`	Upload PDF/DOCX → Supabase Storage
`GET`	`/api/explore`	Search public maps (paginated)
`GET`	`/api/analytics`	Full progress stats
`POST`	`/api/collaborators`	Invite collaborator by email
`POST`	`/api/ai/chat`	Streaming Gemini tutor
`POST`	`/api/ai/generate-map`	PDF/DOCX/YouTube → nodes + edges
`POST`	`/api/ai/quiz`	Generate active-recall quiz
`POST`	`/api/ai/grade`	AI-grade a typed quiz answer
`POST`	`/api/ai/summarize`	Summarize a single node
`GET` `PATCH`	`/api/user/profile`	Get / update profile
`GET`	`/api/user/export`	Export all data as JSON
`DELETE`	`/api/user/delete`	Delete account + cascade
`GET`	`/api/sitemap`	Auto-generated sitemap.xml

📱 Mobile App

The React Native app lives in /mindmap-mobile (a separate Expo project) using Expo Router for file-based navigation, and is distributed as an Android build via EAS.

📥 Download the latest APK from Releases →

Highlights

Email/password + Google OAuth + session persistence (Supabase)
Browse & search all maps
Map detail: Concepts · Graph · People · Notes
Orbital + network graph views with node focus & bond highlighting
AI Tutor on its own screen (Tutor FAB) — streaming Gemini chat, multi-thread history per map
3D flip flashcard deck (Reanimated) · score tracking · FCM push

Setup

cd mindmap-mobile
cp .env.example .env
# Fill EXPO_PUBLIC_SUPABASE_URL, EXPO_PUBLIC_SUPABASE_ANON_KEY,
#      EXPO_PUBLIC_FIREBASE_*, EXPO_PUBLIC_APP_URL

Place your Firebase Android config at mindmap-mobile/google-services.json. Its package_name must match expo.android.package in app.json (com.mazen.mindmap), or the Android build fails with "No matching client found."

⚠️ Development build required (not Expo Go)

As of Expo SDK 53+, Android push notifications were removed from Expo Go, so this app uses a development build (it relies on expo-notifications for FCM).
npm install -g eas-cli && eas login
eas build --profile development --platform android
# install the APK, then:
npx expo start --dev-client
The dev build behaves like Expo Go (scan QR, fast refresh) but bundles the app's native modules. See the development builds guide.

☁️ Deployment

Web → Vercel · mindmap-ai.xyz

The web app deploys from the mindmap-web subfolder of the monorepo.

npm install -g vercel && vercel login
cd mindmap-web
vercel            # first run: link project + preview
vercel --prod     # production deploy

Clean-deploy checklist (learned the hard way):

Root Directory → set the Vercel project's Root Directory to mindmap-web (monorepo). GitHub deploys rely on this.
Do not set outputFileTracingRoot / turbopack.root in next.config.ts for Vercel — they misplace the .next output and break the build with ENOENT … /.next/package.json.
Environment variables → add every var from .env.local in Settings → Environment Variables. NEXT_PUBLIC_* must exist before the build (baked in). Paste FIREBASE_PRIVATE_KEY exactly, preserving \n handling. Missing DIRECT_URL fails prisma generate at install.
Prisma → mindmap-web/package.json must include "postinstall": "prisma generate" (and "build": "prisma generate && next build") so Vercel regenerates the client.
Supabase Auth URLs → set Site URL to https://mindmap-ai.xyz and add https://mindmap-ai.xyz/** to the redirect allow-list, or Google OAuth bounces back to localhost. Use ${window.location.origin}/auth/callback as redirectTo so dev and prod both work.

Mobile → EAS

cd mindmap-mobile
eas build --profile development --platform android   # dev client
eas build --profile production --platform android    # release APK → attach to a GitHub Release

After a production build finishes, download the .apk from the EAS dashboard and attach it to a GitHub Release so the download links above resolve.

Other services

npx prisma db push                                   # schema → Supabase
firebase deploy --only database,firestore:rules      # Firebase rules

See DEPLOYMENT.md for the full step-by-step guide.

🗃️ Database Schema

Managed by Prisma over Supabase PostgreSQL:

users ──< maps ──< nodes ──< node_embeddings
                    │
                    ├──< edges
                    ├──< collaborators >── users
                    ├──< flashcards ──< quiz_answers
                    ├──< quiz_sessions ──< quiz_answers
                    ├──< comments >── users
                    ├──< documents
                    ├──< chat_threads ──< chat_messages
                    └──< map_ratings >── users

flashcards carry a type (MCQ / typed) plus options for MCQ items
quiz_answers record isCorrect, set by direct match (MCQ) or AI grading (typed)
documents store uploaded PDF/DOCX filenames processed into a map
chat_threads / chat_messages back the multi-thread AI tutor history
map_ratings power the 5-star Explore rating (@@unique([mapId, userId]))

Full ERD → docs/erd.png

🎭 Use Case Diagram

Covers all actors (Guest, Registered User, Map Owner, Collaborator) and system boundaries (Gemini, Firebase, Supabase) → docs/usecase.png

⚖️ Ethical Considerations

AI transparency — every AI-generated element is visually labeled
Data minimalism — uploaded documents deleted after processing; no behavioral data sold
No dark patterns — no streak-shaming, no addictive loops
Accessibility — 2D fallback map, ARIA labels, reduced-motion mode
Academic integrity — AI output labeled; no essay generation

🧩 Built With

Next.js · Supabase · Firebase · Three.js · GSAP · Framer Motion · shadcn/ui · Prisma · Google AI Studio — Gemini · Expo

🌐 mindmap-ai.xyz

Built with ❤️ as a senior graduation project

MIT Licensed

Name		Name	Last commit message	Last commit date
docs		docs
mindmap-mobile		mindmap-mobile
mindmap-web		mindmap-web
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

🧠 MindMap AI

Turn documents into interactive 3D knowledge graphs — then study them with AI.

✦ Live now

📥 Download the Android App

Overview

✨ Features

🗺️ 3D Knowledge Maps

🤖 AI Features — Gemini

👥 Real-time Collaboration — Firebase

📊 Analytics & Progress

🌐 Public Explore

📱 Mobile App — React Native + Expo

🧰 Tech Stack

🏗️ Architecture

Data split — why Supabase and Firebase?

🚀 Getting Started

Prerequisites

1 · Clone

2 · Install

3 · Environment variables

4 · Database setup

5 · shadcn/ui components

6 · Run

📁 Project Structure

🔌 API Routes

📱 Mobile App

Setup

⚠️ Development build required (not Expo Go)

☁️ Deployment

Web → Vercel · mindmap-ai.xyz

Mobile → EAS

Other services

🗃️ Database Schema

🎭 Use Case Diagram

⚖️ Ethical Considerations

🧩 Built With

🌐 mindmap-ai.xyz

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages