JSON Data Flow

How JSON moves between endpoints in this API, what shape it takes at each hop, and where that flow could be tightened up.

Request & Response Flow

Every response below — success or error — is wrapped in the same { data, meta, error } envelope (see Where This Flow Improved). It's omitted from the arrows here for readability.

sequenceDiagram
    participant Client
    participant Combined as /api/mortgage-calculation
    participant UserInfo as /api/user-info
    participant UserInput as /api/user-input
    participant Location as /api/items/{state}/{city}
    participant External as External APIs
    participant DB as PostgreSQL

    Note over Client,DB: Recommended path: one atomic call
    Client->>Combined: POST { debt, income, email, ...loan params }
    Combined->>DB: BEGIN
    Combined->>DB: INSERT user_info (skipped if email exists)
    Combined->>DB: INSERT user_input
    Combined->>DB: COMMIT
    Combined-->>Client: 200 { user_info, user_input }
    Note over Combined,DB: Both rows commit together, or neither does
    Note over Combined,Client: Welcome email queued as a background task

    Note over Client,UserInput: Legacy path: still available, two round trips
    Client->>UserInfo: POST { debt, income, email }
    UserInfo->>DB: INSERT user_info
    UserInfo-->>Client: 200 { id, debt, income, email }
    Client->>UserInput: POST { user_info_id, loan params }
    UserInput->>DB: INSERT user_input
    UserInput-->>Client: 200 { id, ...loan params }

    Client->>Location: GET state, city ?enrich=true
    Location->>DB: SELECT from CSV-imported location tables
    Location->>External: Census + BLS lookups (only when enrich=true)
    External-->>Location: demographic + employment data
    Location-->>Client: 200 { ...housing data, external: {...} }
            

Endpoint Groups & Their JSON Shapes

Every card below shows the payload as it sits inside data in the envelope.

POST /api/mortgage-calculation

Recommended. Creates UserInfo + UserInput atomically in one call.

// request
{ "debt": 500, "income": 6000, "email": "a@b.com",
  "state": "California", "city": "Austin",
  "tax": 8000, "insurance": 1200, "fee": 250,
  "loan": "conventional", "rate": 6.5,
  "years": 30, "price": 400000, "upfront": 20 }

// response  { "data": { ... }, "meta": ..., "error": null }
{
  "user_info": { "id": 12, "debt": 500, "income": 6000, "email": "a@b.com" },
  "user_input": { "id": 44, "userInfoId": 12, "city": "Austin", ... }
}
// meta: { "user_info_reused": false }
↓ one round trip, one transaction

POST /api/user-info legacy

Still available for callers not yet on the combined endpoint.

// request
{ "debt": 500, "income": 6000, "email": "a@b.com" }

// response (data)
{ "id": 12, "debt": 500, "income": 6000, "email": "a@b.com" }
↓ id feeds into UserInput

POST /api/user-input legacy

Second half of the legacy two-request flow.

// request
{ "userInfoId": 12, "state": "California", "city": "Austin",
  "tax": 8000, "insurance": 1200, "fee": 250,
  "loan": "conventional", "rate": 6.5,
  "years": 30, "price": 400000, "upfront": 20 }
↓ retrieved later by email

GET /api/user-inputs-by-email/{email}

Joins UserInfo + UserInput history for a returning user. Paginated.

// response (data)
[ { "user_input_id": 1, "email": "a@b.com", "city": "Austin", ... } ]
// meta
{ "total": 7, "limit": 20, "offset": 0 }

// next page: ?limit=20&offset=20

GET /api/items/{state}/{city}

Housing data, plus Census/BLS merged in when enrich=true.

// GET /api/items/texas/austin?enrich=true
// response (data)
{
  "city": "austin", "state": "texas",
  "median_value": 450000, "median_rent": 2100,
  "median_tax": 1.8,
  "external": {
    "data_sources": ["census", "bls"],
    "census": { ... }, "bls": { ... }
  }
}
// meta: { "enriched": true, "data_sources": [...] }

GET /api/affordable-locations

Fans out over the location dataset, filtered by budget. Paginated.

// response (data)
{ "max_price": 400000, "locations": [ { ...location } ] }
// meta
{ "total": 34, "limit": 10, "offset": 0 }

GET /api/mortgage-rate

Single external value (FRED), used to default the rate field above.

// response (data)
{ "rate": 6.22, "date": "2026-08-25", "source": "FRED" }

GET /api/external-data-status

Meta-endpoint reporting health of Census/BLS/etc integrations.

// response (data)
{ "apis": { "census": {...}, "bls": {...} } }
// meta: { "timestamp": "..." }

POST /api/auth/validate-token

Separate flow: turns an emailed token into a session cookie.

// request
{ "token": "..." }
// response (data)
{ "session_token": "...", "email": "a@b.com", "expires_in": 3600 }

Error shape (any endpoint)

Same envelope, data is null, error is populated.

// e.g. 404 from /api/items/{state}/{city}
{
  "data": null,
  "meta": null,
  "error": {
    "message": "No data found for Nowhere, XX",
    "code": "http_404"
  }
}

Where This Flow Improved

Four of the five issues originally flagged here have been fixed. The last is a note for future frontend work.

Legend

POST creates or mutates a record · GET reads existing data · arrows in the diagram show the order data is expected to flow in the typical mortgage-calculation session (UserInfo → UserInput → Location lookup), not a hard dependency enforced by the API itself.