Unicorn approvals

.github/dependabot.yml

@@ -8,7 +8,7 @@ updates:
   - package-ecosystem: "pip" # See documentation for possible values
     directories: 
       - "unicorn_contracts" # Location of package manifests
-      - "unicorn_properties"
+      - "unicorn_approvals"
       - "unicorn_web"
     schedule:
       interval: "weekly"

.github/workflows/auto_assign.yml

@@ -7,4 +7,4 @@ jobs:
   add-reviews:
     runs-on: ubuntu-latest
     steps:
-      - uses: kentaro-m/auto-assign-action@v1.2.5
+      - uses: kentaro-m/auto-assign-action@v2.0.0

.github/workflows/build.yml

@@ -0,0 +1,80 @@
+name: Build Python Services
+
+on:
+  push:
+    branches: [develop, main]
+    paths:
+      - 'unicorn_contracts/**'
+      - 'unicorn_approvals/**'
+      - 'unicorn_web/**'
+  pull_request:
+    branches: [develop, main]
+    paths:
+      - 'unicorn_contracts/**'
+      - 'unicorn_approvals/**'
+      - 'unicorn_web/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service: [unicorn_contracts, unicorn_approvals, unicorn_web]
+        include:
+          - service: unicorn_contracts
+            display_name: Unicorn Contracts Service
+          - service: unicorn_approvals
+            display_name: Unicorn Approvals Service
+          - service: unicorn_web
+            display_name: Unicorn Web Service
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: 0.7.8
+
+      - name: Install AWS SAM CLI
+        uses: aws-actions/setup-sam@v2
+
+      - name: Install cfn-lint and plugins
+        run: |
+          pip install cfn-lint
+          pip install cfn-lint-serverless
+
+      - name: Install yq
+        run: |
+          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
+          sudo chmod a+x /usr/local/bin/yq
+
+      - name: Initialize dependencies for ${{ matrix.display_name }}
+        run: make ci_init
+        working-directory: ./${{ matrix.service }}
+
+      - name: Build ${{ matrix.display_name }}
+        run: |
+          # Use uv run to ensure all commands run in the virtual environment
+          uv run make build
+        working-directory: ./${{ matrix.service }}
+        env:
+          DOCKER_OPTS: --use-container
+
+      - name: Upload build artifacts for ${{ matrix.display_name }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.service }}-build-artifacts
+          path: ${{ matrix.service }}/.aws-sam/
+          retention-days: 7
+
+      - name: Clean up ${{ matrix.display_name }}
+        run: uv run make clean
+        working-directory: ./${{ matrix.service }}
+        if: always() 

.github/workflows/codeql-analysis.yml

@@ -25,18 +25,18 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@2ca79b6fa8d3ec278944088b4aa5f46912db5d63  #v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
 
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     # - name: Autobuild
-    #   uses: github/codeql-action/autobuild@2ca79b6fa8d3ec278944088b4aa5f46912db5d63  #v2
+    #   uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -49,4 +49,4 @@ jobs:
     #   ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@2ca79b6fa8d3ec278944088b4aa5f46912db5d63  #v2
+      uses: github/codeql-action/analyze@v3

.github/workflows/label_pr_on_title.yml

@@ -22,9 +22,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: "Label PR based on title"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           PR_NUMBER: ${{ needs.get_pr_details.outputs.prNumber }}
           PR_TITLE: ${{ needs.get_pr_details.outputs.prTitle }}

.github/workflows/on_label_added.yml

@@ -23,10 +23,10 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       # Maintenance: Persist state per PR as an artifact to avoid spam on label add
       - name: "Suggest split large Pull Request"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           PR_NUMBER: ${{ needs.get_pr_details.outputs.prNumber }}
           PR_ACTION: ${{ needs.get_pr_details.outputs.prAction }}

.github/workflows/on_merged_pr.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
     if: needs.get_pr_details.outputs.prIsMerged == 'true'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "Label PR related issue for release"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           PR_NUMBER: ${{ needs.get_pr_details.outputs.prNumber }}
           PR_BODY: ${{ needs.get_pr_details.outputs.prBody }}

.github/workflows/on_opened_pr.yml

@@ -19,9 +19,9 @@ jobs:
     needs: get_pr_details
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "Ensure related issue is present"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           PR_BODY: ${{ needs.get_pr_details.outputs.prBody }}
           PR_NUMBER: ${{ needs.get_pr_details.outputs.prNumber }}
@@ -36,9 +36,9 @@ jobs:
     needs: get_pr_details
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "Ensure acknowledgement section is present"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           PR_BODY: ${{ needs.get_pr_details.outputs.prBody }}
           PR_NUMBER: ${{ needs.get_pr_details.outputs.prNumber }}

.github/workflows/record_pr.yml

@@ -9,14 +9,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: "Extract PR details"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         with:
           script: |
             const script = require('.github/scripts/save_pr_details.js')
             await script({github, context, core})
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: pr
           path: pr.txt

.github/workflows/reusable_export_pr_details.yml

@@ -59,9 +59,9 @@ jobs:
       prIsMerged: ${{ steps.prIsMerged.outputs.prIsMerged }}
     steps:
       - name: Checkout repository # in case caller workflow doesn't checkout thus failing with file not found
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: "Download previously saved PR"
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         env:
           WORKFLOW_ID: ${{ inputs.record_pr_workflow_id }}
         # For security, we only download artifacts tied to the successful PR recording workflow

.github/workflows/reusable_unit_tests.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v4
         with: { python-version: 3.12 }

.github/workflows/services_unit_tests.yml

@@ -3,13 +3,13 @@ on:
     branches: [develop, main]
     paths:
       - 'unicorn_contracts/**'
-      - 'unicorn_properties/**'
+      - 'unicorn_approvals/**'
       - 'unicorn_web/**'
   pull_request:
     branches: [develop, main]
     paths:
       - 'unicorn_contracts/**'
-      - 'unicorn_properties/**'
+      - 'unicorn_approvals/**'
       - 'unicorn_web/**'
 
 jobs:
@@ -18,10 +18,10 @@ jobs:
     with:
       service_directory: unicorn_contracts
 
-  unicorn_properties:
+  unicorn_approvals:
     uses: ./.github/workflows/reusable_unit_tests.yml
     with:
-      service_directory: unicorn_properties
+      service_directory: unicorn_approvals
 
   unicorn_web:
     uses: ./.github/workflows/reusable_unit_tests.yml

README.md

@@ -1,42 +1,38 @@
-<img src="./docs/workshop_logo.png" alt="AWS Serverless Developer Experience Workshop Reference Architecture" width="80%" />
+[![Build & Test Workflow](https://github.com/aws-samples/aws-serverless-developer-experience-workshop-python/actions/workflows/build.yml/badge.svg)](https://github.com/aws-samples/aws-serverless-developer-experience-workshop-python/actions/workflows/build.yml)
 
 # AWS Serverless Developer Experience workshop reference architecture (Python)
 
-This repository contains the reference architecture for the AWS Serverless Developer Experience workshop.
+<img src="./docs/workshop_logo.png" alt="AWS Serverless Developer Experience Workshop Reference Architecture" width="80%" />
+
+This repository contains the Python reference architecture for the AWS Serverless Developer Experience workshop.
 
-The AWS Serverless Developer Experience workshop provides you with an immersive experience as a serverless developer. The goal of this workshop is to provide you with hands-on experience building a serverless solution using the [**AWS Serverless Application Model (AWS SAM)**](https://aws.amazon.com/serverless/sam/) and **AWS SAM CLI**.
+The AWS Serverless Developer Experience Workshop is a comprehensive, hands-on training program designed to equip developers with practical serverless development skills using the [**AWS Serverless Application Model (AWS SAM)**](https://aws.amazon.com/serverless/sam/) and **AWS SAM CLI**.
 
-Along the way, you will learn about principals of distributed event-driven  architectures, messaging patterns, orchestration, and observability and how to apply them in code. You will explore exciting open-source tools, the core features of Powertools for AWS Lambda, and simplified CI/CD deployments supported by AWS SAM Pipelines.
+The workshop employs a practical, code-centric approach, emphasizing direct implementation and real-world scenario exploration to ensure you develop serverless development skills across several critical areas including distributed event-driven architectures, messaging patterns, orchestration, and observability. You will explore open-source tools, [Powertools for AWS](https://powertools.aws.dev/), and simplified CI/CD deployments with AWS SAM Pipelines. By the end, you will be familiar with serverless developer workflows, microservice composition using AWS SAM, serverless development best practices, and applied event-driven architectures.
 
-At the end of this workshop, you will be familiar with Serverless developer workflows and microservice composition using AWS SAM, Serverless development best practices, and applied event-driven architectures.
+The 6-8 hour workshop assumes your practical development skills in Python, TypeScript, Java, or .NET, and familiarity with [Amazon API Gateway](https://aws.amazon.com/apigateway/), [AWS Lambda](https://aws.amazon.com/lambda/), [Amazon EventBridge](https://aws.amazon.com/eventbridge/), [AWS Step Functions](https://aws.amazon.com/step-functions/), and [Amazon DynamoDB](https://aws.amazon.com/dynamodb/).
 
 ## Introducing the Unicorn Properties architecture
 
 ![AWS Serverless Developer Experience Workshop Reference Architecture](./docs/architecture.png)
 
-Our use case is based on a real estate company called **Unicorn Properties**.
-
-As a real estate agency, **Unicorn Properties** needs to manage the publishing of new property listings and sale contracts linked to individual properties, and provide a way for their customers to view approved property listings.
-
-To support their needs, Unicorn Properties have adopted a serverless, event-driven approach to designing their architecture. This architecture is centred around two primary domains: **Contracts** (managed by the Contracts Service) and **Properties** (managed by the Web and Properties Services).
-
-The **Unicorn Contracts** service (namespace: `Unicorn.Contracts`) is a simplified service that manages the contractual relationship between a seller of a property and Unicorn Properties. Contracts are drawn up that define the property for sale, the terms and conditions that Unicorn Properties sets, and how much it will cost the seller to engage the services of the agency.
+Real estate company **Unicorn Properties** needs to manage publishing of new property listings and sale contracts linked to individual properties, and provide a way for customers to view approved listings. They adopted a serverless, event-driven architecture with two primary domains: **Contracts** (managed by the Contracts Service) and **Properties** (managed by the Web and Approvals Services).
 
-The **Unicorn Web** (namespace: `Unicorn.Web`) manages the details of a property listing to be published on the Unicorn Properties website. Every property listing has an address, a sale price, a description of the property, and some photos that members of the public can look at to get them interested in purchasing the property. Only properties that have been approved for publication can be made visible to the public.
+**Unicorn Contracts** (using the `Unicorn.Contracts` namespace) service manages contractual relationships between property sellers and Unicorn Approvals, defining properties for sale, terms, and engagement costs.
 
-The **Unicorn Properties** service (namespace: `Unicorn.Properties`) approves a property listings. This service implements a workflow that checks for the existence of a contract, makes sure that the content and the images are safe to publish, and finally checks that the contract has been approved. We don’t want to publish a property until we have an approved contract!
+**Unicorn Approvals** (using the `Unicorn.Approvals` namespace) service approves property listings by implementing a workflow that checks for contract existence, content and image safety, and contract approval before publishing.
 
-Have a go at building this architecture yourself! Head over to the [Serverless Developer Experience Workshop](https://catalog.workshops.aws/serverless-developer-experience) for more details.
+**Unicorn Web** (using the `Unicorn.Web` namespace) manages property listing details (address, sale price, description, photos) to be published on the website, with only approved listings visible to the public.
 
 ## Credits
 
-Throughout this workshop we wanted to introduce you to some Open Source tools that can help you build serverless applications. This is not an exhaustive list, just a small selection of what we will be using in the workshop.
+This workshop introduces you to some open-source tools that can help you build serverless applications. This is not an exhaustive list, but a small selection of what you will be using in the workshop.
 
 Many thanks to all the AWS teams and community builders who have contributed to this list:
 
-| Tools                 | Description | Download / Installation Instructions |
-| --------------------- | ----------- | --------------------------------------- |
-| cfn-lint | Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation Resource Specification and additional checks. | https://github.com/aws-cloudformation/cfn-lint |
-| cfn-lint-serverless | Compilation of rules to validate infrastructure-as-code templates against recommended practices for serverless applications. | https://github.com/awslabs/serverless-rules |
-| @mhlabs/iam-policies-cli| CLI for generating AWS IAM policy documents or SAM policy templates based on the JSON definition used in the AWS Policy Generator. | https://github.com/mhlabs/iam-policies-cli |
-| @mhlabs/evb-cli | Pattern generator and debugging tool for Amazon EventBridge | https://github.com/mhlabs/evb-cli |
+| Tools                    | Description                                                                                                                        | Download / Installation Instructions           |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| cfn-lint                 | Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation Resource Specification and additional checks.       | https://github.com/aws-cloudformation/cfn-lint |
+| cfn-lint-serverless      | Compilation of rules to validate infrastructure-as-code templates against recommended practices for serverless applications.       | https://github.com/awslabs/serverless-rules    |
+| @mhlabs/iam-policies-cli | CLI for generating AWS IAM policy documents or SAM policy templates based on the JSON definition used in the AWS Policy Generator. | https://github.com/mhlabs/iam-policies-cli     |
+| @mhlabs/evb-cli          | Pattern generator and debugging tool for Amazon EventBridge                                                                        | https://github.com/mhlabs/evb-cli              |

pyproject.toml

@@ -0,0 +1,6 @@
+[project]
+name = "aws-serverless-developer-experience-workshop-python"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.12"
+dependencies = []

unicorn_approvals/README.md

@@ -0,0 +1,15 @@
+# Developing Unicorn Approvals
+
+![Properties Approval Architecture](https://static.us-east-1.prod.workshops.aws/public/f273b5fc-17cd-406b-9e63-1d331b00589d/static/images/architecture-approvals.png)
+
+## Architecture overview
+
+**Unicorn Approvals** uses an AWS Step Functions state machine to approve property listings for Unicorn Web. The workflow checks for contract information, description sentiment and safe images, and verifies the contract is approved before approving the listing. It publishes the result via the `PublicationEvaluationCompleted` event.
+
+A Unicorn Properties agent initiates the workflow by requesting to approve a listing, generating a `PublicationApprovalRequested` event with property information. To decouple from the Contracts Service, the Approvals service maintains a local copy of contract status by consuming the ContractStatusChanged event.
+
+The workflow checks the contract state. If the contract is in the WaitForContractApproval state, it updates the contract status for the property with its task token, triggering a DynamoDB stream event. The Property Approval Sync function handles these events and passes the task token back to the state machine based on the contract state.
+
+If the workflow completes successfully, it emits a PublicationEvaluationCompleted event with an **approved** or **declined** evaluation result, which Unicorn Web listens to update its publication flag.
+
+**Note:** Upon deleting the CloudFormation stack for this service, check if the `ApprovalStateMachine` StepFunction doesn't have any executions in `RUNNING` state. If there are, cancel those execution prior to deleting the CloudFormation stack.

unicorn_properties/integration/event-schemas.yaml → unicorn_approvals/integration/event-schemas.yaml

@@ -18,7 +18,7 @@ Resources:
     Properties: 
       Description: 'Event schemas for Unicorn Properties'
       RegistryName:
-        Fn::Sub: "{{resolve:ssm:/uni-prop/UnicornPropertiesNamespace}}-${Stage}"
+        Fn::Sub: "{{resolve:ssm:/uni-prop/UnicornApprovalsNamespace}}-${Stage}"
 
   EventRegistryPolicy:
     Type: AWS::EventSchemas::RegistryPolicy
@@ -52,7 +52,7 @@ Resources:
       RegistryName:
         Fn::GetAtt: EventRegistry.RegistryName
       SchemaName:
-        Fn::Sub: '{{resolve:ssm:/uni-prop/UnicornPropertiesNamespace}}@PublicationEvaluationCompleted'
+        Fn::Sub: '{{resolve:ssm:/uni-prop/UnicornApprovalsNamespace}}@PublicationEvaluationCompleted'
       Description: 'The schema for when a property evaluation is completed'
       Content:
         Fn::Sub: |