AWS prescriptive-guidance documentation change
Summary
Updated documentation links, fixed grammatical errors (apostrophes), consolidated paragraphs about scaling strategies, removed markdown code formatting from folder names, and added specificity to section headers.
Security assessment
Changes are editorial and structural (link corrections, grammar fixes, formatting adjustments). No security vulnerabilities, features, or practices are mentioned or modified. The content focuses on architectural patterns and project organization without security implications.
Diff
diff --git a/prescriptive-guidance/latest/hexagonal-architectures/best-practices.md b/prescriptive-guidance/latest/hexagonal-architectures/best-practices.md index 495f4d033..e6250ad9b 100644 --- a//prescriptive-guidance/latest/hexagonal-architectures/best-practices.md +++ b//prescriptive-guidance/latest/hexagonal-architectures/best-practices.md @@ -5 +5 @@ -[Documentation](/index.html)[AWS Prescriptive Guidance](https://aws.amazon.com/prescriptive-guidance/)[Building hexagonal architectures on AWS](welcome.html) +[Documentation](/index.html)[AWS Prescriptive Guidance](https://aws.amazon.com/prescriptive-guidance/)[Building hexagonal architectures on AWS](introduction.html) @@ -13 +13 @@ Model the business domainWrite and run tests from the beginningDefine the behavi -Work back from the business domain to the software design to ensure that that the software you’re writing fits the business need. +Work back from the business domain to the software design to ensure that that the software you're writing fits the business need. @@ -19 +19 @@ Use domain-driven design (DDD) methodologies such as [event storming](https://ww -Use test-driven development (TDD) to verify the correctness of the software that you are developing. TDD works best at a unit test level. The developer designs a software component by writing a test first, which invokes that component. That component has no implementation at the beginning, therefore the test fails. As a next step, the developer implements the component’s functionality, using test fixtures with mock objects to simulate the behavior of external dependencies, or ports. When the test succeeds, the developer can continue by implementing real adapters. This approach improves software quality and results in more readable code, because developers understand how users would use the components. Hexagonal architecture supports the TDD methodology by separating the application core. Developers write unit tests that focus on the domain core behavior. They don’t have to write complex adapters to run their tests; instead, they can use simple mock objects and fixtures. +Use test-driven development (TDD) to verify the correctness of the software that you are developing. TDD works best at a unit test level. The developer designs a software component by writing a test first, which invokes that component. That component has no implementation at the beginning, therefore the test fails. As a next step, the developer implements the component's functionality, using test fixtures with mock objects to simulate the behavior of external dependencies, or ports. When the test succeeds, the developer can continue by implementing real adapters. This approach improves software quality and results in more readable code, because developers understand how users would use the components. Hexagonal architecture supports the TDD methodology by separating the application core. Developers write unit tests that focus on the domain core behavior. They don't have to write complex adapters to run their tests; instead, they can use simple mock objects and fixtures. @@ -46,3 +46 @@ After an initial proof of concept, we recommend that you invest time implementin -If your product is successful, scale your product by decomposing your software project into microservices. Utilize the portability that hexagonal architecture provides to improve performance. Split query services and command handlers into separate synchronous and asynchronous APIs. Consider adopting the command query responsibility segregation (CQRS) pattern and event-driven architecture. - -If you get many new feature requests, consider scaling your organization based on DDD patterns. Structure your teams in such a way that they own one or more features as bounded contexts, as discussed previously in the [Organizational scaling](./adapt-to-change.html#scaling) section. These teams can then implement business logic by using hexagonal architecture. +If your product is successful, scale your product by decomposing your software project into microservices. Utilize the portability that hexagonal architecture provides to improve performance. Split query services and command handlers into separate synchronous and asynchronous APIs. Consider adopting the command query responsibility segregation (CQRS) pattern and event-driven architecture. If you get many new feature requests, consider scaling your organization based on DDD patterns. Structure your teams in such a way that they own one or more features as bounded contexts, as discussed previously in the [Organizational scaling](./adapt-to-change.html#scaling) section. These teams can then implement business logic by using hexagonal architecture. @@ -54 +52 @@ Infrastructure as code (IaC) is a widely adopted practice in cloud development. -We recommend that you divide your application into three folders or projects that map to the concepts of hexagonal architecture: `entrypoints` (primary adapters), `domain` (domain and interfaces), and `adapters` (secondary adapters). +We recommend that you divide your application into three folders or projects that map to the concepts of hexagonal architecture: entrypoints (primary adapters), domain (domain and interfaces), and adapters (secondary adapters). @@ -56 +54 @@ We recommend that you divide your application into three folders or projects tha -The following project structure provides an example of this approach when designing an API on AWS. The project maintains application code (`app`) and infrastructure code (`infra`) in the same repository, as recommended earlier. +The following project structure provides an example of this approach when designing an API on AWS. The project maintains application code (app) and infrastructure code (infra) in the same repository, as recommended earlier. @@ -60,14 +58,14 @@ The following project structure provides an example of this approach when design - |--- adapters/ # implementation of the ports defined in the domain - |--- tests/ # adapter unit tests - |--- entrypoints/ # primary adapters, entry points - |--- api/ # api entry point - |--- model/ # api model - |--- tests/ # end to end api tests - |--- domain/ # domain to implement business logic using hexagonal architecture - |--- command_handlers/ # handlers used to run commands on the domain - |--- commands/ # commands on the domain - |--- events/ # events emitted by the domain - |--- exceptions/ # exceptions defined on the domain - |--- model/ # domain model - |--- ports/ # abstractions used for external communication - |--- tests/ # domain tests + |--- adapters/ # implementation of the ports defined in the domain + |--- tests/ # adapter unit tests + |--- entrypoints/ # primary adapters, entry points + |--- api/ # api entry point + |--- model/ # api model + |--- tests/ # end to end api tests + |--- domain/ # domain to implement business logic using hexagonal architecture + |--- command_handlers/ # handlers used to run commands on the domain + |--- commands/ # commands on the domain + |--- events/ # events emitted by the domain + |--- exceptions/ # exceptions defined on the domain + |--- model/ # domain model + |--- ports/ # abstractions used for external communication + |--- tests/ # domain tests @@ -76 +74 @@ The following project structure provides an example of this approach when design -As discussed earlier, the domain is the core of the application and doesn’t depend on any other module. We recommend that you structure the `domain` folder to include the following subfolders: +As discussed earlier, the domain is the core of the application and doesn't depend on any other module. We recommend that you structure the domain folder to include the following subfolders: @@ -78 +76 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `command handlers` contains the methods or classes that run commands on the domain. + * command handlers contains the methods or classes that run commands on the domain. @@ -80 +78 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `commands` contains the command objects that define the information required to perform an operation on the domain. + * commands contains the command objects that define the information required to perform an operation on the domain. @@ -82 +80 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `events` contains the events that are emitted through the domain and then routed to other microservices. + * events contains the events that are emitted through the domain and then routed to other microservices. @@ -84 +82 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `exceptions` contains the known errors defined within the domain. + * exceptions contains the known errors defined within the domain. @@ -86 +84 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `model` contains the domain entities, value objects, and domain services. + * model contains the domain entities, value objects, and domain services. @@ -88 +86 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `ports` contains the abstractions through which the domain communicates with databases, APIs, or other external components. + * ports contains the abstractions through which the domain communicates with databases, APIs, or other external components. @@ -90 +88 @@ As discussed earlier, the domain is the core of the application and doesn’t de - * `tests` contains the test methods (such as business logic tests) that are run on the domain. + * tests contains the test methods (such as business logic tests) that are run on the domain. @@ -95 +93 @@ As discussed earlier, the domain is the core of the application and doesn’t de -The primary adapters are the entry points to the application, as represented by the `entrypoints` folder. This example uses the `api` folder as the primary adapter. This folder contains an API `model`, which defines the interface the primary adapter requires to communicate with clients. The `tests` folder contains end-to-end tests for the API. These are shallow tests that validate that the components of the application are integrated and work in harmony. +The primary adapters are the entry points to the application, as represented by the entrypoints folder. This example uses the api folder as the primary adapter. This folder contains an API model, which defines the interface the primary adapter requires to communicate with clients. The tests folder contains end-to-end tests for the API. These are shallow tests that validate that the components of the application are integrated and work in harmony. @@ -97 +95 @@ The primary adapters are the entry points to the application, as represented by -The secondary adapters, as represented by the `adapters` folder, implement the external integrations required by the domain ports. A database repository is a great example of a secondary adapter. When the database system changes, you can write a new adapter by using the implementation that’s defined by the domain. There is no need to change the domain or business logic. The `tests` subfolder contains external integration tests for each adapter. +The secondary adapters, as represented by the adapters folder, implement the external integrations required by the domain ports. A database repository is a great example of a secondary adapter. When the database system changes, you can write a new adapter by using the implementation that's defined by the domain. There is no need to change the domain or business logic. The tests subfolder contains external integration tests for each adapter. @@ -107 +105 @@ Adapting to change -Infrastructure examples +Infrastructure examples on AWS