@taktikorg/maiores-architecto NPM

@cats-cradle

The problem

Running multiple applications in the cloud without a solid architectural framework is akin to constructing a house without blueprints - it invites chaos. While many resources focus solely on single-application setups, cloud architecture encompasses an entire city, not just one building. Without a coherent plan in place, any attempt to make changes becomes a daunting task.

This solution

This cloud architecture focuses on modern DevOps practices on AWS^1. This approach transcends individual projects; we're laying the groundwork for the entire landscape of enterprise software on AWS.

It's a practical demonstration featuring tangible code, driving a cooperative RPG.

Features

The below features outline the principles and standards applicable to this repository. Each piece contributes harmoniously to the overall cityscape we're constructing.

A package base monorepo approach is preferred as to create a clear separation in layers. Microsoft backed Rush was selected over Nx, Lerna, Turbo, etc. for monorepo management. Nx is also suitable, but rush has worked fine so far.

The code is divided into several categories: libraries, platform, services, middleware, and clients. Each is further defined in there retrospective folders. When it comes to individual package files, those that typically change in tandem SHOULD generally be kept together. The organization of code SHOULD be based on features. All project dependencies MUST be unidirectional dependencies.

We selected AWS as our Infrastructure as a Service (IaaS) provider because of the advantages of vendor lock-in, allowing us access to a diverse array of standardized services. In this project, prioritizing these benefits takes precedence over maintaining cloud agnosticism. We anticipate potential project failure before AWS, and we've accounted for the potential cost of migrating between IaaS providers. Our approach involves intentional structuring of layers and relies primarily on features offered by multiple cloud providers.

The entire infrastructure is defined as code, allowing for version control, easy replication, and consistent environments across different stages of the development lifecycle. All Infrastructure as Code MUST be defined as or compile to CloudFormation templates.

Getting Started

Setting up Development Environment

The quickest way to start a develop environment is by clicking open in Github Codespaces. To actually save and commit changes back it is recommended to forking the repo .

Alternatively, git clone and install locally using a devcontainer. It's possible to install without a container using the Dockerfile as guidance on package to install.

Flow Chart

Implementing AWS Multi-Account Architecture

These steps only need to be performed once by the platform team to initalize the IaaS.

Setup AWS Org Formation.

rush sso
rush cdk:bootstrap
rush cdk:deploy --to tag:deploy-platform
rush cdk:deploy --to tag:services
rush cdk:deploy --to tag:middleware
rush cdk:deploy --to tag:clients

rush sso -p tools
rush cdk:bootstrap
rush cdk:deploy --to tag:deploy-tools

Documentation

Documentation SHOULD be maintained where it will be looked for. A README.md file SHOULD be added to explain each project and important folder structures. README.md files instructions should adhere to RFC 2119^2. Any code that isn't self-documenting MUST be accompanied by documentation. Tsdoc MAY be selected as a standard for writing Typescript documentation. Typedoc MAY be selected to compile documentation as code.

Note Use rush help for information on builtin commands.

Contributing

We welcome contributions of any size to this open-source project. Please follow the code of conduct when contributing.

Pull requests and bug reports are welcome on GitHub at https://github.com/taktikorg/maiores-architecto.

Checkout a new branch from main using git.
```
git checkout -b feature/improve-readme
```
Work on changes (e.g. fix a bug or add a new feature). Test-driven development encouraged.
```
rushx dev
rushx test
```

Stage and commit changes using conventional commits.

git add .
git commit -m 'doc: fix spelling of computers'

(Optional) If changing a library that is published to NPM, document semantic version changes, generate Changelogs, and commit changes.
```
rush change
rush version --bump
git commit -m 'chore: bump change log'
```
Push code and open a PR. Celebrate contributing to @cats-cradle.
```
git push
```

Acknowledgements

License

Packages available on NPM are MIT licensed. Packages without a specific license have not yet been developed with reuse in mind and are primarily maintained for the game. Simply remove these projects when setting up your architecture.

^1: Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations Paperback – Illustrated, March 27, 2018 by Nicole Forsgren PhD (Author), Jez Humble (Author), Gene Kim (Author).

^2: This document adheres to the guidelines outlined in RFC 2119, which defines the standard interpretations of key words used in IETF documents. These key words include "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL". The usage of these words in this document follows the specifications set forth in RFC 2119, ensuring clarity and consistency in the requirements and recommendations presented herein.