{"id":25694502,"url":"https://github.com/SSWConsulting/CleanArchitectureV2","last_synced_at":"2025-02-25T00:01:47.291Z","repository":{"id":142331633,"uuid":"613110416","full_name":"SSWConsulting/SSW.CleanArchitecture","owner":"SSWConsulting","description":"v2 of the Clean Architecture approach","archived":false,"fork":false,"pushed_at":"2024-05-21T10:05:15.000Z","size":3602,"stargazers_count":81,"open_issues_count":79,"forks_count":14,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-05-22T08:35:52.149Z","etag":null,"topics":["clean-architecture","cqrs","dotnet","ef-core","minimal-api"],"latest_commit_sha":null,"homepage":"https://sswconsulting.github.io/SSW.CleanArchitecture/","language":"C#","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/SSWConsulting.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-12T22:33:45.000Z","updated_at":"2024-05-28T10:26:14.217Z","dependencies_parsed_at":null,"dependency_job_id":"f40a3308-51c0-432c-a1a4-3db15e3c975c","html_url":"https://github.com/SSWConsulting/SSW.CleanArchitecture","commit_stats":null,"previous_names":["sswconsulting/cleanarchitecturev2"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SSWConsulting%2FSSW.CleanArchitecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SSWConsulting%2FSSW.CleanArchitecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SSWConsulting%2FSSW.CleanArchitecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SSWConsulting%2FSSW.CleanArchitecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SSWConsulting","download_url":"https://codeload.github.com/SSWConsulting/SSW.CleanArchitecture/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240576456,"owners_count":19823293,"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","dotnet","ef-core","minimal-api"],"created_at":"2025-02-25T00:01:03.699Z","updated_at":"2025-02-25T00:01:47.267Z","avatar_url":"https://github.com/SSWConsulting.png","language":"C#","readme":"![SSW Banner](https://raw.githubusercontent.com/SSWConsulting/SSW.Rules.Content/main/_docs/images/ssw-banner.png)\n\n# SSW Clean Architecture Template\n\n\u003cdiv align=\"center\"\u003e\n\n[![SSW TV | YouTube](https://img.shields.io/youtube/channel/views/UCBFgwtV9lIIhvoNh0xoQ7Pg?label=SSW%20TV%20%7C%20Views\u0026style=social)](https://youtube.com/@SSWTV)\n\n[![Build and Test](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/build-and-test.yml)\n[![Code Scanning](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/codeql.yml/badge.svg)](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/codeql.yml)\n[![Package](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/package.yml/badge.svg)](https://github.com/SSWConsulting/SSW.CleanArchitecture/actions/workflows/package.yml)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/esta/issues)\n[![ADRs](https://sswconsulting.github.io/SSW.CleanArchitecture/badge.svg)](https://sswconsulting.github.io/SSW.CleanArchitecture/)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![SSW.CleanArchitecture Repo Analytics](https://repobeats.axiom.co/api/embed/3abf953e88642f725e44f5b300f6eddaf8fd9bee.svg \"SSW.CleanArchitecture Repo analytics\")\n\n\u003c/div\u003e\n\n\u003c!-- TOC --\u003e\n- [SSW Clean Architecture Template](#ssw-clean-architecture-template)\n    - [🤔 What is it?](#-what-is-it)\n    - [✨ Features](#-features)\n    - [🚀 Publishing Template](#-publishing-template)\n        - [Process](#process)\n    - [🎉 Getting Started](#-getting-started)\n\u003c!-- TOC --\u003e\n\n## 🤔 What is it?\n\nThis is a template for creating a new project using [Clean Architecture](https://ssw.com.au/rules/rules-to-better-clean-architecture/), leveraging [SSW Rules](https://ssw.com.au/rules) \u0026 SSW's over 30 years of experience developing software in the Microsoft space.\n\n## ✨ Features\n- 🔨 `dotnet new` cli template - to get you started quickly\n- 🚀 Aspire\n  - Dashboard\n  - Resource orchestration\n  - Observability\n  - Simple dev setup - automatic provisioning of database server, schema, and data\n- 🎯 Domain Driven Design Patterns\n  - [Super Hero Domain](./docs/domain.md)\n  - AggregateRoot\n  - Entity\n  - ValueObject\n  - DomainEvent\n- 🌐 Minimal Endpoints - because it's fast \u0026 simple. ⚡\n    - Extension methods to ensure consistent HTTP Verbs \u0026 Status Codes\n- 📝 OpenAPI/Scalar - easily document your API\n    - as per [ssw.com.au/rules/do-you-document-your-webapi/](https://ssw.com.au/rules/do-you-document-your-webapi/)\n- 🔑 Global Exception Handling - it's important to handle exceptions in a consistent way \u0026 protect sensitive information\n    - Transforms exceptions into a consistent format following the [RFC7231 memo](https://datatracker.ietf.org/doc/html/rfc7231#section-6.1)\n- 🗄️ Entity Framework Core - for data access\n    - Comes with Migrations \u0026 Data Seeding\n    - as per [ssw.com.au/rules/rules-to-better-entity-framework/](https://ssw.com.au/rules/rules-to-better-entity-framework/)\n- 🧩 Specification Pattern - abstract EF Core away from your business logic\n- 🔀 CQRS - for separation of concerns\n    - as per [ssw.com.au/rules/keep-business-logic-out-of-the-presentation-layer/](https://ssw.com.au/rules/keep-business-logic-out-of-the-presentation-layer/)\n- 📦 MediatR - for decoupling your application\n- 📦 ErrorOr - fluent result pattern (instead of exceptions)\n- 📦 FluentValidation - for validating requests\n    - as per [ssw.com.au/rules/use-fluent-validation/](https://ssw.com.au/rules/use-fluent-validation/)\n- 🆔 Strongly Typed IDs - to combat primitive obsession\n    - e.g. pass `CustomerId` type into methods instead of `int`, or `Guid`\n    - Entity Framework can automatically convert the int, Guid, nvarchar(..) to strongly typed ID.\n- 📁 Directory.Build.Props\n    - Consistent build configuration across all projects in the solution\n        - e.g. Treating Warnings as Errors for Release builds\n    - Custom per project\n        - e.g. for all test projects we can ensure that the exact same versions of common packages are referenced\n        - e.g. XUnit and NSubstitute packages for all test projects\n- ⚖️ EditorConfig - comes with the [SSW.EditorConfig](https://github.com/SSWConsulting/SSW.EditorConfig)\n    - Maintain consistent coding styles for individual developers or teams of developers working on the same project using different IDEs\n    - as per [ssw.com.au/rules/consistent-code-style/](https://ssw.com.au/rules/consistent-code-style/)\n\n- 🧪 Testing\n    - as per [ssw.com.au/rules/rules-to-better-testing/](https://www.ssw.com.au/rules/rules-to-better-testing/)\n    - Simpler Unit Tests for Application\n        - **No Entity Framework mocking required** thanks to **Specifications**\n        - as per [ssw.com.au/rules/rules-to-better-unit-tests/](https://www.ssw.com.au/rules/rules-to-better-unit-tests/)\n    - Better Integration Tests\n        - Using [Respawn](https://github.com/jbogard/Respawn) and [TestContainers](https://dotnet.testcontainers.org/)\n        - Integration Tests at Unit Test speed\n        - Test Commands and Queries against a Real database\n        - No Entity Framework mocking required\n        - No need for In-memory database provider\n\u003c!-- Commenting out pending #100     - Using [Wire-Mock](https://wiremock.org/) to mock out external services for controlled Integration Tests\n      - e.g. grab real request and responses from external system and then replaying them in the tests --\u003e\n- Architecture Tests\n    - Using [NetArchTest](https://github.com/BenMorris/NetArchTest)\n    - Know that the team is following the same Clean Architecture fundamentals\n    - The tests are automated so discovering the defects is fast\n\u003c!-- Commenting out pending #101  - Mutation Testing\n    - Test our tests!\n    - Helps discover the false-positives in our tests\n      - you will know when your tests pass when they should have failed\n    - Inserts bugs into the production code to make sure our tests are effective and testing the right behavior\n    - Using [Stryker Mutator](https://stryker-mutator.io/) --\u003e\n\n## 🎉 Getting Started\n\n### Prerequisites\n- [Docker](https://www.docker.com/get-started/) / [Podman](https://podman.io/get-started)\n- [Dotnet 9](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)\n\n### Installing the Template\n\n1. Install the SSW CA template\n\n```bash\ndotnet new install SSW.CleanArchitecture.Template\n```\n\n\u003e NOTE: The template only needs to be installed once. Running this command again will update your version of the template.\n\n2. Create a new directory\n\n```bash\nmkdir Northwind365\ncd Northwind365\n```\n\n3. Create a new solution\n\n```bash\ndotnet new ssw-ca\n```\n\n\u003e NOTE: `name` is optional; if you don't specify it, the directory name will be used as the solution name and project namespaces.\n\nAlternatively, you can specify the `name` and `output` directory as follows:\n\n```bash\ndotnet new ssw-ca --name {{SolutionName}} --output .\\\n```\n\n### Adding a Feature\n\n1. Create a query\n\n```bash\ncd src/Application/Features\nmkdir {{FeatureName}}\ncd {{FeatureName}}\ndotnet new ssw-ca-query --name {{QueryName}} --entityName {{Entity}} --slnName {{SolutionName}}\n```\n\n2. Create a command\n\n```bash\ncd src/Application/Features\nmkdir {{FeatureName}}\ncd {{FeatureName}}\ndotnet new ssw-ca-command --name {{CommandName}} --entityName {{Entity}} --slnName {{SolutionName}}\n```\n\n### Running the Solution\n\n1. Change directory\n\n    Windows:\n    ```ps\n    cd tools\\AppHost\\\n    ```\n\n    Mac/Linux:\n    ```bash\n    cd tools/AppHost/\n    ```\n\n2. Run the solution\n\n    ```bash\n    dotnet run\n    ```\n\n\u003e **NOTE:** The first time you run the solution, it may take a while to download the docker images, create the DB, and seed the data.\n\n4. Open https://localhost:7255/scalar/v1 in your browser to see it running ️🏃‍♂️\n\n## 🚀 Publishing Template\n\nTemplate will be published to NuGet.org when changes are made to `CleanArchitecture.nuspec` on the `main` branch.\n\n### Process\n\n1. Update the `version` attribute in `CleanArchitecture.nuspec`\n2. Merge your PR\n3. `package` GitHub Action will run and publish the new version to NuGet.org\n4. Create a GitHub release to document the changes\n\n\u003e **NOTE:** We are now using CalVer for versioning. The version number should be in the format `YYYY.M.D` (e.g. `2024.2.12`).\n\n\u003c!-- TODO Issue #99: Getting Started using the dotnet new template --\u003e\n\n## 🎓 Learn More\n\n### Training\n\nIf you're interested in learning more about Clean Architecture SSW offers two events:\n\n- [SSW 1-day Clean Architecture Superpowers Tour](https://www.ssw.com.au/events/clean-architecture-superpowers-tour)\n- [SSW 2-day Clean Architecture Workshop](https://www.ssw.com.au/events/clean-architecture-workshop)\n\n### Learning Resources\n\nYou're interested learning more about Clean Architecture, please see this excellent video by Matt Goldman:\n\n* [Clean Architecture with ASP.NET Core and MAUI](https://www.youtube.com/live/K9ryHflmQJE?si=VC2FtSZiAA3CxSsK)\n\nAlternatively, SSW has many great rules about Clean Architecture:\n\n* [SSW Rules - Clean Architecture](https://www.ssw.com.au/rules/rules-to-better-clean-architecture/)\n\nYou can also find a collection of commumity projects built on Clean Architecture here:\n\n* [Awesome Clean Architecture](https://github.com/SSWConsulting/awesome-clean-architecture)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome! See [Contributing](./CONTRIBUTING.md) for more information.\n","funding_links":[],"categories":["Templates"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSSWConsulting%2FCleanArchitectureV2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSSWConsulting%2FCleanArchitectureV2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSSWConsulting%2FCleanArchitectureV2/lists"}