Architecture
System Context
The Transactions Service is deployed as a set of AWS Lambda functions behind API Gateway, with DynamoDB as its primary data store. It integrates with Plaid as its core external data source and participates in the FloatMe platform both as a synchronous API and as an event-driven consumer and producer.
Inbound Traffic
| Source | Description |
|---|---|
|
Mobile client requests. Routes transaction, account, item, and institution endpoints for end users. |
|
Internal service-to-service requests from FloatMe backend services (User Service, Float Service, Underwriting, etc.). |
|
Forwards incoming Plaid webhook events to the |
|
Auth0 log stream events routed via EventBridge into the |
|
Raw Plaid transaction and account data published by the miner, consumed by the refiner Lambda. |
Outbound Traffic
| Destination | Description |
|---|---|
|
Outbound stream of refined account and transaction change events, produced by the feeder Lambda from DynamoDB Streams. Consumed by downstream FloatMe services. |
|
Raw Plaid data published by the miner and throttle-miner, consumed internally by the refiner Lambda. |
|
Domain events published on item creation and other key lifecycle operations. |
Lambda Functions
| Function | Trigger | Timeout | Memory | Responsibility |
|---|---|---|---|---|
|
API Gateway (IAM + JWT) |
300s |
1024 MB |
Primary REST API. Handles all CRUD operations for items, accounts, transactions, institutions, liabilities, KYC, categories, and processor tokens. |
|
API Gateway (webhook API) |
300s |
default |
Receives incoming Plaid webhooks. Verifies the request and enqueues the payload onto the |
|
SQS ( |
~810s |
default |
Reacts to Plaid webhook types. Fetches updated transactions and accounts from Plaid and puts raw data onto the |
|
SQS ( |
~810s |
256 MB |
Mines additional pages of transactions when the miner detects pagination is required. Reads from and writes back to the throttle SQS queue. |
|
Kinesis ( |
840s |
512 MB |
Consumes raw Plaid data from Kinesis. Converts transactions and accounts into FloatMe’s internal format and persists them to the transactions DynamoDB table. |
|
DynamoDB Streams (transactions + plaid tables) |
840s |
default |
Reads ACCOUNT and TRANSACTION change events from DynamoDB Streams and publishes them to the |
|
SQS ( |
840s |
512 MB |
Processes Auth0 login events. Checks whether the user’s transactions are stale and, if so, generates a synthetic Plaid webhook to trigger re-mining. |
|
CloudWatch schedule (weekly) |
300s |
256 MB |
Runs every Sunday at 00:00 UTC. Fetches institution metadata from Plaid and writes it to the |
Plaid Mining Architecture
See Plaid Mining Pipeline for a detailed walkthrough of the end-to-end webhook processing and transaction mining flow.
Data Storage
The Transactions Service uses three DynamoDB tables and two legacy tables.
DynamoDB: prod-txn-transactions (us-east-2)
The primary table for user financial data. Multiple entity types share the table, differentiated by key prefixes and a type attribute.
Entity PK SK ──────────────────────────────────────────────────────────────── Transaction TXN#<txn_id> TXN#<txn_id> Account ACCOUNTS#<user_id> ACCOUNT#<acct_id> Webhook WEBHOOK_ITEM#<item_id> DATETIME#<dt>#TYPE#... Balance Hist. BALANCE#<user_id> ACCOUNT#<acct_id>#<date>
DynamoDB Streams are enabled on this table; the feeder Lambda consumes ACCOUNT and TRANSACTION type events.
DynamoDB: prod-txn-plaid (us-east-2)
Stores Plaid-specific state: items, liabilities, KYC sessions, and processor tokens.
Entity PK SK ──────────────────────────────────────────────────────────────── Item USERS#<user_id> ITEMS#<item_id> Liability LIABILITIES#<user_id> ITEM#<item_id>#ACCOUNT#<acct_id> Liability Hist. LIABILITY_HISTORY#<user_id> ITEM#<item_id>#ACCOUNT#<acct_id>#TIMESTAMP#<ts>
DynamoDB Streams are enabled on this table; the feeder Lambda also consumes events from here.
DynamoDB: prod-txn-plaid-institutions (us-east-2)
Simple key-value store for Plaid institution metadata. Primary key is institution_id. Refreshed weekly by the institution Lambda. No DynamoDB Streams.
Legacy Tables (us-east-1)
Two legacy tables are maintained for historical data:
| Table | Purpose |
|---|---|
|
Legacy Plaid item records from before the current table design. |
|
Legacy account change history records. |
See Items, Transactions, and Accounts & Balances for full schema references.
External Service Integrations
| Service | Integration |
|---|---|
Plaid |
Primary data source. The API Lambda calls Plaid for live account data; the miner and throttle-miner call Plaid to fetch transaction pages; the institution Lambda queries institution metadata. |
Auth0 |
Login events arrive via Auth0 Log Stream → EventBridge → SQS → listener Lambda. No outbound calls to Auth0. |
User Service |
Called by the API Lambda during item add (user activation) and item removal (status checks). |
Payments Service |
Called by the miner Lambda. Also called during item add for account/routing number encryption. |
Float Service |
Called by the API Lambda to check for active float balances before allowing item removal or main account changes. |
LOC Service |
Called by the miner and throttle-miner for line-of-credit eligibility. |
Insight Service |
Receives transaction removal signals via the |
GrowthBook |
Feature flags consumed at Lambda startup for mining configuration (personal finance category mining, logo mining, rate limiting parameters). |
Segment |
Analytics events emitted on item state changes (item repaired, item errored, etc.). |
Iterable |
Marketing/notification events (configured as a secret, used selectively). |
Datadog |
Metrics and distributed tracing across all Lambda functions. |
Related Pages
-
Features — Capability reference by domain area
-
Plaid Mining Pipeline — Detailed mining pipeline walkthrough
-
Item Lifecycle — Item status transitions and add/remove flows
-
Event-Driven Flows — Inbound and outbound Kinesis and EventBridge details
-
Infrastructure — Full AWS resource inventory
-
API Specification — Full OpenAPI spec