# TrueDoor — Local dev instructions

This repository contains two parts:

- `Backend/` — Python backend (Flask) that wraps the MCP property lookup and exposes POST `/address`.
- `ChromeExtension/` — A minimal Chrome extension (popup) that posts an address to the backend and displays results.

This README provides step-by-step commands so any team member can run the project locally.

## Prerequisites

- macOS (instructions were tested on macOS)
- Python 3.10+ and `python3` on PATH
- Chrome browser (for loading the extension)
- git (to clone the repository)

## 1) Clone repository

```bash
git clone <your-repo-url> TrueDoor
cd TrueDoor
```

## 2) Backend: create and activate a virtualenv (recommended)

From the repo root:

```bash
python3 -m venv .venv
source .venv/bin/activate
```

You can skip creating a venv if your team prefers a shared environment, but a venv is recommended.

## 3) Install backend dependencies

```bash
cd Backend
pip install -r requirements.txt
```

## 4) Configure API keys (recommended)

The backend will read API keys from environment variables. For security, set them in your shell before running the server.

**MCP API Key** (for property data):
```bash
export MCP_API_KEY="your-real-api-key-here"
```

**Google Gemini API Key** (for AI property estimation):
```bash
export GEMINI_API_KEY="your-gemini-api-key-here"
```

Get your Gemini API key from: https://aistudio.google.com/app/apikey

You can add the exports to your `~/.zshrc` for convenience, or use a secrets manager.

IMPORTANT: Do not commit real API keys to the repository.

## 5) Start the backend server

Run the server from the `Backend` directory (it binds to port 5001 by default):

```bash
cd Backend
python main.py
```

Keep this terminal open to see logs. The server exposes:

- GET `/` — health check (returns `{ "status": "ok" }`)
- GET `/debug` — returns request headers and origin (useful for debugging CORS / extension requests)
- POST `/address` — accepts JSON `{ "address": "..." }` and returns JSON with `results` and AI property estimate

Example: the server listens on `http://127.0.0.1:5001`.

## 6) Test the server from a terminal

In a new terminal (with the venv activated if you used one):

```bash
# Health
curl -s http://127.0.0.1:5001/ | python -m json.tool

# Debug headers (shows what the server sees)
curl -s http://127.0.0.1:5001/debug | python -m json.tool

# POST an address (should print JSON results)
curl -s -X POST http://127.0.0.1:5001/address \
	-H "Content-Type: application/json" \
	-d '{"address":"123 Main St, Miami, FL"}' | python -m json.tool
```

If the POST returns an error, inspect the server terminal; it logs incoming requests and exceptions.

## 7) Chrome extension: load and test

1. Open Chrome and go to `chrome://extensions/`.
2. Enable "Developer mode" (top-right).
3. Click "Load unpacked" and select the `ChromeExtension` folder in this repo.
4. Click the extension icon (popup), enter an address, and click "Get Information".

If the popup shows the JSON results, end-to-end is working.

If the popup shows `HTTP 403` or CORS errors:

- In the extension popup, right-click and choose "Inspect" to open DevTools for the popup and check the Network/Console tabs.
- Check the backend server logs and `GET /debug` for request headers and origin. Paste those logs into an issue and we can diagnose further.

## Troubleshooting notes

- The `main.py` script accepts environment variables `MCP_API_KEY` and `GEMINI_API_KEY`. Use those instead of committing API keys.
- If `GEMINI_API_KEY` is not set, property estimation will be disabled but property lookups will still work.
- If you see `403` before the request hits the server, check firewall or local proxy settings. If requests reach the server, server logs will show the request and headers.

## Additional improvements (optional)

- Move secrets to a `.env` file (with caution) or a real secrets manager.
- Add unit tests that mock the MCP client for CI.
- Replace Flask dev server with a production WSGI server (e.g. gunicorn) if deploying.

---
