Add Backend Search and Filters to the Items API of a Library Lending System

You are given a working full-stack repository for a **Library Lending System**: a backend API, a frontend, and a test suite that already passes. Requirements come from a conversation with a product manager (played by an AI chat assistant) rather than a written specification, and no failing or hidden tests define when the work is done. You are expected to use an AI coding agent, but you must write your own prompts for it instead of pasting the requirements into it, and you are responsible for reviewing what it produces. The feature extends the existing `GET /api/items` endpoint so the catalog can be searched and filtered. After the conversation, the working requirements are: - Search items by title using case-insensitive partial matching. - Filter by item type. - Filter by availability/status. - Combine multiple supplied filters with AND logic. - Return all items when no filters are supplied. - Perform the filtering on the backend. The frontend must send the selected filters to the API rather than filtering an already-fetched list locally. - Add search and filter controls to the frontend. - Add tests for the new behavior. The target request shape is: ```text GET /api/items?search=harry&itemType=book&status=available ``` ### Constraints and Clarifications - The backend builds database queries from an ORM filter object, so it must construct that object dynamically, adding a condition only for each parameter that is present. A title condition, for example, takes the form `{ contains: search, mode: "insensitive" }`. - Availability is not necessarily a stored column. The application may derive it from other records, so you must find out how it currently decides that an item is available before filtering on it. - Existing behavior and existing tests must not break. ### Clarifying Questions - Which status values exist besides `available`, and what should the API return for an unrecognized `status` or `itemType` value? - Does "available" mean only "not currently on loan," or does an item reserved for a patron's hold also count as unavailable? - Should an empty or whitespace-only `search` be ignored, or treated as a search? - Does the endpoint already paginate or sort, and must the filters be applied before pagination? - Should the active filters be reflected in the page URL so a filtered view can be reloaded or shared? ### Part 1 — Turn the Conversation into Acceptance Criteria Before touching code, convert the product manager's statements into explicit, testable acceptance criteria. Identify which statements are still ambiguous and what you would ask about them. ```hint Make each statement falsifiable For every requirement, try to write one concrete request and the exact set of items it should return. Anything you cannot write that way is a question for the product manager. ``` #### What This Part Should Cover - A mapping from each product-manager statement to a criterion with a concrete request and expected result. - Edge cases the requirements imply: no parameters, no matches, mixed case, partial substrings, and combined filters. - A clear split between criteria that can be tested now and policy questions that still need an answer. - How the criteria are used before implementation begins, given that the repository starts with every test passing. ### Part 2 — Investigate the Repository and Implement the Backend Find where the items endpoint, its data access, and the availability logic live. Then implement backend filtering that adds a condition only for each supplied parameter. ```hint Follow how availability is displayed today The application already shows whether an item is available somewhere. Trace that value back to where it is computed before deciding how to filter on it. ``` #### What This Part Should Cover - Dynamic construction of the filter object, AND semantics, and no condition for absent parameters. - How the availability filter stays consistent with the application's existing definition of availability. - Validation and behavior for empty, repeated, or unrecognized parameter values. - Query efficiency, including where the filtering work happens. ### Part 3 — Update the Frontend and Add Tests Add search and filter controls that send parameters to the backend, and write tests that cover the new behavior. ```hint Let each fixture differ in one way Seed a small set of items whose titles, types, and loan states are chosen so that each test isolates exactly one criterion. ``` #### What This Part Should Cover - How selected controls become API parameters, and how the list is refreshed without any local filtering. - Behavior of the search box under rapid typing and responses that arrive out of order. - Backend tests for case-insensitive title search, the type filter, the availability filter, combined filters, no filters, and no matches. - Evidence that the new tests exercise the feature and that existing tests still pass. ### Part 4 — Direct the AI Coding Agent Describe the prompt you would give the coding agent for this feature, and how you would review and iterate on its output. The prompt must be your own, not a copy of the requirements. ```hint Hand over what you learned Your investigation in Part 2 produced information the requirements do not contain. Consider how giving that to the agent changes the quality of its first attempt. ``` #### What This Part Should Cover - What context, constraints, and order of work the prompt gives the agent beyond restating the requirements. - How the generated change is reviewed for correctness, scope, and consistency with existing code. - How test results and discovered gaps drive the next prompt. ### What a Strong Answer Covers - Requirements made explicit and testable before implementation, with ambiguities raised instead of guessed. - Backend filtering that is correct for every combination of parameters and reuses the application's own notion of availability. - Frontend and backend that agree on parameter names and semantics, with filtering done on the server. - Tests that define the new behavior, ideally written first, while existing behavior is preserved. - Critical review of AI-generated code rather than acceptance because it runs. ### Follow-up Questions 1. If availability depends on both active loans and holds, how would you express the "available" filter as a database query rather than filtering after fetching? 2. The catalog grows to millions of items. How does case-insensitive substring search on titles perform, and what would you change? 3. A later feature changes how availability is computed. How do you keep the filter, the displayed status, and any other feature that depends on availability consistent? 4. How would you convince a reviewer that requests with no query parameters return exactly what they returned before your change?