|
| 1 | +# Broker-Sim Demo — Portfolio Summary |
| 2 | + |
| 3 | +SOURCE STATUS: Public-safe, docs-only portfolio summary. No secrets, no |
| 4 | +credentials, no account IDs. Describes a **read-only, simulated / paper** broker |
| 5 | +preview. Not live trading, not financial advice. |
| 6 | + |
| 7 | +> **Plain English:** I built and documented a *read-only simulated broker |
| 8 | +> preview* for MellyTrade — a FastAPI + React trading **terminal**. It shows |
| 9 | +> broker / account / position / order information from demo data, with the whole |
| 10 | +> system locked to read-only and dry-run. It never connects to a real broker, |
| 11 | +> never uses credentials, and never places an order. |
| 12 | +
|
| 13 | +## 1. Overview |
| 14 | + |
| 15 | +MellyTrade is a read-only, dry-run, paper-only portfolio project. The |
| 16 | +**broker-sim milestone** took it from "we have scattered read-only endpoints" to |
| 17 | +"there is a safe, documented, demoable simulated broker preview" — without adding |
| 18 | +any live execution surface. |
| 19 | + |
| 20 | +The work shipped as six small, reviewed PRs (#302–#307), each docs-/test-/UI- |
| 21 | +only and gated by CI plus a safety-config validator. |
| 22 | + |
| 23 | +## 2. What was built |
| 24 | + |
| 25 | +| PR | Deliverable | |
| 26 | +|---|---| |
| 27 | +| [#302](https://github.com/Melly-999/alpha_data_scraper_ai/pull/302) | **Readiness audit** — inventoried backend/API, frontend, docs, tests; classified readiness (see [readiness audit](../tasks/broker_sim_readiness_audit_001.md)) | |
| 28 | +| [#303](https://github.com/Melly-999/alpha_data_scraper_ai/pull/303) | **GET-only smoke script** + evidence — `scripts/broker_sim_readonly_smoke.ps1` ([smoke doc](../tasks/broker_sim_readonly_smoke_001.md)) | |
| 29 | +| [#304](https://github.com/Melly-999/alpha_data_scraper_ai/pull/304) | **Demo walkthrough** — presenter guide + talk tracks ([walkthrough](../tasks/broker_sim_walkthrough_001.md)) | |
| 30 | +| [#305](https://github.com/Melly-999/alpha_data_scraper_ai/pull/305) | **Milestone closeout** — single source of truth ([closeout](../tasks/broker_sim_milestone_closeout_001.md)) | |
| 31 | +| [#306](https://github.com/Melly-999/alpha_data_scraper_ai/pull/306) | **UI label polish** — clearer "paper / simulated / read-only" messaging ([UI polish](../tasks/paper_sim_ui_polish_001.md)) | |
| 32 | +| [#307](https://github.com/Melly-999/alpha_data_scraper_ai/pull/307) | **Screenshot evidence** — public-safe demo screenshots ([evidence](../tasks/broker_sim_screenshot_evidence_001.md)) | |
| 33 | + |
| 34 | +**Readiness classification: B — READY FOR INTERNAL SIMULATED BROKER PREVIEW.** |
| 35 | + |
| 36 | +## 3. Safety-first design |
| 37 | + |
| 38 | +The safety posture is enforced in config, asserted by a pytest suite, validated |
| 39 | +by `scripts/validate_safety_config.py`, and surfaced in the UI: |
| 40 | + |
| 41 | +```text |
| 42 | +autotrade=false |
| 43 | +dry_run=true |
| 44 | +read_only=true |
| 45 | +live_orders_blocked=true |
| 46 | +execution_enabled=false |
| 47 | +max_risk_per_trade <= 1% |
| 48 | +no broker execution |
| 49 | +no live trading UX |
| 50 | +``` |
| 51 | + |
| 52 | +The frontend exposes **no** `placeOrder` / `submitOrder` / `cancelOrder` / |
| 53 | +`executeTrade` / `enableAutotrade`, and there are **no** Buy / Sell / Order / |
| 54 | +Execute controls anywhere. |
| 55 | + |
| 56 | +## 4. Demo proof |
| 57 | + |
| 58 | +The GET-only smoke (`scripts/broker_sim_readonly_smoke.ps1`) drives the read-only |
| 59 | +surface and asserts the safety flags + scans responses for forbidden fields. |
| 60 | +Recorded local run: |
| 61 | + |
| 62 | +```text |
| 63 | +PASS: 47 SAFETY-FAIL: 0 WARN: 0 SKIP: 0 |
| 64 | +RESULT: PASS -- read-only surface safe |
| 65 | +``` |
| 66 | + |
| 67 | +It is GET-only (no POST/PUT/PATCH/DELETE), needs no credentials, and exits 0 even |
| 68 | +when the backend is offline (documented degraded SKIP). |
| 69 | + |
| 70 | +## 5. Screenshots |
| 71 | + |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | + |
| 78 | +(Full inventory and public-safety review: [screenshot evidence](../tasks/broker_sim_screenshot_evidence_001.md).) |
| 79 | + |
| 80 | +## 6. Technical scope |
| 81 | + |
| 82 | +- **Backend:** FastAPI, broad read-only (GET) surface — `/api/safety/status`, |
| 83 | + `/api/brokers/...`, `/api/alpaca-paper/...`, `/api/positions/...`, |
| 84 | + `/api/orders`, `/api/risk/...`, `/api/terminal/...`. Demo/preview services |
| 85 | + back the broker surfaces; no live broker SDK is wired in. |
| 86 | +- **Frontend:** React + TypeScript terminal; display-only broker/paper panels |
| 87 | + with safety chips and demo labelling. |
| 88 | +- **Tooling:** PowerShell GET-only smoke; Python safety-config validator; CI |
| 89 | + (Bandit SAST, secret scanning, dependency audit, build, tests, Playwright e2e). |
| 90 | +- **Process:** small reviewed PRs, each with a review-merge gate (metadata, |
| 91 | + changed-file allow-list, validation, static scan, CI) before squash-merge. |
| 92 | + |
| 93 | +## 7. What this does not do |
| 94 | + |
| 95 | +- Does **not** connect to a real broker or use credentials / broker auth. |
| 96 | +- Does **not** place, submit, or cancel orders; **no** trade execution. |
| 97 | +- Does **not** show real balances, positions, or orders (demo/fallback data). |
| 98 | +- Is **not** production trading-ready and is **not** financial advice. |
| 99 | + |
| 100 | +## 8. What I learned / what this demonstrates |
| 101 | + |
| 102 | +- **Risk-first product thinking:** treat "don't ship an execution surface" as a |
| 103 | + feature, and make safety legible in both the API and the UI. |
| 104 | +- **API validation discipline:** a small, dependency-light GET-only smoke that |
| 105 | + proves invariants and scans for sensitive-field leakage. |
| 106 | +- **Frontend safety messaging:** unambiguous read-only / simulated labelling so a |
| 107 | + viewer can't mistake demo data for real trading. |
| 108 | +- **CI / review discipline:** allow-listed changed files, static scans, and a |
| 109 | + repeatable review-merge gate per PR. |
| 110 | +- **Honest scoping:** classifying readiness (B) and explicitly fencing real |
| 111 | + broker integration as a separate, approval-gated effort. |
| 112 | + |
| 113 | +## 9. Recruiter-friendly summary |
| 114 | + |
| 115 | +> Built and documented a read-only simulated broker preview for a FastAPI/React |
| 116 | +> fintech terminal. Added a safety audit, a GET-only smoke script, a demo |
| 117 | +> walkthrough, UI labelling polish, and public-safe screenshot evidence. The |
| 118 | +> milestone demonstrates API validation, frontend safety messaging, CI |
| 119 | +> discipline, and risk-first product thinking — all without live broker |
| 120 | +> execution. |
| 121 | +
|
| 122 | +## 10. Next steps |
| 123 | + |
| 124 | +- Optional: **DEAD-CODE-DASHBOARD-ROUTING-AUDIT-001** — decide on an unrouted |
| 125 | + legacy dashboard component found during the UI-polish task. |
| 126 | +- Future only (out of scope, separate explicit approval): real broker |
| 127 | + integration planning. |
| 128 | + |
| 129 | +Related portfolio docs: [case study](mellytrade_case_study.md) · |
| 130 | +[CV entry](mellytrade_cv_project_entry.md) · |
| 131 | +[LinkedIn summary](mellytrade_linkedin_summary.md). |
| 132 | + |
| 133 | +--- |
| 134 | + |
| 135 | +*MellyTrade is a read-only, dry-run, paper-only portfolio project. It is not a |
| 136 | +commercial platform, not a live trading system, and not financial advice.* |
0 commit comments