An AI-powered learning platform built to make studying more active, engaging, and effective.
Transform learning materials into study resources, challenge yourself with quizzes, and bring classrooms to life.

---

✨ The idea behind Noted

Studying shouldn't be limited to reading the same notes over and over.

Noted turns learning materials into tools you can actually use to study. Create learning resources, test your understanding, track your progress, and engage with other learners through interactive classroom experiences.

Whether you're studying independently or managing learning across a school, Noted brings your study workflow into one platform.

🚀 Explore the experience

Complete Study Sets

Create a Study Set from pasted notes, PDF/DOCX/PPTX documents, images, or a YouTube video with captions. Each set includes summarized and comprehensive notes, spaced-repetition flashcards, a practice quiz, a short study plan, and a source-grounded AI tutor. Study Sets are private to the account that created them and use the existing AI-credit limits.

🧠 AI Study Studio Turn notes and learning materials into useful study resources. Summaries · Quizzes · Flashcards · Podcasts · Video content	📚 Your Learning Library Keep saved learning materials organised and revisit your resources when you need them. Saved materials · Quiz history · Progress review
⚡ Focus & Practice Make revision more active with focus tools, quizzes, and interactive learning experiences. Focused study · Knowledge checks · Practice	🎮 Live Quiz Experiences Bring competition and collaboration into learning with quiz battles and live classroom game shows. Real-time interactions · Quiz battles · Game shows
🏫 School Learning Support school communities with tools for managing accounts, teachers, students, and quiz results. School administration · Student access · Results	🌗 Flexible Experience Use Noted across desktop and mobile layouts, with light and dark themes. Responsive interface · Light theme · Dark theme

Note: Some capabilities depend on the external services and API credentials configured for a particular deployment.

🛠️ Built with

Noted uses a separate web client and API, with real-time functionality for interactive experiences.

Layer	Technology
Web client	React 19, Vite, React Router
Styling and icons	Tailwind CSS 4, Lucide React
API	Node.js, Express 5
Real-time communication	Socket.IO
Database and data models	MongoDB, Mongoose
Authentication	JWT
AI integrations	Configurable AI providers
Optional media services	Cloudinary, Pexels, Replicate, ElevenLabs
Optional supporting services	OCR.Space and email integration

📋 Table of contents

• Get started
• Environment configuration
• Run Noted locally
• Available scripts
• Main application routes
• Deployment
• Project structure
• Contributing
• Project links

---

💻 Get started

Prerequisites

Before running Noted locally, make sure you have:

• Node.js: ^20.19.0 or >=22.12.0
• npm
• MongoDB: a local instance or a reachable hosted database

The client and server are separate npm projects, each with its own dependencies and lockfile.

⚙️ Environment configuration

Clone the repository and enter the project directory:

git clone https://github.com/mickeyweb1/Noted.git
cd Noted

Create your local environment files from the provided examples:

cp server/.env.example server/.env
cp client/.env.example client/.env

Core variables

Variable	Required	Purpose
MONGO_URI	Yes	MongoDB connection string for the API
JWT_SECRET	Yes	Long, private, randomly generated secret for signing authentication tokens
VITE_API_URL	Yes for local client setup	API base URL, including /api
CLIENT_URL	Required for payments	Frontend origin used for CORS, generated links, and payment callbacks
PAYSTACK_SECRET_KEY	Required for payments	Paystack secret key used to initialize and verify transactions and validate webhooks
PORT	No	API port; defaults to 5000
GAME_SHOW_OUTBOX_DIR	Recommended for production	Directory for pending Game Show results and active match snapshots; point this to a persistent mounted disk to recover them after an API restart

The API uses MongoDB transactions when completing focus sessions. MongoDB must run as a replica set (MongoDB Atlas is supported); a standalone local mongod instance must be configured as a single-node replica set.

For local development, use these values where appropriate:

# server/.env
PORT=5000
CLIENT_URL=http://localhost:5173
PAYSTACK_SECRET_KEY=your_paystack_secret_key

# Configure these with your actual values:
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_long_random_secret

# client/.env
VITE_API_URL=http://localhost:5000/api

The examples above illustrate the core settings. Keep any additional values already present in your .env.example files.

Optional integrations

Configure only the services needed for the features you intend to use.

🤖 AI generation providers

Noted supports configurable AI providers. Configure at least one provider key:

• GROQ_API_KEY
• OPENROUTER_API_KEY
• COHERE_API_KEY
• NVIDIA_API_KEY
• HF_API_KEY

Provider model names can be overridden using:

• GROQ_MODEL
• OPENROUTER_MODEL
• COHERE_MODEL
• NVIDIA_MODEL
• HF_MODEL

🖼️ Images and media

Configure the corresponding credentials for the media features you intend to use:

• CLOUDINARY_CLOUD_NAME
• CLOUDINARY_API_KEY
• CLOUDINARY_API_SECRET
• PEXELS_API_KEY
• REPLICATE_API_TOKEN

🎙️ Audio generation

• ELEVENLABS_API_KEY
• ELEVENLABS_VOICE_ID — optional voice configuration

💳 Paystack payments

Set PAYSTACK_SECRET_KEY in the server environment and CLIENT_URL to the deployed frontend origin. The pricing checkout initializes payments on the server using the plan prices in server/config/prices.js; never put the secret key in the client environment. Configure the Paystack webhook URL as:

https://your-api-host/api/payment/webhook

The checkout returns to /checkout to verify the transaction, while the webhook handles server-to-server confirmation.

📝 Text extraction and email

For text extraction:

• OCR_SPACE_API_KEY

For email notifications:

• EMAIL_USER
• EMAIL_PASS

Security: Keep real credentials in local environment files or your hosting provider's secret manager. Never commit secrets or production credentials to Git.

---

▶️ Run Noted locally

Install the server dependencies:

cd server
npm ci

Install the client dependencies:

cd ../client
npm ci

Start the API

From the repository root, open a terminal and run:

cd server
npm run dev

The API listens on port 5000 by default. Its root health response is available at:

http://localhost:5000

Start the web client

Open a second terminal from the repository root:

cd client
npm run dev

Open Noted in your browser:

http://localhost:5173

Keep both development processes running while using the application.

🧰 Available scripts

Client — client/

Command	Description
npm run dev	Start the Vite development server
npm run build	Create a production build in client/dist/
npm run preview	Preview the production build locally
npm run lint	Run Oxlint

Server — server/

Command	Description
npm run dev	Start the API with Nodemon
npm start	Start the API with Node.js
npm run migrate:quiz-session-retention	Run the quiz-session retention migration

Run commands from the corresponding client/ or server/ directory.

🧭 Main application routes

The client includes the following main routes:

Route	Purpose
/	Landing page
/pricing	Pricing
/personal	Personal learning product page
/school	School product page
/student	Student product page
/contact	Contact form
/login	Sign in
/signup	Account-type selection
/signup/personal	Personal account registration
/signup/school-admin	School registration
/signup/school-student	Join a school with an invite code
/dashboard	Protected learner dashboard
/admin/dashboard	Protected school administration dashboard

The API provides authentication, AI content, quizzes, feedback, support, and contact endpoints under /api.

Socket.IO supports live game-show interactions.

---

☁️ Deployment

Deploy the client and API as separate services, and provision a MongoDB database that both can reach as required by the application architecture.

API deployment

Configure the server's environment variables in your hosting provider. Make sure the MongoDB connection string, JWT secret, and any required service credentials are set securely.

For Game Show recovery, mount persistent storage for the API and set GAME_SHOW_OUTBOX_DIR to a directory on that mount. Completed result writes and active match snapshots are recovered from this directory after restart. Without a persistent mount, local files are not guaranteed to survive instance replacement or redeployment.

Set CLIENT_URL to the deployed frontend origin so browser requests can pass the configured CORS checks.

Client deployment

Set VITE_API_URL to the deployed API base URL, including /api.

For example:

VITE_API_URL=https://your-api-domain.example/api

Replace the example domain with your actual deployed API URL.

Important: Vite embeds VITE_API_URL at build time. If the API URL changes, update the variable and rebuild or redeploy the client.

🗂️ Project structure

Noted/
├── client/
│   ├── public/                  # Static assets
│   └── src/
│       ├── auth/                # Sign-in and registration pages
│       ├── components/          # Shared UI and layouts
│       ├── context/             # Shared application state
│       ├── pages/               # Marketing, dashboard, quiz and admin pages
│       └── utils/                # API and client utilities
│
└── server/
    ├── config/                  # External service configuration
    ├── controllers/             # API handlers
    ├── middleware/              # Authentication and error handling
    ├── models/                  # Mongoose models
    ├── routes/                  # API route definitions
    ├── utils/                   # Server utilities
    └── server.js                # Express and Socket.IO entry point

🤝 Contributing

Contributions and focused improvements are welcome.

1. Fork the repository and create a branch for your change.
2. Keep changes focused and avoid committing environment files or credentials.
3. Run the relevant client lint and production build checks.
4. Open a pull request explaining the change and how you verified it.

Keep changes consistent with the existing architecture and avoid introducing unnecessary dependencies.

🔗 Project links

🌐 Official website   •   💻 GitHub repository

---

Learn smarter. Practice better. Study louder. ⚡
_{Noted — making learning more active, engaging, and accessible.}