Architecture

System Context

The Float Service is deployed as a set of AWS Lambda functions. It exposes a REST API behind API Gateway and participates in the broader FloatMe platform as both an event-driven consumer (Kinesis, SQS, EventBridge) and producer (EventBridge).

Inbound Traffic

Source Description

Source	Description
`prod-floats-api` (API Gateway)	IAM-authenticated requests from internal FloatMe services and JWT-authenticated requests from the mobile app via the global FloatMe API gateway.
`prod-floats-collections` (SQS)	Work queue consumed by the collections-worker Lambda. Messages are enqueued by the collections-scheduler at each scheduled collection run.
`prod-floats-prenotes` (SQS)	Prenote work queue consumed by the prenote-worker Lambda. Messages are enqueued by the prenote-scheduler on its weekday run.
`prod-floats-income-event-tap` (SQS)	Income detection events from the Insight Service, routed via an EventBridge rule. Consumed by the webhook-worker Lambda.
`prod-floats-balance-event-tap` (SQS)	Balance update events from the Transactions Service, routed via an EventBridge rule. Consumed by the webhook-worker-balance Lambda.
`prod-floats-batch-worker` (SQS)	Batch operation requests consumed by the batch-worker Lambda.
`prod-payments` (Kinesis)	Payment outcome events from the Payments Service, filtered for `FLOAT_DEBIT_`, `FLOAT_CREDIT_`, and `FLOAT_DEBIT_CHARGED_BACK` event types. Consumed by the ach-handler Lambda.
EventBridge (schedule)	CloudWatch rules invoke the collections-scheduler on a recurring schedule, the prenote-scheduler weekdays at 12:30 UTC, and the reporter Lambda daily at 12:00 UTC.

prod-floats-api (API Gateway)

IAM-authenticated requests from internal FloatMe services and JWT-authenticated requests from the mobile app via the global FloatMe API gateway.

prod-floats-collections (SQS)

Work queue consumed by the collections-worker Lambda. Messages are enqueued by the collections-scheduler at each scheduled collection run.

prod-floats-prenotes (SQS)

Prenote work queue consumed by the prenote-worker Lambda. Messages are enqueued by the prenote-scheduler on its weekday run.

prod-floats-income-event-tap (SQS)

Income detection events from the Insight Service, routed via an EventBridge rule. Consumed by the webhook-worker Lambda.

prod-floats-balance-event-tap (SQS)

Balance update events from the Transactions Service, routed via an EventBridge rule. Consumed by the webhook-worker-balance Lambda.

prod-floats-batch-worker (SQS)

Batch operation requests consumed by the batch-worker Lambda.

prod-payments (Kinesis)

Payment outcome events from the Payments Service, filtered for FLOAT_DEBIT_*, FLOAT_CREDIT_*, and FLOAT_DEBIT_CHARGED_BACK event types. Consumed by the ach-handler Lambda.

EventBridge (schedule)

CloudWatch rules invoke the collections-scheduler on a recurring schedule, the prenote-scheduler weekdays at 12:30 UTC, and the reporter Lambda daily at 12:00 UTC.

Outbound Traffic

Destination Description

Destination	Description
`float-service` (EventBridge)	Float lifecycle events (e.g. `user_float_created`) published by the API Lambda for consumption by downstream services.
Segment	User analytics events emitted by the ach-handler for float creation, payback, and collection outcomes.
Iterable	Email and in-app notifications triggered by ACH payment events from the ach-handler.
AppsFlyer	Mobile attribution events for float creation, emitted by the ach-handler.
Slack	Daily float origination report sent by the reporter Lambda.

float-service (EventBridge)

Float lifecycle events (e.g. user_float_created) published by the API Lambda for consumption by downstream services.

Segment

User analytics events emitted by the ach-handler for float creation, payback, and collection outcomes.

Iterable

Email and in-app notifications triggered by ACH payment events from the ach-handler.

AppsFlyer

Mobile attribution events for float creation, emitted by the ach-handler.

Slack

Daily float origination report sent by the reporter Lambda.

Lambda Functions

Function Trigger Responsibility

Function	Trigger	Responsibility
`prod-floats-api`	API Gateway (IAM + JWT)	Primary REST API. Handles all float CRUD, bypass management, payback, collection history retrieval, and admin operations. Publishes `user_float_created` events to EventBridge on float creation.
`prod-floats-collections-scheduler`	EventBridge (T-1 Day: 09:30 UTC, Due Date: 09:30 UTC, Daily Retry: 08:30 UTC)	Queries RDS for floats due for collection at each schedule stage. Enqueues qualifying floats to the `prod-floats-collections` SQS queue.
`prod-floats-collections-worker`	SQS (`prod-floats-collections`)	Dequeues float collection jobs. Acquires a DynamoDB distributed lock per user, then attempts pinless debit or ACH collection via the Payments Service. Updates float status on outcome and logs the attempt to DynamoDB.
`prod-floats-webhook-worker`	SQS (`prod-floats-income-event-tap`)	On income detection, checks whether the user has a float in RETRY status, validates daily attempt limits and balance thresholds, then attempts collection if criteria are met.
`prod-floats-webhook-worker-balance`	SQS (`prod-floats-balance-event-tap`)	On balance update events, evaluates whether a RETRY float can be collected based on the updated balance. Attempts opportunistic collection if eligible.
`prod-floats-ach-handler`	Kinesis (`prod-payments`)	Consumes ACH payment callbacks. Updates the float’s status based on the payment outcome. Notifies the user via Segment, Iterable, and AppsFlyer.
`prod-floats-prenote-scheduler`	EventBridge (weekdays, 12:30 UTC)	Queries RDS for floats in `SCHEDULING` status due in 4 business days. Filters by the `floats.prenotes` GrowthBook flag (per user) and enqueues one message per gated-in user to the `prod-floats-prenotes` SQS queue. Does not update float status.
`prod-floats-prenote-worker`	SQS (`prod-floats-prenotes`)	Fetches user identity from the User Service and submits a zero-dollar USIO prenote to the Payments Service. Concurrency capped at 3.
`prod-floats-batch-worker`	SQS (`prod-floats-batch-worker`)	Processes bulk float operations and data management tasks.
`prod-floats-reporter`	EventBridge (daily, 12:00 UTC)	Queries RDS for float origination metrics and sends a daily summary report to a Slack channel. Enabled in production only.

prod-floats-api

API Gateway (IAM + JWT)

Primary REST API. Handles all float CRUD, bypass management, payback, collection history retrieval, and admin operations. Publishes user_float_created events to EventBridge on float creation.

prod-floats-collections-scheduler

EventBridge (T-1 Day: 09:30 UTC, Due Date: 09:30 UTC, Daily Retry: 08:30 UTC)

Queries RDS for floats due for collection at each schedule stage. Enqueues qualifying floats to the prod-floats-collections SQS queue.

prod-floats-collections-worker

SQS (prod-floats-collections)

Dequeues float collection jobs. Acquires a DynamoDB distributed lock per user, then attempts pinless debit or ACH collection via the Payments Service. Updates float status on outcome and logs the attempt to DynamoDB.

prod-floats-webhook-worker

SQS (prod-floats-income-event-tap)

On income detection, checks whether the user has a float in RETRY status, validates daily attempt limits and balance thresholds, then attempts collection if criteria are met.

prod-floats-webhook-worker-balance

SQS (prod-floats-balance-event-tap)

On balance update events, evaluates whether a RETRY float can be collected based on the updated balance. Attempts opportunistic collection if eligible.

prod-floats-ach-handler

Kinesis (prod-payments)

Consumes ACH payment callbacks. Updates the float’s status based on the payment outcome. Notifies the user via Segment, Iterable, and AppsFlyer.

prod-floats-prenote-scheduler

EventBridge (weekdays, 12:30 UTC)

Queries RDS for floats in SCHEDULING status due in 4 business days. Filters by the floats.prenotes GrowthBook flag (per user) and enqueues one message per gated-in user to the prod-floats-prenotes SQS queue. Does not update float status.

prod-floats-prenote-worker

SQS (prod-floats-prenotes)

Fetches user identity from the User Service and submits a zero-dollar USIO prenote to the Payments Service. Concurrency capped at 3.

prod-floats-batch-worker

SQS (prod-floats-batch-worker)

Processes bulk float operations and data management tasks.

prod-floats-reporter

EventBridge (daily, 12:00 UTC)

Queries RDS for float origination metrics and sends a daily summary report to a Slack channel. Enabled in production only.

Collections Architecture

The collections system uses two parallel processing paths — scheduled and webhook-driven — both funneling into the Payments Service for execution.

See Collections Engine for the detailed flow diagrams and decision logic for each collection stage.

Data Storage

RDS PostgreSQL: `FloatMeAPI_userloansmodel`

The primary data store for float records. Holds one row per float with status, amounts, dates, and payment references. Both the API and all collection Lambdas read and write to this table.

Column              Type        Description
──────────────────────────────────────────────────────────────────
loan_id             uuid        Primary key
user_id_id          varchar     Owning user
loan_type           varchar     NORMAL or PINLESS
loan_amount         varchar     Advance amount
ach_debit_status    varchar     Float status (see status reference)
ach_debit_date      timestamp   Due date for collection
ach_credit_id       varchar     Disbursement payment reference
ach_debit_id        varchar     Latest collection payment reference
fee                 varchar     Fee charged to the user
evaluation_id       varchar     Underwriting evaluation reference

See PostgreSQL Schema for the full column reference and status values.

DynamoDB

Three DynamoDB tables support the collections engine:

Table Purpose

Table	Purpose
`collection-history`	Append-only audit log of every collection attempt. PK: `loan_id`, SK: `run_time` (nanosecond timestamp).
`locks`	Distributed locks preventing concurrent collection attempts on the same user. 60-second lease with 1-second heartbeat.
`requirements-bypass`	Per-user eligibility overrides with an expiration date. Used by the bypass API endpoints.

collection-history

Append-only audit log of every collection attempt. PK: loan_id, SK: run_time (nanosecond timestamp).

locks

Distributed locks preventing concurrent collection attempts on the same user. 60-second lease with 1-second heartbeat.

requirements-bypass

Per-user eligibility overrides with an expiration date. Used by the bypass API endpoints.

See DynamoDB Tables for full schema and access pattern details.

External Service Integrations

Service Integration

Service	Integration
Payments Service	Core payment execution layer. The API Lambda submits disbursements on float creation. Collection Lambdas submit pinless debit and ACH attempts. The prenote-worker submits zero-dollar USIO prenotes via `SubmitUsioPrenote`. The ach-handler processes payment outcome callbacks from the `prod-payments` Kinesis stream.
Underwriting Service	Queried by the API Lambda on float creation to validate eligibility and retrieve the approved amount and fee.
User Service	Queried by the API and collection Lambdas for user profile and identity data. The prenote-worker fetches first name, last name, and email here before submitting each prenote.
Transactions Service	Queried by collection Lambdas for current bank account balance data to inform collection routing decisions.
Insight Service	Source of income detection events that drive webhook-triggered collections. Events are routed via EventBridge to the `prod-floats-income-event-tap` SQS queue.
Subscriptions Service	User subscription status checked during collection eligibility evaluation.
GrowthBook	Feature flags controlling collection behavior, ACH routing decisions, the embedded ML model configuration, and per-user prenote enrollment via `floats.prenotes`. Fetched at Lambda startup.
Segment	User analytics events emitted by the ach-handler on payment outcomes.
Iterable	Email and in-app notifications triggered by ACH events in the ach-handler.
AppsFlyer	Mobile attribution tracking for float creation events.
LOC Service	Line-of-credit eligibility data used in fraud checks during float creation.

Payments Service

Core payment execution layer. The API Lambda submits disbursements on float creation. Collection Lambdas submit pinless debit and ACH attempts. The prenote-worker submits zero-dollar USIO prenotes via SubmitUsioPrenote. The ach-handler processes payment outcome callbacks from the prod-payments Kinesis stream.

Underwriting Service

Queried by the API Lambda on float creation to validate eligibility and retrieve the approved amount and fee.

User Service

Queried by the API and collection Lambdas for user profile and identity data. The prenote-worker fetches first name, last name, and email here before submitting each prenote.

Transactions Service

Queried by collection Lambdas for current bank account balance data to inform collection routing decisions.

Insight Service

Source of income detection events that drive webhook-triggered collections. Events are routed via EventBridge to the prod-floats-income-event-tap SQS queue.

Subscriptions Service

User subscription status checked during collection eligibility evaluation.

GrowthBook

Feature flags controlling collection behavior, ACH routing decisions, the embedded ML model configuration, and per-user prenote enrollment via floats.prenotes. Fetched at Lambda startup.

Segment

User analytics events emitted by the ach-handler on payment outcomes.

Iterable

Email and in-app notifications triggered by ACH events in the ach-handler.

AppsFlyer

Mobile attribution tracking for float creation events.

LOC Service

Line-of-credit eligibility data used in fraud checks during float creation.

PostgreSQL Schema — Full float entity schema and status reference
DynamoDB Tables — Collection history, locks, and bypass table schemas
Collections Engine — Detailed collection flow diagrams
API Specification — Full OpenAPI spec