docs: add README for open-source release

Project description, capabilities, deal-type breakdown, architecture,
local-run instructions, link to docs/SUPABASE_SETUP.md, and project-status
note marking this as unmaintained.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PyThonicsML

README.md

@@ -0,0 +1,108 @@
+# DealLens
+
+Commercial real estate underwriting engine with full Excel export.
+
+DealLens is a web-based CRE underwriting platform that runs institutional-grade financial analysis across five deal types and outputs fully linked Excel proformas with live formulas. The math engine is deterministic Python (not LLM-generated), validated against real proformas to within 25 basis points.
+
+## What It Does
+
+You input deal assumptions (manually or by uploading an Offering Memorandum PDF). The engine runs a 120-month DCF model and returns IRR, equity multiples, DSCR, cash flow projections, GP/LP waterfall distributions, and a downloadable Excel workbook where every cell traces to an assumption.
+
+Five deal types, each with its own underwriting logic:
+
+- **Ground-Up Development** — Construction draws (S-curve/sigmoid), lease-up vacancy ramp, perm loan takeout, hold period through stabilization and exit
+- **Value-Add** — In-place NOI with renovation CapEx by unit, post-reno rent lifts, stabilized exit cap
+- **Stabilized Refinance** — Cash-out refi with DSCR-constrained loan sizing, rate modeling, origination fee as closing cost
+- **Acquisition / Disposition** — Full-cycle buy-hold-sell with exit cap sensitivity, levered vs unlevered returns (mode toggle on the Refinance engine)
+- **Fix and Flip** — Short-hold rehab with bridge loan, holding costs, ARV-based exit, monthly IRR
+
+Engine capabilities:
+
+- Constraint-based debt sizing (binding constraint of LTV, LTC, DSCR, or debt yield)
+- N-tier IRR-based European-style waterfall with GP catchup and preferred returns
+- Monte Carlo simulation (1,000 runs across rent growth, cap rate, and cost variance)
+- Scenario presets (Conservative Lender / Aggressive Sponsor / Institutional LP)
+- Six methodology toggles (monthly vs annual DCF, exit cap vs terminal value, S-curve vs linear draws, etc.)
+- AI-powered OM extraction (uploads a PDF, extracts deal assumptions via Claude Sonnet)
+- Live market rates via FRED API (Treasuries, SOFR, credit spreads)
+- Excel export with live formulas across all deal types (zero frozen values)
+
+## Architecture
+
+```
+Frontend:  Next.js + TypeScript + Tailwind CSS
+Backend:   FastAPI + Python (numpy, scipy, XlsxWriter)
+Database:  Supabase (PostgreSQL + Auth + Storage, RLS enforced)
+AI:        Claude Sonnet via OpenRouter (OM extraction only, not used for math)
+```
+
+The frontend and backend are in a single monorepo. The frontend lives in `frontend/`, the backend in `backend/`. Each has its own `.env.example`.
+
+## Running Locally
+
+### Prerequisites
+
+- Node.js 18+
+- Python 3.11+
+- A Supabase project (free tier works)
+- An OpenRouter API key (for OM extraction, optional)
+- A FRED API key (for market rates widget, optional)
+
+### Backend
+
+```bash
+cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env  # Fill in your Supabase and API keys
+uvicorn app.main:app --host 0.0.0.0 --port 8001
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+cp .env.example .env.local  # Fill in your backend URL and Supabase keys
+npm run dev
+```
+
+### Database
+
+The `supabase/migrations/` directory contains all SQL migrations for tables, RLS policies, triggers, and indexes. If you have the Supabase CLI installed:
+
+```bash
+supabase db push
+```
+
+See [`docs/SUPABASE_SETUP.md`](docs/SUPABASE_SETUP.md) for a full walkthrough of creating a Supabase project from scratch.
+
+## Testing
+
+```bash
+cd backend
+pytest
+```
+
+387 tests covering all five deal types, loan sizing, waterfall distributions, Excel export parity, and edge cases. The test suite runs on every push.
+
+## Excel Export
+
+Every deal type produces a multi-tab Excel workbook with live formulas. Tabs include Assumptions, Proforma/Cash Flow, Loan Summary, Returns, and a conditional Waterfall tab. No frozen values. Change an assumption in the workbook and every downstream calculation updates natively in Excel.
+
+The export uses XlsxWriter with the `formulas` library for parity testing between Python-computed values and Excel formula results.
+
+## Why This Exists
+
+Most CRE professionals underwrite deals in personal Excel models. Those models are hard to audit, easy to break, and impossible to standardize across deal types. DealLens was built to replicate the rigor of an institutional Excel proforma in a web-native platform, then give the user a real Excel file they can hand to a lender, LP, or investment committee.
+
+The engine was calibrated against reference proformas built by a real estate principal. Every formula in the codebase exists because it matched a cell in a validated Excel model.
+
+## Project Status
+
+This project is no longer actively maintained. It was built as a solo founder project between January and May 2026. The engine is complete, tested, and functional. You are welcome to fork it, extend it, or use the engine in your own projects.
+
+## License
+
+[MIT](LICENSE)