Underwriting API

Welcome to the Underwriting Service API documentation. This service is the central decision-making engine for Float’s lending operations, evaluating user eligibility for float and loan products through sophisticated rule evaluation and risk assessment.

System Overview

The Underwriting Service operates as a serverless architecture using AWS Lambda, DynamoDB, and SQS. It integrates with other services in the FloatMe ecosystem (Float Service, User Service, Transaction Service) to gather necessary data for eligibility decisions.

Core Capabilities

Rule Evaluation Engine: Execute complex rule sets (rulebooks) to determine user eligibility
Float Profile Management: Store and manage user float settings, limits, and fee structures
Continuous Float Increase (CFI): Automatically adjust float limits based on user behavior
Asynchronous Processing: Decouple heavy computation from API responses using SQS
Event-Driven Updates: React to float creation and profile updates from other services
Comprehensive Auditing: Store detailed evaluation results for analysis and backtesting

Key Features

Feature	Description
Float Eligibility Check	Determines if a user qualifies for a float and returns approved amount, terms, and fees
Loan Eligibility Check	Evaluates user eligibility for installment loans and personal credit lines
Eligibility Check (Combined)	Comprehensive evaluation combining float and loan eligibility with CFI data
Float Profile	Stores user float settings: enabled/disabled status, current float amounts, fee configurations
Temporary Float Profiles	Grants temporary float access with automatic expiration (e.g., for trials or special offers)
Underwriting History	Maintains audit trail of all eligibility evaluations and historical decisions
Event Processing	Reacts to float creation, profile updates, and rulebook changes for state management

Feature

Description

Float Eligibility Check

Determines if a user qualifies for a float and returns approved amount, terms, and fees

Loan Eligibility Check

Evaluates user eligibility for installment loans and personal credit lines

Eligibility Check (Combined)

Comprehensive evaluation combining float and loan eligibility with CFI data

Float Profile

Stores user float settings: enabled/disabled status, current float amounts, fee configurations

Temporary Float Profiles

Grants temporary float access with automatic expiration (e.g., for trials or special offers)

Underwriting History

Maintains audit trail of all eligibility evaluations and historical decisions

Event Processing

Reacts to float creation, profile updates, and rulebook changes for state management

Getting Started

For New Developers

System Architecture - Understand the high-level design and component interactions
API Specification - Explore available endpoints and request/response formats
Rule Engine - Learn how eligibility decisions are made
DynamoDB Schema - Understand data models and storage patterns

See the main README.md for local development setup instructions.

For DevOps/Infrastructure

Lambda Functions - Details on each serverless function
Deployment Guide - Infrastructure setup and operations

For Rule Engineers

Rule Engine Guide - Understand evaluation pipeline
Rulebooks - How to create and configure rule sets
Rules Reference - Complete rules catalog with examples

Architecture Overview

The service uses a layered event-driven architecture:

Layer	Components
API Layer	REST API endpoints for eligibility checks, profile management, and history retrieval
Processing Layer	Asynchronous workers (Rule Runner, Result Runner) for computational heavy operations
Persistence Layer	DynamoDB for structured data, SQS for task queues, EventBridge for cross-service events

Layer

Components

API Layer

REST API endpoints for eligibility checks, profile management, and history retrieval

Processing Layer

Asynchronous workers (Rule Runner, Result Runner) for computational heavy operations

Persistence Layer

DynamoDB for structured data, SQS for task queues, EventBridge for cross-service events

For detailed architecture including system context, component interactions, and data flows, see System Architecture.

Component Overview

Component	Purpose	Key Responsibilities
API Lambda	Request entry point	Validate requests, fetch profiles, determine immediate vs deferred evaluation
Rule Runner Lambda	Execute business rules	Gather user data, execute individual rules, store outcomes
Result Runner Lambda	Aggregate results	Apply priority logic, determine final decision, store evaluation result
DynamoDB	Primary data store	Profiles, rules, evaluation results, historical records
SQS Queues	Task distribution	Decouple API responses from computational work
EventBridge	Inter-service communication	React to float creation, profile updates, trigger cascading processes

Component

Purpose

Key Responsibilities

API Lambda

Request entry point

Validate requests, fetch profiles, determine immediate vs deferred evaluation

Rule Runner Lambda

Execute business rules

Gather user data, execute individual rules, store outcomes

Result Runner Lambda

Aggregate results

Apply priority logic, determine final decision, store evaluation result

DynamoDB

Primary data store

Profiles, rules, evaluation results, historical records

SQS Queues

Task distribution

Decouple API responses from computational work

EventBridge

Inter-service communication

React to float creation, profile updates, trigger cascading processes

Common Workflows

Eligibility Check Request

Client →  API Lambda
    ↓
Get Float Profile (DynamoDB)
    ↓
Fetch Applicable Rulebooks
    ↓
⚡ FAST PATH: Return cached result
⏱️ SLOW PATH: Queue evaluation task
    ↓
Rule Runner: Execute rules
Result Runner: Aggregate outcomes
    ↓
Store EvaluationResult (DynamoDB)
    ↓
Return decision to client

Float Creation Event

Float Service → EventBridge
    ↓
Float Created Handler Lambda
    ↓
Create HistoricalEvaluation record
Update FloatProfile
Send notifications
    ↓
Store in DynamoDB

Rulebook Update

New rulebook deployed
    ↓
Cache invalidation triggered
    ↓
On next request: Fetch fresh rulebook
    ↓
Execute with new rules

Quick Links

Documentation	Purpose
System Architecture	High-level design, components, integrations, deployment patterns
API Specification	OpenAPI endpoints, request/response schemas, examples
Rule Engine	Rule evaluation pipeline, decision determination, superseding logic
Rulebooks	Rule sets, configuration, versioning, A/B testing
Rules Reference	Complete rules catalog with input/output specifications
Continuous Float Increase	CFI eligibility tiers, ranking system, automatic limit increases
Float Profiles	Profile structure, settings, temporary profiles, lifecycle
DynamoDB Schema	Data models, entities, GSI patterns, query examples
Lambda Functions	Function details, environment variables, IAM permissions
Deployment	Infrastructure as Code, environments, monitoring setup

Documentation

Purpose

System Architecture

High-level design, components, integrations, deployment patterns

API Specification

OpenAPI endpoints, request/response schemas, examples

Rule Engine

Rule evaluation pipeline, decision determination, superseding logic

Rulebooks

Rule sets, configuration, versioning, A/B testing

Rules Reference

Complete rules catalog with input/output specifications

Continuous Float Increase

CFI eligibility tiers, ranking system, automatic limit increases

Float Profiles

Profile structure, settings, temporary profiles, lifecycle

DynamoDB Schema

Data models, entities, GSI patterns, query examples

Lambda Functions

Function details, environment variables, IAM permissions

Deployment

Infrastructure as Code, environments, monitoring setup

Development Setup

The service uses Docker for a consistent development environment:

# Start LocalStack (AWS mock)
docker-compose up -d

# Initialize database
./bootstrap/dynamo.sh

# Run API locally
make run.api.host

See README.md for detailed setup instructions.

Key Concepts

Rulebook

A versioned collection of rules applied sequentially to determine eligibility. Multiple rulebooks can be active simultaneously via A/B testing or feature flags.

Rule

An individual eligibility criterion (e.g., "minimum account age 30 days"). Rules are evaluated in order and can supersede earlier rules.

Evaluation Result

The outcome of running a rulebook against a user. Includes rule outcomes, final decision, approved amounts, and metadata.

Float Profile

User-specific configuration: enabled/disabled status for float and loan products, current float limits, fee tier, and settings.

CFI (Continuous Float Increase)

Automatic float limit increase when user meets eligibility criteria (successful payment history, subscription activity).

Historical Evaluation

An immutable record created when a user creates a float, capturing the state of evaluation at that moment for audit and analysis.

Support

For questions or issues: - Check the API Specification for endpoint details - Review Rule Engine Guide for decision logic - Consult DynamoDB Schema for data patterns - See Deployment Guide for infrastructure questions