diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index cdea2e6..8448832 100644 --- a/website/.vitepress/config.mts +++ b/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" }], }, diff --git a/website/docs/domains.md b/website/docs/domains.md new file mode 100644 index 0000000..04f879e --- /dev/null +++ b/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`. diff --git a/website/docs/index.md b/website/docs/index.md index 793d51f..bfd2697 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -22,11 +22,11 @@ } -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? diff --git a/website/docs/modules.md b/website/docs/modules.md index b24f37e..2794393 100644 --- a/website/docs/modules.md +++ b/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