{"id":27671718,"url":"https://github.com/VincentJouanne/nest-clean-architecture-ddd-example","last_synced_at":"2025-04-25T00:01:57.594Z","repository":{"id":43203311,"uuid":"374308646","full_name":"VincentJouanne/nest-clean-architecture","owner":"VincentJouanne","description":"🏛️   Nest.js clean architecture example following some DDD principles with use-cases written in functionnal programming.","archived":false,"fork":false,"pushed_at":"2023-07-28T13:01:23.000Z","size":1858,"stargazers_count":704,"open_issues_count":6,"forks_count":80,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-12T07:03:06.710Z","etag":null,"topics":["clean-architecture","cqrs","ddd","docker","end-to-end-testing","fp-ts","functional-programming","integration-testing","jest","microservices","nestjs","prisma","runtypes","tdd","typescript","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/VincentJouanne.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}},"created_at":"2021-06-06T08:36:31.000Z","updated_at":"2025-04-04T09:16:40.000Z","dependencies_parsed_at":"2024-04-09T09:31:50.663Z","dependency_job_id":null,"html_url":"https://github.com/VincentJouanne/nest-clean-architecture","commit_stats":null,"previous_names":["vincentjouanne/nest-clean-architecture-ddd-example"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VincentJouanne%2Fnest-clean-architecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VincentJouanne%2Fnest-clean-architecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VincentJouanne%2Fnest-clean-architecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VincentJouanne%2Fnest-clean-architecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VincentJouanne","download_url":"https://codeload.github.com/VincentJouanne/nest-clean-architecture/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250730364,"owners_count":21477754,"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":["clean-architecture","cqrs","ddd","docker","end-to-end-testing","fp-ts","functional-programming","integration-testing","jest","microservices","nestjs","prisma","runtypes","tdd","typescript","unit-testing"],"created_at":"2025-04-25T00:01:13.496Z","updated_at":"2025-04-25T00:01:57.557Z","avatar_url":"https://github.com/VincentJouanne.png","language":"TypeScript","funding_links":[],"categories":["Resources"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/juliandavidmr/awesome-nestjs)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n\u003c/div\u003e\n\n# Motivation\n\n\u003e FP and OO work nicely together. Both attributes are desirable as part of modern systems. A system that is built on both OO and FP principles will maximize flexibility, maintainability, testability, simplicity, and robustness. Excluding one in favor of the other can only weaken the structure of a system. - Uncle Bob.\n\nThis repository aims to provide to people an opinionated starter/example project to help them to architecture their next project.\n\nThe [Nest.js](https://nestjs.com/) framework has been chosen for its convenience as it provides out-of-the-box great solutions for modularity, dependency injection, publish-subscribe pattern, error handling, security etc.\n\nThis project uses OOP to handle modularity (modules instances) and on the other hand it uses the convenience of FP to write use-cases as smooth data flows while embracing eventual errors.\n\nFunctionnal Programming may look intimidating, if you are new to it, you should [read the most adequate guide](https://mostly-adequate.gitbook.io/mostly-adequate-guide/) to learn more about it.\n\n# Project Overview\n\n![Nest Clean Architecture](./docs/assets/nest-clean-architecture.png)\n\nClients interacts with the system through the [api-gateway](./api-gateway): the endpoints. The concerned module, executes the corresponding use-case which orchestrate the domain and perform I/O using its injected adapters.\n\nThe **domain modules** are tightly **concerned by the overall goal of the application**, while the **common modules** are **business-agnostic** and only serves as support to decouple logic and responsabilities in the entire system.\n\n# Getting started (1 min)\n\nMake sure to have docker installed, otherwise [install it here](https://docs.docker.com/get-docker/).\n\n1. Clone the project\n\n```\ngit clone https://github.com/VincentJouanne/nest-clean-architecture-ddd-example.git\n```\n\n2. Fetch dependencies\n\n```\ncd nest-clean-architecture-ddd-example \u0026\u0026 yarn install\n```\n\n3. Start the server\n\n```\nyarn start\n```\n\n4. Go to http://localhost:3000/api\n\n5. Run unit tests\n\n```\nyarn test:unit\n```\n\n6. Mount docker container\n\n```\nyarn docker:up\n```\n\n7. Run integration tests\n\n```\nyarn test:inte\n```\n\n8. Run e2e tests\n\n```\nyarn test:e2e\n```\n\n# Tests\n\n## Unit tests\n\nOne of the most controversial subject in Software development is **unit testing**.\n\nWhat and how should we test ?\n\nUnit test should **focus on the business value** of your application: the use-cases.\n\nThey have to be **really fast (\u003c x0 ms)** in order to iterate quickly on the algorithm we are working on.\n\nIn the outside world, we distinguish two approaches for unit testing: [the Classicist vs the Mockist](https://martinfowler.com/articles/mocksArentStubs.html).\n\nThis project uses the classicist approach in order to **focus on the result of the behavior of the use-cases and not on how the behavior has been implemented**: this leads to more meaningful tests, with a lighter syntax.\n\nSo, use-cases are black-boxed tested with fake secondaries adapters injected at the beginning of the test suite.\n\nI/O: A use-case.\n\n![Classicist unit testing](./docs/assets/unit-testing.png)\n\n## Integration tests\n\nIntegration tests focuses on **testing if tier services are well integrated** with our system.\n\nTo have relevant integration test, we want to create a testing environment as close as possible to a production one.\n\nFor example, to test a repository, we will have a local database and make access to it as we would do in production.\n\nThis kind of environment can be easily setup thanks to [docker containers](https://docs.docker.com/get-started/#what-is-a-container).\n\nThey are slower than unit tests since they need an heavier environement. They usually **takes up to \u003c x00 ms**.\n\nI/O: A real secondaries adapters.\n\n![Integration testing](./docs/assets/integration-testing.png)\n\n## End-to-end tests\n\nEnd-to-end tests focuses on testing a whole flow: one endpoint.\n\nThey use our use-cases and real adapters in order to check if the flow under test behave as expected.\n\nThey usually **takes up from \u003c x00 ms to \u003c x000 ms**.\n\nIt allows us to check if our endpoints are accessible from the outside world and what are their responses.\n\nThose tests also wants to reproduce as possible a production enviroment, so they use the real implementations.\n\nThe services that are too weird to keep in the test (mailing for example) will be doubled by a fake implementation.\n\nI/O: An endpoint.\n\n![E2E testing](./docs/assets/end-to-end-testing.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVincentJouanne%2Fnest-clean-architecture-ddd-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVincentJouanne%2Fnest-clean-architecture-ddd-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVincentJouanne%2Fnest-clean-architecture-ddd-example/lists"}