CortexNotes 🧠✨

🌐 Live Application: The production service is active and available for use at cortexnotes.dev. Feel free to sign up and generate your study decks there!

CortexNotes is a premium, AI-powered study companion designed to convert complex documents and lecture materials into minimalist, high-yield Cheat Sheets, interactive Practice Quizzes, and flippable 3D Study Flashcards.

By combining document parsers with Google Gemini's visual and reasoning capabilities, CortexNotes extracts, processes, and formats academic and general resources with dynamically tailored subject-adaptive summaries, strict factual grounding, and multilingual output support.

---

🚀 Key Features

1. Subject-Adaptive & Dynamic Summarization

• Context-Aware Summarizer: Dynamically adjusts output focus based on the document's topic:
  • Qualitative/Conceptual (e.g., Biology, Medicine, History, Law, Literature): Prioritizes key terms, core vocabulary, definitions, historical facts, dates, principles, classification tables, rules, and critical points to memorize.
  • Quantitative/Calculation-Heavy (e.g., Math, Physics, Engineering, Chemistry): Prioritizes formulas, derivations, variables, equations, boundary conditions, and step-by-step problem-solving.
  • General Rules/Guides (e.g., Sports Rules, Manuals): Prioritizes structured rules, procedures, techniques, and core guidelines.

2. Strict Factual Grounding (Zero Hallucinations)

• All generated summaries, quiz questions, explanations, and flashcards are strictly derived from the uploaded text. The system prohibits the AI from assuming or introducing external facts, details, or information not present in the original document.

3. Native Multilingual Support

• Automatically detects the language of the uploaded notes and generates the title, cheat sheet, quiz, and flashcards in the exact same language (e.g., Turkish notes produce Turkish study aids, English notes produce English study aids, etc.).

4. Multi-Format Document Parsing

• PDF Extraction: Fast and reliable text parsing using PyMuPDF.
• PowerPoint PPTX Extraction: Direct presentation slide structure and text frame parsing on the server using python-pptx.
• High-Accuracy Image OCR: Multimodal image processing supporting PNG, JPG, JPEG, and WEBP. Images are processed directly by Gemini's visual engine to parse text, equations, and diagrams.
• Large Capacity: Supports up to 30MB file uploads, utilizing background temp-file spooling on the server disk to prevent RAM bloat under concurrent high traffic.

5. Print-Ready Cheat Sheets (with LaTeX Math)

• Enforces strict LaTeX math syntax (inline math wrapped in $ and block equations wrapped in $$) only when mathematical/physics notations are present.
• Renders formulas seamlessly on the web using KaTeX, ReactMarkdown, remark-math, and rehype-katex, and formats them into publication-grade layouts exportable as A4 PDFs using headless Playwright rendering.

6. Interactive Practice Quizzes

• Automatically designs multiple-choice check-ups based on the notes.
• Gemini decides the ideal question count dynamically (between 5 and 10) depending on content depth.
• Instant correct/incorrect interactive feedback with check/cross metrics and comprehensive conceptual explanations.
• A final score display with dynamic feedback based on performance.

7. Interactive 3D Flashcards

• Generates a deck of key concepts, definitions, rules, or equations.
• Card components flip with a highly tactile 3D CSS rotate animation.
• Fully supports keyboard shortcuts (Spacebar to flip cards, Left/Right arrow keys to navigate the deck) for high-speed studying.

8. Smart State Persistence

• Uses an in-memory DOM visibility controller in Next.js to toggle active tabs.
• Zero Redundant Requests: Toggling between Summary, Quiz, and Flashcard tabs preserves their exact state (current question, selected options, score, flip state) and never resends API requests to Gemini, avoiding API rate limit exhaustions.
• Generates the quiz and flashcards in the background when the document is initially processed, so they are ready instantly.

9. Automated API Key Rotation & Failover

• Supports loading a list of API keys from a local gemini_keys.txt config file, a GEMINI_API_KEYS env variable, or fallback single-keys.
• Automatically catches rate limits (429), quota exhaustions, and service limit exceptions, instantly rotating to the next active key in the stack and retrying the request seamlessly.

10. Credits Billing & Token Security

• Uses secure JWT authorization tokens mapped directly to Supabase authentication.
• Implements a 1-credit-per-upload model via database atomic RPC triggers (decrement_credit/refund_credit).
• Once a document summary is generated, accessing, generating, and retaking quizzes or flashcards is 100% credit-free for the user.

---

🛠️ Technology Stack

Backend API (cortex-notes-api)

• FastAPI & Uvicorn (Python 3.11/3.13)
• google-genai SDK (utilizing gemini-3.5-flash for high-performance visual OCR, JSON schema validation, and structured study aids output)
• Playwright (for isolated, headless PDF formatting and snapshots)
• python-pptx (pure Python PowerPoint text extraction)
• PyMuPDF (high-performance PDF text parser)
• Supabase Python SDK (database integration and token verification)

Web App (cortex-notes-web)

• Next.js (App Router, TypeScript, React 19)
• TailwindCSS (styling and theme modes)
• ReactMarkdown, remark-math, rehype-katex & KaTeX (for mathematical formatting)
• Lucide React (icons system)
• Sonner (notifications system)

---

📁 Repository Structure

cortex-notes/
├── cortex-notes-api/      # FastAPI Python Backend
│   ├── app/
│   │   ├── api/          # Route controller endpoints (summaries, quizzes, flashcards, stripe)
│   │   ├── core/         # Global configurations & prompt instructions
│   │   └── services/     # File parsers, DB client, and Google Gemini SDK wrappers
│   ├── Dockerfile
│   └── requirements.txt  # Python requirements
├── cortex-notes-web/      # Next.js Web Frontend
│   ├── app/              # Views layouts, page router, callback interfaces
│   ├── components/       # UI elements (3D Flashcards, Quiz, Cheat Sheet, Dropzones)
│   └── public/           # Static assets
└── supabase_schema.sql   # Credits, users DB triggers, and PL/pgSQL procedures

---

⚙️ Configuration & Setup

Backend API Keys Rotation

To enable automatic API Key failover:

1. Create a gemini_keys.txt file in the root of the cortex-notes-api/ directory (this file is already ignored by .gitignore).
2. Paste your Gemini API keys line-by-line:

   AIzaSyYourFirstGeminiKeyHere
   AIzaSyYourSecondGeminiKeyHere
   AIzaSyYourThirdGeminiKeyHere

3. If this file is missing, the backend will automatically fallback to the GEMINI_API_KEYS (comma-separated list) or GEMINI_API_KEY environment variables.

Environment Setup

Create a .env in cortex-notes-api/ and a .env.local in cortex-notes-web/ containing:

• API: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
• Web: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_API_URL

Database Migrations (Supabase SQL Editor)

Run these scripts in order against your Supabase project:

1. supabase_schema.sql — users table, signup trigger, increment_credit
2. supabase_notes_migration.sql — notes table, RLS policies, indexes
3. supabase_notes_creator_name_migration.sql — adds creator_name to notes
4. supabase_credit_functions_migration.sql — required: adds decrement_credit/refund_credit (the API fails without them), locks credit RPCs down to the service role so the public anon key cannot mint credits, and adds the Stripe webhook idempotency table

⚠️ If you deployed before supabase_credit_functions_migration.sql existed, run it now — it revokes public EXECUTE on increment_credit, which was previously callable by anyone holding the anon key.

---

⚖️ License

This repository is licensed under a Portfolio & Personal Evaluation License.

• Portfolio & Job Review: You are free to view, fork, download, and study this codebase for portfolio inspection, code review, and job recruitment evaluation.
• Strictly Local Execution Only: You may run the Software locally on your personal machine (restricted to localhost / 127.0.0.1) solely for personal evaluation.
• No Public Hosting or Deployment: You are strictly prohibited from deploying, hosting, or running the Software on any public server or cloud provider (e.g. Vercel, Netlify, AWS, Render, Heroku) for either commercial or non-commercial purposes.
• No Commercial Use: You are strictly prohibited from using this Software, or any portion/modification of it, for any commercial, business, or revenue-generating purposes.
• Copyright Owner Exemption: The copyright owner (Arda Çankaya) retains full, unrestricted rights to commercialize, monetize, host publicly, distribute, sell, and license the Software.

For full licensing terms, please read the LICENSE file in the root directory.