{"id":26758418,"url":"https://github.com/mahmoudelsayed7/plannify-backend","last_synced_at":"2025-03-28T16:19:35.758Z","repository":{"id":282980193,"uuid":"950289037","full_name":"MAHMOUDELSAYED7/Plannify-Backend","owner":"MAHMOUDELSAYED7","description":"A RESTful API built with Express.js and MongoDB for managing todos with secure user authentication, featuring email verification and password reset via OTP.","archived":false,"fork":false,"pushed_at":"2025-03-22T00:46:14.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T16:19:32.708Z","etag":null,"topics":["authentication","express-js","expressjs","javascript","js","jwt","jwt-auth","mongodb","mongoose","mvc","mvc-architecture","node-js","nodejs","rest-api","restful-api","swagger","swagger-ui","todo-app","todo-backend"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MAHMOUDELSAYED7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-17T23:42:08.000Z","updated_at":"2025-03-25T03:32:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"26beed04-adda-4b47-b279-64a4e9c742a6","html_url":"https://github.com/MAHMOUDELSAYED7/Plannify-Backend","commit_stats":null,"previous_names":["mahmoudelsayed7/plannify","mahmoudelsayed7/plannify-backend"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FPlannify-Backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FPlannify-Backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FPlannify-Backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FPlannify-Backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MAHMOUDELSAYED7","download_url":"https://codeload.github.com/MAHMOUDELSAYED7/Plannify-Backend/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246059301,"owners_count":20717085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","express-js","expressjs","javascript","js","jwt","jwt-auth","mongodb","mongoose","mvc","mvc-architecture","node-js","nodejs","rest-api","restful-api","swagger","swagger-ui","todo-app","todo-backend"],"created_at":"2025-03-28T16:19:34.792Z","updated_at":"2025-03-28T16:19:35.752Z","avatar_url":"https://github.com/MAHMOUDELSAYED7.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plainfy\n\nA RESTful API built with Express.js and MongoDB for managing todos with secure user authentication, featuring email verification and password reset via OTP.\n\n---\n\n## ✨ Features\n\n- **User Authentication**  \n   - ✅ Register with email verification (OTP sent via email)  \n   - ✅ Login with JWT token  \n   - ✅ Forgot/Reset password with OTP  \n   - ✅ Role-based access control (protected routes)  \n\n- **Todo Management**  \n   - ✅ Create, read, update, and delete todos  \n   - ✅ Priority levels (low, medium, high)  \n   - ✅ Custom color tagging and due dates  \n   - ✅ Filtering and sorting capabilities  \n\n---\n\n## 🛠️ Installation\n\n1. **Clone the repository**  \n    ```bash\n    git clone https://github.com/MAHMOUDELSAYED7/plainfy.git\n    cd plainfy\n    ```\n\n2. **Install dependencies**  \n    ```bash\n    npm i express mongoose bcryptjs jsonwebtoken nodemailer cors dotenv swagger-ui-express\n    ```\n\n3. **Environment Setup**  \n    Create a `.env` file with:  \n    ```env\n    PORT=your_port\n    MONGO_URI=your_mongo_uri\n    JWT_SECRET=your_ultra_secure_secret\n    EMAIL_USER=your.email@gmail.com\n    EMAIL_PASS=your_gmail_app_password\n    ```\n\n4. **Start the server**  \n    ```bash\n    npm start\n    ```\n\n---\n\n## 🔧 Environment Variables\n\n| Variable       | Required | Default   | Description                          |\n|----------------|----------|-----------|--------------------------------------|\n| `PORT`         | No       | -         | API server port                      |\n| `MONGO_URI`    | Yes      | -         | MongoDB connection string            |\n| `JWT_SECRET`   | Yes      | -         | Secret for signing JWT tokens        |\n| `EMAIL_USER`   | Yes      | -         | Gmail address for OTP delivery       |\n| `EMAIL_PASS`   | Yes      | -         | Gmail app password                   |\n\n---\n\n### 🔐 Authentication Routes\n\n| Endpoint                    | Method | Body Requirements          | Description                     |\n|-----------------------------|--------|----------------------------|---------------------------------|\n| `/api/auth/register`        | POST | `username, email, password`  | Register new user + send OTP    |\n| `/api/auth/verify-otp`      | POST | `email, otp`                 | Verify email address            |\n| `/api/auth/login`           | POST | `email, password`            | Get JWT token                   |\n| `/api/auth/forgot-password` | POST | `email`                      | Initiate password reset         |\n| `/api/auth/reset-password`  | POST | `email, otp, newPassword`    | Complete password reset         |\n\n### 📝 Todo Routes (Require JWT in Header)\n\n| Endpoint          | Method | Parameters           | Description                     |\n|-------------------|--------|----------------------|---------------------------------|\n| `/api/todo`       | POST   | `title` (required)   | Create new todo                 |\n| `/api/todo`       | GET    | -                    | Get all user's todos            |\n| `/api/todo/:id`   | PATCH  | `id` + update fields | Update specific todo            |\n| `/api/todo/:id`   | DELETE | `id`                 | Delete todo by ID               |\n\n**Sample Todo Creation Request:**\n```json\n      {\n            \"title\": \"Test New Deployment\",\n            \"description\": \"Perform end-to-end testing of the new deployment before it goes live.\",\n            \"priority\": \"medium\",\n            \"color\": \"#FFA500\",\n            \"completed\": false,\n            \"dueDate\": \"2025-03-25T02:05:24.425Z\",\n            \"id\": \"67dbb0d8393db0d93e837210\",\n            \"createdAt\": \"2025-03-20T06:08:24.425Z\"\n      }\n```\n\n---\n\n## 🗂️ Project Structure\n\n---\n\n```markdown\n\nplainfy/                       \n├── src/\n│   ├── controllers/                 # Business logic\n│   │   ├── authController.js\n│   │   └── todoController.js\n│   ├── docs/                        # API documentation\n│   │   └── swagger.json             # Swagger configuration\n│   ├── middleware/                  # Auth middleware\n│   │   └── auth.js\n│   ├── models/                      # MongoDB schemas\n│   │   ├── user.js\n│   │   └── todo.js\n│   ├── routes/                      # API endpoints\n│   │   ├── authRoutes.js\n│   │   └── todoRoutes.js\n│   └── app.js                       # Server configuration\n├── .env                             # Environment variables\n└── package.json                     # Dependency management\n\n```\n\n---\n\n## 📦 Dependencies\n\n| Package             | Purpose                          | npm Link                                                                 |\n|---------------------|----------------------------------|--------------------------------------------------------------------------|\n| **Express**         | Web framework                    | [express](https://www.npmjs.com/package/express)                         |\n| **Mongoose**        | MongoDB ORM                      | [mongoose](https://www.npmjs.com/package/mongoose)                       |\n| **BcryptJS**        | Password hashing                 | [bcryptjs](https://www.npmjs.com/package/bcryptjs)                       |\n| **JSONWebToken**    | Authentication tokens            | [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken)               |\n| **Nodemailer**      | Email delivery for OTP           | [nodemailer](https://www.npmjs.com/package/nodemailer)                   |\n| **CORS**            | Cross-origin resource sharing    | [cors](https://www.npmjs.com/package/cors)                               |\n| **Dotenv**          | Environment variable management  | [dotenv](https://www.npmjs.com/package/dotenv)                           |\n| **Swagger-UI-Express** | API documentation UI          | [swagger-ui-express](https://www.npmjs.com/package/swagger-ui-express)   |\n\n---\n\n## 📚 API Documentation\n\nThe API is fully documented using **Swagger (OpenAPI 3.0)**, providing an interactive and user-friendly way to explore and test all endpoints. Swagger documentation is automatically generated and can be accessed directly from the application.\n\n### Key Features of Swagger Documentation:\n- **Interactive UI**: Explore and test API endpoints directly in your browser.\n- **Detailed Endpoint Descriptions**: Each endpoint includes a description, required parameters, example requests, and possible responses.\n- **Schema Definitions**: Clear definitions of request and response models for easy integration.\n- **Authentication Support**: Test authenticated endpoints by providing a JWT token.\n- **Try-It-Out Functionality**: Execute API requests directly from the Swagger UI.\n\n\n### Accessing Swagger UI\nOnce the server is running, you can access the Swagger UI by navigating to:  \n`http://localhost:\u003cPORT\u003e/api-docs`\n\n\n### Using Swagger UI\n1. **Explore Endpoints**: Navigate through the API endpoints organized by tags (e.g., Authentication, Todos).\n2. **Test Endpoints**: Use the \"Try it out\" feature to execute requests directly from the UI.\n3. **View Responses**: See real-time responses, including status codes, headers, and body content.\n4. **Authentication**: Click the \"Authorize\" button and provide a valid JWT token to test protected routes.\n\n\n### Example Workflow in Swagger UI\n1. **Register a User**:\n   - Go to the `/api/auth/register` endpoint.\n   - Click \"Try it out\".\n   - Provide a sample request body:\n     ```json\n     {\n       \"username\": \"mahmoud\",\n       \"email\": \"mahmoudelsayed.dev@gmail.com\",\n       \"password\": \"securePassword123\"\n     }\n     ```\n   - Execute the request and observe the response.\n\n2. **Create a Todo**:\n   - Authorize using a valid JWT token.\n   - Go to the `/api/todo` endpoint.\n   - Provide a sample request body:\n     ```json\n      {\n            \"title\": \"Test New Deployment\",\n            \"description\": \"Perform end-to-end testing of the new deployment before it goes live.\",\n            \"priority\": \"medium\",\n            \"color\": \"#FFA500\",\n            \"completed\": false,\n            \"dueDate\": \"2025-03-25T02:05:24.425Z\",\n            \"id\": \"67dbb0d8393db0d93e837210\",\n            \"createdAt\": \"2025-03-20T06:08:24.425Z\"\n      }\n     ```\n   - Execute the request and observe the response.\n\n---\n\n## ⚠️ Important Notes\n\n1. **Email Configuration**  \n    - Requires a Gmail account with \"Less Secure Apps\" enabled or an app-specific password (if 2FA is enabled).  \n    - Update `EMAIL_USER` and `EMAIL_PASS` in `.env` for OTP delivery.  \n\n2. **Security**  \n    - Keep `.env` out of version control (add to `.gitignore`).  \n    - Use HTTPS and secure JWT secrets in production.  \n\n3. **Database**  \n    - Replace `MONGO_URI` with your MongoDB connection string (e.g., MongoDB Atlas for cloud hosting).  \n\n---\n\n## 📄 License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n---\n\n## Contact\n\nFor any questions or feedback, please reach out via email: [mahmoudelsayed.dev@gmail.com](mahmoudelsayed.dev@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelsayed7%2Fplannify-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahmoudelsayed7%2Fplannify-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelsayed7%2Fplannify-backend/lists"}