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 }
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" }
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 }
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.
-
FixedUserInfo → UserInput is now atomic
POST /api/mortgage-calculationcreates UserInfo (or reuses it if the email already exists) and UserInput in a single DB transaction — seemain.py::create_mortgage_calculation. If the UserInput insert fails, the whole transaction rolls back, so there's no more window for an orphaned UserInfo row. The original two-request endpoints (/api/user-info,/api/user-input) still work for existing callers. -
FixedEvery response now uses one envelope
All endpoints — success and error alike — return
{ data, meta, error }(seeresponse_envelope.py).HTTPException, request-validation errors, and unhandled exceptions are all caught by dedicated exception handlers inmain.pyand reshaped into the same envelope, so the frontend can use one response parser everywhere instead of one per endpoint. -
FixedLocation + external-API data now merge server-side
GET /api/items/{state}/{city}?enrich=truecalls the existingenrich_location_data()helper and merges Census/BLS data into the same payload underexternal. It's opt-in (defaultenrich=false) since it adds external API latency;/api/test-external-apis/{state}still exists separately for API-health testing. -
FixedList endpoints now support pagination
/api/affordable-locationsand/api/user-inputs-by-email/{email}both acceptlimit+offsetand returnmeta: { total, limit, offset }, so a client can page past the first batch instead of results beyond the cap being unreachable. -
LowField naming drifts between snake_case and mixed casing
Most JSON keys are snake_case (
home_price,down_payment), which matches Python/Pydantic defaults, but it's worth confirming the frontend consumes these directly rather than re-mapping to camelCase in multiple places — a shared schema/OpenAPI client generator would keep both sides in sync automatically as fields are added. Not yet implemented.
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.