Mintalyze
https://mintalyze.com/
Your automated minute view of the markets.
Mintalyze is a full-stack financial intelligence platform that combines real-time market data, AI-powered insights, and institutional-grade quantitative trading capabilities. Get instant market summaries, track custom watchlists, and leverage machine learning models for trading signals—all in one unified dashboard.
🆕 Recent Updates
AI Chat Agent & MCP Tools (v2.3 - Dec 2025)
- 🤖 AI Chat Interface - Conversational agent for market queries at
/chat
- 🔧 Model Context Protocol (MCP) - 20+ tools for AI agent to access Mintalyze data
- Market:
get_quote_snapshot, get_top_movers, get_market_summary
- User:
get_watchlists, get_alerts, create_watchlist, edit_watchlist
- QuantLab:
get_quant_signals, get_model_quality, get_top_signals
- Sentinel:
get_sentinel_report, get_insights
- News:
get_ticker_news, get_ticker_events, get_macro_events
- Analysis:
get_sentiment, get_ticker_alerts, get_explanation
- Info:
about_mintalyze
- 📊 Model Quality Tiers - Quality classification for ML models
- Best (🏆) - Excellent Sharpe ratio (>3) and Profit Factor (>2)
- Excellent (✓) - Good metrics, recommended for trading
- Good - Marginal performance
- Low Quality (⚠) - Poor metrics, not recommended
- ⚡ Lambda Agent - Serverless agent orchestrator
- 🔄 Type Coercion - Automatic argument type conversion for tool calls
News-Aware Predictions (v2.2 - Dec 2025)
- 📰 Bayesian News Integration - ML model probabilities adjusted using news sentiment and relevance
- 🎯 Two-Stage Prediction - Raw model output → News-based Bayesian update → Final signal
- 📊 Dual Scores in UI - QuantLab shows both raw and news-adjusted Quant Scores
- 🔄 Daily News Processing - Batch API processes 20 news items per ticker before predictions
- ⚖️ Weighted Categories - Company (1.0x), Sector (0.7x), Macro (0.4x), Noise (0.1x)
- 🧮 Sequential Bayesian Update - Multiple news items multiply likelihoods iteratively
- 💾 Database Storage - NewsItem table stores sentiment, relevance, and category for reuse
EC2 ML Services (v2.1 - Dec 2025)
- 🤖 Sentiment & Relevance Models - ML-powered news analysis deployed on EC2
- ⚡ FastAPI Services - Two microservices running on single t3.medium instance
- Sentiment service (:8001) - Headlines → sentiment scores (-1 to 1)
- Relevance service (:8002) - Headlines + ticker → relevance scores (0 to 1) + category
- 🎯 Intelligent News Filtering - ML models filter and score news for explain API and daily summaries
- 🚀 One-Command Redeployment -
./services/redeploy_models.sh for model updates
- 🔄 Model Training Pipeline - Train locally, deploy to EC2 with Docker
AWS Serverless Infrastructure (v2.0)
- ☁️ Lambda + SageMaker - Fully serverless ML inference pipeline for quant predictions
- ⏰ Automated Daily Analysis - EventBridge cron job (Mon-Fri, 4:05 PM EST)
- 🗄️ Database-Backed Predictions - Results stored in PostgreSQL for instant page loads
- 🐳 Docker Deployment - Containerized Lambda and SageMaker models
- 🏗️ Infrastructure as Code - Terraform for reproducible AWS deployments
- 🔐 Secrets Management - AWS Secrets Manager integration
- 📊 Manual Trigger - Admin panel button for testing cron job
Sentinel AI Agent (v1.0)
- 🧠 Autonomous Market Intelligence - Multi-stage analysis pipeline with anomaly detection
- 📝 Structured Narratives - "What This Means" explanations in plain English
- 📊 Historical Tracking - Database-backed report history with expandable insights
- 🎨 Component Refactoring - Modular dashboard with reusable cards
- 🔄 Collapsible UI - Space-efficient panel design on homepage
Component Library Expansion
- Molecules:
VolatilityCard, MarketSignalsCard, MarketSummaryCard, RegimeComponentsCard
- Organisms:
SentinelExplainToday, WhatThisMeans, ProfessionalInsights, LambdaCronRunner
Database Schema Updates
- Added
NewsItem model for storing ML-scored news (sentiment, relevance, category)
- Updated
LivePrediction with raw and news-adjusted fields for dual scoring
- Raw fields:
rawSignal, rawConfidence, rawProbUp, rawProbNeutral, rawProbDown
- News fields:
newsCount to track Bayesian update influence
- Added
SentinelReport model with structured narrative storage
- Added
DistribionalForecast model for probabilistic forecasts (200+ tickers daily)
- JSON fields for flexible data structures (
whatThisMeans, context, keyDrivers)
- Indexed anomaly flags and
runId for efficient querying
Performance Optimizations (Nov 2025)
- ⚡ Batch API Operations - FMP Premium batch-quote endpoint for single-call ticker fetching
- 🚀 Redis Batch Operations - Pipeline writes and mget reads (N calls → 1-2 calls per request)
- 📊 Database Query Optimization - Fixed N+1 queries in events API (430+ queries → 2 queries)
- 💾 30-Year Historical Data - Upgraded from 5 years to up to 30 years of training data (~7,560 days)
- ⚡ Smart Summary Polling - Summary only loads on page load/watchlist change (not every 5s)
- 📰 Tiered News Fetching - Adaptive news loading: 5 items/symbol for small lists, top movers only for 50+ symbols
- 🔐 AWS Secrets Manager - Secure FMP API key storage instead of environment variables
🎯 Overview
Mintalyze consists of three integrated systems:
Web Application - Modern Next.js dashboard for market monitoring and AI insights
Quant Lab System - ML-powered engine with movement predictions and forecasts
AWS Infrastructure - Serverless Lambda + SageMaker for automated daily analysis
🏗️ System Architecture
System Architecture Diagram:
View System Architecture
Daily Cron Flow:
View Automated Daily Analysis Flow
The system uses a serverless architecture with three main components:
- Web Application (Next.js + Vercel) - User-facing dashboard with real-time data
- Quant Lambda (AWS) - Orchestrates daily market data fetch and ML inference
- SageMaker Endpoint (AWS) - Serves ML model predictions on-demand
Daily Automated Flow:
- 4:05 PM EST (Mon-Fri): EventBridge triggers Lambda function
- Lambda Step 1: Calls webapp API to process news for all tickers
- Fetches latest 20 news items per ticker from FMP
- Scores each headline with EC2 sentiment & relevance models
- Stores in NewsItem database table (sentiment, relevance, category)
- Lambda Step 2: Fetches 30 years of market data from Financial Modeling Prep API
- Lambda Step 3: Calls SageMaker endpoint for raw ML predictions (up/down/neutral probabilities)
- Lambda Step 4: Queries NewsItem table and applies Bayesian news update to probabilities
- Lambda Step 5: Generates distributional forecasts and final trading signals
- Lambda Step 6: Saves results to PostgreSQL database (with both raw and news-adjusted scores)
- Lambda Step 7: Triggers Sentinel AI agent for market analysis
- Webapp: Displays fresh predictions and insights (instant page loads from DB)
✨ Key Features
📊 Market Intelligence
- 🧠 Sentinel AI Agent - Autonomous market intelligence system with anomaly detection
- Multi-stage analysis pipeline (market snapshot → anomaly detection → specialized report)
- Structured "What This Means" narratives explaining market moves in plain English
- Volatility regime classification (VIX tracking, realized volatility)
- Sector rotation detection and analysis
- Macro event integration and surprise detection
- Historical report tracking with expandable insights
- Real-time Market Data - Live quotes with 5s cache via FMP Premium batch API
- Redis-Powered Caching - Shared app-level cache with Upstash Redis for instant updates
- AI Market Summaries - Natural language summaries powered by LangChain & OpenAI
- Smart Alerts - Automated notifications for price movements, volume spikes, and 52-week highs
- Events Timeline - Batch-optimized events API for earnings and macro events
- Historical Analysis - "Since Last Visit" snapshots to see what changed
📈 Watchlist Management
- Custom Watchlists - Create and organize multiple watchlists
- Drag-and-Drop Reordering - Intuitive watchlist item management
- Ticker Search - Quick symbol lookup with autocomplete
- Favorites System - Star important watchlists for quick access
- Smart Macros - Define custom alerts (price changes, volume spikes, near highs)
🤖 Quantitative Trading (Quant Lab)
- ML Predictions - LightGBM/XGBoost/LSTM models for daily trading signals
- News-Aware Predictions - Two-stage prediction pipeline:
- Raw ML Model → Directional probabilities (up/down/neutral)
- Bayesian News Update → Adjust probabilities using sentiment & relevance
- Final Signal → BUY/SELL/NEUTRAL based on posterior probabilities
- Bayesian Inference - Sequential likelihood multiplication across multiple news items
- Sentiment Model (-1 to +1): Bullish/bearish direction from EC2 ML service
- Relevance Model (0 to 1): How relevant the news is to the ticker
- Category Weights: Company (1.0x), Sector (0.7x), Macro (0.4x), Noise (0.1x)
- Likelihood Ratios: Strong bullish + high relevance → 2x up, 0.5x down
- Example: Prior
{up: 0.52, down: 0.31} + bearish news → {up: 0.34, down: 0.51}
- Dual Scoring in UI - QuantLab displays both raw and news-adjusted Quant Scores
- Distributional Forecasts - Probabilistic price predictions with confidence intervals
- Database-Backed Results - Predictions stored in PostgreSQL for instant page loads
- Automated Daily Analysis - AWS Lambda cron job runs at 4:05 PM EST weekdays
- Backtesting Engine - Multi-year historical performance validation
- Paper Trading - Live simulation with realistic execution costs
- Interactive Dashboards - Streamlit-based visualization and monitoring
- Walk-Forward Validation - Robust cross-validation strategy
☁️ AWS Infrastructure
- Lambda Orchestrator - Serverless function coordinates daily analysis workflow
- SageMaker Endpoint - Serverless ML inference for real-time predictions
- EventBridge Scheduler - Automated cron job (Mon-Fri, 4:05 PM EST)
- Docker Deployment - Containerized Lambda and SageMaker models
- Infrastructure as Code - Terraform configuration for reproducible deployments
- Simple API Authentication - FMP API key for data access (no OAuth required)
- Database Integration - Lambda saves results directly to production database
💬 AI Chat Agent
- Conversational Interface - Natural language queries about markets, watchlists, and signals
- MCP Tool Integration - 20+ tools for real-time data access
- Lambda Orchestrator - Serverless agent with GPT-5-mini reasoning
- Context Awareness - Maintains conversation history for follow-up questions
- Auto Type Coercion - Handles OpenAI's string-typed arguments automatically
🎨 User Experience
- Modern UI - Tailwind CSS with custom animations and responsive design
- Dark Theme - Professional dark color scheme optimized for extended viewing
- Authentication - Secure OAuth with NextAuth.js (Google)
- Real-time Updates - 5-second cache revalidation for live data
- Admin Tools - Cache management and system configuration
🛠️ Technology Stack
Frontend & Backend
- Framework: Next.js 16 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS 4
- UI Components: Radix UI, Lucide Icons
- Authentication: NextAuth.js 5 (Beta)
- Database ORM: Prisma
- Database: PostgreSQL (Vercel Postgres)
- Caching: Upstash Redis (TTL, shared app-level cache)
AI & ML (Web App)
- LLM Framework: LangChain
- AI Provider: OpenAI (GPT models)
- Text-to-Speech: OpenAI TTS API
News ML Models (EC2-Hosted)
Custom-trained sentiment and relevance classifiers deployed as FastAPI microservices on AWS EC2 (t3.medium):
Sentiment Model (Port 8001)
- Architecture: sentence-transformers/all-MiniLM-L6-v2 → logistic regression
- Output: Continuous score from -1 (bearish) to +1 (bullish)
- Training: Fine-tuned on financial news headlines with manual annotations
- Endpoint:
POST /score with {"text": "headline"}
- Response:
{"score": 0.73, "category": "bullish"}
Relevance Model (Port 8002)
- Architecture: sentence-transformers embeddings → cosine similarity + category classifier
- Output: Relevance score 0-1 + category (company/sector/macro/noise)
- Category Weights:
- Company: 1.0x (direct mentions, earnings, product launches)
- Sector: 0.7x (industry trends, competitor news)
- Macro: 0.4x (Fed policy, GDP, inflation)
- Noise: 0.1x (unrelated or generic news)
- Endpoint:
POST /score with {"headline": "text", "ticker": "AAPL"}
- Response:
{"score": 0.85, "category": "company"}
Deployment Details:
- Hosting: AWS EC2 t3.medium (Tailscale private network)
- Framework: FastAPI with uvicorn
- Concurrency: Async processing for batch requests
- Latency: ~50-100ms per headline
- Access: Private Tailscale IPs (100.x.x.x) - NOT publicly accessible
News Processing Workflow:
- Lambda →
POST /api/news/process-batch (220 tickers, today's news)
- Webapp → Fetch FMP news API (
/stable/news/stock)
- Webapp → Call sentiment service for each headline
- Webapp → Call relevance service for each headline + ticker pair
- Webapp → Store
NewsItem in database (ticker, headline, sentiment, relevance, category)
- Lambda →
GET /api/news/get?ticker=X&days=2 (retrieve scored news)
- Lambda → Apply
bayesian_update() to raw ML predictions
- Lambda → Save both raw and news-adjusted predictions to
LivePrediction
Example News Scoring:
Headline: "Apple announces record Q4 earnings, stock jumps 5%"
Ticker: AAPL
→ Sentiment: +0.85 (bullish)
→ Relevance: 0.95 (company)
→ Category weight: 1.0x
→ Bayesian impact: Shifts prob_up from 0.52 → 0.67
Quantitative System
- ML Frameworks: LightGBM, XGBoost, Scikit-learn
- Deep Learning: TensorFlow, PyTorch, Transformers
- Optimization: Optuna, Ray[Tune], Hyperopt, CVXPY
- Data Processing: Pandas, NumPy, PyArrow
- Validation: Great Expectations, Pytest
- MLOps: MLflow, Weights & Biases, TensorBoard
- Visualization: Streamlit, Plotly
- Market Data: Financial Modeling Prep API (REST)
Infrastructure & Cloud
- Market Data Provider: Financial Modeling Prep API (Premium - batch quotes, 30 years historical)
- Caching Layer: Upstash Redis (serverless, shared across instances)
- Web Deployment: Vercel (Next.js production hosting)
- ML Infrastructure:
- AWS EC2 (t3.medium) - Sentiment & relevance microservices
- AWS Lambda + SageMaker - Quant predictions (serverless inference)
- Orchestration: AWS EventBridge (cron scheduler)
- Secrets: AWS Secrets Manager
- Container Registry: AWS ECR (Docker images)
- Infrastructure as Code: Terraform
- Version Control: Git
- Environment: Node.js 20+, Python 3.10+
🎨 Component Architecture
Design System
- Atoms - Badge, Box, Button, Card, Container, Dialog, EmptyState, Label, MiniSparkline, SectionHeader, SignOutButton, Stack, StatusBadge
- Molecules - Accordion, AlertCard, EnhancedPredictionCard, ForecastCard, IconLabel, MarketSignalsCard, MarketSummaryCard, NavLink, QuantLabAvailableTickers, QuantLabLimitations, QuantLabMethodology, RegimeComponentsCard, TickerListClient, TickerSearch, TopSignalsView, UserInfo, VolatilityCard
- Organisms - AdminSettings, DistributionalForecasts, EmailVerificationBanner, EventsTimeline, InsightCards, MarketForecastsClient, MintalyzeSummary, MarketTicker, MovementAlertsBar, ProfessionalInsights, QuantLabClient, SentinelExplainToday, SentinelPreferences, SinceLastVisit, WatchlistSelector, WatchlistTimeline, WhatThisMeans, Sidebar
Key Hooks
useScrollAnimation - Scroll-triggered animationsuseWindowSize - Responsive layout management
Utilities
cacheManager - Server-side caching with revalidationfmpData - FMP API data fetchingmarketData - Market data fetching and transformationeventDetector - Macro event detection logic
🧠 Sentinel AI Agent
The Sentinel AI Agent is an autonomous market intelligence system that provides real-time market analysis with human-readable narratives.
Architecture
Multi-Stage Pipeline:
- Market Snapshot - Fetches real-time data from Financial Modeling Prep API
- Index prices (SPY, QQQ, IWM)
- Sector performance (11 sectors)
- Individual stock snapshots
- Anomaly Detection - Rule-based triggers for market events
- Index Move - Significant directional moves (>1% threshold)
- Sector Rotation - Divergence between sectors (>2% spread)
- Volatility Spike - VIX changes >10%
- Macro Surprise - Unexpected economic events
- Market Drilldown - Deep analysis when anomalies detected
- Leading/lagging sector identification
- Volatility regime classification
- Cross-asset correlation analysis
- Report Generation - AI-powered narrative creation
- Summary and key drivers
- Structured "What This Means" explanations
- Macro context integration
- Professional insights and risk assessment
What This Means Structure
Generated AI narratives follow a consistent format:
{
whatHappened: string, // 2-3 sentence plain English summary
whyItMatters: string, // Significance explanation
whatCouldHappenNext: string, // Potential scenarios
whatToWatch: string[] // 3-5 specific monitoring points
}
Tone & Style:
- Conversational, calm, human tone
- No jargon, predictions, or idioms
- Something between Morning Brew + Goldman Sachs notes
- No investment advice
Storage & History
All Sentinel reports are stored in PostgreSQL with:
- Full market context (JSON)
- Anomaly flags for filtering
- Volatility metrics
- Structured narratives
- Historical tracking with expandable UI
Dashboard Features
- Collapsible Panel - Accessible from homepage
- One-Click Analysis - Generate reports on demand
- Historical Reports - View past 20 analyses
- What This Means - Expandable narratives in history table
- Link to Full Dashboard -
/sentinel page with comprehensive views
🤖 Model Information
Machine Learning Models
MarketMinute's Quant Lab employs four specialized models for market prediction:
1. LightGBM Classifier
- Type: Gradient Boosting Decision Trees
- Framework: Microsoft LightGBM
- Architecture: Multiclass classifier (3 classes)
- Tuner: Optuna hyperparameter optimization (40 trials)
- Key Features:
- Fast training with histogram-based learning
- Leaf-wise tree growth strategy
- Built-in categorical feature support
- GPU acceleration support
- Tuned Parameters:
- Learning rate: 0.01–0.15
- Num leaves: 16–128
- Max depth: 3–9
- Feature/bagging fractions
- L1/L2 regularization
2. XGBoost Classifier
- Type: Gradient Boosting Decision Trees
- Framework: XGBoost
- Architecture: Multiclass classifier (3 classes)
- Tuner: Optuna hyperparameter optimization (40 trials)
- Key Features:
- Depth-wise tree growth
- Advanced regularization techniques
- Parallel tree construction
- GPU acceleration support
- Tuned Parameters:
- Learning rate: 0.01–0.15
- Max depth: 3–7
- Min child weight: 1.0–10.0
- Gamma, subsample, colsample
- Alpha/lambda regularization
3. LSTM Classifier
- Type: Bidirectional Long Short-Term Memory Neural Network
- Framework: PyTorch
- Architecture: 2-layer bidirectional LSTM with attention
- Tuner: Built-in training with early stopping
- Key Features:
- Bidirectional processing for temporal context
- Multi-head attention mechanism
- Batch normalization and dropout
- Sequence modeling for time series
- Network Architecture:
- Input → Bidirectional LSTM (128 hidden units)
- Multi-head attention layer
- Fully connected layers with dropout (0.3)
- Softmax output (3 classes)
4. Transformer Classifier
- Type: Transformer Neural Network
- Framework: PyTorch
- Architecture: 4-layer transformer encoder with positional encoding
- Tuner: Built-in training with early stopping
- Key Features:
- Positional encoding for sequence information
- Self-attention across all time steps
- Layer normalization
- Captures long-range dependencies
- Network Architecture:
- Input embedding (d_model=128)
- Positional encoding
- 4 transformer encoder layers (8 attention heads)
- Feed-forward network (512 dimensions)
- Softmax output (3 classes)
Labeling Strategy
Multiclass Triple-Barrier Method:
Optimization Metrics
- Primary: Macro-F1 Score (balanced across all classes)
- Secondary: Multi-class log loss (for early stopping)
- Validation: Walk-forward cross-validation
- Ensemble: Weighted averaging by macro-F1 performance
Model Training Pipeline
- Data Preparation: Feature engineering (50+ indicators)
- Labeling: Dynamic volatility-adjusted labels
- Balancing: Hybrid oversampling + class weights
- Hyperparameter Tuning: Optuna optimization (40 trials)
- Training: Walk-forward cross-validation
- Ensemble: Weighted combination of all models
- Validation: Out-of-sample testing
📁 Project Structure
MarketMinute/
├── .env # Environment variables
├── .gitignore # Git ignore rules
├── README.md # Project documentation
├── deploy.sh # Main deployment script
│
├── platform/ # AI Agent & MCP infrastructure
│ ├── agent/ # Lambda agent orchestrator
│ │ ├── scripts/
│ │ │ └── build-lambda.sh # Build and deploy script
│ │ ├── src/
│ │ │ ├── lambda/
│ │ │ │ ├── handler.ts # Lambda entry point
│ │ │ │ └── orchestrator.ts # Agentic loop with tool calling
│ │ │ └── tools/
│ │ │ └── registry.ts # Tool registry for Lambda
│ │ ├── Dockerfile # Lambda container
│ │ └── package.json
│ │
│ ├── mcp/ # Model Context Protocol tools
│ │ └── src/
│ │ ├── tools/ # Tool implementations
│ │ │ ├── market/ # get_quote_snapshot, get_top_movers, etc.
│ │ │ ├── user/ # get_watchlists, create_watchlist, etc.
│ │ │ ├── quantlab/ # get_quant_signals, get_model_quality, etc.
│ │ │ ├── sentinel/ # get_sentinel_report, get_insights
│ │ │ ├── news/ # get_ticker_news, get_ticker_events, etc.
│ │ │ ├── analysis/ # get_sentiment, get_explanation, etc.
│ │ │ └── info/ # about_marketminute
│ │ └── ops/ # Shared operations (db, time)
│ │
│ └── shared/ # Shared schemas and types
│ ├── schemas/
│ │ └── tools/ # Zod schemas for all tools
│ └── types/
│
├── services/ # ML microservices (EC2-hosted)
│ ├── redeploy_models.sh # Model redeployment script
│ ├── sentiment/ # Sentiment analysis service
│ │ ├── app.py # FastAPI application
│ │ ├── config.py # Service configuration
│ │ ├── Dockerfile # Container definition
│ │ ├── requirements.txt # Python dependencies
│ │ ├── model/ # Model artifacts
│ │ │ ├── sentiment_classifier.pkl # Trained model
│ │ │ └── sentiment_classifier.py # Model class
│ │ ├── training/ # Training scripts
│ │ │ └── train.py # Model training
│ │ └── data/ # Training data
│ │
│ └── relevance/ # Relevance scoring service
│ ├── app.py # FastAPI application
│ ├── config.py # Service configuration
│ ├── Dockerfile # Container definition
│ ├── requirements.txt # Python dependencies
│ ├── model/ # Model artifacts
│ │ ├── relevance_classifier.pkl # Trained model
│ │ └── relevance_scorer.py # Model class
│ ├── training/ # Training scripts
│ │ └── train.py # Model training
│ └── data/ # Training data
│
├── webapp/ # Next.js web application
│ ├── .env # Environment variables
│ ├── .gitignore # Git ignore rules
│ ├── auth.ts # NextAuth configuration
│ ├── next.config.ts # Next.js configuration
│ ├── package.json # Node dependencies
│ ├── tsconfig.json # TypeScript configuration
│ ├── tailwind.config.ts # Tailwind CSS configuration
│ ├── vercel.json # Vercel deployment config
│ │
│ ├── app/ # App router pages
│ │ ├── (auth)/ # Authentication pages
│ │ │ ├── login/ # Login page
│ │ │ └── signup/ # Signup page
│ │ ├── about/ # About page
│ │ ├── admin/ # Admin dashboard
│ │ ├── api/ # API routes (58 endpoints)
│ │ │ ├── auth/ # Authentication endpoints
│ │ │ ├── quant/ # Quant data endpoints
│ │ │ ├── sentinel/ # Sentinel agent endpoints
│ │ │ ├── watchlist/ # Watchlist endpoints
│ │ │ └── ... # Market data, news, etc.
│ │ ├── features/ # Features showcase page
│ │ ├── forecasts/ # ML forecasts page
│ │ ├── history/ # Historical data view
│ │ ├── how-it-works/ # How it works page
│ │ ├── privacy/ # Privacy policy
│ │ ├── quant/ # Quant lab interface
│ │ ├── sentinel/ # Sentinel AI dashboard
│ │ │ ├── page.tsx # Sentinel dashboard
│ │ │ └── [reportId]/ # Individual report view
│ │ ├── settings/ # User settings
│ │ ├── subscription/ # Subscription management
│ │ ├── support/ # Support pages
│ │ ├── terms/ # Terms of service
│ │ ├── use-cases/ # Use cases page
│ │ ├── watchlist/ # Watchlist management
│ │ │ ├── page.tsx # Watchlist dashboard
│ │ │ └── [symbol]/ # Individual stock view
│ │ ├── why-marketminute/ # Why MarketMinute page
│ │ ├── DashboardClient.tsx # Main dashboard client
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Homepage
│ │ ├── sitemap.ts # Dynamic sitemap
│ │ └── globals.css # Global styles
│ │
│ ├── agents/ # AI agent systems
│ │ └── sentinel/ # Sentinel agent implementation
│ │ ├── agent/ # Core agent logic
│ │ │ ├── context.ts # Context builder
│ │ │ ├── drilldown.ts # Drilldown causation
│ │ │ ├── loop.ts # Main execution loop
│ │ │ ├── report.ts # Report generation
│ │ │ ├── triggers.ts # Anomaly trigger detection
│ │ │ └── types.ts # Type definitions
│ │ ├── config/ # Configuration
│ │ │ ├── prompts.ts # LLM prompts
│ │ │ └── types.ts # Config types
│ │ ├── llm/ # LLM integration
│ │ │ ├── openai.ts # OpenAI client
│ │ │ └── prompts/ # Prompt engineering templates
│ │ └── services/ # Market data fetchers
│ │ ├── macro/ # Macro event services
│ │ ├── market/ # Market snapshot (get_market_snapshot.ts)
│ │ ├── notify/ # Notification services
│ │ └── volatility/ # Volatility data services
│ │
│ ├── components/ # React components
│ │ ├── README.md # Component documentation
│ │ ├── atoms/ # Basic UI components (13)
│ │ │ ├── Badge.tsx
│ │ │ ├── Box.tsx
│ │ │ ├── Button.tsx
│ │ │ ├── Card.tsx
│ │ │ ├── Container.tsx
│ │ │ ├── Dialog.tsx
│ │ │ ├── EmptyState.tsx
│ │ │ ├── Label.tsx
│ │ │ ├── MiniSparkline.tsx
│ │ │ ├── SectionHeader.tsx
│ │ │ ├── SignOutButton.tsx
│ │ │ ├── Stack.tsx
│ │ │ └── StatusBadge.tsx
│ │ ├── molecules/ # Composite components (17)
│ │ │ ├── Accordion.tsx
│ │ │ ├── AlertCard.tsx
│ │ │ ├── EnhancedPredictionCard.tsx
│ │ │ ├── ForecastCard.tsx
│ │ │ ├── IconLabel.tsx
│ │ │ ├── MarketSignalsCard.tsx
│ │ │ ├── MarketSummaryCard.tsx
│ │ │ ├── NavLink.tsx
│ │ │ ├── QuantLabAvailableTickers.tsx
│ │ │ ├── QuantLabLimitations.tsx
│ │ │ ├── QuantLabMethodology.tsx
│ │ │ ├── RegimeComponentsCard.tsx
│ │ │ ├── TickerListClient.tsx
│ │ │ ├── TickerSearch.tsx
│ │ │ ├── TopSignalsView.tsx
│ │ │ ├── UserInfo.tsx
│ │ │ └── VolatilityCard.tsx
│ │ └── organisms/ # Complex feature components (18)
│ │ ├── AdminSettings.tsx
│ │ ├── DistributionalForecasts.tsx
│ │ ├── EmailVerificationBanner.tsx
│ │ ├── EventsTimeline.tsx
│ │ ├── InsightCards.tsx
│ │ ├── MarketForecastsClient.tsx
│ │ ├── MarketMinuteSummary.tsx
│ │ ├── MarketTicker.tsx
│ │ ├── MovementAlertsBar.tsx
│ │ ├── ProfessionalInsights.tsx
│ │ ├── QuantLabClient.tsx
│ │ ├── SentinelExplainToday.tsx
│ │ ├── SentinelPreferences.tsx
│ │ ├── SinceLastVisit.tsx
│ │ ├── WatchlistSelector.tsx
│ │ ├── WatchlistTimeline.tsx
│ │ ├── WhatThisMeans.tsx
│ │ └── sidebar.tsx
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useMarketData.tsx
│ │ └── useWatchlist.tsx
│ │
│ ├── lib/ # Utilities and helpers
│ │ ├── cacheManager.ts # Redis caching
│ │ ├── eventDetector.ts # Market event detection
│ │ ├── eventsDb.ts # Event database
│ │ ├── explainCache.ts # Explanation caching
│ │ ├── macroNews.ts # Macro news fetcher
│ │ ├── marketData.ts # Market data utils (FMP API)
│ │ ├── news.ts # News aggregation
│ │ ├── openai.ts # OpenAI integration
│ │ ├── redis.ts # Redis caching client
│ │ ├── tickerCache.ts # Ticker data caching
│ │ ├── smartAlerts.ts # Alert system
│ │ ├── summary.ts # Market summaries
│ │ ├── summaryCache.ts # Summary caching
│ │ ├── tickerMappings.ts # Ticker utilities
│ │ └── utils.ts # General utilities
│ │
│ ├── prisma/ # Database schema and migrations
│ │ ├── migrations/ # Database migrations
│ │ └── schema.prisma # Prisma schema
│ │
│ └── public/ # Static assets
│ ├── icons/ # Icon files
│ └── images/ # Image assets
│
├── quant/ # Quantitative trading system
│ ├── .env # Environment variables
│ ├── .gitignore # Git ignore rules
│ ├── requirements.txt # Python dependencies
│ ├── setup.py # Package setup
│ ├── serverless.yml # Serverless config (legacy)
│ ├── SYSTEM_SPEC.yaml # System specifications
│ │
│ ├── lambda/ # AWS Lambda orchestrator
│ │ ├── .gitignore # Lambda ignore rules
│ │ ├── Dockerfile # Lambda container config
│ │ ├── requirements.txt # Lambda dependencies
│ │ ├── deploy_lambda.sh # Deployment script
│ │ ├── lambda_handler.py # Main orchestrator function
│ │ ├── predictions.py # Prediction generation logic
│ │ ├── forecasting.py # Distributional forecasts logic
│ │ └── tickers.py # Ticker list configuration
│ │
│ ├── logs/ # Log files (generated)
│ │
│ ├── models/ # Saved ML models (generated)
│ │
│ ├── outputs/ # Training outputs
│ │ ├── backtests/ # Backtest results
│ │ ├── predictions/ # Generated predictions
│ │ └── reports/ # Analysis reports
│ │
│ ├── sagemaker/ # SageMaker inference endpoint
│ │ ├── .gitignore # SageMaker ignore rules
│ │ ├── Dockerfile # SageMaker container config
│ │ ├── requirements.txt # SageMaker dependencies
│ │ ├── deploy.py # Deployment utility
│ │ ├── deploy_sagemaker.sh # Deployment script
│ │ ├── inference.py # Inference handler
│ │ ├── serve # Serve script
│ │ ├── wsgi.py # WSGI application
│ │ └── models/ # Model artifacts (copied at build)
│ │
│ ├── scripts/ # CLI utilities
│ │ ├── cleanup.py # Data cleanup
│ │ ├── compare_ensemble_strategies.py
│ │ ├── eval_multiclass_trading.py
│ │ ├── generate_distributional_forecasts.py
│ │ ├── generate_predictions.py
│ │ ├── prep_data.py # Data preparation (FMP API)
│ │ └── train_model.py # Model training
│ │
│ └── src/ # Core library
│ ├── data/ # Data processing
│ │ ├── __init__.py
│ │ ├── fmp_data.py # FMP API client
│ │ ├── features/ # Feature engineering
│ │ │ ├── __init__.py
│ │ │ ├── FEATURE_DICTIONARY.md
│ │ │ ├── curated_features.py
│ │ │ └── feature_engine.py
│ │ ├── labels/ # Label generation
│ │ │ ├── __init__.py
│ │ │ ├── binary_labeler.py
│ │ │ └── multiclass_labeler.py
│ │ └── preprocessing/ # Data preprocessing
│ │ ├── __init__.py
│ │ └── scaler.py
│ │
│ └── models/ # ML model implementations
│ ├── __init__.py
│ ├── ensemble_classifier.py # Ensemble model
│ ├── hyperparameter_tuner.py # Optuna tuning
│ ├── xgb_hyperparameter_tuner.py
│ ├── base/ # Base models
│ │ ├── __init__.py
│ │ ├── lgbm_classifier.py # LightGBM
│ │ └── xgb_classifier.py # XGBoost
│ └── deep_learning/ # Deep learning models
│ ├── __init__.py
│ ├── lstm_classifier.py # LSTM
│ └── transformer_classifier.py # Transformer
│
└── infrastructure/ # Cloud infrastructure
├── scripts/ # Management utilities
│ ├── deploy_ec2_ml_services.sh # EC2 ML services deployment
│ ├── deploy_lambda.sh # Lambda deployment
│ ├── manage_scheduler.sh # Cron job management
│ ├── setup.sh # Initial setup
│ ├── teardown.sh # Infrastructure teardown
│ └── view_cron_history.sh # View cron logs
│
└── terraform/ # Infrastructure as Code
├── main.tf # Main configuration
├── variables.tf # Variable definitions
├── terraform.tfvars # Variable values
├── outputs.tf # Output definitions
├── ecr.tf # ECR repositories
├── iam.tf # IAM roles and policies
├── ec2_ml_services.tf # EC2 instance for ML services
├── iam_ec2_ml.tf # IAM roles for EC2
├── user_data.sh # EC2 initialization script
├── docker-compose.yml # Docker Compose for ML services
├── lambda.tf # Lambda function config
├── sagemaker.tf # SageMaker endpoint config
├── scheduler.tf # EventBridge cron job
└── secrets.tf # Secrets Manager config
🚀 Getting Started
Prerequisites
Web Application Setup
cd webapp
# Install dependencies
npm install
# Note: postinstall script automatically runs "prisma generate"
# Configure environment variables
cp .env.example .env.local
# Edit .env.local with your credentials:
# - DATABASE_URL (PostgreSQL)
# - NEXTAUTH_SECRET
# - OPENAI_API_KEY
# - FMP_API_KEY (Financial Modeling Prep - Premium tier for quotes, news, and events)
# - SENTIMENT_SERVICE_URL (e.g., http://100.31.239.246:8001)
# - RELEVANCE_SERVICE_URL (e.g., http://100.31.239.246:8002)
# - UPSTASH_REDIS_REST_URL (optional - Redis caching)
# - UPSTASH_REDIS_REST_TOKEN (optional - Redis caching)
# Initialize database
npx prisma migrate dev
# Latest migration includes SentinelReport model
# Run development server
npm run dev
# Access the app at http://localhost:3000
# Visit /sentinel for Sentinel AI dashboard
Visit http://localhost:3000
Quantitative Lab Setup
cd quant
# Install dependencies
pip install -r requirements.txt
# Set up environment
pip install -e .
# FMP requires only an API key (no authentication script needed)
# Prepare data
python3 scripts/prep_data.py
# Train initial models
python3 scripts/train_model.py
# Generate Predictions
python3 scripts/generate_predictions.py
# Generate Forecasts
python3 scripts/generate_distributional_forecasts.py
ML Services Setup (EC2)
Deploy Sentiment & Relevance Models:
cd services
# Option 1: Deploy both services
./redeploy_models.sh both
# Option 2: Deploy individual services
./redeploy_models.sh sentiment
./redeploy_models.sh relevance
The script will:
- Verify model artifacts exist (
.pkl files in model/ directories)
- Build Docker images with
--no-cache for AMD64 architecture
- Push images to AWS ECR
- Restart services on EC2 via AWS SSM
- Verify health endpoints
Test the services:
# Sentiment analysis
curl -X POST http://<EC2_IP>:8001/score \
-H "Content-Type: application/json" \
-d '{"text": "Stock prices surge on positive earnings"}'
# Relevance scoring
curl -X POST http://<EC2_IP>:8002/score \
-H "Content-Type: application/json" \
-d '{"headline": "Apple unveils new iPhone", "ticker": "AAPL"}'
Train new models:
# Sentiment
cd services/sentiment/training
python3 train.py
# Relevance
cd services/relevance/training
python3 train.py
# Then redeploy
cd ../../
./redeploy_models.sh both
AWS Infrastructure Setup
Prerequisites:
- AWS CLI configured with credentials
- Terraform installed
- Docker installed
- AWS account with appropriate permissions
1. Configure Terraform Variables
cd infrastructure/terraform
# Create terraform.tfvars
cat > terraform.tfvars << 'EOF'
project_name = "marketminute"
environment = "dev"
aws_region = "us-east-1"
sagemaker_image_uri = "YOUR_ECR_URI/marketminute-sagemaker:latest"
lambda_image_uri = "YOUR_ECR_URI/marketminute-lambda:latest"
webapp_url = "https://market-minute.vercel.app"
EOF
2. Deploy SageMaker Model
cd ../../quant/sagemaker
# Build and push Docker image
./deploy_sagemaker.sh
# Copy the ECR URI and update terraform.tfvars
3. Deploy Lambda Function
cd ../lambda
# Build and push Docker image
./deploy_lambda.sh
# Copy the ECR URI and update terraform.tfvars
4. Apply Terraform
cd ../../infrastructure/terraform
# Initialize Terraform
terraform init
# Preview changes
terraform plan
# Apply infrastructure
terraform apply
# Note the Lambda Function URL output
5. Test the Integration
# Manual trigger test
cd ../scripts
./manage_scheduler.sh test
# Check logs
./manage_scheduler.sh logs
# Verify EventBridge schedule
./manage_scheduler.sh status
Automated Daily Schedule:
- Time: 4:05 PM EST (21:05 UTC)
- Days: Monday - Friday
- Rule:
marketminute-dev-daily-analysis
The Lambda function will:
- Fetch market data via Financial Modeling Prep API
- Generate features for 21 tech tickers
- Call SageMaker endpoint for predictions
- Generate distributional forecasts
- Save results to production database
- Trigger Sentinel agent analysis
📊 API Endpoints
ML Services (EC2-hosted)
POST :8001/score - Sentiment analysis
- Body:
{"text": "string"}
- Returns:
{"score": -1.0 to 1.0, "category": "very_negative|negative|neutral|positive|very_positive"}
POST :8002/score - Relevance scoring
- Body:
{"headline": "string", "ticker": "string"}
- Returns:
{"score": 0.0 to 1.0, "category": "not_relevant|marginally_relevant|somewhat_relevant|highly_relevant"}
GET :8001/health - Sentiment service health checkGET :8002/health - Relevance service health check
Market Data
GET /api/snapshots - Real-time stock quotesGET /api/market-ticker - Streaming market ticker dataGET /api/events - Upcoming earnings and eventsGET /api/ticker-search - Symbol search and lookup
Watchlists
GET/POST /api/watchlist - Manage watchlistsPOST/DELETE/PATCH /api/watchlist/items - Manage watchlist itemsPATCH /api/watchlist/favorite - Toggle favorite status
AI & Insights
POST /api/summary - Generate AI market summariesPOST /api/explain - Get detailed explanations for market movementsGET /api/smart-alerts - Fetch triggered smart alertsGET /api/macro-news - Macro event detectionPOST /api/sentinel - Generate Sentinel AI market intelligence report
Quant Lab
GET /api/quant/predictions - Fetch ML trading predictions (from database)GET /api/quant/forecasts - Get distributional forecasts (from database)POST /api/quant/save-results - Save Lambda predictions to database (internal)POST /api/quant/generate - Trigger new predictionsPOST /api/quant/run-script - Execute quant scripts
Admin & Monitoring
POST /api/admin/trigger-cron - Manually trigger Lambda cron job (testing)
User & Admin
PATCH /api/user/active-watchlist - Set active watchlistPOST /api/visit-snapshot - Create user visit snapshotsGET /api/daily-summary - Historical daily summariesPOST /api/admin/cache - Cache managementGET /api/admin/scripts - List available scripts
🔐 Authentication
MarketMinute uses NextAuth.js v5 with OAuth providers:
Configure providers in webapp/auth.ts and set environment variables:
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret
🗄️ Database Schema
Key models:
- User - User accounts with OAuth integration
- Watchlist - Custom watchlists with favorites
- WatchlistItem - Individual stocks with ordering
- Session - Session Auth
- DailyWatchlistSummary - Historical performance snapshots
- NewsItem - Processed news with ML-based sentiment and relevance scores
- SentinelReport - AI-generated market intelligence reports with structured narratives
- InsightReport - Historical insight reports
- LivePrediction - ML trading signals from Lambda (21 tickers daily)
- DistribionalForecast - Probabilistic price forecasts (21 tickers daily)
User
├── Watchlists (1-to-many)
│ ├── WatchlistItems (1-to-many)
│ └── Macros (1-to-many)
├── Accounts (OAuth providers)
├── Sessions (Auth)
├── DailyWatchlistSummaries (through watchlist)
└── SentinelReports (1-to-many)
NewsItem
├── id, ticker, headline
├── sentiment (Float) - ML model score (-1.0 to 1.0)
├── relevance (Float, nullable) - ML model score (0.0 to 1.0)
├── category (String, nullable) - Relevance category
├── summary (String, nullable)
└── createdAt (DateTime)
SentinelReport
├── summary (Text)
├── keyDrivers (JSON)
├── macroContext (Text, nullable)
├── whatThisMeans (JSON, nullable) - Structured narrative
├── anomaly flags (indexMove, sectorRotation, macroSurprise, volSpike)
├── volatility metrics (vix, vixChangePct, realizedVol)
└── context (JSON) - Full market context for reprocessing
LivePrediction
├── ticker, timestamp, currentPrice
├── Raw ML Model Outputs (before news):
│ ├── rawSignal, rawConfidence
│ └── rawProbUp, rawProbNeutral, rawProbDown
├── News-Adjusted Outputs (after Bayesian update):
│ ├── signal (BUY/SELL/NEUTRAL)
│ ├── confidence, probUp, probNeutral, probDown
│ └── newsCount (number of news items that influenced the update)
├── shouldTrade, takeProfit, stopLoss, atr
└── runId (groups predictions from same Lambda run)
NewsItem
├── ticker, headline
├── sentiment (-1 to +1, from EC2 ML model)
├── relevance (0 to 1, from EC2 ML model)
├── category (company/sector/macro/noise)
└── createdAt (for querying recent news)
DistribionalForecast
├── ticker, timestamp, currentPrice
├── expectedRangePct, upperBound, lowerBound
├── directionalBias, conviction, convictionScore
├── probability distribution (probLargeUp, probMildUp, probFlat, probMildDown, probLargeDown)
├── percentiles (p10, p50, p90)
└── runId (groups forecasts from same Lambda run)
Run migrations:
npx prisma migrate dev
🔧 Configuration
Web App
Configure in webapp/.env.local:
- Market data refresh interval (default: 30s)
- OpenAI model selection
- Cache TTL settings
Quant System
Edit quant/SYSTEM_SPEC.yaml:
- Tickers to trade
- Feature engineering parameters
- TP/SL multipliers
- Risk management settings
- Walk-forward CV windows
📝 License
This project is private and proprietary.
🤝 Contributing
This is a private project. For questions or access, contact the repository owner.
� Deployment
Vercel (Web Application)
Important Configuration:
- Root Directory: Set to
webapp in Vercel project settings
- Environment Variables: Configure in Vercel Dashboard
DATABASE_URL - Production PostgreSQL connection stringNEXTAUTH_SECRET - Authentication secretNEXTAUTH_URL - https://market-minute.vercel.appOPENAI_API_KEY - OpenAI API keyFMP_API_KEY - Financial Modeling Prep API keyLAMBDA_FUNCTION_URL - AWS Lambda function URL
Deploy:
cd webapp
vercel deploy --prod
Build Configuration:
- Build Command:
prisma generate && next build
- Output Directory:
.next
- Install Command:
npm install
AWS (Infrastructure)
See AWS Infrastructure Setup section above for full deployment instructions.
Quick Deploy:
# 1. Deploy models
cd quant/sagemaker && ./deploy_sagemaker.sh
cd ../lambda && ./deploy_lambda.sh
# 2. Apply infrastructure
cd ../../infrastructure/terraform
terraform apply
# 3. Test
cd ../scripts && ./manage_scheduler.sh test
📚 Additional Resources
Architecture Diagrams
Code & Configuration
🐛 Troubleshooting
Common Issues
TypeScript errors after schema changes:
npx prisma generate
FMP API errors:
Ensure your FMP_API_KEY is valid and has sufficient quota. Free tier includes 250 requests/day.
Database connection issues:
npx prisma migrate reset
npx prisma migrate dev
Missing environment variables:
Check that all required variables are set in .env.local or .env
Built with ❤️ for traders and quants
