From 6121dc2a4f70696f84bbfd9dd11ab49838cff46d Mon Sep 17 00:00:00 2001 From: Sivamoorthyp Date: Sat, 14 Nov 2026 15:58:55 +0530 Subject: [PATCH] docs: correct setup and API documentation --- API_DOCUMENTATION.md | 62 +++++++++++-- README.md | 210 +++++++++++++++---------------------------- backend/.env.example | 4 +- 3 files changed, 129 insertions(+), 147 deletions(-) diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md index 94889754..27cfa1f1 100644 --- a/API_DOCUMENTATION.md +++ b/API_DOCUMENTATION.md @@ -4,7 +4,7 @@ This guide documents the backend API endpoints for PrepPilot. It includes endpoint paths, request and response examples, authentication requirements, and error cases. -> **Ground truth:** Route registration in `backend/server.js` is the authoritative source for all paths and prefixes. Run `node scripts/check-routes.js` to verify this document stays in sync. +> **Ground truth:** Route registration in `backend/server.js` and the mounted route modules are authoritative for all paths and prefixes. --- @@ -25,9 +25,14 @@ Authorization: Bearer | Limiter | Applied to | Window | Max requests | |---|---|---|---| -| `authLimiter` | `/api/auth/register`, `/api/auth/login` | 15 min | 50 | -| `aiLimiter` | `/api/generate`, `/api/ai/generate`, `/api/resume/compile`, `/api/resume/analyze` | 1 hour | 20 | -| `generalLimiter` | All other routes | 15 min | 100 | +| `loginLimiter` | `POST /api/auth/login` | 15 min | 10 per IP | +| `authLimiter` | Auth register, refresh, logout, resend-verification, and verify-email routes | 15 min | 50 per IP | +| `aiLimiter` | AI generation/solve and resume compile/analyze routes | 1 hour | 20 per IP | +| `aiUserLimiter` | `/api/generate`, `/api/ai/generate`, and `/api/solve` | 1 hour | 20 per authenticated user | +| `generalLimiter` | Routes where this middleware is explicitly applied | 15 min | 100 per IP | +| `sensitiveAuthLimiter` | Password change and account deletion | 15 min | 10 per IP | + +`GET /api/test` is not rate-limited. Routes may have more than one limiter. --- @@ -77,7 +82,7 @@ Errors: ### Login User - `POST /api/auth/login` -- Public (rate-limited: 50 req / 15 min per IP) +- Public (rate-limited: 10 req / 15 min per IP) Request Body: @@ -267,9 +272,7 @@ Errors: ### Upload Profile Image - `POST /api/auth/upload-image` -- Public — no authentication or rate limiter applied - -> ⚠️ **Note for contributors:** This endpoint has no `protect` guard and no rate limiter. See [issue #128](https://github.com/Canopus-Labs/PrepPilot/issues/128) for the tracked remediation. Do not add features that depend on `req.user` in this handler until auth is added. +- Private (requires authentication; rate-limited: 100 req / 15 min per IP) Form field: @@ -294,7 +297,7 @@ Errors: ### Generate AI Text - `POST /api/ai/generate` -- Public (rate-limited: 20 req / hour per IP) +- Private (requires authentication; rate-limited: 20 req / hour per IP and per user) > ⚠️ **Note:** The path is `/api/ai/generate`. An alias `/api/generate` also exists (same handler, same rate limit). Both are registered via `app.use("/api", aiRoutes)` in `server.js`. Prefer `/api/ai/generate` for clarity. @@ -1151,6 +1154,47 @@ Response `200`: --- +## Other Registered Routes + +These routes are registered by `backend/server.js` and are not covered by the +request/response examples above: + +- Auth lifecycle: `GET /api/auth/csrf-token`, `POST /api/auth/refresh`, + `POST /api/auth/logout`, `POST /api/auth/resend-verification`, and + `GET /api/auth/verify-email`. +- AI problem solving: `POST /api/solve`. +- Questions: `GET /api/question/my-questions` and + `POST /api/question/study-plan`. +- Aptitude questions: `GET /api/questions/`. +- Sheets: `GET /api/sheets/` and `GET /api/sheets/:id`; + `POST /api/sheets/upload` and `POST /api/sheets/validate`; + `PUT /api/sheets/:id` and `DELETE /api/sheets/:id`. +- Sheet progress: `GET /api/user/sheet-progress/export`, + `POST /api/user/sheet-progress/import`, and + `DELETE /api/user/sheet-progress/:sheetId`. +- Courses and jobs: `GET /api/courses/` and `GET /api/jobs/`. +- Google Calendar: `GET /api/google-calendar/connect`, + `GET /api/google-calendar/callback`, `GET /api/google-calendar/status`, and + `POST /api/google-calendar/events`. +- Interview experiences: `GET /api/interview-experiences/approved`, + `GET /api/interview-experiences/mine`, + `POST /api/interview-experiences/`, and + `PATCH /api/interview-experiences/:id/status`. +- Notes summaries: `POST /api/notes-summary/summarize`, + `POST /api/notes-summary/save`, `GET /api/notes-summary/my-summaries`, and + `DELETE /api/notes-summary/:id`. +- Roadmaps: `POST /api/roadmaps/`, `GET /api/roadmaps/`, + `GET /api/roadmaps/:id`, `PUT /api/roadmaps/:id`, + `PATCH /api/roadmaps/:id/tasks`, and `DELETE /api/roadmaps/:id`. +- Resume analysis history and matching: `GET /api/resume/analysis-history` + and `POST /api/resume/ats-match`; saved resume deletion uses + `DELETE /api/resume/:id`. +- Achievements: `GET /api/user/achievements` and + `POST /api/user/achievements`. + +Sheet read routes are public; sheet write routes require an authenticated +administrator. The jobs endpoint requires authentication. + ## Testing Endpoint ### Health Check diff --git a/README.md b/README.md index a5e9b015..f48d65a5 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ - [⚡ Quick Start Guide](#-quick-start-guide) - [📁 Project Structure](#-project-structure) - [🤝 Contributing Guidelines](#-contributing-guidelines) -- [� Troubleshooting & FAQs](#-troubleshooting--faqs) +- [🔧 Troubleshooting & FAQs](#-troubleshooting--faqs) - [📖 API Documentation](#-api-documentation) - [🚀 Deployment Guide](#-deployment-guide) - [📄 License](#-license) @@ -116,8 +116,8 @@ Nodemon Auto-reload during development Before getting started, ensure you have the following installed: -- **Node.js** (v16 or higher) - [Download](https://nodejs.org/) -- **npm** or **yarn** (v7 or higher) +- **Node.js** (v20.19+ or v22.12+) - [Download](https://nodejs.org/) +- **npm** (included with Node.js) - **MongoDB** instance (Local or [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) - Free tier available) - **Google Gemini API Key** - Get it free at [Google AI Studio](https://aistudio.google.com/app/apikey) @@ -162,7 +162,7 @@ JWT_SECRET=your_super_secret_jwt_key_here_generate_a_strong_one # Google Gemini API GEMINI_API_KEY=your_gemini_api_key_from_ai_studio -GEMINI_MODEL=gemini-1.5-flash +GEMINI_MODEL=gemini-2.5-flash # Server Configuration PORT=8000 @@ -171,9 +171,7 @@ NODE_ENV=development # Frontend Origin (for CORS) FRONTEND_ORIGIN=http://localhost:5173 -# Optional: Additional configurations -RATE_LIMIT_WINDOW_MS=15000000 -RATE_LIMIT_MAX_REQUESTS=100 +# Rate limits are configured in backend/middlewares/rateLimiter.js. ``` #### 5️⃣ Start Development Servers @@ -224,16 +222,25 @@ PrepPilot/ │ │ ├── questionController.js # Question management │ │ ├── resumeController.js # Resume operations │ │ ├── sessionController.js # Session management -│ │ └── userSheetProgressController.js # Progress tracking -| | -│ ├── 📂 Input_Validators/ # Extract the logic for Input validations -│ │ ├── ValidateAchievement.js # Validate and check input for Achievement Controller -│ │ ├── ValidateAi.js # Validate and check input for Ai/Gemini Controller -│ │ ├── ValidateAuth.js # Validate and check input for Authentication Controller -│ │ ├── ValidateQuestions.js # Validate and check input for Question Management Controller -│ │ ├── ValidateResume.js # Validate and check input for Resume Controller -│ │ ├── ValidateSession.js # Validate and check input for Session Controller Controller -│ │ └── ValidateUserSheetProgess.js # Validate and check input for UserSheetProgress Controller +│ │ ├── userSheetProgressController.js # Progress tracking +│ │ ├── adaptiveInterviewController.js +│ │ ├── flashcardController.js +│ │ ├── interviewExperienceController.js +│ │ ├── notesSummaryController.js +│ │ └── roadmapController.js +│ │ +│ ├── 📂 Input_validators/ # Request input validation +│ │ ├── ValidateAchievement.js +│ │ ├── ValidateAi.js +│ │ ├── ValidateAuth.js +│ │ ├── ValidateFlashcard.js +│ │ ├── ValidateInterviewExperience.js +│ │ ├── ValidateNotesSummary.js +│ │ ├── ValidateQuestions.js +│ │ ├── ValidateResume.js +│ │ ├── ValidateRoadmap.js +│ │ ├── ValidateSession.js +│ │ └── ValidateUserSheetProgress.js │ │ │ ├── 📂 middlewares/ # Express middlewares │ │ ├── authMiddleware.js # JWT verification @@ -244,8 +251,14 @@ PrepPilot/ │ │ │ ├── 📂 models/ # MongoDB Mongoose schemas │ │ ├── User.js # User profile & credentials +│ │ ├── AdaptiveInterviewSession.js +│ │ ├── Flashcard.js +│ │ ├── InterviewExperience.js +│ │ ├── JobCache.js +│ │ ├── NotesSummary.js │ │ ├── Question.js # Interview questions │ │ ├── Resume.js # Resume documents +│ │ ├── RoadmapProject.js │ │ ├── Session.js # Practice sessions │ │ ├── Sheet.js # Question sheets (DSA, etc.) │ │ ├── Book.js # Reference books @@ -259,6 +272,15 @@ PrepPilot/ │ │ ├── sessionRoutes.js # Session endpoints │ │ ├── booksRoutes.js # Books endpoints │ │ ├── AptitudeQuestions.js # Aptitude test endpoints +│ │ ├── adaptiveInterviewRoutes.js +│ │ ├── achievementRoutes.js +│ │ ├── coursesRoutes.js +│ │ ├── flashcardRoutes.js +│ │ ├── googleCalendarRoutes.js +│ │ ├── interviewExperienceRoutes.js +│ │ ├── jobRoutes.js +│ │ ├── notesSummaryRoutes.js +│ │ ├── roadmapRoutes.js │ │ ├── sheetJsonUpload.js # Sheet upload │ │ └── userSheetProgressRoutes.js# Progress endpoints │ │ @@ -349,9 +371,22 @@ PrepPilot/ │ ├── package.json │ └── index.html │ -├── .gitignore # Git ignore rules +├── .github/ # Issue, PR, and workflow templates +├── .gitignore +├── .mavis/ # Generated run report +├── .prettierrc # Formatting configuration +├── API_DOCUMENTATION.md # Backend API reference +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md +├── docker-compose.yml # Local development stack ├── LICENSE # MIT License -└── README.md # This file +├── m.txt +├── orchestrate.py +├── package-lock.json +├── package.json +├── README.md # This file +├── render.yaml # Render static-site configuration +└── TROUBLESHOOT.md ``` ## 🤝 Contributing Guidelines @@ -364,7 +399,7 @@ We love contributions from the community! PrepPilot is better because of talente ```bash # Fork via GitHub UI, then: - git clone https://github.com/YOUR_USERNAME/PrepPilot.git + git clone https://github.com/Canopus-Labs/PrepPilot.git cd PrepPilot ``` @@ -490,7 +525,7 @@ throw new Error("User not found with the provided email"); - 📧 Contact maintainers for sensitive issues - 🤖 Check our FAQ section (coming soon) -## � Troubleshooting & FAQs +## 🔧 Troubleshooting & FAQs ### Common Issues & Solutions @@ -507,7 +542,12 @@ throw new Error("User not found with the provided email"); --- -## Flashcard (Spaced Repetition System) Routes +## 📖 API Documentation + +For complete endpoint paths, request/response examples, authentication, and +rate limits, see [API_DOCUMENTATION.md](./API_DOCUMENTATION.md). + +### Flashcard (Spaced Repetition System) Routes ### Create / Add Flashcard - `POST /api/flashcards` @@ -628,8 +668,6 @@ Response `200`: --- -## Testing Endpoint - ### Health Check - `GET /api/test` - Public @@ -641,109 +679,22 @@ Response `200`: } ``` -### Getting Help - -```bash -# Check Node version -node --version - -# Check npm version -npm --version - -# Test MongoDB connection -mongosh "your_connection_string" - -# View backend logs -npm run dev # Shows server logs - -# Clear npm cache if installation fails -npm cache clean --force -npm install -``` - -## 📖 API Documentation - -### Authentication Endpoints - -``` -POST /api/auth/register - Register new user -POST /api/auth/login - Login user -POST /api/auth/logout - Logout user -GET /api/auth/profile - Get user profile -PUT /api/auth/profile - Update user profile -``` - -### AI Endpoints - -``` -POST /api/ai/generate - Generate interview questions -POST /api/ai/explain - Get detailed explanations -POST /api/ai/evaluate - Evaluate user answer -``` - -### Question Endpoints - -``` -POST /api/question/add - Add questions to a session -POST /api/question/:id/pin - Pin or unpin a question -POST /api/question/:id/note - Update note for a question -``` - -### Resume Endpoints - -``` -GET /api/resume - Get user resumes -POST /api/resume - Create resume -PUT /api/resume/:id - Update resume -DELETE /api/resume/:id - Delete resume -``` - -For detailed API documentation, see [API.md](./API.md) (if available) - ## 🚀 Deployment Guide -### Deploy Backend to Heroku - -```bash -# Install Heroku CLI -npm install -g heroku - -# Login to Heroku -heroku login +The checked-in [Render configuration](./render.yaml) deploys the frontend as a +static site. It does not configure a backend service; deploy the backend +separately and set its environment variables and frontend origin for your +hosting environment. -# Create new app -heroku create your-app-name - -# Set environment variables -heroku config:set MONGO_URI=your_mongodb_url -heroku config:set JWT_SECRET=your_jwt_secret -heroku config:set GEMINI_API_KEY=your_api_key - -# Deploy -git push heroku main -``` - -### Deploy Frontend to Vercel +For local development with MongoDB, the frontend, and backend in containers, +run the repository's [Docker Compose configuration](./docker-compose.yml): ```bash -# Install Vercel CLI -npm install -g vercel - -# Deploy -vercel +docker compose up --build ``` -### Deploy with Docker - -```bash -# Build and push to Docker Hub -docker build -t username/preppilot:latest . -docker push username/preppilot:latest - -# Pull and run on server -docker pull username/preppilot:latest -docker run -p 8000:8000 --env-file .env username/preppilot:latest -``` +The Compose file and per-service Dockerfiles use development servers and are +intended for local development, not as production deployment instructions. ## 📄 License @@ -787,7 +738,7 @@ This project stands on the shoulders of amazing open-source projects and communi ### 📖 Resources Used -- [DSA Resources](https://github.com/striver79/striver-sde-sheet) - Striver's SDE Sheet +- [DSA Resources](https://takeuforward.org/prep-hub/strivers-180-master-dsa-patterns) - Striver's SDE Sheet - [NeetCode](https://neetcode.io/) - Curated DSA problems - [GeeksforGeeks](https://www.geeksforgeeks.org/) - Educational content @@ -804,7 +755,6 @@ This project stands on the shoulders of amazing open-source projects and communi ### 🌟 Planned Features - [ ] Multi-language support -- [ ] Spaced repetition system - [ ] Integration with LeetCode - [ ] Machine learning-based recommendations - [ ] Interview experience matching @@ -832,11 +782,7 @@ We owe a huge thank you to the brilliant individuals who help build, refine, and ### Get Connected -- 💌 **Email**: contact@preppilot.com -- 🐦 **Twitter**: [@PrepPilot](https://twitter.com/preppilot) -- 💻 **GitHub Issues**: [Report bugs here](https://github.com/yourusername/PrepPilot/issues) -- 💬 **Discussions**: [Ask questions here](https://github.com/yourusername/PrepPilot/discussions) -- 🤝 **Discord**: [Join our community](https://discord.gg/preppilot) +- 💻 **GitHub Issues**: [Report a bug or request a feature](https://github.com/Canopus-Labs/PrepPilot/issues) ### Support This Project @@ -855,9 +801,7 @@ If PrepPilot helped you land that dream job or ace your interview, consider: ## 💖 Built with passion by developers, for developers -[![GitHub followers](https://img.shields.io/github/followers/karanunix?style=social&label=Follow)](https://github.com/karanunix) -[![GitHub stars](https://img.shields.io/github/stars/YOURUSERNAME/PrepPilot?style=social&label=Star)](https://github.com/Canopus-Labs/PrepPilot) -[![Twitter Follow](https://img.shields.io/twitter/follow/PrepPilot?style=social)](https://twitter.com/PrepPilot) +[![GitHub stars](https://img.shields.io/github/stars/Canopus-Labs/PrepPilot?style=social&label=Star)](https://github.com/Canopus-Labs/PrepPilot) ### Made with ❤️ for the tech community @@ -868,9 +812,3 @@ If PrepPilot helped you land that dream job or ace your interview, consider: ### ⭐ If this project helped you, please give it a star! Your support means everything! 🌟 - -## 🤝 Contributing - -We welcome contributions from the community! - -Please read the [Contributing Guidelines](./CONTRIBUTING.md) before submitting a Pull Request. \ No newline at end of file diff --git a/backend/.env.example b/backend/.env.example index 7755544f..28c7bee9 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -39,8 +39,8 @@ ADMIN_EMAILS= # Google Gemini AI Configuration # Get your API key from: https://makersuite.google.com/app/apikey GEMINI_API_KEY=your_gemini_api_key_here -# Gemini model to use (defaults to gemini-1.5-flash-latest if unset) -GEMINI_MODEL=gemini-1.5-flash-latest +# Optional preferred Gemini model; if unset, the backend tries gemini-2.5-flash first. +GEMINI_MODEL=gemini-2.5-flash # GitHub Configuration # Personal access token for fetching book data from GitHub