{"id":18784061,"url":"https://github.com/melzar/clean-architecture-nextjs-react-boilerplate","last_synced_at":"2025-09-13T08:45:29.111Z","repository":{"id":220019995,"uuid":"711339395","full_name":"Melzar/clean-architecture-nextjs-react-boilerplate","owner":"Melzar","description":"Next.js Clean Architecture boilerplate with Typescript","archived":false,"fork":false,"pushed_at":"2024-04-06T17:15:46.000Z","size":2131,"stargazers_count":68,"open_issues_count":0,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-03T05:41:16.599Z","etag":null,"topics":["architecture","boilerplate","clean-architecture","docker","frontend","jest","mockoon","next-auth","nextjs","reactjs","rest","solid","stryker","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/Melzar.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}},"created_at":"2023-10-29T00:06:09.000Z","updated_at":"2025-04-01T13:00:53.000Z","dependencies_parsed_at":"2024-01-30T23:02:16.887Z","dependency_job_id":"9b8a35ae-6a20-4d95-8d02-a3583073f622","html_url":"https://github.com/Melzar/clean-architecture-nextjs-react-boilerplate","commit_stats":null,"previous_names":["melzar/clean-architecture-nextjs-react-boilerplate"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Melzar/clean-architecture-nextjs-react-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Melzar%2Fclean-architecture-nextjs-react-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Melzar%2Fclean-architecture-nextjs-react-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Melzar%2Fclean-architecture-nextjs-react-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Melzar%2Fclean-architecture-nextjs-react-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Melzar","download_url":"https://codeload.github.com/Melzar/clean-architecture-nextjs-react-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Melzar%2Fclean-architecture-nextjs-react-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273218428,"owners_count":25065913,"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","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["architecture","boilerplate","clean-architecture","docker","frontend","jest","mockoon","next-auth","nextjs","reactjs","rest","solid","stryker","typescript"],"created_at":"2024-11-07T20:41:47.857Z","updated_at":"2025-09-02T01:32:24.185Z","avatar_url":"https://github.com/Melzar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clean Architecture Next.js Boilerplate\n\n### DESCRIPTION\n\nThis repository is a real life example of Clean Architecture with use of `Next.js` and `Typescript`\n\n![Clean Architecture Diagram](clean.diagram.architecture.svg)\n\n\u003e Diagrams have copyrights, if you want to use it on larger scale, feel free to contact me.\n\n### BUSINESS CONTEXT\n\nProject is a simple logistic dashboard for managing packages and clients.\nThere are two separate roles `Admin` and `Member`.\n\n### USER STORIES\n\n##### Member\n\n    TODO\n\n##### Admin\n\n    Given I'm Admin\n    When I'm on Dashboard\n    Then I see recent new packages\n    And I see recent packages in transit\n    And I see packages delivered\n    \n    Given I'm Admin\n    When I'm on clients screen\n    Then I can see clients list\n\n    Given I'm Admin\n    When I'm on clients screen\n    And I click on client item\n    Then I'm navigated to client details screen\n\n    Given I'm Admin\n    When I'm on client details screen\n    Then I can see client name\n    And packages list\n\n    Given I'm Admin\n    When I'm on packages screen\n    Then I can see packages list\n\n    Given I'm Admin\n    When I'm on packages screen\n    And I click on package item\n    Then I can see package products\n    \n    Given I'm Admin\n    When I tap on logout button\n    Then I'm navigated to login screen\n\n\n### PREREQUISITES\n\n* `Yarn`\n* `Docker`\n\n### TECHNOLOGIES USED\n\n* `Typescript`\n* `Next.js 14`\n* `Docker`\n* `Cucumber`\n* `Mockoon`\n* `Jest`\n* `Playwright`\n* `Storybook`\n\n### SETUP\n\n* `Yarn install`\n\n### STRUCTURE\n\n1. app ( `Next.js app folder` )\n\n        Contains application structure related to Next.js 14\n\n2. core ( `Application Core` )\n\n        Contains loggers, event tracking logic etc\n\n3. data\n\n        Contains definition of data sources \n\n4. dataStore \n    \n        Contains definition of state like redux, zustand etc\n\n5. domain\n\n        Contains definition of models, repositories, usecases etc\n\n6. ioc\n\n        Contains definition of dependency injection related structures ( Container and modules )\n\n7. presentation\n\n        Contains definition of presenters ( MVP ) and presenter related models\n\n8. ui\n\n        Contains definition for user facing markup ( React.js ), server side components, styles etc\n\n### DATA FLOW\n\nThere is specific data flow applied for Clean architecture, and it's important to understand layers separation.\nIn this example you can see clean architecture with MVP ( Model View Presenter ) pattern as it seems like the best \nsolution long term when it comes to web apps development. There are few alternatives which you can see on diagram.\nCode is focused on primary ( first proposal ).\n\n#### PRIMARY FLOW\n\n![Clean Architecture Data Flow Diagram](clean.diagram.flow.svg)\n\n#### ALTERNATIVE FLOW\n\n![Clean Architecture Alternative Data Flow Diagram](clean.diagram.flow2.svg)\n\n#### ALTERNATIVE FLOW \n\n![Clean Architecture Alternative Data Flow Diagram](clean.diagram.flow3.svg)\n\n### LAYERS RESTRICTIONS\n\nWhole approach defines layer access restrictions which are defined in `eslint`. \n\n* `DEPENDENCY INJECTION` has access to every layer to provide proper abstractions implementations.\n* `UI` have access to `PRESENTATION ( MVP )` and `DATA STORE` layers\n   * `Product features` can be grouped into `Bounded Context`\n   * Given `Product features` do not have direct access to each other, \n     * If you need to have some cross product functionality then you need to define `shared` product feature.\n* `PRESENTATION` have access to `DATA STORE` and `DOMAIN`\n   * `Presenters` can be also part of `Bounded Context` and also can be part of `shared` product feature\n   * `Presenters` can access data store in need to update data ( when fetching data from data sources ) or fetch it\n* `DATA STORE` can't access any layer, it defines data structures and stores data mostly related to some framework\n* `DOMAIN LAYER` can't access any layer, it's the core of whole architecture. It defines structures and business logic\n   * `Mappers` are defined here and are responsible for mapping data source models into domain models in scope of repository\n   * `Use Cases`, `Scenarios`, `Interactors` defines business logic and communicates with repositories\n   * `Repositories` in domain are just abstractions / interfaces, not a specific implementation\n\n### ARCHITECTURE LAYERS\n\nTake a look at detailed diagrams for every layer for better understanding data flow and related structures\n\n![Clean Architecture UI Layer](clean.diagram.ui.svg)\n\n![Clean Architecture PRESENTATION Layer](clean.diagram.presentation.svg)\n\n![Clean Architecture DATA STORE Layer](clean.diagram.dataStore.svg)\n\n![Clean Architecture DOMAIN Layer](clean.diagram.domain.svg)\n\n![Clean Architecture DATA Layer](clean.diagram.data.svg)\n\n### HOW TO RUN LOCALLY\n\n* `docker compose up`\n* To access app `http://localhost:3000/`\n* To access storybook `http://localhost:6006/`\n\nEvery role has its own account\n\n* `member@clean.com`\n* `admin@clean.com`\n\nYou can use any password\n\n### TESTING\n\n#### Unit Tests\n\n1. Run `yarn test`\n\n#### E2E Tests\n\n1. Run `yarn test:e2e`\n\n#### Mutational Tests\n\n1. Read guide [here](https://stryker-mutator.io/stryker/quickstart) to setup global dependencies\n2. Run `yarn test:mutate` command\n\n### APPLIED CONCEPTS\n\n#### Page Object\n\n`Page Object` - models objects used within specific tests.\n\n#### Request Object\n\n`Request object` - holds data which is transferred between modules ( `DTO` ). \n\n#### Repository / Unit of Work\n\n`Repository` is an abstraction over data source. Defined actions which can be done over data source, and clear definition of\ninput and output\n\n`Unit of work` is a wrapper around multiple repositories, you can use it if you have dependency between few data sources,\nand you would like to combine output into one model\n\n#### UseCase / Scenario / Interactor\n\n`UseCase` can be understood as operation performed by user which is based on a specific data source. \n\n#### Mapper\n\nThe Simple concept, where one module data structure is translated to another module\n\n##### Data -\u003e Domain Mapper\n\nThis mapper is prepared for mapping data source format data into domain format. The Simplest example would be that, in\na database we store `first_name` and `last_name` in separate columns, but in a domain we need to have field `name` which\nis combined value of previously mentioned columns. In that case we define domain model with required fields and new `name` field.\nIn a Mapper, we can perform merging of those 2 values. \n\n##### Domain -\u003e Presentation Mapper\n\nThis mapper is for preparing Domain data format into specific presentation data format. This mapper separates domain data format \nfrom UI / Presentation data format. If you plan to use `dataStore` layer then you can combine `domain` + `dataStore` data \ninto one `presentation` model for specific screen\n\n##### Scoping - Public / Private access interface\n\nIt's a simple pattern for better access control within domains and folders. Sometimes we want to just keep some files accessible\nwithin given package. To achieve that we are using scopes.\n\n### KNOWN ISSUES\n\n* Order of stylesheets combined with routing - [GitHub Issue here](https://github.com/vercel/next.js/issues/13092)\n  * After update to `14.2.0-canary.60` canary version seems like styling issue related to order has been resolved, but \n  * there is different issue now - sometimes styles are not loaded for some components and user needs to refresh\n* Slow routes loading https://github.com/vercel/next.js/issues/61259\n* There are still some weird issues over authentication...\n* Project is sometimes still unstable, it's crashing here and there. I'll try to correct it in a free moment\n  * Applied some patches to gracefully handle crashes due to lack of mocked data\n\n### STILL TODO\n\n* Add more tests for prepared code ( e2e and unit test )\n* Update exising tests\n* Add more functionality to existing project \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelzar%2Fclean-architecture-nextjs-react-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelzar%2Fclean-architecture-nextjs-react-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelzar%2Fclean-architecture-nextjs-react-boilerplate/lists"}