Implement a rail freight quote API service layer and scale it for slow dependencies

You receive a requirements document in Markdown for a REST API: a price-quote endpoint for rail freight shipments. Serving a quote requires calls to other dependent services, plus reads and writes against a database. The one-hour session has two halves: 1. Write a sample program that implements the endpoint's logic in the service layer. 2. Design an architecture that improves the endpoint's quality of service under high traffic, when its dependent services may respond slowly. ### Constraints and Clarifications The original requirements document was not reported. For practice, use the stand-in specification below, which is an assumption, or substitute your own and say so. - `POST /quotes` takes a JSON body with `origin` and `destination` station codes, a `commodity`, a `car_count`, and a requested `ship_date`. - The tariff for each commodity is read from a database table and gives a rate per car per mile. - A route service returns the rail distance between two stations, or reports that no route exists. - A surcharge service returns the surcharge rate that applies on the ship date. - An illustrative price: `base = rate_per_car_mile * miles * car_count` and `total = base + base * surcharge_rate`. The quote is saved to the database with an expiry time and returned with an id. ### Clarifying Questions - When the route service or the surcharge service fails or times out, should the endpoint return an error, or a quote built from cached data? - Must the quote be saved before the response is sent, and how long does a quote stay valid? - Should a repeated identical request, such as a client retry, return the same quote or create a new one? - What request rate and latency target define "high traffic" and acceptable service quality? - Must prices be exact as of the request time, or may a recently cached surcharge or route be used? ### Part 1 — Service-layer implementation Write the service-layer code for `POST /quotes`: validation, the calls to the dependencies and the database, the price computation, and the mapping of outcomes to HTTP responses. Make the logic testable without the real dependencies. ```hint Keep the edges thin Separate HTTP parsing, business logic and the code that talks to other systems, so that each can be replaced in a test. ``` #### What This Part Should Cover - Layering and dependency injection that make the logic unit-testable - Input validation, and a clear error contract that distinguishes client errors, unquotable requests and dependency failures - Money computed with exact decimal arithmetic and consistent rounding - A few focused tests ### Part 2 — Architecture for high traffic and slow dependencies The endpoint now receives high traffic, and its dependent services may have high latency. What architecture would improve its quality of service? ```hint What is on the critical path For each dependency call, ask whether it must happen on every request, whether it must happen in sequence, and what the endpoint should do if it does not return in time. ``` #### What This Part Should Cover - Removing dependency calls from the critical path or shortening them (parallel calls, caching) - Protection against slow dependencies: timeouts, retries, circuit breakers, bulkheads, load shedding - Synchronous versus asynchronous quote APIs, and the effect on clients - Scaling the service and the database, and the metrics to watch ### What a Strong Answer Covers - Ambiguities in the requirements document clarified before coding, not guessed silently - Working, readable service-layer code with tests, delivered within the first half of the hour - Design choices tied to the two stated stressors: request volume and dependency latency - Explicit trade-offs between price freshness and availability - Idempotent handling of client retries ### Follow-up Questions - If the surcharge changes while cached values are still being served, how do you bound the pricing error, and who should decide whether it is acceptable? - How would you prevent duplicate quotes when a client retries a `POST` that timed out? - If one dependency is down for an hour, what does the endpoint return during that hour, and how does it recover?