Richfolio

A zero-maintenance portfolio monitoring system. Set your target allocations once, get daily briefings with allocation gaps, AI-powered buy signals, and relevant news — delivered via email and Telegram, automatically via GitHub Actions.

Who Should Use This

Richfolio does not pick stocks for you. You should already have your own research and investment thesis — your own portfolio of stocks, ETFs, or crypto that you believe in.

What Richfolio does is monitor your portfolio daily and help you decide when to buy. It tracks prices, technicals, news sentiment, and allocation gaps, then uses AI to surface the best timing opportunities across your holdings.

• You bring the portfolio — set your target allocations once in a simple JSON config
• Richfolio brings the signals — buy recommendations, limit order prices, and detailed analysis
• You make the final call — every purchase decision is yours; the tool only suggests

No coding skill required. Fork the repo, spend ~10 minutes registering free API accounts (Resend, NewsAPI, Gemini), paste your keys into GitHub Settings, and you're done. Everything runs automatically via GitHub Actions at $0/month.

Features

• AI Buy Recommendations — Gemini-powered analysis considering valuation, allocation gap, news sentiment, technicals, and risk (with gap-based fallback). STRONG BUY tickers get a "More Details" link to a dedicated analysis page with interactive chart, buy thesis, risk analysis, and full metrics
• Value Investing Framework — AI rates individual stocks A–D based on ROE, debt/equity, FCF, earnings growth, and analyst targets (data from Yahoo Finance, zero extra API calls)
• Crypto Bottom-Fishing Model — AI detects accumulation zones for BTC/ETH using RSI, volume contraction, 200MA position, and death cross signals
• Technical Momentum Signals — SMA50, SMA200, RSI(14), golden/death cross, and momentum classification (bullish/bearish/neutral) for each ticker
• Limit Order Prices — AI-suggested limit order prices based on nearby support levels (moving averages, recent lows, round numbers)
• Allocation Gap Analysis — current vs target %, flagged by priority with suggested buy amounts
• Dynamic P/E Signals — trailing P/E compared against historical averages fetched from Yahoo Finance (no manual benchmarks needed)
• ETF Overlap Detection — reduces buy priority for ETFs where you already hold overlapping stocks (e.g., holding AAPL reduces VOO's priority)
• 52-Week Range Signals — highlights tickers near their 52-week low (opportunity) or high (caution)
• News Digest — top headlines per ticker from NewsAPI
• Portfolio Health — weighted beta, estimated annual dividend income
• Intraday Alerts — periodic checks that alert only when buy signals strengthen vs the morning brief (configurable thresholds)
• Weekly Rebalancing Report — focused drift analysis with BUY/TRIM/OK actions
• Dual Delivery — dark-themed HTML email via Resend + condensed Telegram message

Quick Start

1. Fork this repo on GitHub
2. Add config — go to Settings → Secrets and variables → Actions:
   • Variables tab: CONFIG_JSON (portfolio config) + RECIPIENT_EMAIL (your email)
   • Secrets tab: RESEND_API_KEY — for email delivery
   • Optionally: NEWS_API_KEY, GEMINI_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
3. Run — trigger manually from Actions → Portfolio Monitor → Run workflow, or wait for the daily cron (8am AEST)

That's it — no local setup required. See the full setup guide for detailed instructions on each API key.

git clone https://github.com/furic/richfolio.git
cd richfolio
npm install
cp config.example.json config.json
cp .env.example .env

Edit config.json and .env, then:

npm run dev       # Daily brief (email + Telegram)
npm run intraday  # Intraday alert check (compares vs morning)
npm run weekly    # Weekly rebalancing report
npm run refresh -- SMH  # Re-analyze single ticker with after-hours price

Stack

| Component | Service | Cost | |-----------|---------|------| | Runtime | Node.js + TypeScript (tsx) | Free | | Prices & Fundamentals | Yahoo Finance (yahoo-finance2) | Free | | News | NewsAPI.org | Free (100 req/day) | | AI Analysis | Google Gemini 2.5 Flash | Free (250 req/day) | | Email | Resend.com | Free (3,000/month) | | Telegram | Telegram Bot API | Free | | Scheduler | GitHub Actions | Free (cron) |

Project Structure

richfolio/
├── src/
│   ├── config.ts          # Typed loader for config.json + .env
│   ├── index.ts           # Entry point (daily/intraday/weekly mode)
│   ├── fetchPrices.ts     # Yahoo Finance: price, P/E, 52w, beta, dividends, ETF holdings, fundamentals
│   ├── fetchTechnicals.ts # Yahoo Finance chart: SMA50, SMA200, RSI, momentum, volume change
│   ├── fetchNews.ts       # NewsAPI: headlines per ticker
│   ├── analyze.ts         # Allocation gaps, P/E signals, overlap discounts
│   ├── aiAnalysis.ts      # Gemini AI: buy recs, limit prices, value ratings, bottom signals
│   ├── detailedAnalysis.ts# Gemini 2.5 Flash: detailed buy thesis + risk analysis for STRONG BUY
│   ├── analysisUrl.ts     # Compress analysis data into URL hash for GitHub Pages
│   ├── email.ts           # Daily HTML email template + Resend
│   ├── intradayEmail.ts   # Intraday alert email template
│   ├── intradayCompare.ts # Compare current vs morning baseline
│   ├── state.ts           # Morning baseline persistence
│   ├── weeklyEmail.ts     # Weekly rebalancing email template
│   └── telegram.ts        # Telegram bot delivery (daily/intraday/weekly)
├── docs/
│   ├── analysis/          # Static analysis page (decodes URL hash, renders with TradingView)
│   └── *.md               # GitHub Pages documentation site
├── .github/workflows/
│   └── portfolio-monitor.yml  # Daily + intraday + weekly cron jobs
├── config.example.json    # Template portfolio config
├── .env.example           # Template environment variables
├── package.json
└── tsconfig.json

How It Works

config.json + .env
  → fetchPrices (Yahoo Finance: prices, P/E, 52w range, beta, dividends, ETF holdings, fundamentals)
  → fetchTechnicals (Yahoo Finance chart: SMA50, SMA200, RSI, momentum, volume change)
  → fetchNews (NewsAPI: top headlines per ticker)
  → analyze (allocation gaps, P/E signals, overlap discounts, portfolio metrics)
  → aiAnalyze (Gemini: buy recs + confidence + limit prices + value ratings + bottom signals)
  → email + telegram (deliver daily brief with value ratings, bottom signals, technicals)

Weekly mode (--weekly) skips news and AI, producing a focused rebalancing report.

Intraday mode (--intraday) re-fetches prices, technicals, and AI (skipping news), compares against the morning baseline, and alerts only for STRONG BUY-related changes: upgrades to STRONG BUY, downgrades from STRONG BUY, or confidence shifts ≥10 while at STRONG BUY.

Refresh mode (--refresh TICKER) re-analyzes a single ticker using the latest available price (including after-hours/pre-market from Yahoo Finance). Outputs updated analysis to terminal and sends email + Telegram with a new analysis URL. Useful when you see an alert after market close and want an updated limit order based on after-hours price movement.

Updating Your Portfolio

Edit config.json and push (or update the CONFIG_JSON GitHub Actions variable). The next run will reflect the changes.

References

See docs/references.md for repos and resources referenced during design and build.

License

ISC