DynamoDB Documentation

The Float Service utilizes Amazon DynamoDB.

Tables

collection-history

Stores a detailed audit trail of all float collection attempts (ACH, Pinless, success, or failure).

  • Primary Key (PK): loan_id (String) - Maps to the Float ID in RDS.

  • Sort Key (SK): run_time (Number) - Unix nanosecond timestamp of the event.

Attribute Description

float_id

Unique ID of the float.

runtime

Unix nanosecond timestamp of the event.

user_id

Unique ID of the user associated with the float.

due_date

The original due date of the float (YYYY-MM-DD).

run_date

The actual date the collection was attempted (YYYY-MM-DD).

process

The collection stage (e.g., TODAY6AM, RETRY, WEBHOOK).

outcome

Result of the attempt (e.g., SUCCESS, FAILURE, NSF).

Query Pattern: Retrieve all attempts for a specific float.

repo.GetByFloatID(ctx, floatID) // Query using PK = loan_id

locks

Used for distributed locking via the cirello.io/dynamolock client. This prevents concurrent processes from attempting collections on the same float simultaneously.

  • Primary Key (PK): PartitionKey (String)

  • Key Format: loan-processing:user_id:{userID}

Locks are held with a 60-second lease duration and 1-second heartbeat period to ensure safety and responsiveness.

requirements-bypass

Stores temporary overrides for service eligibility requirements.

  • Primary Key (PK): user_id (String)

Attribute Description

expiration_date

Date the bypass expires (YYYY-MM-DD).

reason

Internal reason for the manual override.

Query Pattern: Check if a user has an active bypass.

repo.Get(ctx, userID) // GetItem using user_id

Next Generation (Single-Table Design)

float-service

The newest table designed for consolidation using the single-table design pattern. It supports both direct lookups and complex indexes.

  • Partition Key: PK (String)

  • Sort Key: SK (String)

  • Secondary Index: GSI1PK / GSI1SK

Entity Type PK SK

CollectionLog

FLOAT#{floatID}

LOG#{timestamp}

locks - us-east-1

Locks

Distributed locks for managing concurrent loan processing events.

Keys

  • PK - loan-processing:user_id:{userID}

Attributes

  • data - unix timestamp of when lock was acquired

  • deleteOn - ttl for the record

  • leaseDuration - duration of the lease

  • owner - owner of the lock

  • recordVersionNumber - version number for optimistic locking