StudySphere

Collaborative Notes Sharing with Token Economy

Tags: EdTech · RAG · Token Economy · Gemini · Pinecone · LangChain · Node.js · Express · PostgreSQL · Vector Database · AI Auto-Grading · Full-Stack · Multi-Tenancy · Peer Learning

StudySphere is a decentralized, pool-based notes-sharing and RAG (Retrieval-Augmented Generation) platform that turns passive note-taking into an active, rewarded learning ecosystem. It bridges the gap between individual effort and collective knowledge by solving the "freeloader" problem through an AI-driven token economy.

---

Links

🚀 Live Demo	studysphere.vercel.app
🎥 Demo Video	Watch the Walkthrough
🗺️ System Architecture	Excalidraw ER Diagram

Hackathon Evaluators: Email delivery may be delayed in the staging environment due to third-party sandbox limitations. Use these demo credentials for immediate testing:

Account	Email	Password
User 1	user1@gmail.com	keerthivasan
User 2	user2@gmail.com	keerthivasan

---

The Problem

Traditional digital learning environments face three structural flaws:

• The Freeloader Problem — Peer-to-peer learning fails because there is no systemic incentive to reward core contributors or engage passive students.
• Unstructured Information — Fast-paced, messy student notes lose context and meaning over time.
• Inefficient Revision — Learners waste critical hours re-reading entire documents instead of precision-targeting missing concepts.

The Solution

• Isolated Context Pools — Each subject or lecture series has its own Pool with a dedicated RAG context. The AI strictly draws answers from documents uploaded to that exact namespace, eliminating cross-subject hallucinations.
• Token-Based Learning Economy — Users earn tokens by uploading high-quality study materials, and spend tokens to query the AI or generate summaries. Continuous contribution is the only path to continued access.
• AI-Powered Auto-Grading — Every uploaded note is parsed for clarity and depth, with tokens dynamically allocated based on assessed value.

---

Tech Stack

Layer	Technologies
Backend	Node.js, Express
Database	PostgreSQL, Drizzle ORM
Vector & AI	Pinecone (multi-tenant namespaces), Gemini 1.5 Flash/Pro, LangChain
Auth	JWT, bcrypt
File & Mail	Multer, Cloudinary, Nodemailer
Dev Tools	dotenv, Nodemon

---

Architecture

Upload Quality Notes ➔ Earn Tokens ➔ Ask Complex Questions ➔ Spend Tokens ➔ Repeat

How It Works

1. Auth — Secure signup with mandatory email verification. Issues short-lived access tokens and HTTP-only refresh tokens.
2. Pools — Users spin up subject workspaces and distribute cryptographic join codes to classmates.
3. Note Ingestion — Uploads are parsed by LangChain, split into semantic chunks, assigned metadata, and upserted into isolated Pinecone namespaces.
4. Token System — Tokens are stored as integer units. Uploading earns tokens (amount determined by AI grade); each AI query costs 1 token.
5. Contextual Q&A — Each prompt validates the user's token balance, retrieves top-k relevant vectors, and returns source-grounded answers via Gemini.

---

Screenshots

Authentication

Dashboard

Pools

Notes

Chat

---

API Reference

All protected routes require:

Authorization: Bearer <access_token>

Some routes use HTTP-only cookies for refresh tokens.

Authentication

Method	Endpoint	Description
POST	/auth/signup	Register a new account and dispatch verification email
GET	/auth/verify/:token	Verify user email address
POST	/auth/signin	Validate credentials and return JWT access tokens
POST	/auth/refresh	Rotate access keys via secure refresh token cookie
POST	/auth/logout	Invalidate the active session

Users & Workspaces

Method	Endpoint	Description
GET	/users/me	Fetch current user profile metadata
GET	/users/me/:id	Fetch pool statistics for a specific user
POST	/pools	Create a new pool and generate a unique access code
POST	/pools/join	Join an existing workspace via shared code
GET	/pools	List all active workspaces for the current user

Chat & RAG Engine

Method	Endpoint	Description
POST	/chats	Initialize an isolated conversation inside a pool
GET	/chats	Fetch global chat logs for the workspace
POST	/chats/:chatId/ask	Validate token budget, query Pinecone, return AI response
GET	/chats/:chatId	Load historical message thread for a specific chat

Notes

Method	Endpoint	Description
POST	/notes	Upload a file (multipart/form-data), run auto-grading, mint tokens
GET	/notes/:poolId	List metadata for all notes in a pool
GET	/notes/:noteId	Retrieve raw text and evaluation history for a note

---

Local Setup

1. Clone & Install

git clone <your-repository-url>
cd server
npm install

2. Environment Variables

Create a .env file in the server/ root:

PORT=8080
DATABASE_URL=postgresql://user:password@localhost:5432/studysphere

# Security
JWT_SECRET=your_super_secret_access_key
JWT_REFRESH_SECRET=your_super_secret_refresh_key
JWT_EXPIRES_IN=1d
JWT_REFRESH_EXPIRES_IN=5d

# Storage & Email
CLOUDINARY_CLOUD_NAME=your_cloudinary_name
CLOUDINARY_API_KEY=your_cloudinary_key
CLOUDINARY_API_SECRET=your_cloudinary_secret
EMAIL_USER=your_verified_app_email@gmail.com
EMAIL_PASS=your_gmail_app_password
BASE_URL=http://localhost:8080

# Vector & AI
PINECONE_API_KEY=your_pinecone_api_key
PINECONE_INDEX=vashist
PINECONE_HOST=your_pinecone_host_url
GEMINI_API_KEY=your_google_gemini_api_key

3. Run

npm run seed   # Seed the database schema
npm run dev    # Start the dev server with hot reload

---

Hackathon Evaluation Notes

Criterion	Weight	Approach
Innovation	20%	Token economy framework designed to solve human-centric engagement bottlenecks in peer learning
Technical Implementation	35%	Multi-tenant RAG with isolated Pinecone namespaces and automated AI grading pipelines
Feasibility	20%	Production-ready architecture with integer-based token ledger optimized for classroom scale
Video Presentation	15%	Watch here
Deployment	10%	Live on Vercel

---

Roadmap

• Personal Workspace Sandboxing — Private chat module where users can ingest personal documents and research into an exclusive vector space, independent of public pool dynamics.
• Multimodal Note Evaluation — Expand the grading engine to analyze handwriting, math diagrams, and lecture screenshots via Gemini's native vision models.