Project 3: Interactive List and Search App

Build a deterministic search/list experience with filters, pagination, and explainable results.

Quick Reference

Attribute Value
Difficulty Intermediate
Time Estimate 1-2 weeks
Main Programming Language TypeScript
Alternative Programming Languages Python, Rust
Coolness Level Level 3
Business Potential Team Productivity Lever
Prerequisites Query modeling, pagination concepts, schema validation
Key Topics Filter grammar, cursor pagination, state synchronization

1. Learning Objectives

  1. Design stable list/search tool contracts.
  2. Implement filter and sort state that survives chat turns.
  3. Build deterministic pagination and explainable ranking.
  4. Handle empty/noisy queries gracefully.

2. All Theory Needed (Per-Concept Breakdown)

Deterministic Retrieval in Conversational UX

Fundamentals Search in chat contexts fails when result ordering and filter semantics shift between turns. Determinism means the same query + filters produce stable ordering given equivalent data snapshots. Users need this to trust the system and reason about changes.

Deep Dive into the concept Natural-language query intent is fluid, but execution contracts must be strict. Define a filter grammar and normalize user inputs into canonical query objects. Include explicit sort keys and tie-breakers to prevent random ordering drift. Cursor pagination is preferred for mutable datasets because offset pages become unstable during inserts/deletes.

Expose query echo in results so users can verify what was executed. Add lightweight explanations per item (why included) for trust. In tests, run replay traces with fixed fixtures and ensure stable outputs.

Minimal concrete example

query object:
{ text:"open incidents", team:"payments", severity:["SEV-1"], sort:"severity_desc,created_desc,id_asc" }

3. Project Specification

3.1 What You Will Build

A searchable list app with chips, sort controls, and cursor pagination.

3.2 Functional Requirements

  1. Parse user intent into canonical query object.
  2. Support multi-filter combinations.
  3. Return deterministic order with cursor pagination.
  4. Render query echo and result count summary.

3.3 Real World Outcome

User applies filters -> widget reflects exact filter chips.
Result ordering remains stable across refreshes.
Pagination shows consistent page boundaries.

4. Solution Architecture

Prompt -> query normalizer -> search tool -> ranked result envelope -> widget renderer

5. Implementation Guide

5.1 The Core Question You’re Answering

“How do I make conversational search behave like a trustworthy product surface, not a guessing engine?”

5.2 Concepts You Must Understand First

  1. Canonical query representation.
  2. Stable sorting and tie-breakers.
  3. Cursor lifecycle handling.

5.3 Questions to Guide Your Design

  1. Which filters are required vs optional?
  2. How do you encode and validate cursors?
  3. How do users understand why items were included?

5.4 Thinking Exercise

Create three ambiguous prompts and map each to canonical query objects.

5.5 The Interview Questions They’ll Ask

  1. Offset vs cursor pagination tradeoffs?
  2. How do you prevent ordering drift?
  3. How do you test query determinism?
  4. What does explainable ranking look like?
  5. How do you handle empty queries?

5.6 Hints in Layers

  • Hint 1: Freeze one fixture dataset first.
  • Hint 2: Add tie-breakers in sorting.
  • Hint 3: Echo normalized filters in UI.
  • Hint 4: Test replay stability before UX polish.

5.7 Books That Will Help

Topic Book Chapter
Data model stability “Designing Data-Intensive Applications” Ch. 2
API pagination patterns “Clean Architecture” Boundaries chapter
Retrieval reasoning “Algorithms, Fourth Edition” Searching sections

6. Testing Strategy

  • Canonical query parser tests.
  • Stable sort snapshot tests.
  • Cursor replay tests.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
No canonical filters UI/backend mismatch Centralize query builder
Missing tie-breaker Order changes unexpectedly Add deterministic secondary keys
Cursor drift Duplicates/skips between pages Use opaque validated cursors

8. Extensions & Challenges

  • Add saved searches.
  • Add semantic query explanation panel.
  • Add cross-collection federated search.

9. Real-World Connections

  • Incident queues
  • CRM lead triage
  • Document compliance review lists

10. Resources

  • OpenAI apps metadata optimization docs
  • OpenAI testing/troubleshooting docs

11. Self-Assessment Checklist

  • I can map prompts to canonical query objects.
  • I can guarantee deterministic ordering under fixed data.
  • I can explain pagination behavior to users.

12. Submission / Completion Criteria

Minimum Viable Completion

  • Deterministic search/list behavior with filter echo.

Full Completion

  • Includes replay tests, explainability cues, and robust cursor handling.