Spaces:
Running
Running
File size: 3,373 Bytes
4811dd1 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# Functional Requirements Document: "The Munger Engine" (Unified TS Stack)
**Project Goal:** Automated paper-trading dashboard that executes a 200-Week Moving Average (WMA) strategy on high-quality stocks.
**Architecture:** Unified TypeScript Stack (Next.js + Node.js + Alpaca SDK).
---
## 1. System Architecture Overview
- **Core:** Next.js 14/15 (App Router) using Server Actions and API Routes.
- **Engine:** Automated logic running via Vercel Cron or GitHub Actions (Node.js).
- **Execution:** Alpaca Trade API (Node SDK) for paper trading.
- **Data:** `yahoo-finance2` for fundamental and technical metrics.
---
## 2. Technical Stack Specifications
- **Language:** TypeScript (Strict Mode).
- **Frontend:** Tailwind CSS, Lucide React (Icons), Shadcn/UI (Components).
- **Backend:** Next.js Route Handlers (Serverless Functions).
- **External APIs:**
- `@alpacahq/alpaca-trade-api` (Execution).
- `yahoo-finance2` (Market Data).
---
## 3. Backend Logic & Strategy (TypeScript)
### 3.1 The "Forever Stock" Filter
Every asset in the watchlist must be validated against these fundamental criteria:
- **Return on Equity (ROE):** > 15% (Source: `quoteSummary.financialData`).
- **Debt-to-Equity:** < 50 (Source: `quoteSummary.financialData`).
- **Market Cap:** Filter for "Large Cap" (> $10B).
### 3.2 Strategy Execution Logic
- **Buy Trigger:** 1. Calculate $SMA_{200}$ using the last 200 weekly closing prices.
2. Condition: $CurrentPrice \leq SMA_{200} \times 1.05$ (within 5% of the average).
3. Action: Execute `buy` order via Alpaca.
- **Sell Trigger:**
1. **Trend Death:** $CurrentPrice < SMA_{200} \times 0.90$ (10% breakdown).
2. **Fundamental Decay:** $ROE < 10\%$ or $Debt/Equity > 100$.
3. Action: Execute `liquidate` order via Alpaca.
---
## 4. Frontend Requirements (Next.js Dashboard)
### 4.1 Component: Opportunity Heatmap
- **Visual Goal:** Show distance from the "Munger Entry Point".
- **Logic:** Calculate $(\frac{Price - SMA_{200}}{SMA_{200}}) \times 100$.
- **UI:** Color-coded cards (Green: < 3% distance, Yellow: 3-8%, Grey: > 8%).
### 4.2 Component: Discipline Tracker
- **Visual Goal:** Gamify "Wait-and-See" investing.
- **Logic:** Days since `last_trade_event`.
- **UI:** Counter "Days of Discipline" with a progress bar towards a "Munger Badge".
### 4.3 Component: Quality Scorecards
- **Visual Goal:** Display the "Why" behind the holding.
- **Logic:** Real-time fetch of ROE, Debt/Equity, and Net Profit Margin.
- **UI:** Dashboard cards with a "Strategy Compliance" status (e.g., "Active Support" or "Risk: Fundamental Decay").
---
## 5. Workflow & Scheduling
1. **The Sync:** A Cron Job calls `/api/strategy/execute` every Sunday before market open.
2. **The Scan:** The handler iterates through the `WATCHLIST`, fetches Yahoo Finance data, and compares it with Alpaca positions.
3. **The Trade:** If signals match, the Alpaca SDK sends orders.
4. **The Log:** All results are stored in a database (Supabase/Prisma) or a `state.json` for the frontend.
---
## 6. Safety Guardrails
- **Paper Trading Only:** The `paper` flag in the Alpaca client must be hardcoded to `true`.
- **Max Position Size:** No single stock should exceed 10% of the paper account's total buying power.
- **Error Handling:** Use `Zod` for validating Yahoo Finance responses to prevent engine crashes on missing data.
|