MindScribe

Transform dense text into interactive, AI-powered mind maps.

Transform your lecture notes, research papers, and textbook chapters into visual concept maps you can explore, quiz yourself on, and track your understanding of — all in one place.

Live Demo

---

Preview

---

Features

Paste any block of text and get a structured visual concept map in seconds.

Click any node for an AI-generated explanation grounded in the original text.

Select two nodes to understand exactly how those concepts connect.

Generate multiple-choice questions for any concept and get instant feedback.

Mark concepts as understood, fuzzy, or lost — colour-coded directly on the map.

Visited nodes and ratings persist across sessions via Cloud Firestore.

Download your completed mind map as an image with one click.

Google Sign-In and email/password auth via Firebase.

---

How It Works

Paste text  →  AI extracts concepts  →  Interactive mind map
     ↓                                         ↓
  Up to 5,000 characters            Click nodes to explore
                                         ↓
                              Explain · Relate · Quiz
                                         ↓
                              Progress saved to Firestore

---

Tech Stack

Layer	Technology
Frontend	React 19 + TypeScript + Vite
Visualization	React Flow (@xyflow/react)
Backend	FastAPI + Python 3.11
AI	OpenAI GPT-4o-mini
Authentication	Firebase Authentication
Database	Cloud Firestore
Rate Limiting	SlowAPI
Export	html-to-image
Frontend Host	Firebase Hosting
Backend Host	Render

---

Architecture

                    +------------------+
                    |     React App    |
                    |   (Vite + TS)    |
                    +---------+--------+
                              |
                              v
                    +------------------+
                    |     FastAPI      |
                    |  Python Backend  |
                    +---------+--------+
                              |
               +--------------+--------------+
               |                             |
               v                             v
       +---------------+             +---------------+
       |   OpenAI API  |             | Firebase Auth |
       +---------------+             +---------------+
                                             |
                                             v
                                     +----------------+
                                     | Cloud Firestore |
                                     +----------------+

---

API Endpoints

All endpoints require Authorization: Bearer <firebase_id_token>.

Method	Endpoint	Description	Rate Limit
POST	/generate-mindmap	Generate a structured mind map	10/hour
POST	/explain-node	Explain a concept	30/hour
POST	/relate-nodes	Explain concept relationships	20/hour
POST	/quiz-node	Generate multiple-choice quiz	20/hour

---

Local Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• A Firebase project with Authentication and Firestore enabled
• An OpenAI API key

Clone the Repository

git clone https://github.com/yourusername/MindScribe.git
cd MindScribe

Backend

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

Create a .env file in the backend folder:

OPENAI_API_KEY=your_openai_api_key
FIREBASE_SERVICE_ACCOUNT=your_firebase_service_account_json

Start the server:

uvicorn main:app --reload

Frontend

cd frontend
npm install

Create a .env file in the frontend folder:

VITE_API_URL=http://localhost:8000
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=

Start the development server:

npm run dev

---

Environment Variables

Backend

Variable	Description
OPENAI_API_KEY	OpenAI API key
FIREBASE_SERVICE_ACCOUNT	Firebase service account JSON

Frontend

Variable	Description
VITE_API_URL	Backend URL
VITE_FIREBASE_API_KEY	Firebase API key
VITE_FIREBASE_AUTH_DOMAIN	Firebase auth domain
VITE_FIREBASE_PROJECT_ID	Firebase project ID
VITE_FIREBASE_STORAGE_BUCKET	Firebase storage bucket
VITE_FIREBASE_MESSAGING_SENDER_ID	Firebase messaging sender ID
VITE_FIREBASE_APP_ID	Firebase app ID

---

Project Structure

MindScribe
├── backend
│   ├── main.py
│   ├── requirements.txt
│   ├── Procfile
│   └── .env
└── frontend
    ├── src
    │   ├── components
    │   │   ├── AuthPage.tsx
    │   │   ├── InputPage.tsx
    │   │   ├── MindMapPage.tsx
    │   │   ├── NodePanel.tsx
    │   │   └── PasswordGate.tsx
    │   ├── hooks
    │   │   └── useMaps.ts
    │   ├── firebase.ts
    │   ├── App.tsx
    │   └── main.tsx
    ├── package.json
    └── .env

---

Roadmap

• PDF upload with automatic text extraction
• AI-generated study summaries
• Flashcard export (Anki-compatible)
• Collaborative mind maps
• Mobile application

---

Contributing

Contributions, feature suggestions, and bug reports are welcome. Fork the repository, create a new branch, commit your changes, and open a pull request.

---

License

This project is licensed under the MIT License.

---

Built to make learning more visual, interactive, and engaging.