Clean API Architecture with IaC

The Clean API Archectecture approach is a design pattern that is intended to help developers build scalable, maintainable, and testable APIs. The approach emphasizes the use of layers, separation of concerns, and the use of design patterns to help developers build better APIs. Although Clean Code pricipals are largly not used, Dependancy Injection is used in the CDKTF Infrastructure as Code Files to help organize the code in a flattened and sequential mannor.

Stack Anatomy Diagram

Stacks as Groups of Serverless Services

Each stack is a seperate project within the repo and are designed to be deployed independantly. The term Stack is used as a collection of serverless and microservices rather than compute instances and/or virtual machines. Although, if needed, instances and virtual machines (eg: using Docker or EC2 instances) could be added to existing stacks or as newly created stacks.

Stack File Structure Overview

Stacks will have a folder structure that represents the Clean API Archetecture layers. Layers are included only when needed. The exhaustive generic folder structure of a stack is as follows:

• DirectorystackName

  • stackNameStack.ts // root IaC file that contains the code to deploy the stack
  • Directoryapp

    • Directoryservice-genericServiceName1

      • service.ts //IaC file that contains the code to deploy the specificservice
      • DirectoryspecificServiceName1 //contains the files required for the specific service outlined in service.ts

        • specificServiceFile1.ts
        • specificServiceFile2.ts
        • …
      • DirectoryspecificServiceSharedResourcesFolder // optional folder that contains files/classes/snippets that are shared across the services in the folders above

        • serviceSharedResource1.ts
        • serviceSharedResource2.ts
        • …
      • tests //optional folder that contains the test files for the specific service
    • Directoryservice-genericServiceName2

      • …
    • Directorytests //optional folder that contains the test files for the vartious services

      • specificServiceFile1.test.ts
      • specificServiceFile2.test.ts
      • …
  • Directoryentities

    • DirectoryspecificEntityName

      • specificEntityCode.ts //this code can be referred to by applicatin services
    • Directorytests

      • specificEntityCode.test.ts //independant test code here
  • Directoryinfrastructure // this folder contains all the Infrastructure code for use in the stackNameStack.ts root Iac file. eg any AWS, Stripe, Google Cloud, Azure, etc., resources are defined here.

    • Directoryaws

      • specificResource1.ts //example of a specific resource
      • specificResource2.ts //example of a specific resource
    • Directorystripe

      • specificResource1.ts //example of a specific resource
      • specificResource2.ts //example of a specific resource
    • googleCloud
    • …
  • Directoryinterface // this folder contains the code for bridging the infrastructure resources to the application layer. It’s fine to break out the controllers and the presenters in their own folder but ir’s joined here as it’s more like one set if files defining both.

    • DirectorycontrollerPresenter-specificName1

      • specificController1.ts
      • specificController2.ts
      • …
      • Directorytests

        • specificController1.test.ts
        • specificController2.test.ts
        • …
    • Directorygateway-specificName1

      • specificGateway1.ts
      • specificGateway2.ts
      • Directorytests

        • specificGateway1.test.ts
      • …
  • Directorytests // optional folder that contains the test files for the interface adapters

    • specificInterfaceFile1.test.ts
    • …

Although extensive, most stack folders and files will contain only what folders and files are necessary for the stack. Some stacks (eg: the blueGreenToggleStack) will only have Infrastructure as Code files and no Interface or Application logic folders/files at all.

• Directorystacks

  • DirectoryblueGreenToggle

    • blueGreenToggleStack.ts

Avoiding A Single Giant IaC Stack

IaC can become a gigantic Stack or collection of files that can become difficult for teams or individuals to navigate. This is a common pitfall in IaC repos. s6pack.build uses a collection-of-stacks approach.

These stacks can communicate between eachother as dependancies. They are deployed sometimes in sequence, but more oftenly deployed individually. This is so that only stacks that require updates are deployed as necessary. This speeds up time deploying stacks as well as troubleshooting since stack code files are more bite-sized.