feat: domains

website/.vitepress/config.mts

@@ -16,6 +16,10 @@ export default defineConfig({
         text: "Modules",
         link: "/modules",
       },
+      {
+        text: "Domains",
+        link: "/domains",
+      },
     ],
     socialLinks: [{ icon: "github", link: "https://github.com/pwlmc/morando" }],
   },

website/docs/domains.md

@@ -0,0 +1,58 @@
+# Domains
+
+## What Is a Domain?
+
+In Morando, a domain is a folder containing a collection of modules.
+
+Domains are intentionally simpler than modules. Their role is to group related
+modules under a shared, high-level business area.
+
+## Domain Location
+
+Every domain folder must be located at the root of the source code folder. That
+source code folder is usually called `src/`, but for simplicity we will be
+referring to it in the rest of the documentation as `@/`.
+
+By convention, domain names start with an uppercase letter, just like module
+names. This makes domains easy to spot and keeps the top-level structure
+consistent.
+
+## Domains Contain Modules
+
+Each module must be placed inside a domain. In other words, modules are never
+top-level folders on their own. Consequently, domains can contain only modules;
+files or layer folders cannot be placed directly inside a domain folder. Below
+is an example structure:
+
+```text
+.
+├── Checkout/
+│   ├── Cart/
+│   └── Payment/
+├── Catalog/
+│   ├── ProductDetails/
+│   └── ProductList/
+└── DesignSystem/
+    ├── Button/
+    ├── Dropdown/
+    └── Theme/
+```
+
+In this example, `Checkout`, `Catalog`, and `DesignSystem` are domains, and each
+contains one or more modules.
+
+:::tip File path anatomy  
+Given any path, we can easily identify the domain and module where the file is
+located. For example, `@/Api/Product/useProduct.ts` tells us that the
+`useProduct.ts` file is part of the `Api` domain and the `Product` module.  
+:::
+
+## Domain Dependencies
+
+As with modules, analyzing domain dependencies gives a lot of useful information
+about the application architecture. `Domain A` depends on `Domain B` if any
+module from `Domain A` depends on any module from `Domain B`.
+
+Unlike modules, however, domains can be circularly dependent on each other. If
+`Domain A` depends on `Domain B`, there is nothing preventing `Domain B` from
+depending on `Domain A`.

website/docs/index.md

@@ -22,11 +22,11 @@
 }
 </style>
 
-Morando is a full front-end architecture framework built around two simple
-ideas: `Modules` and `Layers`.
+Morando blends Modules and Layers into a front-end architecture that scales with
+your application.
 
-It comes with dedicated tooling and helps teams keep code healthier as systems
-grow by making architectural decisions explicit, measurable, and enforceable.
+Together with its dedicated tooling, it helps teams keep codebases healthy by
+making architectural decisions explicit, measurable, and enforceable.
 
 ## Why Morando?
 

website/docs/modules.md

@@ -15,19 +15,20 @@ contain source code files. Below you can find an example of a `User` module:
 
 ```text
 User/
-├── api.ts
-├── model.ts
 ├── UserAvatar.tsx
-└── useUser.ts
+├── useUser.ts
+├── api.ts
+└── model.ts
 ```
 
 ## Modules Are Flat
 
-One module folder can't be placed inside another module folder. That said,
-modules can contain folders. They cannot be just any folders, and their names
-are strictly tied to the layers defined in your project. They are _layer
-folders_, and to make them easier to tell apart from modules, their names start
-with a lowercase letter.
+One module folder can't be placed inside another module folder.
+
+That said, modules can contain folders. They cannot be just any folders, and
+their names are strictly tied to the layers defined in your project. They are
+_layer folders_, and to make them easier to tell apart from modules, their names
+start with a lowercase letter.
 
 We will cover them in the [Layers](./layers.md) chapter, but for this chapter,
 it is enough to remember that they are optional. Like modules, layer folders
@@ -38,12 +39,12 @@ layer folders.
 
 ```text
 Shared/
-├── utils/
-│   ├── getId.ts
-│   └── getName.ts
-└── components/
-    ├── FilterButton.tsx
-    └── ProductIcon.tsx
+├── components/
+│   ├── FilterButton.tsx
+│   └── ProductIcon.tsx
+└── utils/
+    ├── getId.ts
+    └── getName.ts
 ```
 
 ## Module Dependencies