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():

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)

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)

# 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:

# 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:

# 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?