adjust css. improve filesystem layout docs

cloudposse · Nov 11, 2024 · cbb688c · cbb688c
1 parent a2e0961
commit cbb688c
Show file tree

Hide file tree

Showing 2 changed files with 187 additions and 139 deletions.
diff --git a/website/docs/core-concepts/projects/layout.mdx b/website/docs/core-concepts/projects/layout.mdx
@@ -3,7 +3,7 @@ title: Folder Structure
 sidebar_position: 1
 sidebar_label: Folder Structure
 description: Recommended way to organize your Atmos stacks and components
-id: layout    
+id: layout
 ---
 import KeyPoints from '@site/src/components/KeyPoints'
 import Intro from '@site/src/components/Intro'
@@ -18,7 +18,66 @@ At the root of your project, you’ll typically find an `atmos.yaml` configurati
 - Different ways to organize your project
 </KeyPoints>
 
-You can find some demos of how we organize projects in the Atmos GitHub repository under the [`examples/`](https://github.com/cloudposse/atmos/tree/main/examples) folder.
+## Recommended Filesystem Layout
+
+Atmos is fully configurable, and you can organize your project in any way that makes sense for your team by adusting the paths in [`atmos.yaml`](/core-concepts/projects/configuration). We also provide detailed guidance on organizing your folder structure, whether it’s for a simple project or enterprise-scale architecture in our [Design Patterns](/design-patterns) section. Choose the model that best fits the stage you plan to reach when you complete the project.
+
+Here's a simple layout, if you just have 3 deployments for things like dev, staging, and prod:
+```plaintext
+├── components/          # Folder containing all your components, usually organized by toolchain
+│   └── terraform/       # Folder for all Terraform "root modules"
+└── stacks/
+    ├── deploy/          # Folder for deployable stacks
+    │   ├── dev/         # Folder for development environment configurations
+    │   ├── staging/     # Folder for staging environment configurations
+    │   └── prod/        # Folder for production environment configurations
+    ├── catalog/         # Folder for the service catalog
+    ├── schemas/         # Folder for the schema validations
+    └── workflows/       # Folder for workflows that operate on top of stacks
+```
+
+Alternatively, here’s a more complex layout for a larger project broken into multiple organizations, organizational units, and environments:
+
+```plaintext
+├── components/                  # Folder containing all your components, usually organized by toolchain
+│   └── terraform/               # Folder for all Terraform "root modules"
+└── stacks/
+    ├── orgs/                    # Folder for deployable stacks
+    │   └── acme/                # Folder for the Acme organization
+    │       ├── core/            # OU for core services
+    │       │   ├── security/    # Folder for security-related configurations
+    │       │   ├── audit/       # Folder for audit-related configurations
+    │       │   ├── identity/    # Folder for identity management configurations
+    │       │   └── network/     # Folder for networking-related configurations
+    │       └── plat/            # OU for platform environments
+    │           ├── dev/         # Folder for development environment configurations
+    │           ├── staging/     # Folder for staging environment configurations
+    │           └── prod/        # Folder for production environment configurations
+    ├── catalog/                 # Folder for the service catalog
+    ├── schemas/                 # Folder for the schema validations
+    └── workflows/               # Folder for workflows that operate on top of stacks
+```
+
+Note, that these are just a couple of examples.
+
+<dl>
+    <dt>`components/`</dt>
+    <dd>folder containing all your components, usually organized by your toolchain</dd>
+
+    <dt>`components/terraform`</dt>
+    <dd>folder for all Terraform "root modules"</dd>
+
+    <dt>`stacks/orgs/`</dt>
+    <dd>folder for deployable stacks</dd>
+
+    <dt>`stacks/catalog/`</dt>
+    <dd>folder for the service catalog</dd>
+
+    <dt>`stacks/workflows/`</dt>
+    <dd>folder for workflows that operate on top of stacks.</dd>
+</dl>
+
+You can find some demos of how we organize projects in the Atmos GitHub repository under the [`examples/`](https://github.com/cloudposse/atmos/tree/main/examples) folder. Or check out our [Reference Architecture for AWS](https://docs.cloudposse.com/learn) for a more detailed look at how we organize our projects.
 
 To effectively organize an Atmos project, we want to ensure you have specific locations for Atmos to find your stack configurations and components. At a minimum, we recommend the following folder structure in your project:
 
@@ -32,38 +91,22 @@ Next, you’ll have your stacks configurations, which are organized into multipl
 
 ### Schema Validations
 
+This folder contains the [JSON or OPA schemas used to validate the stack configurations](/core-concepts/validate).
+
 ### Catalogs
+
 This should be a separate top-level folder containing your stack configurations. Stack configurations are divided into several parts:
 - **Schemas Folder**: This folder contains the schemas used to validate the stack configurations.
 - **Catalog Folder**: This includes all reusable imports, which can be organized into subfolders based on logical groupings.
 - **Stacks Folder**: This contains the deployable stacks. Each stack is defined in a separate YAML file.
 
 We follow a few conventions in our reference architecture:
 
-### Deployable Stacks
+### Deployments
+
+We usually organize our stacks by organization, organizational unit, and environment. For example:
 
 - **Orgs Folder**: Represents the AWS organizations to which you deploy. You might use a folder called deploy if you have a few simple stacks.
 - **Multi-Cloud Projects**: If your project involves multiple clouds, consider additional organizational strategies.
 
 
-## Recommended Filesystem Layout
-<dl>
-    <dt>`components/`</dt>
-    <dd>folder containing all your components, usually organized by your toolchain</dd>
-
-    <dt>`components/terraform`</dt>
-    <dd>folder for all Terraform "root modules"</dd>
-
-    <dt>`stacks/orgs/`</dt>
-    <dd>folder for deployable stacks</dd>
-
-    <dt>`stacks/catalog/`</dt>
-    <dd>folder for the service catalog</dd>
-
-    <dt>`stacks/workflows/`</dt>
-    <dd>folder for workflows that operate on top of stacks.</dd>
-</dl>
-
-We provide detailed guidance on organizing your folder structure, whether it’s for a simple project or enterprise-scale architecture. 
-
-Remember, you can’t optimize for everything at once, so choose the model that best fits the stage you plan to reach when you complete the project.