# getlift/lift architecture

> Architecture diagram of the GitHub repository getlift/lift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getlift/lift
- Repository: https://github.com/getlift/lift

## Overview

##### Project Type and Purpose
- Type: Open-source Serverless Framework plugin
- Purpose: Expose high-level “constructs” (static websites, SPAs, queues, storage, etc.) in serverless.yml by generating AWS CDK constructs and synthesizing CloudFormation templates.

##### Key Architectural Components
A. Serverless Framework CLI
– Entry point for users writing serverless.yml
– Loads plugins (including serverless-lift) and executes hooks (deploy, package, invoke, etc.)

B. serverless-lift Plugin (src/plugin.ts)
– Registers itself with the Serverless Framework hook system
– Parses the “constructs” section in serverless.yml
– For each construct: instantiates the right Construct class via an internal registry

C. Construct Layer (src/constructs)
– ConstructInterface / StaticConstructInterface define the public API
– Concrete constructs under src/constructs/aws (e.g., StaticWebsite, Queue, Storage, Webhook, DynamoDBSingleTable, Vpc, ServerSideWebsite, SinglePageApp)
– Each construct implements a high-level resource definition and CDK best practices

D. CloudFormation Synthesis (src/CloudFormation.ts)
– Orchestrates AWS CDK App and Stack creation
– Feeds in CDK constructs from the Construct layer
– Synthesizes a CloudFormation template (JSON/YAML)

E. Provider Abstraction (src/providers)
– ProviderInterface / StaticProviderInterface define hooks to integrate into different runtimes
– AwsProvider implements AWS-specific logic: credentials resolution, region, environment, bootstrapping CDK context

F. Utilities (src/utils)
– Helper functions (logger, naming conventions, error handling, S3 sync, sleep, CFN function associations)

G. Testing and Fixtures (test/)
– Unit tests for each construct and utility
– End-to-end fixtures for common serverless.yml variations

##### Relationships & Data Flow
1. User runs “serverless deploy”
2. Serverless Framework loads serverless-lift plugin
3. plugin.ts:
– Reads “constructs” from serverless.yml
– For each construct:
a. Selects provider (AwsProvider)
b. Instantiates the Construct class
c. Calls its “toCloudFormation” or equivalent method
4. Constructs call into CloudFormation.ts:
– Build CDK App & Stack, add CDK resources
– Stack.synth() generates CloudFormation template
5. Serverless Framework receives synthesized template and merges with functions, resources sections, then deploys to AWS via CloudFormation
6. (Optional) User runs “serverless lift eject” to export CFN template directly

##### Architectural Patterns & Principles
- Plugin architecture: decouples CLI integration from core logic
- Factory/Registry: dynamic instantiation of constructs by name/type
- Adapter/Provider: abstracts AWS-specific behavior to allow future providers
- Composition over inheritance: constructs compose CDK low-level constructs
- Single Responsibility: each file/class has one primary concern

##### Detailed Elements to Capture
– plugin.ts as orchestrator
– src/constructs/abstracts vs. src/constructs/aws implementations
– src/providers/AwsProvider role
– src/CloudFormation.ts synthesizer
– How utilities support naming and syncing
– Interaction between user’s serverless.yml constructs block and the plugin

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "CLI & Plugin"
    CLI["Serverless CLI"]:::external
    Plugin["Lift Plugin"]:::plugin
  end

  subgraph "Construct Factory"
    Registry["Construct Registry"]:::factory
    CI["ConstructInterface"]:::interface
    SCI["StaticConstructInterface"]:::interface
    ABase["AwsConstruct Abstract"]:::abstract
  end

  subgraph "AWS Constructs"
    SW["StaticWebsite"]:::construct
    SPA["SinglePageApp"]:::construct
    SSW["ServerSideWebsite"]:::construct
    Q["Queue"]:::construct
    STG["Storage"]:::construct
    DB["DynamoDBSingleTable"]:::construct
    VPC["Vpc"]:::construct
    WH["Webhook"]:::construct
  end

  subgraph "CloudFormation"
    Synth["Synthesizer"]:::synth
    CFN["Generated CFN Template"]:::artifact
  end

  subgraph "Providers"
    PEntry["Providers Entry"]:::factory
    PI["ProviderInterface"]:::interface
    SPI["StaticProviderInterface"]:::interface
    AwsProv["AwsProvider"]:::provider
    StripeProv["StripeProvider"]:::provider
  end

  subgraph "Utilities"
    Lg["Logger"]:::util
    Nm["Naming"]:::util
    Err["Error Handling"]:::util
    S3["S3 Sync"]:::util
    Slp["Sleep"]:::util
    CFNA["CFN Function Assoc."]:::util
  end

  subgraph "CDK Helpers"
    CHAWS["aws.ts"]:::helper
    CHCF["cloudfrontFunctions.ts"]:::helper
  end

  subgraph "Testing"
    UT["Unit Tests"]:::test
    FX["Fixtures"]:::test
    RS["runServerless.ts"]:::test
    RSC["runServerlessCli.ts"]:::test
    MA["mockAws.ts"]:::test
  end

  CLI -->|"load plugin"| Plugin
  Plugin -->|"uses registry"| Registry
  Registry --> CI
  Registry --> SCI
  Registry --> ABase
  Registry -->|"instantiates"| SW & SPA & SSW & Q & STG & DB & VPC & WH
  Plugin -->|"selects provider"| PEntry
  PEntry --> PI
  PEntry --> SPI
  PEntry --> AwsProv
  PEntry --> StripeProv
  SW & SPA & SSW & Q & STG & DB & VPC & WH -->|"toCloudFormation()"| Synth
  Synth --> CFN
  CLI -->|"deploy CFN"| CFN

  Plugin --> Lg
  CI --> Nm
  ABase --> Err
  Synth --> S3
  Synth --> Slp
  Synth --> CFNA
  SW & SPA & SSW & Q & STG & DB & VPC & WH --> CHAWS
  SW & SPA & SSW & Q & STG & DB & VPC & WH --> CHCF

  UT --> CI
  UT --> SW
  FX --> UT
  RS --> Plugin
  RSC --> CLI
  MA --> AwsProv

  click Plugin "https://github.com/getlift/lift/blob/master/src/plugin.ts"
  click CI "https://github.com/getlift/lift/blob/master/src/constructs/ConstructInterface.ts"
  click SCI "https://github.com/getlift/lift/blob/master/src/constructs/StaticConstructInterface.ts"
  click ABase "https://github.com/getlift/lift/blob/master/src/constructs/abstracts/AwsConstruct.ts"
  click SW "https://github.com/getlift/lift/blob/master/src/constructs/aws/StaticWebsite.ts"
  click SPA "https://github.com/getlift/lift/blob/master/src/constructs/aws/SinglePageApp.ts"
  click SSW "https://github.com/getlift/lift/blob/master/src/constructs/aws/ServerSideWebsite.ts"
  click Q "https://github.com/getlift/lift/blob/master/src/constructs/aws/Queue.ts"
  click STG "https://github.com/getlift/lift/blob/master/src/constructs/aws/Storage.ts"
  click DB "https://github.com/getlift/lift/blob/master/src/constructs/aws/DatabaseDynamoDBSingleTable.ts"
  click VPC "https://github.com/getlift/lift/blob/master/src/constructs/aws/Vpc.ts"
  click WH "https://github.com/getlift/lift/blob/master/src/constructs/aws/Webhook.ts"
  click Registry "https://github.com/getlift/lift/blob/master/src/constructs/index.ts"
  click PEntry "https://github.com/getlift/lift/blob/master/src/providers/index.ts"
  click PI "https://github.com/getlift/lift/blob/master/src/providers/ProviderInterface.ts"
  click SPI "https://github.com/getlift/lift/blob/master/src/providers/StaticProviderInterface.ts"
  click AwsProv "https://github.com/getlift/lift/blob/master/src/providers/AwsProvider.ts"
  click StripeProv "https://github.com/getlift/lift/blob/master/src/providers/StripeProvider.ts"
  click Synth "https://github.com/getlift/lift/blob/master/src/CloudFormation.ts"
  click Lg "https://github.com/getlift/lift/blob/master/src/utils/logger.ts"
  click Nm "https://github.com/getlift/lift/blob/master/src/utils/naming.ts"
  click Err "https://github.com/getlift/lift/blob/master/src/utils/error.ts"
  click S3 "https://github.com/getlift/lift/blob/master/src/utils/s3-sync.ts"
  click Slp "https://github.com/getlift/lift/blob/master/src/utils/sleep.ts"
  click CFNA "https://github.com/getlift/lift/blob/master/src/utils/getDefaultCfnFunctionAssociations.ts"
  click CHAWS "https://github.com/getlift/lift/blob/master/src/classes/aws.ts"
  click CHCF "https://github.com/getlift/lift/blob/master/src/classes/cloudfrontFunctions.ts"
  click UT "https://github.com/getlift/lift/tree/master/test/unit/"
  click FX "https://github.com/getlift/lift/tree/master/test/fixtures/"
  click RS "https://github.com/getlift/lift/blob/master/test/utils/runServerless.ts"
  click RSC "https://github.com/getlift/lift/blob/master/test/utils/runServerlessCli.ts"
  click MA "https://github.com/getlift/lift/blob/master/test/utils/mockAws.ts"

  classDef external fill:#f9f,stroke:#333,stroke-width:1px
  classDef plugin fill:#bbf,stroke:#333,stroke-width:1px
  classDef factory fill:#bfb,stroke:#333,stroke-width:1px
  classDef interface fill:#ffb,stroke:#333,stroke-width:1px
  classDef abstract fill:#fbb,stroke:#333,stroke-width:1px
  classDef construct fill:#fbf,stroke:#333,stroke-width:1px
  classDef synth fill:#bff,stroke:#333,stroke-width:1px
  classDef artifact fill:#ffd,stroke:#333,stroke-width:1px
  classDef provider fill:#cdf,stroke:#333,stroke-width:1px
  classDef util fill:#eee,stroke:#333,stroke-width:1px
  classDef helper fill:#def,stroke:#333,stroke-width:1px
  classDef test fill:#ece,stroke:#333,stroke-width:1px
```
