DynamoDB Data Models

The service uses a single DynamoDB table (Single Table Design) to store multiple entity types. The generic PK/SK patterns allow for efficient querying by User or by Time.

Table Overview

  • Partition Key (PK): String (Generic)

  • Sort Key (SK): String (Generic)

  • Global Secondary Index 1 (GSI1): GSI1PK, GSI1SK

Document Types

Float Profile

Stores user-specific settings for floats and loans, including limits and enabled status. Profiles are versioned by creation date, allowing history tracking.

  • PK: USER#<user_id>

  • SK: PROFILE#<created_on> (RFC3339 Timestamp)

Table 1. Fields
Field Type Description

user_id

String

The generic FloatMe user ID.

is_float_enabled

Boolean

Global toggle for float eligibility.

is_loan_enabled

Boolean

Global toggle for loan eligibility.

floats

List

List of float settings (Amount, Enabled/Disabled).

loans

List

List of loan settings (Amount, Enabled/Disabled).

created_on

String

Timestamp of profile creation.

reason

String

Reason for the current settings.

notes

String

Administrative notes.

Query Patterns

  • Get Latest Profile: Query PK=USER#<user_id>, SK begins_with PROFILE#, ScanIndexForward=False, Limit=1.

Temporary Float Profile

Stores temporary overrides for a user’s float profile. These have an expiration time and take precedence over the standard Float Profile while active.

  • PK: USER#<user_id>

  • SK: TEMP_FLOAT_PROFILE#EXPIRES#<expires_on> (RFC3339 Timestamp)

Table 2. Fields
Field Type Description

user_id

String

The generic FloatMe user ID.

expires_on

String

RFC3339 timestamp when this temporary profile becomes invalid.

created_on

String

Timestamp of creation.

reason

String

Reason for the temporary override.

is_float_enabled

Boolean

(Inherited) Float eligibility override.

floats

List

(Inherited) List of float settings overrides.

Query Patterns

  • Get Active Temporary Profiles: Query PK=USER#<user_id>, SK > TEMP_FLOAT_PROFILE#EXPIRES#<current_time>.

Rule Outcome

Represents the result of a single rule execution within a rulebook. These are transient records used to calculate the final evaluation.

  • PK: USER#<user_id>

  • SK: RULE_OUTCOME#<rule_name>

Table 3. Fields
Field Type Description

rule_name

String

Name of the rule executed.

loan

Number

-1 for Approval, 0 for Denial, >0 for specific amount.

error

Boolean

True if the rule execution encountered an error.

features

Map

Input features or intermediate values used by the rule.

updated_date

String

Timestamp of update.

ttl

Number

Time-to-live timestamp for automatic cleanup.

Query Patterns

  • Get Outcomes for User: Query PK=USER#<user_id>, SK begins_with RULE_OUTCOME#. Filter by ttl > now to ensure freshness.

Evaluation Result

Represents the aggregated final decision for a user at a specific point in time. This is the "answer" to a float-check.

  • PK: USER#<user_id>

  • SK: EVAL_RESULTS#<item_id>#<account_id>#<created_date>

  • GSI1PK: USER#<user_id>

  • GSI1SK: EVAL_RESULTS#<result_id>

Table 4. Fields
Field Type Description

result_id

String

Unique ID for the evaluation.

item_id

String

The Plaid Item ID related to the check.

account_id

String

The Plaid Account ID related to the check.

float_results

Map

Final decision for Float products (Approved, Amount, etc.).

loan_results

Map

Final decision for Loan products.

cfi_state

Map

Snapshot of CFI (Cash Flow Insight) data used.

created_date

String

RFC3339 timestamp.

ttl

Number

Time-to-live timestamp.

Query Patterns

  • Get Latest Result: Query PK=USER#<user_id>, SK begins_with EVAL_RESULTS#<item>#<account>, ScanIndexForward=False, Limit=1.

  • Get by Result ID: Query GSI1PK=USER#<user_id>, GSI1SK=EVAL_RESULTS#<result_id>.

Historical Evaluation

A permanent record of an evaluation that resulted in a Float or Loan being taken. This snapshots the state of the world when the credit was extended.

  • PK: USER#<user_id>

  • SK: HISTORICAL_EVALUATION#<result_id>

Table 5. Fields
Field Type Description

result_id

String

ID of the original evaluation.

amount

Number

The amount taken.

float_id

String

ID of the float created (if applicable).

loan_id

String

ID of the loan created (if applicable).

float_results

Map

Snapshot of float evaluation.

loan_results

Map

Snapshot of loan evaluation.

created_date

String

RFC3339 timestamp.

Query Patterns

  • Get by Result ID: GetItem PK=USER#<user_id>, SK=HISTORICAL_EVALUATION#<result_id>.

Rulebook

Stores configuration for a set of rules (a Rulebook). Rulebooks define the logic applied during underwriting.

  • PK: RULEBOOK

  • SK: RULEBOOK#<rulebook_id>

  • GSI1PK: RULEBOOK_TYPE#<type>

  • GSI1SK: RULEBOOK#<rulebook_id>

Table 6. Fields
Field Type Description

rulebook_id

String

Unique identifier for the rulebook (e.g., core_v2).

rulebook_name

String

Human-readable name.

type

String

Type of rulebook (e.g., floats, loans).

rules

List

List of Rule objects defining the logic to run.

apply_to

Number

Percentage of users this applies to (for A/B testing or rollouts).

priority

Number

Evaluation priority (higher runs first).

superseding

Boolean

If true, stops evaluation of lower priority rulebooks if this one matches.

last_updated

String

Timestamp of last update.

Query Patterns

  • Get All Rulebooks: Query PK=RULEBOOK.

  • Get Rulebooks by Type: Query GSI1PK=RULEBOOK_TYPE#<type>.

  • Get Specific Rulebook: GetItem PK=RULEBOOK, SK=RULEBOOK#<id>.

Note on Caching: To optimize performance, Rulebooks are often cached in-memory by the CachedRulebooks component in the lambda functions. This cache is refreshed periodically (e.g., every 5-10 minutes) or on demand, reducing the load on DynamoDB for static configuration data.