FASTAPI_QUICKSTART.md

# FastAPI Setup - What You Need to Do

## Summary: 3 Steps

1. **Refactor `analyze_blueprint.py`** — Extract core logic into a reusable function (you do this)
2. **Push to GitHub** — Create a repo and push your code (you do this)
3. **Deploy on Railway** — Click a button and it's live (Railway does this)

---

## Step-by-Step

### STEP 1: Refactor Your Analyzer (30 mins)

Your `analyze_blueprint.py` has a `main()` function that's tightly coupled to CLI arguments. The FastAPI needs a cleaner interface.

**What to do:**

Open `python_files/analyze_blueprint.py` and find where `main()` starts (around line 2242).

Add this new function BEFORE `main()`:

```python
def analyze_pdf(pdf_path: str, out_dir: str, dpi: int = 150, min_conf: int = 40):
    """
    Analyze a PDF blueprint and return results (non-CLI version).
    
    Args:
        pdf_path: Path to the blueprint PDF
        out_dir: Directory to save output files
        dpi: Resolution for rendering (150 = fast, 300 = accurate)
        min_conf: YOLO confidence threshold (0-100)
    
    Returns:
        tuple: (floor_results, schedule_tags)
    """
    
    # 1. Load PDF and get manifest
    pages_manifest = _load_and_classify_pages(Path(pdf_path), dpi=dpi)
    
    # 2. Extract schedule from schedule pages
    schedule_tags = _extract_all_schedules(Path(pdf_path), pages_manifest)
    
    # 3. Run YOLO detection on plan pages
    floor_results = _detect_units_on_plans(Path(pdf_path), pages_manifest, min_conf=min_conf, dpi=dpi)
    
    # 4. Reconcile detections with schedule
    floor_results = _reconcile_detections(floor_results, schedule_tags)
    
    # 5. Save output files (CSVs, images) to out_dir
    Path(out_dir).mkdir(parents=True, exist_ok=True)
    _save_results_to_disk(floor_results, schedule_tags, Path(out_dir))
    
    return floor_results, schedule_tags
```

The functions like `_load_and_classify_pages()` already exist in your code — they're just currently called from within `main()`. You're just reorganizing them.

**Easiest approach:**
- Copy the core logic from `main()` into `analyze_pdf()`
- Keep all the helper functions as-is
- Update the import in `app.py` to call `analyze_pdf` instead of the stub

Don't worry about perfection — just make it work.

---

### STEP 2: Test Locally (15 mins)

```bash
cd /path/to/hvac_project

# Install FastAPI dependencies
pip install fastapi uvicorn python-multipart

# Test the API
python -m uvicorn app:app --reload
```

Visit `http://localhost:8000/docs` in your browser. You'll see an interactive API explorer.

Click "Try it out" on `/analyze`, upload a test PDF, and see if it works.

**If it works:** You're good for deployment.
**If it fails:** Check the error message, fix `analyze_blueprint.py`, and retry.

---

### STEP 3: Push to GitHub (10 mins)

```bash
# Initialize git repo (if not already done)
cd /path/to/hvac_project
git init

# Add all files
git add .

# Commit
git commit -m "Add FastAPI backend"

# Create repo on GitHub at https://github.com/new
# Then push (replace YOUR_USERNAME and hvac-analyzer with your details)
git remote add origin https://github.com/YOUR_USERNAME/hvac-analyzer.git
git branch -M main
git push -u origin main
```

---

### STEP 4: Deploy on Railway (5 mins)

1. Go to https://railway.app
2. Click "New Project"
3. Select "Deploy from GitHub repo"
4. Authorize Railway to access your GitHub
5. Select your `hvac-analyzer` repo
6. Railway auto-deploys (takes ~2 minutes)
7. You get a URL: `https://hvac-analyzer-prod-abc123.railway.app`

Done!

---

## What Happens When You Update Code

### Workflow:

```bash
# Make a change to app.py or analyze_blueprint.py
vim app.py

# Test locally
python -m uvicorn app:app --reload
# Visit http://localhost:8000/docs and test

# Push to GitHub
git add .
git commit -m "Improve YOLO confidence handling"
git push origin main
```

### Railway watches and auto-deploys:
1. You push to `main`
2. Railway gets notified (via webhook)
3. Railway pulls your code
4. Reinstalls dependencies from `requirements.txt`
5. Starts the app using `Procfile`
6. Your URL gets the new code (usually within 2-3 minutes)

You can watch the deployment in the Railway dashboard:
- Dashboard → Your Project → Deployments → click the latest one → View Logs

---

## What If Something Breaks?

**Scenario 1: Code has a bug**
- Railway will show a failed deployment
- Your old version keeps running (no downtime)
- Fix the code locally, test, push again
- Railway auto-deploys the fix

**Scenario 2: Missing dependency**
- Error: `ModuleNotFoundError: No module named 'foo'`
- Add to `requirements.txt`: `foo==1.0.0`
- Commit and push
- Railway reinstalls and redeploys

**Scenario 3: App runs but is slow**
- Check Railway logs to see response times
- Reduce DPI in `app.py` (use 150 instead of 300)
- Or upgrade Railway plan ($5 → $7/mo)

---

## Testing Your Live API

Once deployed to Railway, test it:

```bash
# Replace with your actual Railway URL
URL="https://hvac-analyzer-prod-abc123.railway.app"

# Health check
curl $URL/

# Upload a test PDF
curl -X POST $URL/analyze \
  -F "file=@/path/to/test_blueprint.pdf"
```

---

## Next Steps

1. ✅ Refactor `analyze_blueprint.py` → `analyze_pdf()`
2. ✅ Test locally with FastAPI
3. ✅ Push to GitHub
4. ✅ Deploy on Railway
5. ⬜ Build a frontend (HTML/Canvas) that talks to the API
6. ⬜ Deploy frontend to Netlify
7. ⬜ Wire them together

Want help with the frontend next?