@pplancq/react-template 2.8.17 → 2.9.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## @pplancq/react-template [2.9.0](https://github.com/pplancq/dev-tools/compare/@pplancq/react-template@2.8.17...@pplancq/react-template@2.9.0) (2026-06-15)
+
+### Features
+
+* **react-template:** restructure react-template to Clean Architecture and DDD bounded contexts ([#1742](https://github.com/pplancq/dev-tools/issues/1742)) ([bbd8a9d](https://github.com/pplancq/dev-tools/commit/bbd8a9da2028a3f070993e38bd7140a5edbe6d2c))
+
+### Bug Fixes
+
+* **deps:** update commitlint monorepo to ^21.0.2 ([#1769](https://github.com/pplancq/dev-tools/issues/1769)) ([f3c7f42](https://github.com/pplancq/dev-tools/commit/f3c7f42c1229060f6471d68a3bdfc0517543ef3a))
+* **deps:** update dependency @hookform/resolvers to ^5.4.0 ([#1755](https://github.com/pplancq/dev-tools/issues/1755)) ([e7f1d68](https://github.com/pplancq/dev-tools/commit/e7f1d68a868fba6247fe360b8e8b5e9fc6275be4))
+* **deps:** update dependency @rsbuild/core to ^2.0.12 ([#1744](https://github.com/pplancq/dev-tools/issues/1744)) ([22a93b3](https://github.com/pplancq/dev-tools/commit/22a93b3d027b2a88c4bc9f80ecbeb4af91e3f0e6))
+* **deps:** update dependency @rsbuild/plugin-eslint to ^2.0.2 ([#1759](https://github.com/pplancq/dev-tools/issues/1759)) ([eeaa6cb](https://github.com/pplancq/dev-tools/commit/eeaa6cbe616a365066611c39a3ccc36db6598b7c))
+* **deps:** update dependency @rsbuild/plugin-react to ^2.0.1 ([#1766](https://github.com/pplancq/dev-tools/issues/1766)) ([b1527e6](https://github.com/pplancq/dev-tools/commit/b1527e6097daf03e8dbe82959e14899cf11d1086))
+* **deps:** update dependency @rsbuild/plugin-sass to ^1.5.3 ([#1767](https://github.com/pplancq/dev-tools/issues/1767)) ([b25e848](https://github.com/pplancq/dev-tools/commit/b25e848e00e384b3a378ec243ce69c7151ff4c8c))
+* **deps:** update dependency monocart-coverage-reports to ^2.12.12 ([#1768](https://github.com/pplancq/dev-tools/issues/1768)) ([8a5ba24](https://github.com/pplancq/dev-tools/commit/8a5ba24051ff8f7eb6409b5ab6738ebdb01055d9))
+* **deps:** update dependency react-hook-form to ^7.78.0 ([#1756](https://github.com/pplancq/dev-tools/issues/1756)) ([2cccd51](https://github.com/pplancq/dev-tools/commit/2cccd5144d875d0accf485b256ef3d91ca8fe893))
+* **deps:** update dependency stylelint to ^17.13.0 ([#1752](https://github.com/pplancq/dev-tools/issues/1752)) ([acfc13f](https://github.com/pplancq/dev-tools/commit/acfc13f61041ffc9323a3e469c1b2e51fbf3bf9f))
+* **deps:** update react monorepo ([#1745](https://github.com/pplancq/dev-tools/issues/1745)) ([8424cfe](https://github.com/pplancq/dev-tools/commit/8424cfed2645554410e1e7df2632376b26b1fb04))
+* **deps:** update react-query mono repo to ^5.101.0 ([#1749](https://github.com/pplancq/dev-tools/issues/1749)) ([31d0cfd](https://github.com/pplancq/dev-tools/commit/31d0cfdedf9a5c1ed2779cff2a0b8a0fd8a8ac5d))
+* **deps:** update react-router monorepo to ^7.17.0 ([#1763](https://github.com/pplancq/dev-tools/issues/1763)) ([6cfffba](https://github.com/pplancq/dev-tools/commit/6cfffba0a99f0c0dcb4f271ace035e60b2d951d3))
+
+
+### Dependencies
+
+* **@pplancq/commitlint-config:** upgraded to 4.0.2
+* **@pplancq/eslint-config:** upgraded to 6.0.17
+
 ## @pplancq/react-template [2.8.17](https://github.com/pplancq/dev-tools/compare/@pplancq/react-template@2.8.16...@pplancq/react-template@2.8.17) (2026-05-19)
 
 ### Bug Fixes

package/_README.md

@@ -81,64 +81,69 @@ Allows you to fix prettier lint errors.
 
 To remove the demo application.
 
-### `npm run migrate:vite`
-
-To migrate from webpack to vite.
-
 ## 🏗 <span id="project-structure">Project Structure</span>
 
-```
-📁 my-projet
+```text
+📁 my-project
 ├── 📁 src
-│   ├── 📁 ui
-│   │   ├── 📁 Atoms
-│   │   ├── 📁 Molecules
-│   │   ├── 📁 Organisms
-│   │   ├── 📁 Templates
-│   ├── 📁 components
-│   │   ├── 📁 formFields
-│   ├── 📁 providers
-│   ├── 📁 pages
-│   │   ├── 📁 homePage
-│   │   ├── 📁 page1
-│   │   │   ├── 📁 sousPage1
-│   ├── 📁 forms
-│   │   ├── 📁 hooks
-│   │   ├── 📁 risk
-│   │   ├── 📁 contact
-│   ├── 📁 hooks
-│   │   ├── 📁 api
-│   │   ├── 📁 useCustom1
-│   │   ├── 📁 useCustom2
-│   ├── 📁 utils
-│   │   ├── 📁 services
-│   │   ├── 📁 tests
-│   │   ├── 📁 helpers
-│   ├── 📁 routing
-│   ├── 📁 api
-│   ├── 📁 types
-│   ├── 📁 assets
-│   ├── 📁 config
+│   ├── 📄 README.md
+│   ├── 📁 app
+│   │   ├── 📄 README.md
+│   │   ├── 📄 App.tsx
+│   │   ├── 📄 AppHTMLElement.tsx
+│   │   ├── 📁 assets
+│   │   ├── 📁 config
+│   │   ├── 📁 providers
+│   │   └── 📁 routing
+│   ├── 📁 shared
+│   │   ├── 📄 README.md
+│   │   ├── 📁 application
+│   │   │   └── 📄 README.md
+│   │   ├── 📁 domain
+│   │   │   └── 📄 README.md
+│   │   ├── 📁 infrastructure
+│   │   │   └── 📄 README.md
+│   │   └── 📁 ui
+│   │       └── 📄 README.md
+│   ├── 📁 demo
+│   │   ├── 📄 README.md
+│   │   ├── 📁 application
+│   │   ├── 📁 domain
+│   │   ├── 📁 infrastructure
+│   │   ├── 📁 ui
+│   │   │   ├── 📁 assets
+│   │   │   ├── 📁 components
+│   │   │   ├── 📁 forms
+│   │   │   ├── 📁 hooks
+│   │   │   ├── 📁 layouts
+│   │   │   ├── 📁 pages
+│   │   │   └── 📁 routing
+│   │   ├── 📄 serviceDemo.ts
+│   │   └── 📄 serviceIdentifiers.ts
+│   ├── 📄 main.ts
+│   └── 📄 react-app-env.d.ts
 ```
 
 ### 📚 Folder Definitions
 
 Here is the project folder structure, with a brief description of each folder:
 
-| Folder                                               | Description                                                                                                                                                                                      |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **📁 src**                                           | **_The root directory of the application source code._**                                                                                                                                         |
-| [**📁 ui**](./src/ui/README.md)                      | Contains reusable components designed to be used across projects. Components can be basic (Atoms), more complex (Molecules), higher-level components (Organisms), or page templates (Templates). |
-| [**📁&#160;components**](./src/components/README.md) | Contains project-specific reusable components, for example, form components using React Hook Form.                                                                                               |
-| [**📁 providers**](./src/providers/README.md)        | This folder contains context providers or custom hooks that provide data to the entire application.                                                                                              |
-| [**📁 pages**](./src/pages/README.md)                | Contains the pages of the application. Each subfolder represents a distinct page or view of the application.                                                                                     |
-| [**📁 forms**](./src/forms/README.md)                | Contains the forms of the application, grouping hooks related to forms.                                                                                                                          |
-| [**📁 hooks**](./src/hooks/README.md)                | Includes custom hooks for various application features, such as API calls with React Query.                                                                                                      |
-| [**📁 utils**](./src/utils/README.md)                | Contains utilities and services such as test files, utility functions, etc.                                                                                                                      |
-| [**📁 routing**](./src/routing/README.md)            | This folder is intended for native API calls using the `fetch`. function. These calls are essential for fetching real-time data from external sources, such as remote servers or web services.   |
-| [**📁 types**](./src/types/README.md)                | Provides TypeScript type definitions to enhance the robustness of your code.                                                                                                                     |
-| [**📁 assets**](./src/assets/README.md)              | Contains static files such as images, fonts, etc., used in the application.                                                                                                                      |
-| [**📁 config**](./src/config/README.md)              | Contains all the important configurations and utilities needed for our project.                                                                                                                  |
+| Folder                                                                | Description                                                                                                                                                |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **📁 src**                                                            | **_The root directory of the application source code._** It also contains [`src/README.md`](./src/README.md), which serves as the documentation index.     |
+| [**📁 app**](./src/app/README.md)                                     | Owns the application bootstrap layer: root app composition, custom element entry point, routing, providers, global configuration, and app-wide assets.     |
+| [**📁 shared**](./src/shared/README.md)                               | Contains only genuinely reusable cross-context code. In this starter it is intentionally conservative and avoids hosting demo-specific UI.                 |
+| [**📁 shared/application**](./src/shared/application/README.md)       | Shared application-layer abstractions, DTO helpers, or orchestration utilities that can be reused by several bounded contexts.                             |
+| [**📁 shared/domain**](./src/shared/domain/README.md)                 | Shared pure types and contracts. This folder must stay framework-free and focused on stable, reusable domain-facing definitions.                           |
+| [**📁 shared/infrastructure**](./src/shared/infrastructure/README.md) | Shared technical helpers backed by external tools or browser APIs, such as generic HTTP utilities.                                                         |
+| [**📁 shared/ui**](./src/shared/ui/README.md)                         | Shared UI-facing helpers with no feature identity. In the current template it mainly exists for common hooks such as DI-to-React integration.              |
+| [**📁 demo**](./src/demo/README.md)                                   | The example bounded context included in the starter. It demonstrates how to structure a feature using `application`, `domain`, `infrastructure`, and `ui`. |
+| **📁 demo/ui/components**                                             | Demo visual components and building blocks. The structure stays practical and readable instead of exposing `atoms`, `molecules`, or `organisms` folders.   |
+| **📁 demo/ui/layouts**                                                | Demo layouts used to compose pages.                                                                                                                        |
+| **📁 demo/ui/pages**                                                  | Demo pages such as the overview page and the example feature pages.                                                                                        |
+| **📁 demo/ui/forms**                                                  | Demo form composition and form-related UI pieces.                                                                                                          |
+| **📁 demo/ui/hooks**                                                  | Demo-specific React hooks, such as query hooks that connect the UI to the application layer.                                                               |
+| **📁 demo/ui/routing**                                                | Demo route definitions and route path constants consumed by the app router.                                                                                |
 
 ## 🏗 <span id="component-structure">React Component Structure</span>
 
@@ -171,7 +176,7 @@ export { ComponentName } from './ComponentName';
 This will allow importing a component like this:
 
 ```typescript
-import { ComponentName } from '@Front/ComponentName';
+import { ComponentName } from '@Demo/ui/components/ComponentName';
 ```
 
 #### 📄 ComponentName.tsx
@@ -236,13 +241,13 @@ export const ComponentName = () => {
 
 ## ⚠️ Caution with Environment Variables
 
-The webpack configuration of this project allows for environment variables to be included in the application bundle. This could potentially expose sensitive information if the bundle is publicly accessible.
+The build configuration of this project allows for environment variables to be included in the application bundle. This could potentially expose sensitive information if the bundle is publicly accessible.
 
 It is recommended to only include non-sensitive environment variables in the application bundle. Sensitive information should not be exposed even if the bundle is publicly accessible.
 
 Ensure you understand the security implications before including environment variables in your bundle.
 
-Please note that the web configuration pre-filters environment variables via the default prefix ‘FRONT*’. This means that only environment variables starting with ‘FRONT*’ will be included in the bundle. This is an additional layer of security to prevent the accidental exposure of sensitive environment variables.
+Please note that the build configuration pre-filters environment variables via the default prefix `FRONT*`. This means that only environment variables starting with `FRONT*` will be included in the bundle. This is an additional layer of security to prevent the accidental exposure of sensitive environment variables.
 
 ## 🙇 <span id="learnmore">Learn More</span>
 

package/mise.toml

@@ -1,3 +1,3 @@
 [tools]
-node = "24.15.0"
-npm = "11.14.1"
+node = "24.16.0"
+npm = "11.17.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pplancq/react-template",
-  "version": "2.8.17",
+  "version": "2.9.0",
   "license": "MIT",
   "description": "react template",
   "author": "pplancq <paul.plancq@outlook.fr>",
@@ -13,7 +13,7 @@
   "bin": {
     "template-install": "bin/template-install.js"
   },
-  "packageManager": "npm@11.14.1",
+  "packageManager": "npm@11.17.0",
   "scripts": {
     "start": "rsbuild dev",
     "start:mock": "rsbuild dev --env-mode mock",
@@ -49,18 +49,19 @@
     "template"
   ],
   "dependencies": {
-    "@hookform/resolvers": "^5.2.2",
-    "@tanstack/react-query": "^5.100.10",
-    "@tanstack/react-query-devtools": "^5.100.10",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-hook-form": "^7.75.0",
-    "react-router": "^7.15.1",
+    "@hookform/resolvers": "^5.4.0",
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-query-devtools": "^5.101.0",
+    "inversify": "^8.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-hook-form": "^7.78.0",
+    "react-router": "^7.17.0",
     "yup": "^1.7.1"
   },
   "devDependencies": {
-    "@bdellegrazie/playwright-sonar-reporter": "^0.5.0",
-    "@commitlint/cli": "^21.0.1",
+    "@bdellegrazie/playwright-sonar-reporter": "^0.5.1",
+    "@commitlint/cli": "^21.0.2",
     "@msw/playwright": "^0.6.7",
     "@playwright/test": "^1.60.0",
     "@pplancq/commitlint-config": "*",
@@ -68,34 +69,34 @@
     "@pplancq/postcss-config": "*",
     "@pplancq/prettier-config": "*",
     "@pplancq/stylelint-config": "*",
-    "@rsbuild/core": "^2.0.6",
-    "@rsbuild/plugin-eslint": "^2.0.0",
-    "@rsbuild/plugin-react": "^2.0.0",
-    "@rsbuild/plugin-sass": "^1.5.2",
+    "@rsbuild/core": "^2.0.12",
+    "@rsbuild/plugin-eslint": "^2.0.2",
+    "@rsbuild/plugin-react": "^2.0.1",
+    "@rsbuild/plugin-sass": "^1.5.3",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
-    "@vitest/coverage-v8": "^4.1.6",
-    "concurrently": "^9.2.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "concurrently": "^10.0.3",
     "eslint": "^9.39.4",
-    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-prettier": "^5.5.6",
     "husky": "^9.1.7",
     "jsdom": "^29.1.1",
-    "lint-staged": "^17.0.4",
-    "monocart-coverage-reports": "^2.12.11",
+    "lint-staged": "^17.0.7",
+    "monocart-coverage-reports": "^2.12.12",
     "msw": "^2.14.6",
     "nodemon": "^3.1.14",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "rsbuild-plugin-stylelint": "^1.2.0",
-    "stylelint": "^17.11.1",
+    "stylelint": "^17.13.0",
     "stylelint-prettier": "^5.0.3",
     "tsc-files": "^1.1.4",
     "typescript": "^6.0.3",
     "vite-plugin-svgr": "^5.2.0",
-    "vitest": "^4.1.6",
+    "vitest": "^4.1.8",
     "vitest-axe": "^1.0.0-pre.5",
     "vitest-sonar-reporter": "^3.0.0"
   },

package/scripts/removeDemo.cjs

@@ -4,79 +4,118 @@ const { resolve } = require('node:path');
 
 const resolveSrc = path => resolve(__dirname, `../src${path}`);
 
-rmSync(resolveSrc('/api/demoApi.ts'));
-
-rmSync(resolveSrc('/assets/css/mainBody.css'));
-rmSync(resolveSrc('/assets/css/reset.css'));
-writeFileSync(resolveSrc('/assets/css/global.css'), ':root {\n  --white-color: #fff;\n}\n', { encoding: 'utf-8' });
-let assetsIndex = readFileSync(resolveSrc('/assets/css/index.ts'), { encoding: 'utf-8' });
-assetsIndex = assetsIndex.replaceAll("import './reset.css';\nimport './mainBody.css';\n", "import './global.css';\n");
-writeFileSync(resolveSrc('/assets/css/index.ts'), assetsIndex, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/assets/images/logo.png'));
-rmSync(resolveSrc('/assets/images/templatePlugins.png'));
-
-rmSync(resolveSrc('/components/Footer'), { recursive: true });
-rmSync(resolveSrc('/components/Header'), { recursive: true });
-rmSync(resolveSrc('/components/TextInput'), { recursive: true });
-
-rmSync(resolveSrc('/forms/ProfileForm'), { recursive: true });
-
-rmSync(resolveSrc('/hooks/api/useDemoApi.ts'));
-let queryKey = readFileSync(resolveSrc('/hooks/api/queryKey.ts'), { encoding: 'utf-8' });
-queryKey = queryKey.replaceAll("export const demoQuery = () => ['dataWithDelay'];\n", '');
-writeFileSync(resolveSrc('/hooks/api/queryKey.ts'), queryKey, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/pages/Demo'), { recursive: true });
-rmSync(resolveSrc('/pages/Layout'), { recursive: true });
-rmSync(resolveSrc('/pages/UnexpectedError'), { recursive: true });
-mkdirSync(resolveSrc('/pages/Home'));
-writeFileSync(resolveSrc('/pages/Home/index.ts'), "export { homeRoutes } from './routes';\n", { encoding: 'utf-8' });
+rmSync(resolveSrc('/demo'), { recursive: true, force: true });
+
+rmSync(resolveSrc('/app/assets/css/mainBody.css'), { force: true });
+writeFileSync(resolveSrc('/app/assets/css/global.css'), ':root {\n  --white-color: #fff;\n}\n', { encoding: 'utf-8' });
+writeFileSync(resolveSrc('/app/assets/css/index.ts'), "import './reset.css';\nimport './global.css';\n", {
+  encoding: 'utf-8',
+});
+
+mkdirSync(resolveSrc('/home/domain'), { recursive: true });
+writeFileSync(resolveSrc('/home/domain/.gitkeep'), '', { encoding: 'utf-8' });
+
+mkdirSync(resolveSrc('/home/application'), { recursive: true });
+writeFileSync(resolveSrc('/home/application/.gitkeep'), '', { encoding: 'utf-8' });
+
+mkdirSync(resolveSrc('/home/infrastructure'), { recursive: true });
+writeFileSync(resolveSrc('/home/infrastructure/.gitkeep'), '', { encoding: 'utf-8' });
+
+writeFileSync(resolveSrc('/home/serviceIdentifiers.ts'), 'export const HOME_SERVICES = Object.freeze({});\n', {
+  encoding: 'utf-8',
+});
+
 writeFileSync(
-  resolveSrc('/pages/Home/routes.tsx'),
-  "import type { RouteObject } from 'react-router';\n" +
-    "import { Home } from './Home';\n" +
-    '\n' +
-    'export const homeRoutes: RouteObject = {\n' +
-    '  index: true,\n' +
-    '  element: <Home />,\n' +
-    '};\n',
+  resolveSrc('/home/serviceHome.ts'),
+  [
+    "import { ContainerModule } from 'inversify';",
+    '',
+    'export const serviceHome: ContainerModule = new ContainerModule(_options => {',
+    '  // Register your home context services here',
+    '});',
+    '',
+  ].join('\n'),
   { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/pages/Home/Home.tsx'), 'export const Home = () => {\n  return <div>HomePage</div>;\n};\n', {
-  encoding: 'utf-8',
-});
 
-let appRoutes = readFileSync(resolveSrc('/routing/appRoutes.ts'), { encoding: 'utf-8' });
-appRoutes = appRoutes.replaceAll(
-  "\n  reactQueryDemo: '/reactQueryDemo',\n  reactHookFormDemo: '/reactHookFormDemo',",
-  '',
+mkdirSync(resolveSrc('/home/ui/pages/Home'), { recursive: true });
+writeFileSync(
+  resolveSrc('/home/ui/pages/Home/Home.tsx'),
+  [
+    'export const Home = () => {',
+    '  return (',
+    '    <section>',
+    '      <h1>Home</h1>',
+    '      <p>Your demo context has been removed. Start building your first bounded context from here.</p>',
+    '    </section>',
+    '  );',
+    '};',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/routing/appRoutes.ts'), appRoutes, { encoding: 'utf-8' });
-let routes = readFileSync(resolveSrc('/routing/routes.tsx'), { encoding: 'utf-8' });
-routes = routes.replaceAll(
-  "import { demoRoutes } from '@Front/pages/Demo';",
-  "import { homeRoutes } from '@Front/pages/Home';",
+
+mkdirSync(resolveSrc('/home/ui/routing'), { recursive: true });
+writeFileSync(
+  resolveSrc('/home/ui/routing/homeAppRoutes.ts'),
+  ['export const homeAppRoutes = Object.freeze({', "  home: '/',", '});', ''].join('\n'),
+  { encoding: 'utf-8' },
+);
+
+writeFileSync(
+  resolveSrc('/home/ui/routing/homeRoutes.tsx'),
+  [
+    "import { Home } from '@Home/ui/pages/Home/Home';",
+    "import type { RouteObject } from 'react-router';",
+    '',
+    'export const homeRoutes: RouteObject = {',
+    '  children: [',
+    '    {',
+    '      index: true,',
+    '      element: <Home />,',
+    '    },',
+    '  ],',
+    '};',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
+);
+
+writeFileSync(
+  resolveSrc('/app/config/serviceContainer.ts'),
+  [
+    "import { serviceHome } from '@Home/serviceHome';",
+    "import { Container } from 'inversify';",
+    '',
+    'export const serviceContainer = new Container();',
+    '',
+    'serviceContainer.load(serviceHome);',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-routes = routes.replaceAll("\nimport { Layout } from '@Front/pages/Layout';", '');
-routes = routes.replaceAll("\nimport { UnexpectedError } from 'src/pages/UnexpectedError';", '');
-routes = routes.replaceAll(
-  'element: <Layout />,\n    children: [demoRoutes],\n    errorElement: <UnexpectedError />,',
-  'children: [homeRoutes],',
+
+writeFileSync(
+  resolveSrc('/app/routing/routes.tsx'),
+  [
+    "import { homeRoutes } from '@Home/ui/routing/homeRoutes';",
+    "import type { RouteObject } from 'react-router';",
+    '',
+    'export const routeObject: RouteObject[] = [',
+    '  {',
+    "    path: '/',",
+    '    children: [homeRoutes],',
+    '  },',
+    '];',
+    '',
+  ].join('\n'),
+  { encoding: 'utf-8' },
 );
-writeFileSync(resolveSrc('/routing/routes.tsx'), routes, { encoding: 'utf-8' });
-
-rmSync(resolveSrc('/types/demoApi.ts'));
-rmSync(resolveSrc('/types/profileTypes.ts'));
-
-rmSync(resolveSrc('/ui/atoms/Input'), { recursive: true });
-rmSync(resolveSrc('/ui/atoms/Logo'), { recursive: true });
-rmSync(resolveSrc('/ui/atoms/NavLink'), { recursive: true });
-rmSync(resolveSrc('/ui/molecules/Navigation'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/Footer'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/Header'), { recursive: true });
-rmSync(resolveSrc('/ui/organisms/MainContent'), { recursive: true });
-rmSync(resolveSrc('/ui/templates/MainTemplate'), { recursive: true });
+
+const tsconfigJson = JSON.parse(readFileSync(resolve(__dirname, '../tsconfig.json'), { encoding: 'utf-8' }));
+delete tsconfigJson.compilerOptions.paths['@Demo/*'];
+tsconfigJson.compilerOptions.paths['@Home/*'] = ['./src/home/*'];
+writeFileSync(resolve(__dirname, '../tsconfig.json'), JSON.stringify(tsconfigJson, null, 2), { encoding: 'utf-8' });
 
 const packagesJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), { encoding: 'utf-8' }));
 const { 'remove:demo': _, ...scripts } = packagesJson.scripts;

package/src/README.md

@@ -0,0 +1,81 @@
+# `src`
+
+This directory contains the template source code and its explanatory documentation.
+
+## Architecture Philosophy
+
+This starter follows a **hybrid architecture** combining two complementary patterns:
+
+- **Clean Architecture** (Robert C. Martin) — code is organized into horizontal layers that enforce a strict
+  dependency direction. Dependencies always flow **inward toward the domain**. The domain is the most protected
+  layer; it has zero external dependencies.
+- **DDD Bounded Contexts** — code is also organized into vertical slices, each representing an isolated business
+  domain. A bounded context owns its full stack: domain, application, infrastructure, and UI.
+
+The result is a structure where every folder belongs to either a **horizontal layer** (domain, application,
+infrastructure, ui) or a **vertical slice** (a bounded context such as `demo`), and both dimensions are always
+visible.
+
+## Top-level structure
+
+```
+src/
+├── app/       # Application bootstrap layer (not a bounded context)
+├── shared/    # Shared kernel — genuinely cross-context code
+│   ├── domain/
+│   ├── application/
+│   ├── infrastructure/
+│   └── ui/
+└── demo/      # Example bounded context (domain / application / infrastructure / ui)
+```
+
+## Fundamental dependency rule
+
+```
+UI  →  Application  →  Domain
+Infrastructure  -.→  Domain (implements its interfaces)
+```
+
+- **Domain** depends on nothing. Pure TypeScript.
+- **Application** depends on Domain only. Orchestrates use cases, defines infrastructure interfaces.
+- **Infrastructure** implements interfaces defined by Domain/Application. May use external libraries.
+- **UI** depends on Application (use cases) and Domain (DTOs). No business logic.
+
+This rule applies **within each bounded context** and **within the shared kernel**.
+
+## Path aliases
+
+Each first-class section of the source tree has a TypeScript path alias. Use these aliases instead of long
+relative paths; they signal architectural intent and prevent accidental cross-context coupling.
+
+| Alias       | Maps to        |
+| ----------- | -------------- |
+| `@App/*`    | `src/app/*`    |
+| `@Shared/*` | `src/shared/*` |
+| `@Demo/*`   | `src/demo/*`   |
+| `@Mocks/*`  | `mocks/*`      |
+
+When you add a real bounded context alongside `demo`, add its own alias to `tsconfig.json`.
+
+## Table of contents
+
+1. [`app/README.md`](./app/README.md) — application bootstrap, composition root, routing, and providers
+2. [`shared/README.md`](./shared/README.md) — shared kernel concept and usage rules
+3. [`shared/domain/README.md`](./shared/domain/README.md) — shared pure contracts, types, and domain rules
+4. [`shared/application/README.md`](./shared/application/README.md) — shared application-layer abstractions
+5. [`shared/infrastructure/README.md`](./shared/infrastructure/README.md) — shared technical adapters and helpers
+6. [`shared/ui/README.md`](./shared/ui/README.md) — shared UI-facing hooks and utilities
+7. [`demo/README.md`](./demo/README.md) — the example bounded context and how to replicate it
+
+## Suggested reading order
+
+If you are discovering the template for the first time:
+
+1. This file — understand the big picture
+2. `app` — see how the application boots and wires everything together
+3. `shared/domain` — understand why the domain layer is the most protected
+4. `shared` — understand what the shared kernel is and what it must not become
+5. `demo` — walk through a complete bounded context layer by layer
+
+That sequence starts with the overall architecture, moves to the heart of Clean Architecture (domain purity),
+then shows how a real bounded context puts all the pieces together.

package/src/app/App.tsx

@@ -0,0 +1,18 @@
+import { queryClient } from '@App/config/queryClientConfig';
+import { serviceContainer } from '@App/config/serviceContainer';
+import { Providers } from '@App/providers/Providers/Providers';
+import { Router } from '@App/routing/Router';
+
+import '@App/assets/css';
+
+type AppProps = {
+  basename?: string;
+};
+
+export const App = ({ basename }: AppProps) => {
+  return (
+    <Providers queryClient={queryClient} container={serviceContainer}>
+      <Router basename={basename} />
+    </Providers>
+  );
+};

package/src/{bootstrap.tsx → app/AppHTMLElement.tsx}

@@ -1,9 +1,9 @@
-import { App } from '@Front/components/App';
+import { App } from '@App/App';
 import { StrictMode } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 
 // eslint-disable-next-line import/no-default-export
-export default class Bootstrap extends HTMLElement {
+export default class AppHTMLElement extends HTMLElement {
   private readonly root: Root;
 
   private isMounted = false;