Call For Rent (CFR) Process Documentation

Context

The Call For Rent (CFR) process is a core business flow used to charge tenants for their rent. This is achieved by generating a hierarchy of accounting events.

There are two types of parent events:

• INITIAL_RENT — when it's the first rent call.
• RECURRING_RENT — for subsequent periods.

These parent events wrap a set of child accounting events:

Project Structure

Components:

• adb-contracts: A BE service that exposes /propose and /process endpoints, reads and updates contract data, and coordinates with accounting.
• adb-accounting: A BE service that handles accounting logic and data. It generates accounting events and corresponding entries.
• MongoDB: Each service has its own MongoDB instance. For adb-contracts, it stores real and temporary contract data. For adb-accounting, it stores event and entry records.
• MongoDB Triggers: Similar to SQL triggers, they react to insert/update/delete events on collections and can emit messages externally (in our case, to AWS).
• AWS EventBridge: An event bus that routes triggered messages to specific SQS queues.
• AWS SQS Queues: Queues that ensure reliable, asynchronous delivery of messages between services.
• WebSocket (WS): Used by adb-contracts to push real-time propose results back to the frontend UI.

Architecture Overview

CFR Process Flows

A. User-Initiated Flows

A1. Propose Flow

The Propose Flow is the first step in the Call For Rent process. It allows users to preview the generation of accounting events for eligible contracts without making any real changes. This flow simulates the process and returns event data in real time.

2. User clicks "Generate Call for Rent".
3. Frontend sends a POST /contracts/accounting/rent/periods/{period}/propose request to adb-contracts.
4. adb-contracts filters eligible contracts and saves them to the temporary propose_contracts collection.
5. For each contract, it calls adb-accounting to simulate the generation of events.
6. Event data is returned (not persisted).
7. Final result is sent back to the user in real time via WebSocket.

A2. Process Flow

The Process Flow is the second step in the Call For Rent process. It finalizes the proposed contracts and updates their statuses in the database, triggering downstream event generation.

1. After previewing results, the user selects the contracts to finalize.
2. A POST /contracts/accounting/rent/periods/{period}/process request is sent.
3. The adb-contracts service updates the real contract with a PROCESSING status.
4. This change activates the downstream event generation flow.

B. DB-Initiated Flows

Triggered automatically after a contract is marked as PROCESSING.

1. MongoDB contract-modified trigger detects the change.
2. Event is sent to contracts-contract-modified SQS queue.
3. adb-accounting listens and generates real accounting events and entries.
4. Events and entries are saved in the adb-accounting MongoDB collections.
5. adb-contracts is notified via accounting-contract-modified queue to update the contract's nextCallForRentPeriod.
6. adb-contracts updates the contract with the new callForRentPeriods and nextCallForRentPeriod.
7. The user can then view the updated contract with the new rent periods.
8. The process is complete, and the contract is ready for further actions.

B1. Contract Modified → Generate Events

B2. Accounting Events Saved → Contract Final Update

Trigger & Queue Event Map

Post-CFR Actions

Once the Call For Rent (CFR) process is finalized and accounting events are created, both adb-accounting and adb-contracts perform additional actions to complete downstream workflows. These actions are automated and triggered by event-driven mechanisms.

On the adb-accounting Side

When a CALL_FOR_RENT event is stored in the accounting_events collection, the MongoDB accounting-event-modified trigger fires and emits a message to the accounting-accounting-event-modified SQS queue.

adb-accounting listens to this queue and processes the following logic:

• Invoice for Management Fees

  • A new invoice is generated for the owner to reflect management fees charged by the platform.

• Invoice for GLI Insurance (if applicable)

  • If the rental contract includes GLI insurance, an additional invoice is generated.
  • This invoice records the insurance-related charge.

These invoices are persisted and can be reviewed under the accounting records of the respective contract and organization.

On the adb-contracts Side

After the CFR period is marked as processed for a contract, adb-contracts automatically generates relevant tenant-facing files.

File 1: Individual Call For Rent Report (PDF)

• A PDF file is generated summarizing the rent call for the tenant.
• This file is sent to the adb-files service.
  • adb-files stores file metadata in its database.
  • The actual PDF is uploaded to AWS S3.
• Once processed, the file becomes visible:
  • On the documents tab of the rental contract.
  • On the tenant's personal page.

This file serves as the tenant’s official notice that rent has been generated and is due.

File 2: Rent Review Notification (Conditional)

• If a rent amount review took place in the called period:
  • A second notification PDF is generated to inform the tenant of the reviewed rent amount.
  • This file follows the same flow through adb-files and appears alongside the first document.

These files ensure the tenant is clearly informed and all compliance requirements are met.

Summary

• CFR is a multi-stage process:
  • /propose — previews rent generation and events, without real data changes.
  • /process — finalizes and saves changes using Mongo triggers + SQS.
• Each service owns its data and reacts via event-driven architecture.
• Diagrams break down the logic across UI, services, data, and events.

Related Endpoints

• POST /contracts/accounting/rent/periods/{period}/propose
• POST /contracts/accounting/rent/periods/{period}/process
• POST /accounting/events/propose
• POST /files
• Triggers:
  • contract-modified
  • accounting-event-modified
  • accounting-entry-modified