{"id":28957644,"url":"https://github.com/magdi14/zeff","last_synced_at":"2025-06-23T22:04:00.180Z","repository":{"id":57405394,"uuid":"247127196","full_name":"magdi14/Zeff","owner":"magdi14","description":"A simple structure for MVC with node.js, it makes building REST API's very easy for those guys who have experience in Laravel/Lumen projects structure.","archived":false,"fork":false,"pushed_at":"2025-02-17T18:17:31.000Z","size":127,"stargazers_count":12,"open_issues_count":6,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-23T22:02:15.006Z","etag":null,"topics":["api","express-js","mongodb","mongoose","mvc-framework","nodejs","rest-api","restful-api","restful-webservices"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magdi14.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2020-03-13T17:31:05.000Z","updated_at":"2025-02-17T18:16:24.000Z","dependencies_parsed_at":"2023-12-24T22:22:13.215Z","dependency_job_id":"a02c968a-c9fe-43e8-a8ec-f40338a394c3","html_url":"https://github.com/magdi14/Zeff","commit_stats":{"total_commits":44,"total_committers":4,"mean_commits":11.0,"dds":"0.11363636363636365","last_synced_commit":"03053053d3b3510fd09df2ef4d6027864a898bce"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/magdi14/Zeff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magdi14%2FZeff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magdi14%2FZeff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magdi14%2FZeff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magdi14%2FZeff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magdi14","download_url":"https://codeload.github.com/magdi14/Zeff/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magdi14%2FZeff/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261565320,"owners_count":23177749,"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":["api","express-js","mongodb","mongoose","mvc-framework","nodejs","rest-api","restful-api","restful-webservices"],"created_at":"2025-06-23T22:01:40.726Z","updated_at":"2025-06-23T22:04:00.169Z","avatar_url":"https://github.com/magdi14.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://bit.ly/3aregLh\" width=\"200\" height=\"200\"\u003e\n\n\nA simple MVC structure with node.js, it makes building RESTful API's very handy for those guys who have experience in Laravel/Lumen projects structure. also it prevents the developer from writing an unreadable, unstructured, difficult-to-maintain source code `spaghetti-code` which's a problem i faced when i first started coding with node.js. and it's a good template for a quick start of personal projects.\n\n## Getting Started\nYou can start using zeff structure via multiple ways:\n* You can clone or download the repo from [here](https://github.com/magdi14/Zeff.git).\n``\nOR\n``\n* You can install it from the install command provided in node package manager npm.\n```\nnpm install zeff.js\n```\nOR\n```\nyarn add zeff.js\n```\nOf course you'll see that it's initially install dependencies needed like:\n* [express](https://expressjs.com/) `pkg`\n* [mongoose](https://mongoosejs.com/) `pkg` \n* [body-parser](https://www.npmjs.com/package/body-parser) `pkg` \n* [dotenv](https://www.npmjs.com/package/dotenv) `pkg`.\n```\nOR\n```\n* run ```npm init``` and install all of these packages manually via ```npm install [package_name]```\n### Prerequisites\n* First of all you'll need [node.js](https://nodejs.org/en/download/) installed and running on your machine.\n* Also [MongoDB](https://www.mongodb.com/download-center/community) with its default installation.\nSee this [tutorial](https://www.youtube.com/watch?v=FwMwO8pXfq0) for setting up mongodb on windows 10.\n\nProject Structure Conventions\n============================\n\u003e Folders structure options and naming conventions for `zeff`\n### A typical top-level directory layout\n    .\n    ├── ...\n    ├── app                                 # app folder (the `main` folder).\n    │   ├── controllers                     # has all the controllers file needed to each module\n    │   │     ├── UsersController.js        # an example of controller file.\n    │   │     ├── ...                       # ..\n    │   │     └── ...                       # ..\n    │   │\n    │   └── helpers                         # herlper folder with all the helper function needed.     \n    │       └── helpers.js                  # has tha implementation of helper functions. \n    ├── bootstrap                           # the bootstrap folder that have the app.js file.\n    │   └── app.js                          # app file that bootsraping all the needed packages and seting up environment in the app.\n    │\n    ├── config                              # configration files (`auth`, `permission`, `jwt`, etc ..).\n    │   └── e.g: auth.js                    # auth files.\n    │\n    ├── database                            # the folder that hs all the needed actions dealing with the db.\n    │    ├── models                         # the folder has the schemas definations for app modules.\n    │    │     ├── User.js                  # example of user defined schema.\n    │    │     └── ...\n    │    └── db.js                          # here's the most important file that initiate the connection to your db.\n    │    \n    ├── public                              # has the main file of the app and the uploads folder that have media of your app.\n    │   ├── uploads                         # the folder with all media that app contains.\n    │   └── server.js                       # the entry point of your application.\n    │\n    ├── resourses                           # this will have your views of your app.\n    │   └── views                           # a folder that has all the views needed for the app.\n    │          ├── view#1\n    │          └── ...\n    │\n    ├── routes                              # folder that has all routes in your app.\n    │   └── router.js                       # here you can define the routes and endpoints for the modules you've created.\n    │\n    ├── .env_example                        # file that has all the configrations keys of your app like db_name, db_user, your main port ..\n    │\n    ├── package.json                        # file of all your app info and dependencies.\n    │\n    └── ...\n    \nDocumentation\n=============\n## 1- Models\nHere in `mongo` we need to define schemas for our models, and the package we use ``mongoose`` has a very good `docs` provided [here](https://mongoosejs.com/docs/guide.html).\n* First we define the schema with all the properties we want e.g: name, email, etc ...\n```node\nconst mongoose = require(\"mongoose\")\nconst Schema = mongoose.Schema;  // make instance from mongoose schema\n\nconst user = new Schema({\n  name: String,\n  email: { type: String, unique: true }, //specifying email as unique\n  password: String,\n})\n```\n* The the most important part is to export the model with the defined schema as follows:\n```node\nmodule.exports = mongoose.model(\"User\", user)\n```\nHere the first argument model takes is the name of the model you want, and the second is the schema you've defined.\n### - NOTES\n   * When you insert a new document to the collection the `_id` generated automaticlly by mongoose.\n   * mongoose defines `_id` by default with type `ObjectId` for the collection, but you have the ability to overwrite that but it's not         recommended.\n   * Also if you want to create a `ref` to another collection which called in relational dbs Relations the `_id` should be of type               `ObjectID`.\n   * Visit mongoose [documentations](https://mongoosejs.com/docs/guides.html) for more of definnig schemas, documents, quiries ..\n## 2- Controllers\n* So Controllers is the part which's responsible for do all the logic between the view and the model, it has the CRUD operations and any other logic you want to add, then returns a response to the user even if it's a view `HTML-Files` or a JSON with the data needed which's we concern here.\n* First Thing you want to ``require`` your model you've been created in the models folder to deal with the collection -table- in db.\n\u003e Notice that the collection won't appear in the db you created till you insert a document.\n* Then You will need to export the methods as follows:\n```node\nmodule.exports = {\n     index: (req, res){\n            // Get all docs from your collection\n     },\n     show: (req, res){\n            // TODO\n     },\n     store: (req, res){\n            // TODO\n     },\n     ...   \n}\n```\n\u003e Future Work: Enhance the controller structure with ES6 classes.\n## 3- Routing\nYou will define most of the routes for your application in the `routes/router.js` file, which is loaded by the `app.js` file located in bootstrap. here we're using express.router class to create modular, mountable route handlers.\n```node\nconst express = require(\"express\")\nconst router = express.Router()\n```\nThen require the controller you want to add its routes here as follows: \n```node\nconst usersCtrl = require(\"../app/controllers/UsersController\")\n```\nNow we're able to defines URI's for this controller doing the logic we have defined.\n```node\n//template\nrouter.route(\"{URI}\").{request_type}({controller.method})\n\n//Here's an example of the users endpoints.\nrouter.route(\"/users\").get(usersCtrl.index)\nrouter.route(\"/permissions\").post(permissionsCtrl.store)\n...\n\nmodule.exports = router\n```\n\u003e it's not mandatory you can use any structure of defining routes for the application but make sure that you export it and use while app's bootstraping in `app.js` \n\n## 4- Starting the server\n* As we see the start point of the application is in public folder so to start serving you need to make sure the start script in `package.json` is as ``node ./public/server.js``\n* if you'll use `nodemon` which is i recommend also you'll need to make sure of the start script also.\n* By defining app from bootstrap file we're making an instance of our application and it'll be ready to listen on the port you defined in `.env` file\n```node\nconst app = require('../bootstrap/app')\n\napp.listen(process.env.APP_PORT, function(){\n    console.log(\"Listening on Port \" + process.env.APP_PORT)\n});\n```\n\u003e NOTE: if you want to import any of the npm packages you'll need to import it in bootstrap file `app`.\n\n## Adds On\n* There's some additional files and features come with the installation i added for mapping between admins, roles and permissions feel free to ignore them and add your favourite structure or style.\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on code of conduct.\n## License\nsee the [MIT](LICENSE) license file for details.\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagdi14%2Fzeff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagdi14%2Fzeff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagdi14%2Fzeff/lists"}