docs/funct_reqs.md

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.