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.