PortOpt — Best Practices Reference

Description

# PortOpt — Best Practices Reference This document lists every best-practice rule to follow for this project going forward. Organised by layer. Each rule states **what** to do, **why**, and **when it applies**. --- ## 1. Git & Version Control | # | Rule | Why | |---|------|-----| | 1 | Add `.gitignore` **before** the first commit | Binary/generated files (`.db`, `__pycache__`, `.env`) are hard to purge from history once committed | | 2 | Never commit secrets or local config (`.env`, credentials) | Leaked keys cannot be un-leaked | | 3 | Verify `git config user.email` matches your GitHub account before pushing | Vercel blocks deployments from unrecognised committers | | 4 | Use feature branches; merge to `main` via PR | Protects main from broken pushes; gives a review checkpoint | | 5 | Prefer a new commit over force-push to trigger Vercel builds | Vercel's webhook may ignore a force-push even if history changed | | 6 | Use concise, imperative commit messages (`Fix`, `Add`, `Remove`) | GitHub squashes long bodies into subject-only views | --- ## 2. Dependency Management | # | Rule | Why | |---|------|-----| | 7 | Pin **all** deps (including transitive) in `requirements.txt` for Vercel | Vercel Python 3.12 doesn't auto-install transitive deps at runtime | | 8 | Use upper-bound pins for fast-moving libs (`cvxpy<2`, `numpy<2`) | Major version breaks are common; upper bounds prevent surprise failures | | 9 | Add a `.python-version` file (`3.12`) | Documents the exact runtime; tools like pyenv respect it | | 10 | Use a virtual environment locally (`python -m venv .venv`) | Prevents version conflicts with system packages | --- ## 3. Flask Application Structure | # | Rule | Why | |---|------|-----| | 11 | Split the app into `services/` (business logic) and `routes/` (Flask Blueprints) | A 850-line `app.py` is unreadable and untestable | | 12 | Register Blueprints in `app.py`; keep `app.py` under ~30 lines | The entry point should just wire things up, not contain logic | | 13 | Never use `warnings.filterwarnings("ignore")` globally | Masks real bugs; scope it to the specific module/category that needs it | | 14 | Use `logging` instead of `print()` / `traceback.print_exc()` | Serverless logs need structured output; print goes to stdout with no level | | 15 | Add a `/health` endpoint that returns `{"status": "ok"}` | Required by load balancers, uptime monitors, and Vercel warm-pings | --- ## 4. Input Validation & Error Handling | # | Rule | Why | |---|------|-----| | 16 | Call `request.get_json(silent=True)` and check for `None` before accessing keys | Bare `request.json["key"]` throws `TypeError` or `KeyError` on malformed input | | 17 | Validate all required fields at the top of each route; return **400** for bad input | Routes that accept whatever they get silently fail or crash | | 18 | Return correct HTTP status codes: 400 for bad input, 500 for server errors, 404 for not found | A 200 response with `{"error": "..."}` confuses monitoring tools and CDNs | | 19 | Catch **specific** exceptions (`ValueError`, `KeyError`) not bare `except Exception` | Bare except hides bugs; you can't distinguish expected failures from crashes | | 20 | Log the full traceback server-side; return only a safe error message to the client | Stack traces in API responses leak internal structure | --- ## 5. Database (SQLite / db.py) | # | Rule | Why | |---|------|-----| | 21 | Never use `PRAGMA journal_mode=WAL` in serverless | WAL requires `-shm`/`-wal` shared-memory files that don't exist in Vercel/Lambda containers | | 22 | Replace `datetime.utcnow()` with `datetime.now(timezone.utc)` | `utcnow()` is deprecated in Python 3.12 and will be removed in 3.14 | | 23 | Wrap `init_db()` in a try/except; don't let import-time side-effects crash the module | An `init_db()` failure at import kills the entire Lambda cold start with a cryptic error | | 24 | **SQLite in `/tmp` is ephemeral on Vercel** — saved data is lost on every cold start | Vercel's container filesystem is wiped between cold starts; use a real DB for persistence | | 25 | For production persistence on serverless: use Supabase (PostgreSQL) or move to Railway/Render | These provide either a managed DB or a persistent disk without changing the Flask code much | --- ## 6. Frontend (HTML/CSS/JS) | # | Rule | Why | |---|------|-----| | 26 | Split a 2000-line `index.html` into `static/css/app.css` and `static/js/app.js` | One file is unmaintainable; split enables browser caching and better diffs | | 27 | Add a `<link rel="icon">` (favicon) | Browsers make a request for `/favicon.ico` on every load; 404 is a log noise source | | 28 | Add Subresource Integrity (SRI) hashes to CDN `<script>` tags | Without SRI, a compromised CDN can inject arbitrary JS into your page | | 29 | Use `showError(msg)` helper instead of `alert()` for user-facing errors | `alert()` blocks the thread, is not styleable, and is terrible UX | | 30 | Wrap all `localStorage` calls in try/catch | Private/incognito mode and storage quota exceeded throw synchronously | | 31 | Define a localStorage schema version key (`portopt_v3`) and migrate on load | Without versioning, adding a field to the stored object will silently break old data | | 32 | Use event listeners instead of inline `onclick=` handlers | Inline handlers make it impossible to apply Content Security Policy headers | | 33 | Namespace all global JS (`window.PortOpt = {}`) or use ES modules | Every `let x = ...` in a `<script>` tag is a global; name collisions cause subtle bugs | --- ## 7. Platform & Architecture | # | Rule | Why | |---|------|-----| | 34 | Set `maxDuration: 30` in `vercel.json` for CPU-heavy endpoints | Default is 10 s; portfolio optimization can take 15–25 s on cold start | | 35 | Vercel serverless is **not** the right platform for heavy computation + persistent state | Cold starts add ~5 s; 30 s timeout; ephemeral filesystem. Use Railway/Render for this app | | 36 | Separate dev and prod environments | Never test against the live production database/URL | | 37 | Add a `README.md` with setup instructions | New contributors (and future-you) should be able to run the project in under 5 minutes | --- ## Quick Checklist for New Routes ``` [ ] request.get_json(silent=True) and null check → 400 [ ] Validate required fields (type, range, presence) → 400 [ ] Catch specific exceptions; log traceback; return 500 [ ] Return correct HTTP status code (not always 200) [ ] No bare `data["key"]` — use data.get("key") with a default ``` ## Quick Checklist Before Every Deploy ``` [ ] .gitignore updated (no .db, .env, __pycache__) [ ] requirements.txt includes all transitive deps [ ] No print() or traceback.print_exc() left in routes [ ] No warnings.filterwarnings("ignore") at global scope [ ] /health returns 200 [ ] Tested locally with python app.py ```

Security Status