A full-stack tutor discovery platform where students find teachers, start conversations, and share feedback. Separate Student, Teacher, and Admin workspaces keep each role's tasks organized.
Built with React, Tailwind CSS, Node.js, Express, MongoDB, and Socket.IO.
Teacher and Admin workspaces, plus live chat
Screenshots show development and test data. The project runs locally; a hosted demo is not available yet.
| Workspace | Features |
|---|---|
| Student | Search tutors by subject and city, explore nearby tutors on a map, save favourites, chat, and write reviews |
| Teacher | Build a teaching profile, set lesson fees and location, manage conversations, and view feedback |
| Admin | Review teacher applications, manage accounts and subjects, and publish announcements |
- Account registration and login with role-based access.
- Public tutor cards; login required for full tutor profiles and reviews.
- Teacher approval and public-profile settings control discovery.
- Private chat with saved history and live Socket.IO delivery.
- Notifications, profile editing, preferences, and password changes.
- Optional email password recovery and Cloudinary photo uploads.
| Layer | Tools |
|---|---|
| Frontend | React, Vite, React Router, Tailwind CSS, custom CSS, Leaflet |
| Backend | Node.js, Express, Mongoose, Socket.IO |
| Database | MongoDB |
| Authentication | JWT, bcrypt password hashing, role checks |
| Optional services | SMTP email, Cloudinary image storage |
| Checks | Node.js test runner, Supertest, Oxlint |
Use Node.js 22 or newer, npm, Git, and a running local MongoDB server. MongoDB Compass is optional for viewing data.
git clone https://github.com/qowais38/FindMyTutor.git
cd FindMyTutor
npm --prefix backend ci
npm --prefix frontend ciCopy backend/.env.example to backend/.env. In PowerShell:
Copy-Item backend/.env.example backend/.envThe template uses mongodb://127.0.0.1:27017/findmytutor. Generate a login secret:
node -e "console.log(require('node:crypto').randomBytes(48).toString('hex'))"Paste the generated value into JWT_SECRET in your private backend/.env. Then add starter subjects:
npm --prefix backend run seed-subjectsFrom the project root, use two terminals:
npm run backendnpm run frontend- Website: http://127.0.0.1:5173
- API health: http://127.0.0.1:5000/api/health
Register as a Student or Teacher through the website. Teachers complete their profile and wait for Admin approval before appearing in public tutor searches.
For the first Admin, set ADMIN_NAME, ADMIN_EMAIL, and ADMIN_PASSWORD in your private backend environment file, then run:
npm --prefix backend run create-adminRemove ADMIN_PASSWORD from the environment file after creation. Use the chosen email and password to log in. There are no shared default login credentials.
- SMTP settings are needed to send password-reset emails.
- Cloudinary settings are needed to upload profile photos.
- The frontend defaults to the local API. For a different backend address, use
frontend/.env.exampleas a template. - Private environment files are excluded from Git. Frontend Vite variables must never contain backend secrets.
- GitHub stores the source code; existing MongoDB accounts and messages need a separate database backup.
FindMyTutor/
frontend/
src/components/ Shared interface components and route guards
src/pages/workspace/ Student, Teacher, and Admin pages
src/context/ Account and workspace state
src/api/ API request helpers
tests/ Frontend API-client tests
backend/
routes/ API endpoints and request logic
models/ MongoDB schemas
middleware/ Authentication, permissions, and errors
scripts/ Admin creation and subject setup
tests/ Database and API integration tests
docs/ Backup and restore guide
The backend keeps request logic in route files to make the code easier to follow while learning.
With local MongoDB running:
npm run test:frontend
npm run test:backend
npm --prefix frontend run lint
npm --prefix frontend run buildThe backend tests use a separate temporary database. See the verification guide for test coverage and limitations.