NestHunt — real-estate search on the map

Scope

• Split-view search: listing cards and an interactive map that stay in sync (hover a card → its pin highlights, and vice-versa).
• Geospatial search that re-queries as you pan/zoom the map, plus filters for price, beds, type and amenities.
• Immersive listing detail with gallery, specs, description and a neighborhood map.
• JWT auth with two roles: buyers save favorites; agents publish, edit and manage their own listings.
• Fully bilingual (EN/ES) and responsive, with a role-aware guided demo layer.

Architecture

One Next.js app serves both the React UI (with SSR for search and listing pages) and the REST API as Route Handlers, organized in clean layers. MongoDB Atlas stores listings with a geospatial index.

Design patterns

Auth & security

• Stateless JWT (HS256, jose) stored in an httpOnly, SameSite=Lax cookie — not reachable from JS.
• Passwords hashed with bcrypt; login uses a constant-time compare and a uniform error to avoid leaking which accounts exist.
• RBAC: only agents reach publish/edit endpoints, and an agent can only mutate their own listings (403 on others).
• All input validated server-side with Zod; errors surface per-field, never a generic failure.

Data integrity & domain rules

• Listings belong to one agent; ownership is enforced on every update and delete.
• Draft listings are hidden from public search and only visible to their owner.
• Favorites use a unique (user, property) index, so saving is idempotent — no duplicates.
• Property coordinates are stored as GeoJSON Points validated to [lng, lat].

Maps & geospatial

• A 2dsphere index powers $geoWithin bounding-box queries as the user pans the map.
• Leaflet with free CARTO tiles (no API key); price pins are custom markers synced to the list on hover.
• Agents set a listing's location by dropping or dragging a pin on a Leaflet map.
• The map is mounted only when visible — a hidden, zero-size map would otherwise wipe results.

Performance

• Server-side pagination + load-more; map searches are debounced and stale responses discarded.
• Mongoose connection cached on globalThis to survive serverless cold starts (Atlas connection limits).
• Indexed queries (price, beds, type, status, 2dsphere) and lean reads mapped to slim DTOs.
• The Leaflet map is code-split (dynamic import, ssr:false) so it never blocks first paint.

Testing

• Vitest unit tests for the critical domain: JWT sign/verify (round-trip, tamper, garbage), bcrypt hashing, DTO validation, and the geo-filter builder.
• The geo-filter test asserts the exact $geoWithin $box, price range, $all amenities and text $or are constructed correctly.
• An end-to-end Playwright pass exercises the guest → login → favorite → publish flow and fails on any console error.

Conscious trade-offs

• Listing photos are styled gradient placeholders, not hosted images — it keeps the demo free and on-brand without an image pipeline.
• The API lives in Next.js Route Handlers rather than a separate service; for this scope it keeps one deploy and one type system, with the same clean layering a standalone Node API would have.
• Geospatial search uses a bounding box ($geoWithin $box) rather than radius ($near) because it maps exactly to the visible map rectangle.
• No image upload or payments — out of scope for a portfolio demo; the architecture leaves clear seams to add them.