Indexation Feature Documentation

Overview

The indexation feature allows for the dynamic adjustment of rental prices based on changes in the Insee Index. This process involves updating rental contracts with new rent values as the index changes. Below is a detailed breakdown of the components involved and the flow of data.

Components

Database

• Indexes Collection: Stores the Insee Indexes values.
• Contracts Collection: Contains contracts with fields such as rentAmounts and nextExpectedIndexKey.

Messaging

• MongoDB Trigger: Listens for changes in the Indexes collection and sends a message to the AWS SQS queue when a new index is published.

Services

• adb-contracts: Processes messages from the SQS queue and updates rental contracts based on the new index values.

Process Flow

1. Index Publication: A new index is published to the Indexes collection in the adb-utilities database.
2. Trigger Activation: A MongoDB trigger detects the new index and sends a message to an AWS SQS queue.
3. Message Processing: The adb-contracts service processes the message, finds rental contracts that need updating, and calculates the new rent values.
4. Contract Update: The adb-contracts service updates the rentAmounts, indexes, nextExpectedIndexKey, nextExpectedRentReviewDate field in the relevant rental contracts.

Detailed Description

Database Level

1. Indexes Collection

   • New indexes are added to this collection. The effectiveDate determines when the index becomes active.

2. Contracts Collection

   • Fields: rentAmounts, nextExpectedIndexKey,
   • rentAmounts is an array that stores the base rental value and additional fees.
   • nextExpectedIndexKey indicates which index the contract is expecting next.

Messaging (Trigger and Queue)

1. MongoDB Trigger

   • Monitors the Indexes collection for new entries.
   • On detecting a new index, the trigger sends a notification to an AWS SQS queue.

2. AWS SQS Queue

   • Receives messages from the MongoDB trigger.
   • Messages contain details about the new index (e.g., indexValue, effectiveDate).

Services (adb-contracts)

1. Index Processing

   • The adb-contracts service listens to the AWS SQS queue for new messages.
   • On receiving a message, it identifies rental contracts with nextExpectedIndexKey matching the new index.

2. Rent Calculation

   • For each identified contract, the service determines the qualifier of the new Index (CURRENT or FUTURE).
   • The service calculates the new rent value based on the difference between the current and new index values.
   • The new rent value is appended to the rentAmounts array in the contract.

Gherkin Features

Feature: Indexation of Rental Contracts

  Scenario: Publish a new index
    Given a new index is published to the "Indexes Collection" in the "adb-utilities" database
    When the MongoDB trigger detects the new index
    Then a message is sent to the AWS SQS queue with details about the new index

  Scenario: Process new index message
    Given the "adb-contracts" service listens to the AWS SQS queue for new messages
    When a message about the new index is received
    Then the "adb-contracts" service identifies rental contracts with "nextExpectedIndexKey" matching the new index

  Scenario: Determine index qualifier
    Given the "adb-contracts" service identifies rental contracts with "nextExpectedIndexKey" matching the new index
    When the new index is processed
    Then the qualifier of the new index is determined for the identified contracts
    And the qualifier can be either "CURRENT" or "FUTURE"

  Scenario: Calculate new rent value
    Given the qualifier of the new index is "CURRENT"
    When the "adb-contracts" service calculates the new rent value based on the difference between the current and new index values
    Then the new rent value is appended to the "rentAmounts" array in the relevant rental contracts

  Scenario: Update rental contracts
    Given the "adb-contracts" service has calculated the new rent value
    When the new rent value is appended to the "rentAmounts" array in the relevant rental contracts
    Then the rental contracts are updated with the new rent values

PlantUML Diagrams

Sequence Diagram