A better explanation

1_context

We are trying to lock down a communication pattern by which our back-end server (which processes the applications) will communicate with our front-end React templates.  We have all agreed that the separation of responsibilities should be this:

1. Both the front-end and the back-end are aware of the full suite of React templates that exist.  The front-end and the back-end agree on a set of keys that correspond to each template.  For example, there may be templates for gathering personal information, bank account information, housing information, and employment information.  Both parts of the system will agree that those can be referred to (as an example) as `identity_information`, `bank_information`, `housing_information`, and `employment_information`.
2. The server persists the application, and evaluations whether the application is fit to make a final decision yet.
3. The server tells the the front end which templates to render, and returns if there are any errors with the submitted data.
4. The front-end allows customers to fill in the form information, and has client side validations to ensure correct data.

The only pieces of information required to persist an application are name, email address, and social security number/tax identification number.  There are business/privacy reasons behind that.

The only part of this pattern that poses a real risk (as far as I can tell) is that there must be a tight coupling of knowledge of template names between the front and back end.  If there is a good way to solve this, that would be good to know.

Two new ideas that have come up (that I'd love everyone's thoughts on) are
1.  To have the request format be broken up so that each of the actual form fields live inside of a hash that corresponds to its type of template.
2.  That the response should include a structured format of everything that we know about the application so far.  That should make form re-rendering easier.

2_app_communication_pattern.rb

### An example of requests over time to complete a dummy application:

# Request 1.
#  Doesn't even contain the minimal amount of data to complete an application.
POST /applications
{
  identity_information: {
    first_name: 'Tom',
    last_name: 'Smith',
    email: 'bad.mail.com',
    social_security_number: '485225431'
  }
}

# Response 1.
#  Could not even persist an application.  It tells the front end that some of the data was invalid.
#  For something as simple as email, we would actually have client side validations to ensure that the email was a 
#  valid format, but let's pretend those don't exist for this example.
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  missing: [],
  errors: {
    identity_information: {
      'email' => ['is invalid']
    }
  }
}

# Request 2.
#  Trying again with the correct information
POST /applications
{
  identity_information: {
    first_name: 'Tom',
    last_name: 'Smith',
    email: '[email protected]',
    social_security_number: '485225431'
  }
}

# Response 2.
#  We have persisted the application, but require more data.  Note that we know that we need data
#  from two additional templates at this point, so we could render either one of those templates and then
#  re-submit just to persist the data, or we could gather the data from both templates since we know that both
#  will be required.
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  missing: ['bank_information', 'housing_information'],
  errors: {
    identity_information: {}
  }
  request: {
    identity_information: {
      first_name: 'Tom',
      last_name: 'Smith',
      email: '[email protected]',
      social_security_number: '485225431'
    }  
  }
}

# Request 3.
#  Submitting information for some of the missing templates, but again with some errors.
POST /applications
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  bank_information: {
    first_name: 'Thomas',
    last_name: 'Smith',
    account_number: nil,
    routing_number: '12345678'
  },
  housing_information: {
    ownership: 'rent',
    monthly_payment: 600,
    street: '1 Main St.',
    city: nil,
    state: 'North Carolina',
    zip_code: '28806'
  }
}

#  Response 3.
#  We are letting the front end know where the errors are, and returning the templates where data is incomplete as `missing`.
#  Note that we are also returning all of the data we have on the application under the  `request` tag, in case the user
#  wants to go back and edit that on prior templates.
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  missing: [],
  errors: {
    identity_information: {},
    bank_information: {
      account_number: ['cannot be blank']
    },
    housing_information: {
      city: ['cannot be blank']
    }
  }
  request: {
    identity_information: {
      first_name: 'Tom',
      last_name: 'Smith',
      email: '[email protected]',
      social_security_number: '485225431'
    }  
    bank_information: {
      first_name: 'Thomas',
      last_name: 'Smith',
      account_number: nil,
      routing_number: '12345678'
    },
    housing_information: {
      ownership: 'rent',
      monthly_payment: 600,
      street: '1 Main St.',
      city: nil,
      state: 'North Carolina',
      zip_code: '28806'
    }  
  }
}

#  Request 4.
#  Finally we have all of the required data.
POST /applications
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  bank_information: {
    first_name: 'Thomas',
    last_name: 'Smith',
    account_number: '200911232',
    routing_number: '12345678'
  },
  housing_information: {
    ownership: 'rent',
    monthly_payment: 600,
    street: '1 Main St.',
    city: 'Asheville',
    state: 'North Carolina',
    zip_code: '28806'
  }
}

#  Response 4
#  We have made a credit decision and are returning that, as well as indicating that no data is missing.
{
  application: {
    id: 'LTOAPP123',
    status: 'pending'
  },
  missing: [],
  errors: {
    identity_information: {},
    bank_information: {},
    housing_information: {}
  }
  request: {
    identity_information: {
      first_name: 'Tom',
      last_name: 'Smith',
      email: '[email protected]',
      social_security_number: '485225431'
    }  
    bank_information: {
      first_name: 'Thomas',
      last_name: 'Smith',
      account_number: '200911232',
      routing_number: '12345678'
    },
    housing_information: {
      ownership: 'rent',
      monthly_payment: 600,
      street: '1 Main St.',
      city: 'Asheville',
      state: 'North Carolina',
      zip_code: '28806'
    }  
  }
}