chore: updated approvals readme

Author: sliedig

unicorn_approvals/src/README.md

@@ -1,25 +1,15 @@
-# ContractStatusChanged
+# Developing Unicorn Approvals
 
-*Automatically generated by the [Amazon Event Schemas](https://aws.amazon.com/)*
+![Properties Approval Architecture](https://static.us-east-1.prod.workshops.aws/public/f273b5fc-17cd-406b-9e63-1d331b00589d/static/images/architecture-approvals.png)
 
-## Requirements
+## Architecture overview
 
-1. Python 36+
-2. six 1.12.0
-3. regex 2019.11.1
+**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.
 
-## Install Dependencies
-### pip users
+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 Approval service maintains a local copy of contract status by consuming the ContractStatusChanged event.
 
-Create and update it in current project's **requirements.txt**:
+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 approvals sync function handles these events and passes the task token back to the state machine based on the contract state.
 
-```
-six == 1.12.0
-regex == 2019.11.1
-```
+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.
 
-Run Command:
-
-```sh
-pip3 install -r requirements.txt
-```
+**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.