Self-hosted equity analysis dashboard with AI-powered insights, real-time alerts, and trade tracking.

Dashboard	Equity detail
Market overview	Playbook

More screenshots

Market snapshot	Price chart	Fundamentals

Ratios	News	Watchlist

Alerts	Economic calendar	Advisor context packs

_{Screenshots from the live demo in demo mode.}

Free tools like Yahoo Finance and Google Finance are fine for checking a stock price, but fall apart when you want to compare ratios across a watchlist, track your actual trades, or get AI-generated analysis that considers your specific holdings. Paid tools (TradingView, Koyfin) are great but expensive for a hobbyist investor. This project fills the gap: a self-hosted dashboard that combines data from multiple sources, runs analysis you care about, and sends alerts to Discord when something moves.

Try it live at invest.smithadifd.com

Log in with demo@example.com / demo1234! to explore the full dashboard. Data resets weekly and write operations (creating trades, alerts, watchlists) are disabled in demo mode.

Dual-stack application: Python/FastAPI backend handles data ingestion, analysis, and scheduling; Next.js frontend provides the interactive dashboard.

                    +-----------+
                    |  Browser  |
                    +-----+-----+
                          |
                    +-----+-----+
                    |   Caddy   |  (reverse proxy)
                    +--+-----+--+
                       |     |
              +--------+     +--------+
              |                       |
        +-----+-----+          +-----+-----+
        | Next.js 16 |          |  FastAPI   |
        |  Frontend  |          |  Backend   |
        +-----+-----+          +--+--+--+---+
              |                    |  |  |
              +--------+-----------  |  |
                       |             |  |
                 +-----+-----+      |  |
                 | PostgreSQL |      |  |
                 | TimescaleDB|  +---+  +---+
                 +-----------+   |          |
                              +--+--+  +----+----+
                              | Redis|  | Celery  |
                              +-----+  +---------+

Data flows through Celery background tasks that pull from Yahoo Finance on a schedule, normalize it, and store it in TimescaleDB hypertables. The frontend reads from the API, never from external sources directly.

• Equity Dashboard -- Search, quote, and chart any publicly traded stock with TradingView charts
• Watchlists -- Organize equities into named watchlists with sorting
• Fundamental Analysis -- P/E, P/B, dividend yield, market cap, and 20+ financial ratios with cross-equity comparison
• Market Overview -- Index tracking (S&P 500, NASDAQ, Dow) with sector heatmaps and daily movers
• AI Analysis -- Claude-powered equity analysis that considers price history, fundamentals, and your watchlist context
• Price Alerts -- Configurable alerts (price crosses, percent change, volume spike) with Discord notifications
• Trade Tracker -- Log trades, calculate P&L, track position sizes, and review trade history
• Calendar & Events -- Earnings dates, ex-dividend dates, and macro economic events
• Scheduled Tasks -- Celery-powered background jobs for data refresh, alert checking, and daily summaries
• Authentication -- Single-user auth with secure password hashing and session management

Beyond the in-app AI analysis, you can stand up an external investing advisor -- a Claude project tuned to your portfolio that reads a live context pack from this app and proposes changes back through a handoff loop. The Advisor Starter Kit is a fill-in-the-blanks scaffold for exactly that.

In plain English: the app exports a snapshot of your holdings, watchlists, and ratios; you paste it to an AI assistant (e.g. Claude Code, a terminal tool that can read and act on files); it hands back a structured block of proposed trades and alerts; you review it and the app applies the changes. The exact shape of that exchange is the handoff schema.

Clone investing-hub, open that checkout in Claude Code, and say "Walk me through docs/onboarding/ONBOARDING.md" -- it interviews you and fills the templates. The optional app-integration layer wires the advisor to this app's read/write contract (docs/api/handoff-schema.md and docs/api/advisor-actions.md).

git clone https://github.com/smithadifd/investing_companion.git
cd investing_companion
cp .env.example .env

# Edit .env -- set SECRET_KEY, optionally add DISCORD_WEBHOOK_URL and CLAUDE_API_KEY

docker compose up -d

# Run database migrations
docker compose exec api alembic upgrade head

The frontend will be at http://localhost:3000 and the API at http://localhost:8000 (with interactive docs at /docs).

# Backend
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Requires Python 3.11+, Node.js 20+, PostgreSQL 15+ with TimescaleDB, and Redis.

# Backend
cd backend && pytest --cov=app

# Frontend
cd frontend && npm test

Market data flows through a resilient provider chain: the primary is wrapped in retry + exponential backoff + a circuit breaker, and if it is unavailable the request fails over to a fallback. Data served by a fallback is flagged stale so the UI can show a "delayed data" badge with the source and an "as of" timestamp.

Stooq needs no key and is always active, so failover works out of the box. Alpha Vantage is added to the chain only when its key is configured. Polygon.io remains documented-but-unimplemented (paid tier).

Investing Companion is free and self-hosted. If it saves you a subscription or you just want to help keep it maintained, you can chip in:

• Sponsor on GitHub
• Buy me a coffee on Ko-fi

MIT

Built with Claude Code