# PropertyLab chatbot — agreed scope summary

> **Delivery annotation — 8 September 2026.** The existing Laravel portal repository has since been located and the Property Research module implemented in an isolated checkout. OpenAI is selected; its local configured credential was validated during integration. MySQL research import and scoped automated fixtures have run locally. No public or production deployment has occurred. The planning text below is retained for scope/acceptance traceability: statements that the repository was absent, AI was unconnected or implementation had not begun describe the original drafting state. See [the current module handbook](../readMe.md) for implemented behavior and outstanding release gates. No milestone is marked complete by copying this design.


**v1.1 · 8 September 2026 · Laravel / Vue portal target · Proposed development**

## What we are building

A real AI buyer workspace with conversation on the left and the current property explorer on the right. It helps buyers understand **price position** and **daily-life fit**. The assistant accepts natural language and follow-up questions; forms and suggested prompts are optional guidance within the conversation.

Every answer, chart and map update uses the same verified research result. Buyers can inspect the source evidence and change assumptions without losing earlier comparisons.

## Required experience

- Default Satellite Streets in 3D, pitch 70°, zoom 16, bearing −20°. Map appearance and property-type legend start collapsed.
- Preserve the existing five map styles, property-type colors and checkbox filters, distinct rail/amenity categories and conventional explorer.
- Resize chat and map; enlarge evidence. Mobile uses Chat / Map / Evidence with shared state.
- Free-form AI chat, an editable buyer brief and explicit selected-property/search-area context.
- Concise answer pattern: conclusion, relevant visual, material limitation and useful next action.
- Interactive price/PSF trends, bars, distributions, comparisons and supported journey visualisations.
- Cursor near Property A’s bar highlights its map marker and chart row; reverse map highlighting also works. Hover keeps the camera steady. Click/tap/keyboard provides deliberate selection and focus.
- Source drilldown, missing-data disclosure, Cancel/Retry, undo and restore of an answer’s visual scene.
- Scenarios A/B, two-to-five-property comparison, shortlist notes and before-decision checklist.

## Two analytical focuses

**Price position:** resolve a scheme; collect buyer-entered asking price and compatible area; compare with declared historical evidence; show asking PSF, sample statistics, dates, coverage, exclusions and uncertainty. Do not equate small displayed samples with complete transactions or formal valuations.

**Daily-life fit:** use buyer-chosen destinations and preferences; distinguish straight-line distances from route estimates; compare supported walking/driving journeys under consistent time assumptions. Keep unknown criteria visible. Transit, live listings and unsupported suitability scores are outside v1.

## Current prototype and chosen production stack

The current Site still runs React/Vinext. The chatbot will be developed for the user’s existing Laravel/Vue portal; this specification revision does not migrate the live application.

| Layer | Running prototype | Target portal |
|---|---|---|
| UI | React 19, TypeScript, Vinext, shadcn/Base UI | Vue 3.5, Inertia, portal UI components, Tailwind CSS, Vite/Node 22 |
| Charts | Recharts | Chart.js 4.4 with shared map/chart entity state and accessible evidence tables |
| Map | Mapbox GL JS 3.30.0 | Portal CDN Mapbox 3.7.0, subject to feature parity verification |
| Backend | Workers-compatible Sites runtime with a small configuration API | Laravel 13.18.1 / PHP 8.4.19 services, policies, tools and authenticated streaming |
| Data | Static JSON; offline SQLite source | MySQL 8 with versioned imports, provenance and private research/scenario storage |
| Background work | None for AI research | Existing Horizon infrastructure with Redis, after deployment verification |
| Users/roles | Private Site, browser-local shortlist | Existing portal login and Spatie roles plus per-record ownership/tenant policies |
| AI | Not connected | Real configurable server-side model connection orchestrated in PHP |

Portal versions are user-reported. The Laravel Inertia adapter is reported as 2.0.24 and the Vue adapter as 3.3; audit lockfiles and align compatible adapters before building. Reuse portable map/data logic, rebuild React components as Vue components, and translate Recharts visuals to Chart.js. Preserve the existing three.js avatar as optional UI; it does not provide AI capabilities.

Inertia handles workspace navigation. Ordinary authenticated HTTP streams deliver chat events without refreshing the page. MySQL persists research; Redis/Horizon handles queues and bounded coordination. The current D1/R2 proposal is superseded.

## Delivery plan

1. **Portal foundation:** inspect actual lockfiles, auth and deployment; add the module behind a feature flag, reconcile MySQL imports, and port the explorer to Vue/Chart.js with the required map behavior.
2. **Real chat and price research:** tool-backed conversation, linked evidence, cancellation and source drilldown.
3. **Daily-life fit:** confirmed destinations, routing and explicit criterion comparisons.
4. **Decision workflow:** private persistence, scenarios, scene replay, shortlist and checklist.
5. **Launch quality:** accessibility/mobile, multilingual evaluation, performance, security and buyer usability sessions.

No “first in the world” claim is supported. Success is a buyer being able to understand a result, inspect the evidence, change a condition and restore the earlier comparison without help.

Read `propertylab-chatbot-development-spec.md` for the full requirements, methodology, architecture, contracts, prerequisites and acceptance suite. `propertylab-chatbot-backlog.csv` provides the implementation work packages.

The full specification includes a migration sequence, source reconciliation, stream/proxy checks and staged cutover/rollback. The existing Laravel portal repository is required for implementation; it has not yet been supplied locally.