001. Adoption of MongoDB for Inbound Service Persistence

001. Adoption of MongoDB for Inbound Service Persistence

Date: 2026-01-12 Status: Accepted

Context

The Inbound Service handles high-volume payload ingestion and manages the state of Saga workflows. Initially, a hybrid approach using DynamoDB (for metadata/state) and S3 (Claim Check pattern for large payloads) was proposed to handle the volume and varying payload sizes.

However, during the POC/Implementation phase, we realized the need for a more flexible schema for the incoming payloads (InputRequest) which can vary significantly in structure. Additionally, MongoDB offers a higher document size limit (16MB) compared to DynamoDB (400KB), which simplifies the architecture by reducing the immediate need for S3 offloading for medium-sized payloads.

Decision

We will use MongoDB as the primary persistence layer for the inbound service.

1. Core Entities:

   • InputRequest (was Insumo): Stores the raw incoming request and metadata.
   • SagaControl (was RotaControle): Stores the orchestration state.

2. Schema Flexibility: MongoDB’s BSON structure allows us to store the payload as a dynamic Map<String, Object> without rigid schema enforcement, accommodating the “insumos” variability.

3. Entity Renaming:

   • Insumo -> InputRequest (English, more accurate).
   • RotaControle -> SagaControl (English, reflects orchestration).

Consequences

Positive

• Simplified Architecture: Reduces the initial complexity of coordinating DynamoDB + S3 for every request.
• Flexible Schema: Easier to handle diverse JSON payloads.
• Development Speed: Faster iteration during the POC phase.

Negative

• Operational Overhead: Managing a MongoDB instance (or cluster) vs serverless DynamoDB.
• Scaling Model: Scaling MongoDB is different from DynamoDB’s RCU/WCU model; we need to monitor connection pools and cluster resources.

Compliance

This change adheres to the Hexagonal Architecture standards, implementing MongoRepository adapters in the Infrastructure layer.