{"id":26222726,"url":"https://github.com/vyancharuk/nodejs-todo-api-boilerplate","last_synced_at":"2025-03-12T17:02:18.844Z","repository":{"id":198685959,"uuid":"259490827","full_name":"vyancharuk/nodejs-todo-api-boilerplate","owner":"vyancharuk","description":"A production-ready Node.js \u0026 TypeScript REST API template, with a focus on Clean Architecture to ensure scalability and maintainability","archived":false,"fork":false,"pushed_at":"2024-08-24T13:27:30.000Z","size":432,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-24T14:43:01.066Z","etag":null,"topics":["boilerplate","clean-architecture","docker","docker-compose","express-boilerplate","express-typescript-boilerplate","expressjs","inversifyjs","inversifyjs-examples","ioc","knexjs","modular-monolith","nodejs","postman","restful-api","supertest","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/vyancharuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2020-04-28T00:37:51.000Z","updated_at":"2024-08-24T13:27:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd0962f1-97b7-4298-b57f-6babfbf5b0fd","html_url":"https://github.com/vyancharuk/nodejs-todo-api-boilerplate","commit_stats":null,"previous_names":["vyancharuk/nodejs-todo-api-boilerplate"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyancharuk%2Fnodejs-todo-api-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyancharuk%2Fnodejs-todo-api-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyancharuk%2Fnodejs-todo-api-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vyancharuk%2Fnodejs-todo-api-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vyancharuk","download_url":"https://codeload.github.com/vyancharuk/nodejs-todo-api-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243258488,"owners_count":20262298,"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":["boilerplate","clean-architecture","docker","docker-compose","express-boilerplate","express-typescript-boilerplate","expressjs","inversifyjs","inversifyjs-examples","ioc","knexjs","modular-monolith","nodejs","postman","restful-api","supertest","typescript"],"created_at":"2025-03-12T17:02:17.714Z","updated_at":"2025-03-12T17:02:18.808Z","avatar_url":"https://github.com/vyancharuk.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 🛠️ LLM-Powered Node.js CRUD API template\n\n\u003cp align=\"center\"\u003e\n  \u003cimg height=\"300\" src=\"./llm-codegen/LLMCodegenLogo.png?raw=true\" alt=\"LLM-Powered Node.js CRUD API template\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n![node](https://img.shields.io/badge/node-v14.21.3--v20.15.1-brightgreen) ![npm](https://img.shields.io/badge/npm-v6.14.18-blue) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com/)\n\n## Description\nAn LLM-powered code generation tool that relies on the built-in [Node.js API Typescript Template Project](#nodejs-api-typescript-template-project) to easily generate clean, well-structured CRUD module code from text description.\n\n\n### Prerequisites\nBefore you proceed, verify that Node.js and npm are installed, and update your `.env` file with a valid LLM provider API key (e.g., `OPENAI_API_KEY`). You may choose from providers like OpenAI, Claude, DeepSeek, or OpenRouter/Llama.\n\n### How it works?\nIt orchestrates 3 LLM micro-agents (`Developer`, `Troubleshooter` and `TestsFixer`) to generate code, fix compilation errors, and ensure passing E2E tests. The process includes module code generation, DB migration creation, seeding data, and running tests to validate output. By cycling through these steps, it guarantees consistent and production-ready CRUD code aligned with vertical slicing architecture. It uses OpenAI/Anthropic/DeepSeek/Llama LLM API to perform code-generation\n\n### How to run?\nFirst, navigate to the root `./llm-codegen` folder and run `npm install` to install dependencies. Then execute `npm run start` and provide the requested module description when prompted. Finally, after the code generation finishes, review the output, and if the output meets your expectations, begin integrating it into your codebase\n\n\n![LLMCodegenDemo](./llm-codegen/LLMCodegenDemo.gif)\n\n---\n\n# Node.js API Typescript Template Project\n\n## Description\n\nThis project is a simple Node.js boilerplate using TypeScript and Docker. It demonstrates vertical slicing architecture for a REST API, as detailed here: [https://markhneedham.com/blog/2012/02/20/coding-packaging-by-vertical-slice/](https://markhneedham.com/blog/2012/02/20/coding-packaging-by-vertical-slice/). Unlike horizontal slicing (layered architecture), vertical slicing reduces the model code gap, making the modeled domain easier to understand. The implementation also follows the principles of Clean Architecture by Uncle Bob: [https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html).\n\nThe application provides APIs for users to get, create, update, and delete Todo (CRUD operations)\n\n## Features\n\n- Vertical slicing architecture based on **DDD \u0026 MVC** principles\n- Services input validation using **ZOD**\n- Decoupling application components through dependency injection using **InversifyJS**\n- Integration and E2E testing with **Supertest**\n- **Docker-compose** simplifies multi-service setup, running application, DB, and Redis in isolated docker containers easily\n- Simple DB transaction management with **Knex**\n- Multi-layer trace ID support for logging with **winston**\n- Support graceful shutdown for the **express.js** server\n- In-memory data storage and caching with **ioredis**\n- Auto-reload on save using **ts-node-dev**\n- Automated documentation generation with **TypeDoc**\n- Scheduled server-side cron jobs using **node-cron**\n- AWS S3 integration for file uploads using **aws-sdk**\n\n\n## Development\n\n### Before install\n\nPlease make sure that you have docker installed [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)\n\nHow to run locally (in dev mode):\n\n1. Copy `.env.sample` and rename it to `.env`, providing the appropriate environment variable values. Some of the variables are defined in the docker-compose file\n2. Install dependencies locally `npm i`\n3. Start the app using `npm run docker:run`\n4. By default, the API server is available at `http://localhost:8080/`\n\nMigrations and seed run automatically\n\nHow to run tests in separate docker containers locally:\n\n1. Install dependencies locally `npm i`\n2. Run API tests in separate docker containers `npm run docker:test`\n\nHow to run tests locally with a local SQLite DB:\n\n1. Install dependencies locally `npm i`\n2. Execute API tests using a local SQLite DB that stores data in a file: `npm run local:test`\n\n\n### Application structure\n\n```bash\ntodo-api\n├─ package.json\n├─ src\n│  ├─modules (domain components)\n│  │ ├─ todos\n│  │ │ ├─ tests\n│  │ │ ├─ repository\n│  │ │ ├─ routes\n│  │ │ ├─ controllers\n│  │ │ ├─ *.service (business logic implementation)\n│  ├─ users\n│  ├─ ...\n│  │\n├─ infra (generic cross-component functionality)\n│  ├─ data (migrations, seeds)\n│  ├─ integrations (services responsible for integrations with 3rd party services - belong to repository layer)\n│  ├─ loaders\n│  ├─ middlewares\n```\n\n\n## API Docs\nComprehensive API documentation is created directly from the source code using **TypeDoc**. To generate the documentation, run:\n\n1. Generate documentation: `npm run generate:docs`\n2. Serve documentation locally: `npm run serve:docs`\n\nAfter running these commands, the documentation will be accessible at [http://127.0.0.1:8081](http://127.0.0.1:8081).\n\nHere is Postman collection to work with API locally:\n\n[\u003cimg src=\"https://run.pstmn.io/button.svg\" alt=\"Run In Postman\" style=\"width: 128px; height: 32px;\"\u003e](https://app.getpostman.com/run-collection/429508-4b29a48c-b45d-4d09-912f-83090fd70b5e?action=collection%2Ffork\u0026source=rip_markdown\u0026collection-url=entityId%3D429508-4b29a48c-b45d-4d09-912f-83090fd70b5e%26entityType%3Dcollection%26workspaceId%3Dcb523e15-e316-4367-a52b-6caab455c64a)\n\n### API Endpoints\n\nList of available routes:\n\n**Auth routes**:\\\n`POST /api/signup` - register\\\n`POST /api/signin` - login\\\n`POST /api/jwt/refresh` - refresh auth token\\\n`POST /api/signout` - logout\n\n**User routes**:\\\n`GET /v1/users` - get all users (requires admin access rights)\\\n`GET /v1/users/me` - get current user\n\n**Todo routes**:\\\n`POST /api/todos` - create new todo\\\n`PUT /api/todos/:todoId` - update todo\\\n`GET /api/todos/:todoId` - get specific todo\\\n`GET /api/todos/my` - get all users' todos\\\n`DELETE /api/todos/:todoId` - delete user\\\n`GET /api/todos` - get all created todos (requires admin access rights)\n\n\n### Modules\n\nThe codebase is organized into modules, with each module representing either a use case (business logic) or an integration service (with a third-party service, e.g., AWS). Each module defines its dependencies using dependency injection and validates input parameters with ZOD.\n\n### Dependency injection\n\nTo easily manage dependencies and decouple parts of the application, the **InversifyJS** package is used. Each class or module can consume one of the registered dependencies via decorators. In the dependency container file located at `src/infra/loaders/diContainer.ts`, you can find each dependency and its corresponding imported module.\n\n### Logging and tracing\n\nThe application uses the `winston` logger for effective logging and implements cross-layer trace IDs in the winston wrapper output logic. As a result, logs related to the same request but from different layers (service, repository, controller) are outputted with the same trace ID without any extra implementation. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyancharuk%2Fnodejs-todo-api-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvyancharuk%2Fnodejs-todo-api-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvyancharuk%2Fnodejs-todo-api-boilerplate/lists"}