feat: Implement Munger Engine API with v1 routes, data storage, core logic, and Docker deployment configuration.

Dockerfile

@@ -0,0 +1,26 @@
+
+FROM node:20-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build the Next.js application
+RUN npm run build
+
+# Expose port (HF Spaces defaults to 7860 usually, but Next.js defaults to 3000)
+# We can configure Next.js to run on 7860 or redirect port.
+# Better to use 7860 for HF Spaces compatibility if standard.
+ENV PORT=7860
+
+EXPOSE 7860
+
+# Ensure data directory exists and is writable
+RUN mkdir -p data && chmod 777 data
+
+CMD ["npm", "start"]

README_API.md

@@ -0,0 +1,111 @@
+
+# Munger Engine API
+
+This project converts the Munger Stock Analysis Strategy into a deployable API for Hugging Face Spaces.
+
+## Quick Start
+
+### Local Development
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Run the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+   *Note: If behind a corporate proxy or experiencing SSL issues, use:*
+
+   ```bash
+   npm run dev:insecure
+   ```
+
+3. Endpoints will be available at `http://localhost:3000/api/v1/...`
+
+### API Endpoints
+
+> [!TIP]
+> You can import the included `munger-api.postman_collection.json` file into Postman to quickly test all endpoints.
+
+| Method | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/v1/health` | Check system status. |
+| `POST` | `/api/v1/sync` | Trigger scan. Payload: `{ "force": true, "symbols": ["AAPL"] }`. |
+| `GET` | `/api/v1/signals` | Get list of filtered stocks. Query params: `signal` (e.g. BUY_TRIGGER), `interesting=true` (BUY_TRIGGER + WATCHLIST). |
+| `GET` | `/api/v1/ticker/[symbol]` | Get detailed analysis for a specific stock. |
+| `GET` | `/api/v1/portfolio` | Get Alpaca Paper Trading positions. |
+
+### Usage Examples
+
+**Trigger Scan (Full):**
+
+```bash
+curl -X POST http://localhost:3000/api/v1/sync \
+  -H "Content-Type: application/json" \
+  -d '{"force": true}'
+```
+
+**Trigger Scan (Specific Symbols - Ideal for Testing):**
+
+```bash
+curl -X POST http://localhost:3000/api/v1/sync \
+  -H "Content-Type: application/json" \
+  -d '{"symbols": ["ERIE", "AAPL"], "force": true}'
+```
+
+**Get Signals:**
+
+```bash
+curl http://localhost:3000/api/v1/signals
+```
+
+**Get Ticker Details:**
+
+```bash
+curl http://localhost:3000/api/v1/ticker/AAPL
+```
+
+## Order Execution Engine
+
+The API uses a deterministic **Trade Plan Builder** for signals marked as `BUY_TRIGGER`.
+
+### Advanced Logic Blueprint
+
+* **Playbook:** `BUY_TRIGGER_REBOUND_CONFIRM` (Breakout-style Entry).
+* **Risk Model:** Wilder's ATR(14) with 1:3 Risk-Reward Ratio.
+  * *Risk Unit (R):* 2.0 * ATR.
+* **Entry Order:** `STOP_LIMIT` (Day).
+  * *Stop Price:* Trigger Level + Tick ($0.01).
+  * *Limit Price:* Entry Stop + Slippage Buffer (0.75%).
+  * *Expiry:* 5 Trading Days.
+* **Protective Stop:** `STOP` Order (GTC).
+  * *Price:* Entry - 1R.
+* **Take Profit:** `LIMIT` Order (GTC).
+  * *Price:* Entry + 3R.
+* **Position Sizing:** Portfolio Aware (Alpaca Integration).
+  * Fetches Equity & Buying Power.
+  * Risks **0.5%** of Equity per trade.
+  * Caps Position Size at **10%** of Equity.
+  * Checks Buying Power constraints.
+* **Output:** Returns a comprehensive JSON `TradePlan` including specific order parameters, risk calculation details, and sizing constraints.
+
+### Deployment to Hugging Face Spaces
+
+1. Create a new **Docker** Space on Hugging Face.
+2. Upload this repository.
+3. Set the following **Secret** variables in your Space settings:
+   * `ALPACA_KEY`
+   * `ALPACA_SECRET`
+   * `HF_TOKEN` (optional, for future dataset integration)
+
+The Dockerfile is configured to run the Next.js application on port 7860.
+
+## Configuration
+
+* **Watchlist**: Currently uses `scripts/sp500_symbols.json`.
+* **Persistence**: Data is stored in `data/stocks.json`. **Note:** On standard HF Spaces, this data is ephemeral and will reset on restart. For production, consider using HF Datasets or an external DB.

api_reqs.md

@@ -0,0 +1,97 @@
+# Documento de Especificaciones Técnicas: Munger Intelligence Engine API
+
+**Versión:** 1.0  
+**Tecnologías:** Node.js, Next.js (App Router), TypeScript, yahoo-finance2  
+**Despliegue:** Hugging Face Spaces (Docker)  
+
+---
+
+## 1. Resumen del Proyecto
+
+El "Munger Intelligence Engine" es una API de análisis financiero diseñada para automatizar la estrategia de inversión de Charlie Munger: comprar empresas de "alta calidad" cuando cotizan cerca de su media móvil de 200 semanas (200-WMA). El sistema debe realizar descargas diarias, filtrar por capitalización de mercado y gestionar estados de señales en tiempo real.
+
+---
+
+## 2. Definición de la Watchlist e Ingesta de Datos
+
+### 2.1 Segmentación por Capitalización (Market Cap)
+
+El sistema debe ignorar cualquier activo que no cumpla con los umbrales de seguridad institucional:
+
+* **Elite Compounders (Mega Cap):** > $100B. Empresas con fosos económicos globales.
+* **Blue Chips (Large Cap):** > $10B. Estándar mínimo de liquidez y estabilidad para la estrategia.
+
+### 2.2 Estrategia de Descarga Paralelizada (Batching)
+
+Para optimizar el rendimiento y evitar bloqueos de IP/Rate Limiting de Yahoo Finance:
+
+* **Tamaño de Lote (Batch):** 50 tickers por iteración.
+* **Concurrencia:** Utilizar `Promise.all` para procesar los 50 tickers de cada lote simultáneamente.
+* **Frecuencia:** Descarga diaria automatizada de `quote` y `quoteSummary`.
+
+---
+
+## 3. Lógica del Motor de Análisis (Munger Strategy)
+
+Cada ticker debe ser evaluado bajo tres filtros secuenciales:
+
+1. **Filtro Fundamental (Calidad):**
+    * **ROE (Return on Equity):** > 15% (Mínimo), > 25% (Excelente).
+    * **Debt/Equity:** < 50% (Mínimo), < 15% (Ideal).
+2. **Filtro Técnico (Valor):**
+    * **200-WMA:** Media móvil simple de los últimos 200 cierres semanales.
+    * **Gatillo (Trigger):** Precio Actual $\leq$ (200-WMA * 1.05).
+3. **Margen de Seguridad:** Diferencia porcentual entre el Precio Actual y el Target Mean de analistas.
+
+---
+
+## 4. Gestión de Estados por Ticker
+
+El sistema debe mantener un estado persistente para cada ticker en la base de datos o archivo de estado en Hugging Face:
+
+| Estado | Descripción |
+| :--- | :--- |
+| `SCANNING` | Iniciando descarga de datos de `yahoo-finance2`. |
+| `FILTERING` | Validando Market Cap y métricas de calidad (ROE/Deuda). |
+| `TECHNICAL_EVAL` | Calculando posición respecto a la 200-WMA. |
+| `SIGNAL_READY` | Activo listo para compra o seguimiento activo. |
+| `ERROR` | Fallo en la ingesta de datos o ticker no encontrado. |
+
+---
+
+## 5. Especificación de Endpoints de la API
+
+### `GET /api/v1/health`
+
+* **Propósito:** Monitorización del sistema y estado de las APIs externas.
+* **Response:** JSON con `status`, `last_sync_timestamp` y `api_latency`.
+
+### `POST /api/v1/sync`
+
+* **Propósito:** Disparador del ciclo de descarga diaria (vía Cron).
+* **Lógica:** Ejecuta el procesamiento por lotes (50 tickers) usando `Promise.all`.
+* **Payload:** `{ "force": boolean, "segments": ["mega", "large"] }`.
+
+### `GET /api/v1/signals`
+
+* **Propósito:** Listar oportunidades activas para el Dashboard.
+* **Filtros:** Por `sector`, `munger_score` (0-100) y `upside`.
+* **Response:** Array de objetos `MungerStock`.
+
+### `GET /api/v1/ticker/:id`
+
+* **Propósito:** Deep Dive de un activo específico.
+* **Response:** Detalle completo incluyendo `quoteSummary`, histórico de WMA y catalizadores fundamentales.
+
+### `GET /api/v1/portfolio`
+
+* **Propósito:** Estado de las posiciones actuales en Alpaca (Paper Trading).
+* **Response:** Equity total, P&L de posiciones y "Días de Disciplina" (tiempo sin trades impulsivos).
+
+---
+
+## 6. Despliegue en Hugging Face Spaces
+
+* **Docker Image:** Base `node:20-slim`.
+* **Persistencia:** Utilizar **HF Datasets** o **R2 de Cloudflare** para evitar pérdida de datos por reinicio del Space.
+* **Variables de Entorno:** `ALPACA_KEY`, `ALPACA_SECRET`, `HF_TOKEN`.

app/api/v1/health/route.ts

@@ -0,0 +1,14 @@
+
+import { NextResponse } from 'next/server';
+import { JsonStore } from '@/lib/store';
+
+export async function GET() {
+    const status = JsonStore.getStatus();
+
+    return NextResponse.json({
+        status: 'ok',
+        engineStatus: status.status,
+        lastSync: status.lastSyncTimestamp,
+        timestamp: new Date().toISOString()
+    });
+}

app/api/v1/portfolio/route.ts

@@ -0,0 +1,43 @@
+
+import { NextResponse } from 'next/server';
+import Alpaca from '@alpacahq/alpaca-trade-api';
+
+export async function GET() {
+    const key = process.env.ALPACA_KEY;
+    const secret = process.env.ALPACA_SECRET;
+
+    if (!key || !secret) {
+        return NextResponse.json({
+            message: 'Alpaca credentials not found in env',
+            isConnected: false
+        }, { status: 503 });
+    }
+
+    try {
+        const alpaca = new (Alpaca as any)({
+            keyId: key,
+            secretKey: secret,
+            paper: true,
+        });
+
+        const account = await alpaca.getAccount();
+        const positions = await alpaca.getPositions();
+
+        return NextResponse.json({
+            isConnected: true,
+            equity: account.equity,
+            cash: account.cash,
+            buyingPower: account.buying_power,
+            positions: positions.map((p: any) => ({
+                symbol: p.symbol,
+                qty: p.qty,
+                marketValue: p.market_value,
+                unrealizedPl: p.unrealized_pl,
+                unrealizedPlpc: p.unrealized_plpc
+            }))
+        });
+    } catch (error: any) {
+        console.error('Alpaca error:', error);
+        return NextResponse.json({ error: 'Failed to fetch portfolio', details: error.message }, { status: 500 });
+    }
+}

app/api/v1/signals/route.ts

@@ -0,0 +1,30 @@
+
+import { NextResponse } from 'next/server';
+import { JsonStore } from '@/lib/store';
+
+export async function GET(request: Request) {
+    const { searchParams } = new URL(request.url);
+    const signalFilter = searchParams.get('signal');
+    const interestingFilter = searchParams.get('interesting');
+
+    let stocks = JsonStore.getStocks();
+
+    if (signalFilter) {
+        stocks = stocks.filter(s => s.signal === signalFilter);
+    } else if (interestingFilter === 'true') {
+        stocks = stocks.filter(s => s.signal === 'BUY_TRIGGER' || s.signal === 'WATCHLIST');
+    } else {
+        // Default: Show everything except IGNORE? Or just return all?
+        // Let's return all but maybe sort by signal priority
+        // Priority: BUY_TRIGGER > WATCHLIST > WAIT > IGNORE
+    }
+
+    // Sorting
+    const priority = { 'BUY_TRIGGER': 0, 'WATCHLIST': 1, 'WAIT': 2, 'IGNORE': 3 };
+    stocks.sort((a, b) => (priority[a.signal] || 99) - (priority[b.signal] || 99));
+
+    return NextResponse.json({
+        count: stocks.length,
+        stocks
+    });
+}

app/api/v1/sync/route.ts

@@ -0,0 +1,73 @@
+
+import { NextResponse } from 'next/server';
+import fs from 'fs';
+import path from 'path';
+import { MungerEngine } from '@/lib/munger-engine';
+import { JsonStore } from '@/lib/store';
+import { SyncPayload } from '@/lib/types';
+
+export async function POST(request: Request) {
+    try {
+        const body: SyncPayload = await request.json().catch(() => ({}));
+        const force = body.force || false;
+
+        // Status check - avoid overlapping scans
+        const currentStatus = JsonStore.getStatus();
+        if (currentStatus.status === 'SCANNING' && !force) {
+            return NextResponse.json({ message: 'Scan already in progress', status: currentStatus }, { status: 409 });
+        }
+
+        // Update status to SCANNING
+        JsonStore.updateStatus({ status: 'SCANNING', lastSyncTimestamp: new Date().toISOString() });
+
+        // Load symbols
+        let watchlist: string[] = [];
+        if (body.symbols && Array.isArray(body.symbols) && body.symbols.length > 0) {
+            console.log(`Using provided symbol list: ${body.symbols.join(', ')}`);
+            watchlist = body.symbols;
+        } else {
+            const jsonPath = path.resolve(process.cwd(), 'scripts/sp500_symbols.json');
+            if (fs.existsSync(jsonPath)) {
+                watchlist = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+            } else {
+                // Fallback list
+                watchlist = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'META', 'BRK-B', 'V', 'JNJ', 'WMT', 'PG'];
+            }
+        }
+
+        // Start background processing? 
+        // Next.js Serverless functions have 10s-60s timeout (Vercel). 
+        // On a container (Docker/HF Spaces), we can run longer.
+        // However, if we simply await here, the request might time out if it takes too long.
+        // For now, I will await the result, assuming the client (Cron) can handle the wait 
+        // or that we are running in an environment where timeout is not an issue (Docker).
+        // A better approach for really long jobs is to spawn a background process or use a queue, but that's overengineering for now.
+
+        console.log(`Starting scan for ${watchlist.length} symbols...`);
+        const results = await MungerEngine.processBatch(watchlist);
+
+        // Save results
+        JsonStore.saveStocks(results);
+
+        // Update status
+        const buyTriggers = results.filter(r => r.signal === 'BUY_TRIGGER').length;
+        JsonStore.updateStatus({
+            status: 'IDLE',
+            lastSyncTimestamp: new Date().toISOString(),
+            totalAssets: watchlist.length,
+            assetsAnalyzed: results.length,
+            buyTriggers: buyTriggers
+        });
+
+        return NextResponse.json({
+            message: 'Scan completed',
+            count: results.length,
+            buyTriggers
+        });
+
+    } catch (error: any) {
+        console.error('Sync failed:', error);
+        JsonStore.updateStatus({ status: 'ERROR', errors: [error.message] });
+        return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+    }
+}

app/api/v1/ticker/[id]/route.ts

@@ -0,0 +1,27 @@
+
+import { NextResponse } from 'next/server';
+import { MungerEngine } from '@/lib/munger-engine';
+import { JsonStore } from '@/lib/store';
+
+export async function GET(
+    request: Request,
+    { params }: { params: Promise<{ id: string }> }
+) {
+    const { id } = await params;
+    const symbol = id.toUpperCase();
+
+    // Get basic info from store first
+    const basicInfo = JsonStore.getStock(symbol);
+
+    try {
+        const detailedData = await MungerEngine.deepDive(symbol);
+
+        return NextResponse.json({
+            symbol,
+            ...basicInfo,
+            ...detailedData
+        });
+    } catch (error) {
+        return NextResponse.json({ error: 'Failed to fetch data', symbol }, { status: 404 });
+    }
+}

data/status.json

@@ -0,0 +1,9 @@
+{
+  "status": "IDLE",
+  "lastSyncTimestamp": "2026-01-20T14:33:50.686Z",
+  "apiLatencyMs": 0,
+  "totalAssets": 1,
+  "assetsAnalyzed": 1,
+  "buyTriggers": 1,
+  "errors": []
+}

data/stocks.json

@@ -0,0 +1,78 @@
+[
+  {
+    "symbol": "ERIE",
+    "price": 283.2099914550781,
+    "wma200": 314.65810050964353,
+    "roe": 0.30444,
+    "debtToEquity": 2.353,
+    "isQuality": true,
+    "lastCandleColor": "GREEN",
+    "touchedWMA": true,
+    "signal": "BUY_TRIGGER",
+    "details": "Rebound Confirm",
+    "sector": "Unknown",
+    "marketCap": 14810582016,
+    "lastUpdated": "2026-01-20T14:33:49.438Z",
+    "tradePlan": {
+      "symbol": "ERIE",
+      "recommendation": "NO_TRADE",
+      "playbook": "BUY_TRIGGER_REBOUND_CONFIRM",
+      "riskModel": {
+        "atrPeriod": 14,
+        "atr": 6.15,
+        "kAtr": 2,
+        "rr": 3
+      },
+      "levels": {
+        "entry": 290.17,
+        "entryLimit": 292.35,
+        "stopLoss": 277.86,
+        "takeProfit": 327.09
+      },
+      "sizing": {
+        "equity": 2467.46,
+        "buyingPower": 1913.66,
+        "riskPct": 0.005,
+        "riskBudget": 12.34,
+        "riskPerShare": 12.31,
+        "qty": 0,
+        "caps": {
+          "maxPositionPct": 0.1,
+          "qtyByRisk": 1,
+          "qtyByNotional": 0,
+          "qtyByBuyingPower": 6
+        }
+      },
+      "orders": [
+        {
+          "role": "ENTRY",
+          "type": "STOP_LIMIT",
+          "side": "BUY",
+          "stopPrice": 290.17,
+          "limitPrice": 292.35,
+          "timeInForce": "DAY",
+          "qty": 0,
+          "expireAfterDays": 5
+        },
+        {
+          "role": "EXIT_AFTER_FILL",
+          "type": "OCO",
+          "side": "SELL",
+          "takeProfitLimit": 327.09,
+          "stopLossStop": 277.86,
+          "qty": 0
+        }
+      ],
+      "reasons": [
+        "signal=BUY_TRIGGER",
+        "playbook=REBOUND_CONFIRM",
+        "ATR_Risk_Model=1:3"
+      ],
+      "followUp": [
+        "Submit stop-limit entry.",
+        "When filled, submit OCO exits (TP + SL).",
+        "Cancel entry if not filled after 5 trading days."
+      ]
+    }
+  }
+]

lib/munger-engine.ts

@@ -0,0 +1,396 @@
+
+import YahooFinance from 'yahoo-finance2';
+import { MungerStock, TradePlan } from './types';
+import { JsonStore } from './store';
+import Alpaca from '@alpacahq/alpaca-trade-api';
+
+// Suppress excessive logging from specific modules if needed
+// Suppress excessive logging from specific modules if needed
+const yahooFinance = new (YahooFinance as any)({
+    suppressNotices: ['yahooSurvey']
+});
+
+// Constants
+const BATCH_SIZE = 50;
+
+// Config for Advanced Engine
+const RISK_CONFIG = {
+    atrPeriod: 14,
+    kAtr: 2.0,
+    rr: 3.0,
+    riskPct: 0.005, // 0.5%
+    maxPositionPct: 0.10, // 10%
+    entryLimitBufferBps: 75.0
+};
+
+export class MungerEngine {
+
+    /**
+     * Calculates the date of the last Sunday
+     */
+    private static getLastSunday(): Date {
+        const d = new Date();
+        const day = d.getDay();
+        const diff = d.getDate() - day;
+        const sunday = new Date(d.setDate(diff));
+        sunday.setHours(23, 59, 59, 999);
+        return sunday;
+    }
+
+    /**
+     * Core analysis logic for a single stock
+     */
+    private static async analyzeStock(symbol: string, refDate: Date): Promise<MungerStock | null> {
+        try {
+            const queryOptions = { period1: '2019-01-01', period2: refDate, interval: '1wk' as const };
+
+            // Fetch chart data
+            let history;
+            try {
+                history = await yahooFinance.chart(symbol, queryOptions);
+            } catch (e) {
+                console.warn(`Failed to fetch chart for ${symbol}`);
+                return null;
+            }
+
+            const quotes = history.quotes.filter((q: any) => q.close && q.open);
+
+            if (quotes.length < 205) return null;
+
+            const latestIndex = quotes.length - 1;
+            const currentPrice = quotes[latestIndex].close as number;
+
+            // Simple MA 200 Calculation
+            const calculateMA200 = (endIndex: number) => {
+                if (endIndex < 199) return 0;
+                const slice = quotes.slice(endIndex - 199, endIndex + 1).map((q: any) => q.close as number);
+                return slice.reduce((a: number, b: number) => a + b, 0) / slice.length;
+            };
+
+            const MA200 = calculateMA200(latestIndex);
+
+            // Fetch fundamental data
+            let summary;
+            try {
+                summary = await yahooFinance.quoteSummary(symbol, { modules: ['financialData', 'summaryDetail', 'price'] });
+            } catch (e) {
+                console.warn(`Failed to fetch summary for ${symbol}`);
+                return null;
+            }
+
+            const roe = summary.financialData?.returnOnEquity || 0;
+            const debtToEquity = summary.financialData?.debtToEquity || 999;
+            const marketCap = summary.price?.marketCap || 0;
+            const sector = summary.summaryProfile?.sector || 'Unknown';
+            const fiftyTwoWeekLow = summary.summaryDetail?.fiftyTwoWeekLow;
+
+            // Quality Check (Refined from requirements)
+            // Note: Requirements say ROE > 15% (0.15) and Debt/Equity < 50
+            const isQuality = roe > 0.15 && debtToEquity < 50;
+
+            // Strategy Logic
+            let touchedWMA = false;
+            for (let i = 0; i < 4; i++) {
+                const idx = latestIndex - i;
+                if (idx < 0) continue;
+                const candle = quotes[idx];
+                const ma = calculateMA200(idx);
+                if (candle.low <= ma) touchedWMA = true;
+            }
+
+            const lastCandle = quotes[latestIndex];
+            const isGreen = lastCandle.close > lastCandle.open;
+            let signal: 'BUY_TRIGGER' | 'WATCHLIST' | 'IGNORE' | 'WAIT' = 'WATCHLIST';
+
+            if (!isQuality) {
+                signal = 'IGNORE';
+            } else if (touchedWMA) {
+                if (isGreen) signal = 'BUY_TRIGGER';
+                else signal = 'WAIT';
+            } else {
+                const dist = (currentPrice - MA200) / MA200;
+                if (dist > 0 && dist < 0.05) signal = 'WATCHLIST'; // Within 5%
+                else if (dist < 0) signal = 'WAIT';
+                else signal = 'IGNORE';
+            }
+
+            // Details string
+            let details = '';
+            if (!isQuality) details = 'Low Quality';
+            else if (touchedWMA) details = isGreen ? 'Rebound Confirm' : 'Testing Support';
+            else details = `Dist: ${(((currentPrice - MA200) / MA200) * 100).toFixed(1)}%`;
+
+            return {
+                symbol,
+                price: currentPrice,
+                wma200: MA200,
+                roe,
+                debtToEquity,
+                isQuality,
+                lastCandleColor: isGreen ? 'GREEN' : 'RED',
+                touchedWMA,
+                signal,
+                details,
+                sector,
+                marketCap,
+                lastUpdated: new Date().toISOString(),
+                tradePlan: signal === 'BUY_TRIGGER' ? await this.buildTradePlan(symbol, currentPrice, lastCandle.high) : undefined
+            };
+
+        } catch (error: any) {
+            console.error(`Error analyzing ${symbol}:`, error.message);
+            return null;
+        }
+    }
+
+    /**
+     * Wilder's ATR Calculation
+     */
+    private static calculateWilderATR(quotes: any[], period: number): number {
+        if (quotes.length < period + 1) return 0;
+
+        // 1. Calculate TRs
+        const trs = [];
+        for (let i = 1; i < quotes.length; i++) {
+            const high = quotes[i].high;
+            const low = quotes[i].low;
+            const prevClose = quotes[i - 1].close;
+            trs.push(Math.max(high - low, Math.abs(high - prevClose), Math.abs(low - prevClose)));
+        }
+
+        if (trs.length < period) return 0;
+
+        // 2. Initial SMA
+        let atr = trs.slice(0, period).reduce((a, b) => a + b, 0) / period;
+
+        // 3. Wilder Smoothing
+        for (let i = period; i < trs.length; i++) {
+            atr = (atr * (period - 1) + trs[i]) / period;
+        }
+
+        return atr;
+    }
+
+    /**
+     * Get Alpaca Portfolio State
+     */
+    private static async getAlpacaState(): Promise<{ equity: number; buyingPower: number; positions: any[] }> {
+        const alpaca = new Alpaca({
+            keyId: process.env.ALPACA_KEY,
+            secretKey: process.env.ALPACA_SECRET,
+            paper: true,
+        });
+
+        const account = await alpaca.getAccount();
+        const positions = await alpaca.getPositions();
+
+        return {
+            equity: Number(account.equity),
+            buyingPower: Number(account.buying_power),
+            positions
+        };
+    }
+
+    /**
+     * Constructs a deterministic trade plan based on the "Rebound Confirm" playbook
+     */
+    private static async buildTradePlan(symbol: string, currentPrice: number, triggerHigh: number): Promise<TradePlan> {
+        // Fetch Daily Bars for ATR (Yahoo currently used for simplicity and consistency)
+        // User requested Daily bars. analyzeStock used weekly.
+        const dailyHistory = await yahooFinance.chart(symbol, {
+            period1: '2023-01-01', // Enough for 14 ATR
+            interval: '1d'
+        });
+        const dailyQuotes = dailyHistory.quotes.filter((q: any) => q.close && q.open);
+
+        const atr = this.calculateWilderATR(dailyQuotes, RISK_CONFIG.atrPeriod);
+
+        // Fetch Alpaca State
+        let alpacaState = { equity: 100000, buyingPower: 100000, positions: [] as any[] };
+        try {
+            if (process.env.ALPACA_KEY) {
+                alpacaState = await this.getAlpacaState();
+            }
+        } catch (e) {
+            console.warn('Failed to fetch Alpaca state, using defaults:', e);
+        }
+
+        // Logic
+        const tick = 0.01;
+        const triggerLevel = triggerHigh;
+        const entryStop = Number((triggerLevel + tick).toFixed(2));
+        const entryLimit = Number((entryStop * (1 + RISK_CONFIG.entryLimitBufferBps / 10000)).toFixed(2));
+
+        const R = RISK_CONFIG.kAtr * atr;
+        const stopLoss = Number((entryStop - R).toFixed(2));
+        const takeProfit = Number((entryStop + RISK_CONFIG.rr * R).toFixed(2));
+
+        // Sizing
+        const riskBudget = alpacaState.equity * RISK_CONFIG.riskPct;
+        const riskPerShare = entryStop - stopLoss;
+
+        let qty = 0;
+        let qtyByRisk = 0;
+        let qtyByNotional = 0;
+        let qtyByBuyingPower = 0;
+
+        if (riskPerShare > 0) {
+            qtyByRisk = Math.floor(riskBudget / riskPerShare);
+            qtyByNotional = Math.floor((alpacaState.equity * RISK_CONFIG.maxPositionPct) / entryStop);
+            qtyByBuyingPower = Math.floor(alpacaState.buyingPower / entryStop);
+            qty = Math.max(0, Math.min(qtyByRisk, qtyByNotional, qtyByBuyingPower));
+        }
+
+        const recommendation = qty >= 1 ? 'BUY' : 'NO_TRADE';
+
+        return {
+            symbol,
+            recommendation,
+            playbook: 'BUY_TRIGGER_REBOUND_CONFIRM',
+            riskModel: {
+                atrPeriod: RISK_CONFIG.atrPeriod,
+                atr: Number(atr.toFixed(2)),
+                kAtr: RISK_CONFIG.kAtr,
+                rr: RISK_CONFIG.rr
+            },
+            levels: {
+                entry: entryStop,
+                entryLimit,
+                stopLoss,
+                takeProfit
+            },
+            sizing: {
+                equity: alpacaState.equity,
+                buyingPower: alpacaState.buyingPower,
+                riskPct: RISK_CONFIG.riskPct,
+                riskBudget: Number(riskBudget.toFixed(2)),
+                riskPerShare: Number(riskPerShare.toFixed(2)),
+                qty,
+                caps: {
+                    maxPositionPct: RISK_CONFIG.maxPositionPct,
+                    qtyByRisk,
+                    qtyByNotional,
+                    qtyByBuyingPower
+                }
+            },
+            orders: [
+                {
+                    role: 'ENTRY',
+                    type: 'STOP_LIMIT',
+                    side: 'BUY',
+                    stopPrice: entryStop,
+                    limitPrice: entryLimit,
+                    timeInForce: 'DAY',
+                    qty,
+                    expireAfterDays: 5
+                },
+                {
+                    role: 'EXIT_AFTER_FILL',
+                    type: 'OCO',
+                    side: 'SELL',
+                    takeProfitLimit: takeProfit,
+                    stopLossStop: stopLoss,
+                    qty
+                }
+            ],
+            reasons: [
+                `signal=BUY_TRIGGER`,
+                `playbook=REBOUND_CONFIRM`,
+                `ATR_Risk_Model=1:${RISK_CONFIG.rr}`
+            ],
+            followUp: [
+                "Submit stop-limit entry.",
+                "When filled, submit OCO exits (TP + SL).",
+                "Cancel entry if not filled after 5 trading days."
+            ]
+        };
+    }
+
+    /**
+     * Processes a list of symbols in batches
+     */
+    static async processBatch(symbols: string[]): Promise<MungerStock[]> {
+        const lastSunday = this.getLastSunday();
+        const results: MungerStock[] = [];
+
+        // Chunking
+        for (let i = 0; i < symbols.length; i += BATCH_SIZE) {
+            const chunk = symbols.slice(i, i + BATCH_SIZE);
+            console.log(`Processing batch ${i / BATCH_SIZE + 1} / ${Math.ceil(symbols.length / BATCH_SIZE)}...`);
+
+            const promises = chunk.map(symbol => this.analyzeStock(symbol, lastSunday));
+            const chunkResults = await Promise.all(promises);
+
+            chunkResults.forEach(res => {
+                if (res) results.push(res);
+            });
+
+            // Small delay to be polite to the API
+            await new Promise(r => setTimeout(r, 500));
+        }
+
+        return results;
+    }
+
+    /**
+     * Deep dive method for single ticker
+     */
+    static async deepDive(symbol: string): Promise<any> {
+        try {
+            const [quote, summary, fundamentalsTimeSeries] = await Promise.all([
+                yahooFinance.quote(symbol),
+                yahooFinance.quoteSummary(symbol, {
+                    modules: [
+                        'assetProfile',
+                        'balanceSheetHistory',
+                        'balanceSheetHistoryQuarterly',
+                        'calendarEvents',
+                        'cashflowStatementHistory',
+                        'cashflowStatementHistoryQuarterly',
+                        'defaultKeyStatistics',
+                        'earnings',
+                        'earningsHistory',
+                        'earningsTrend',
+                        'financialData',
+                        'fundOwnership',
+                        'incomeStatementHistory',
+                        'incomeStatementHistoryQuarterly',
+                        'indexTrend',
+                        'industryTrend',
+                        'insiderHolders',
+                        'insiderTransactions',
+                        'institutionOwnership',
+                        'majorDirectHolders',
+                        'majorHoldersBreakdown',
+                        'netSharePurchaseActivity',
+                        'price',
+                        'quoteType',
+                        'recommendationTrend',
+                        'secFilings',
+                        'sectorTrend',
+                        'summaryDetail',
+                        'summaryProfile',
+                        'upgradeDowngradeHistory'
+                    ]
+                }).catch((e: any) => {
+                    console.warn(`Partial summary fail for ${symbol}: ${e.message}`);
+                    return {};
+                }),
+                // Disable validation as Yahoo API frequently changes schema causing library errors
+                yahooFinance.fundamentalsTimeSeries(symbol, { period1: '2020-01-01', module: 'all' }, { validateResult: false }).catch((e: any) => {
+                    console.warn(`Fundamentals fail for ${symbol}: ${e.message}`);
+                    return [];
+                })
+            ]);
+
+            return {
+                quote,
+                fundamentalsTimeSeries,
+                ...summary
+            };
+        } catch (e: any) {
+            console.error(`Deep dive failed for ${symbol}`, e);
+            throw e;
+        }
+    }
+}

lib/store.ts

@@ -0,0 +1,66 @@
+
+import fs from 'fs';
+import path from 'path';
+import { MungerStock, EngineStatus } from './types';
+
+const DATA_DIR = path.resolve(process.cwd(), 'data');
+const STOCKS_FILE = path.join(DATA_DIR, 'stocks.json');
+const STATUS_FILE = path.join(DATA_DIR, 'status.json');
+
+// Ensure data dir exists
+if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+}
+
+export class JsonStore {
+    private static readJson<T>(filePath: string, defaultValue: T): T {
+        try {
+            if (!fs.existsSync(filePath)) {
+                return defaultValue;
+            }
+            const data = fs.readFileSync(filePath, 'utf-8');
+            return JSON.parse(data);
+        } catch (error) {
+            console.error(`Error reading ${filePath}:`, error);
+            return defaultValue;
+        }
+    }
+
+    private static writeJson<T>(filePath: string, data: T): void {
+        try {
+            fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+        } catch (error) {
+            console.error(`Error writing ${filePath}:`, error);
+        }
+    }
+
+    static getStocks(): MungerStock[] {
+        return this.readJson<MungerStock[]>(STOCKS_FILE, []);
+    }
+
+    static saveStocks(stocks: MungerStock[]): void {
+        this.writeJson(STOCKS_FILE, stocks);
+    }
+
+    static getStatus(): EngineStatus {
+        return this.readJson<EngineStatus>(STATUS_FILE, {
+            status: 'IDLE',
+            lastSyncTimestamp: new Date().toISOString(),
+            apiLatencyMs: 0,
+            totalAssets: 0,
+            assetsAnalyzed: 0,
+            buyTriggers: 0,
+            errors: []
+        });
+    }
+
+    static updateStatus(partialStatus: Partial<EngineStatus>): void {
+        const current = this.getStatus();
+        this.writeJson(STATUS_FILE, { ...current, ...partialStatus });
+    }
+
+    static getStock(symbol: string): MungerStock | undefined {
+        const stocks = this.getStocks();
+        return stocks.find(s => s.symbol === symbol);
+    }
+}

lib/types.ts

@@ -0,0 +1,83 @@
+
+export interface MungerStock {
+    symbol: string;
+    price: number;
+    wma200: number;
+    roe: number;
+    debtToEquity: number;
+    isQuality: boolean;
+    lastCandleColor: 'GREEN' | 'RED';
+    touchedWMA: boolean;
+    signal: 'BUY_TRIGGER' | 'WATCHLIST' | 'IGNORE' | 'WAIT';
+    details: string;
+    sector?: string;
+    marketCap?: number;
+    mungerScore?: number;
+    lastUpdated: string;
+    tradePlan?: TradePlan;
+}
+
+export interface TradeOrder {
+    role: 'ENTRY' | 'PROTECTIVE_STOP' | 'TAKE_PROFIT' | 'EXIT' | 'EXIT_AFTER_FILL';
+    type: 'MARKET' | 'LIMIT' | 'STOP' | 'STOP_LIMIT' | 'OCO';
+    side: 'BUY' | 'SELL';
+    limitPrice?: number;
+    stopPrice?: number;
+    takeProfitLimit?: number;
+    stopLossStop?: number;
+    timeInForce?: 'GTC' | 'DAY';
+    qty?: number;
+    expireAfterDays?: number;
+}
+
+export interface TradePlan {
+    symbol: string;
+    recommendation: 'BUY' | 'SELL' | 'NO_TRADE';
+    playbook: string;
+    riskModel?: {
+        atrPeriod: number;
+        atr: number;
+        kAtr: number;
+        rr: number;
+    };
+    levels?: {
+        entry: number;
+        entryLimit?: number;
+        stopLoss: number;
+        takeProfit: number;
+    };
+    sizing?: {
+        equity: number;
+        buyingPower: number;
+        riskPct: number;
+        riskBudget: number;
+        riskPerShare: number;
+        qty: number;
+        caps: {
+            maxPositionPct: number;
+            qtyByRisk: number;
+            qtyByNotional: number;
+            qtyByBuyingPower: number;
+        };
+    };
+    orders: TradeOrder[];
+    followUp: string[];
+    reasons: string[];
+}
+
+
+export interface EngineStatus {
+    status: 'IDLE' | 'SCANNING' | 'ERROR';
+    lastSyncTimestamp: string;
+    apiLatencyMs: number;
+    totalAssets: number;
+    assetsAnalyzed: number;
+    buyTriggers: number;
+    errors: string[];
+}
+
+export interface SyncPayload {
+    force?: boolean;
+    segments?: ('mega' | 'large')[];
+    symbols?: string[];
+}

munger-api.postman_collection.json

@@ -0,0 +1,142 @@
+{
+    "info": {
+        "_postman_id": "munger-engine-v1",
+        "name": "Munger Engine API",
+        "description": "API collection for the Munger Stock Analysis Engine.",
+        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+    },
+    "item": [
+        {
+            "name": "Health Check",
+            "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                    "raw": "{{baseUrl}}/api/v1/health",
+                    "host": [
+                        "{{baseUrl}}"
+                    ],
+                    "path": [
+                        "api",
+                        "v1",
+                        "health"
+                    ]
+                }
+            },
+            "response": []
+        },
+        {
+            "name": "Trigger Sync",
+            "request": {
+                "method": "POST",
+                "header": [],
+                "body": {
+                    "mode": "raw",
+                    "raw": "{\n    \"force\": true\n}",
+                    "options": {
+                        "raw": {
+                            "language": "json"
+                        }
+                    }
+                },
+                "url": {
+                    "raw": "{{baseUrl}}/api/v1/sync",
+                    "host": [
+                        "{{baseUrl}}"
+                    ],
+                    "path": [
+                        "api",
+                        "v1",
+                        "sync"
+                    ]
+                }
+            },
+            "response": []
+        },
+        {
+            "name": "Get Signals",
+            "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                    "raw": "{{baseUrl}}/api/v1/signals",
+                    "host": [
+                        "{{baseUrl}}"
+                    ],
+                    "path": [
+                        "api",
+                        "v1",
+                        "signals"
+                    ]
+                }
+            },
+            "response": []
+        },
+        {
+            "name": "Get Ticker Details",
+            "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                    "raw": "{{baseUrl}}/api/v1/ticker/AAPL",
+                    "host": [
+                        "{{baseUrl}}"
+                    ],
+                    "path": [
+                        "api",
+                        "v1",
+                        "ticker",
+                        "AAPL"
+                    ]
+                }
+            },
+            "response": []
+        },
+        {
+            "name": "Get Portfolio (Paper)",
+            "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                    "raw": "{{baseUrl}}/api/v1/portfolio",
+                    "host": [
+                        "{{baseUrl}}"
+                    ],
+                    "path": [
+                        "api",
+                        "v1",
+                        "portfolio"
+                    ]
+                }
+            },
+            "response": []
+        }
+    ],
+    "event": [
+        {
+            "listen": "prerequest",
+            "script": {
+                "type": "text/javascript",
+                "exec": [
+                    ""
+                ]
+            }
+        },
+        {
+            "listen": "test",
+            "script": {
+                "type": "text/javascript",
+                "exec": [
+                    ""
+                ]
+            }
+        }
+    ],
+    "variable": [
+        {
+            "key": "baseUrl",
+            "value": "http://localhost:3000",
+            "type": "string"
+        }
+    ]
+}

package.json

@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "dev": "next dev",
+    "dev:insecure": "NODE_TLS_REJECT_UNAUTHORIZED=0 next dev",
     "build": "next build",
     "start": "next start",
     "lint": "eslint"
@@ -28,4 +29,4 @@
     "tsx": "^4.21.0",
     "typescript": "^5"
   }
-}
+}

scripts/test-api.ts

@@ -0,0 +1,61 @@
+
+import { spawn } from 'child_process';
+
+const BASE_URL = 'http://localhost:3000/api/v1';
+
+async function testEndpoint(name: string, path: string, method: string = 'GET', body?: any) {
+    console.log(`Testing ${name} (${method} ${path})...`);
+    try {
+        const res = await fetch(`${BASE_URL}${path}`, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: body ? JSON.stringify(body) : undefined
+        });
+
+        const data = await res.json();
+        console.log(`[${res.status}] Response:`, JSON.stringify(data).substring(0, 100) + '...');
+        if (!res.ok) {
+            console.error(`FAILED: ${JSON.stringify(data)}`);
+        }
+    } catch (e: any) {
+        console.error(`Error testing ${name}:`, e.message);
+    }
+}
+
+async function main() {
+    console.log('Starting Next.js server...');
+    const server = spawn('npm', ['run', 'start'], {
+        detached: false,
+        stdio: 'inherit',
+        env: { ...process.env, PORT: '3000' }
+    });
+
+    // Wait for server to be ready
+    await new Promise(resolve => setTimeout(resolve, 5000));
+
+    try {
+        await testEndpoint('Health', '/health');
+        await testEndpoint('Signals (Empty)', '/signals');
+
+        // Test Sync with a subset to save time (mocking not easy here, so actual call)
+        // We are running against the built app. 
+        // The sync will try to load sp500_symbols.json. 
+        // If it takes too long this script might exit, but let's try.
+        // Actually, sp500_symbols.json has many symbols. 
+        // Let's rely on the user manual verification for full sync or just trigger it and check if it starts.
+        // But since I didn't implement 'background' fully (it awaits), it will hang.
+        // So let's skip SYNC test or expect it to timeout if I await.
+        // I entered a "check if scanning" logic.
+
+        // Let's just check the endpoints exist.
+        await testEndpoint('Portfolio (No Auth)', '/portfolio');
+        await testEndpoint('Ticker (AAPL)', '/ticker/AAPL');
+
+    } finally {
+        console.log('Stopping server...');
+        server.kill();
+        process.exit(0);
+    }
+}
+
+main();

tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -19,7 +23,9 @@
       }
     ],
     "paths": {
-      "@/*": ["./*"]
+      "@/*": [
+        "./*"
+      ]
     }
   },
   "include": [
@@ -30,5 +36,8 @@
     ".next/dev/types/**/*.ts",
     "**/*.mts"
   ],
-  "exclude": ["node_modules"]
-}
+  "exclude": [
+    "node_modules",
+    "scripts"
+  ]
+}