Quiet Spot Finder

Quiet Spot Finder is a working React and Next.js portfolio project built around a realistic product problem: helping users discover places that are more likely to feel calm and useful for focused time.

Instead of scraping third-party interfaces, the project uses a protected provider flow, server-side normalization, and a custom quiet-score model. The result is not just a UI demo. It is a structured product slice with search, filtering, detail pages, shortlist state, compare mode, visible-result bulk actions, and a live-provider path that keeps external API keys on the server.

1. The Product Shape

The core question is simple: where can someone go right now if they want a place that is likely to feel calm, usable, and worth saving for later? The app answers that through a search experience built around category, search area, ranking, and provider-supported filters.

The project intentionally has two modes. The mock mode demonstrates a richer review-and-time-slot scoring model. The protected live mode shows how the same UI can switch to a real provider while staying honest about the provider’s limits. In live mode, the broad discovery request is shaped on the server, and then a second layer of client-side refinement works on the already loaded results.

2. Why This Is a Strong Portfolio Project

This project works well as a portfolio piece because it feels like a real product instead of a renamed CRUD app. It has a clear user problem, real filtering and ranking decisions, and enough complexity to show architectural judgment rather than only component styling.

• It solves a believable discovery problem.
• It uses external provider data without exposing keys in the browser.
• It mixes server-rendered search pages with client-side shortlist behavior.
• It documents trade-offs instead of pretending provider data is perfect.

3. Current Product Scope

3.1 Discovery page

The main page supports URL-based filtering, paginated results, a shortlist sidebar, provider-backed live mode, and a server-side scoring model. Filters stay shareable through the URL and survive navigation into detail pages. In the live provider flow, request filters and response-level refinements are separated deliberately so the UI can stay fast without sending unnecessary extra requests. The loaded results can also be saved or removed in bulk based on the currently visible set.

3.2 Detail page

Each place has a detail page that explains why it scored the way it did, exposes provider metadata such as website, facilities, address, and coordinates, and links to related alternatives without losing filter context.

3.3 Shortlist, compare, and PDF export

Saved places can be noted, compared side by side, and exported through a print-friendly PDF flow. That turns the project from simple search into a more product-like decision tool.

4. What It Shows in React

• Interactive search forms with transition-aware filtering
• Shortlist state stored client-side and reused across multiple views
• Note-taking and comparison flows layered onto server-rendered pages
• Visible-result bulk save and remove actions that respond to client-side refinement
• Reusable cards, forms, pagination, and detail patterns
• Loading, empty, and pending states that support the product flow
• UI that adapts to provider capabilities instead of exposing broken filters

In other words, the React side is not there just to render components. It drives real product behavior.

5. What It Shows in Next.js

• App Router with nested demo, detail, and compare routes
• Server Components for data-heavy pages and client components for interactivity
• Route Handlers that normalize provider data behind internal API routes
• searchParams-based filter state for deep linking and pagination
• Protected live mode with server-side provider requests and page-based offsets
• Protected live mode using server-only env variables and an access cookie
• Route-level loading states for list and detail transitions
• Detail pages and JSON endpoints that can be inspected separately from the UI

This is the part that makes the project a real Next.js application rather than just a React app inside a Next.js folder.

6. The Working Vertical Slice

• Mock mode and live provider mode behind the same product surface
• Provider-side live data accessed through a protected server adapter
• Custom quiet-score heuristics rather than misleading pseudo-live claims
• Hybrid live filtering with request-side discovery and response-side refinement
• Provider-backed pagination with URL state preserved across navigation
• Bulk save and remove actions based on the currently visible results
• Shortlist notes reused across results, detail, and compare mode
• Print-friendly compare flow that doubles as lightweight PDF export

7. Data and Provider Strategy

The frontend does not talk directly to the external places provider. The UI calls internal route handlers, and those handlers decide whether to use mock data or the live provider adapter.

• Read URL filters on the server
• Call the provider through a server-only adapter
• Normalize the external payload into an app-shaped place model
• Request provider pages with offset and limit, then keep local refinements client-side
• Apply request-side discovery logic and response-side refinement separately
• Return a stable shape to both the UI and JSON routes

That separation keeps the frontend cleaner, protects the provider key, and makes it easier to swap or extend providers later.

8. Advanced Thinking Inside the Project

• Adapting the UI when live provider data does not support certain filters
• Normalizing uncertain external data without overpromising accuracy
• Keeping filter state in the URL while still supporting rich interactions
• Separating true provider pagination from client-only refinement and shortlist actions
• Using client-side shortlist features without making the whole page client-heavy
• Designing live mode so provider keys never need to reach the browser
• Exposing raw JSON routes for inspection while keeping the UI product-focused

9. What This Project Teaches

This project teaches the kinds of decisions strong frontend engineers make all the time: what belongs on the server, what belongs on the client, how to model uncertain data, how to shape filters around real provider capabilities, and how to make a product flow feel deliberate rather than accidental.

The point is not only to ship a polished UI. The point is to show architectural restraint, product thinking, and a clear understanding of where React and Next.js add the most value.

10. What a Reviewer Should Notice

• This project goes beyond static pages and basic CRUD operations.
• The data flow is intentional and separated from the presentation layer.
• The live mode is protected, paginated, and honest about its provider constraints.
• The feature set is shaped around a real user decision flow.
• The codebase leaves room for future providers and deeper persistence.

11. Next Step

The next natural step would be persistence beyond local browser state, richer provider support, and an authenticated shortlist that can survive across sessions. The current version is already a strong vertical slice, but it is also structured in a way that leaves clear room for deeper product expansion.