A full-scale, production-grade investment analyst platform you deploy on your own server.

A personal Bloomberg-style terminal for monitoring your investments, tracking world news and insider activity, and getting AI-powered analysis of your portfolio.

I started this project to explore three ideas:

1. An unbiased personal financial analyst. No bank selling you products, no subscription service with conflicts of interest — just a data platform that pulls from 20+ sources and an AI analyst swarm that evaluates your holdings and watchlists on metrics that matter to you: ROIC, free cash flow, P/B, margin of safety, and whatever else you configure.

2. Spec-driven development, not vibe coding. Every feature starts as a written specification. The entire system was built by AI agent teams with distinct roles — Product Owner, Architect, DBA, Frontend Developer, Backend Developer — each responsible for their domain. The result is a maintainable codebase with proper database schema, security boundaries, and the tech stack I actually wanted, not whatever the LLM felt like using.

3. Fully local, zero external dependencies at runtime. The entire platform deploys with docker compose up on your own server or localhost. The analyst swarm runs on Ollama (local LLMs) or Claude — your choice. No data leaves your machine unless you want it to.

The analyst swarm — 9 specialized agents from Portfolio Manager to Compliance Officer — runs multiple times per day, analyzing your current assets and watchlist securities for buy/sell/hold opportunities. And everything is tweakable: the agent definitions are plain Markdown files you can edit to match your own investment thesis.

Portfolio heatmap — treemap of your current holdings weighted by position size, color-coded by performance.

An autonomous swarm of specialized investment analysts runs 3x daily, each with deep domain expertise:

The swarm runs on Claude Code CLI or Ollama (local LLMs) — your choice. Agent definitions are fully customizable Markdown files in .claude/agents/.

This project uses spec-driven development — every feature starts as a written specification before any code is written. All specs, agent definitions, and architectural decisions live in the repository (AGENTS.md, CLAUDE.md, .claude/agents/).

The terminal itself was developed by an AI development team of 5 agents:

Security Detail — single ticker with AI analyst overview, fundamentals, charts, insider activity	AI Recommendations — Portfolio Manager synthesizes input from Risk Manager, Tax Strategist, Macro Strategist, and 6 more analysts
Macro Strategist Report — AI-generated macro regime analysis

• Portfolio Dashboard — real-time holdings, P&L, portfolio value chart, allocation by asset class and account
• AI Recommendations — buy/sell/hold signals from the analyst swarm with bull/bear cases, confidence levels, target prices, and retrospective accuracy tracking. Every recommendation carries a staleResearch flag set at write time: true when the underlying stock has no per-security research-analyst note in the last 7 days (non-stock asset classes are always false because the research-analyst pipeline skips them). See F16 rule #11.
• Performance — period-scoped P&L (MTD / YTD / 1Y / custom) split into 5 buckets: realized gains, realized losses, dividends paid, unrealized gains, unrealized losses. Uses period-attributed math (V_end − V_start − net_flows) so cash deposits and withdrawals don't distort investment returns. Compact YTD strip on the dashboard, full breakdown with per-security table on /performance
• Holdings — current positions across accounts with cost basis, unrealized P&L, live quotes, dividend income
• Transactions — filterable transaction log with type/account filters, search, pagination, and summary stats. sell rows show realized P/L in EUR (green/red) computed from the FIFO tax-lot chain; buys and unmatched sells show —.
• Nordnet Import — paste Nordnet portfolio exports (Finnish CSV), automatic security matching and reconciliation

• 20+ Data Pipelines — automated fetching from Yahoo Finance, ECB, FRED, CoinGecko, Morningstar, SEC EDGAR, and more
• Watchlists — multiple watchlists tracking Nordic, European, and US markets
• TradingView Charts — candlestick/line charts with SMA, EMA, Bollinger, RSI, MACD
• Heatmap — treemap visualization with 1D/1W/1M/3M/6M/1Y/YTD periods

• Risk Analysis — Sharpe/Sortino ratios, max drawdown, VaR, beta, correlation heatmap, stress tests, glidepath tracking
• Research Notes — per-security notes with bull/bear/base cases, intrinsic value, margin of safety, moat ratings
• Research Coverage — dashboard showing which securities have stale or missing analyst coverage, with staleness badges and filters
• Analyst Consensus — view how the 9 AI agents agree or disagree per security, with conflict detection between Research Analyst and Portfolio Manager
• Recommendation Accuracy — mark-to-market tracking of PM recommendations at 30/90/180 day checkpoints with win rates, avg returns, and best/worst calls
• Sector Rotation (RRG) — 14-week Relative Rotation Graph of the 11 GICS sectors vs SPY, plotting each sector by RS-Ratio and RS-Momentum on a 4-quadrant chart (Leading / Weakening / Lagging / Improving). Flags BUY signals (Improving→Leading) and SELL signals (Weakening→Lagging), and lists the top ETFs by dollar-volume and top stocks by market cap from your watchlist in each mover sector
• Fundamentals — P/B, FCF, DCF valuation, ROIC, margins, short interest. Style presets one-click filter the universe against Graham/Browne (statistical deep value), Buffett/Munger (quality compounders at a fair price), plus Quality Compounders, Value, Deep Value, Dividend, Undervalued (DCF), and Low Debt. Style-preset criteria are documented in specs/06-investment-philosophy/.
• Earnings — calendar with estimates, actual EPS, revenue surprises
• Retirement Projections — Monte Carlo simulation (10,000 paths) with fan chart, survival probabilities, safe withdrawal rate, and sensitivity analysis
• Portfolio Optimization — efficient frontier, optimal portfolio for risk tolerance, risk parity, tax-aware rebalancing with trade suggestions
• What-If Simulator — preview how a hypothetical trade affects risk, allocation, and glidepath before executing
• Currency Hedging — FX exposure analysis by currency, rate changes, FX impact on portfolio returns

• Tax Analysis — Finnish tax law (30/34%), tax lot tracking, deemed cost comparison, loss harvesting
• Fixed Income — bond holdings with coupon rates, YTM, credit ratings, duration
• Dividends — calendar, yield metrics, income projections, historical events

• Macro Dashboard — Finland, Eurozone, and US indicators with yield curves
• News Feed — Google News RSS + CNBC, ECB, YLE, DI, FT, Yardeni
• Global Events — GDELT-powered macro event tracking with sector impact analysis

• Insider Trades — FI/SE/US insider transactions with signal detection (cluster buying, CEO/CFO buys)
• Congress Trades — US Congress member stock trades (STOCK Act)
• SEC Filings — Form 4 & 13F-HR filings

• Security Detail Pages — deep-dive per ticker with fundamentals, charts, news, insider activity, analyst reports
• TV Dashboard — 2-page fullscreen mode with portfolio heatmap, recommendations, news, per-holding AI analysis tiles
• Command Palette (Cmd+K) — search across features and securities
• Privacy Mode (Cmd+Shift+P) — blur all monetary amounts
• PWA — installable on mobile, offline access to dashboard, recommendations, holdings
• Status Bar — live pipeline indicators, market hours for Nordic/EU/London/US/Crypto
• Notifications & Bot — PM recommendations, macro regime changes, insider cluster buying, insider/congress trades on held securities, weekly Monday digest. Default provider is Signal (via signal-gateway); Telegram also supported. The bot is bidirectional — message it on your phone for portfolio summary, latest brief, system status, or free-form LLM chat backed by the same model the web app uses.

graph TB
    subgraph Docker Compose
        FE[Next.js Frontend<br/>Port 3000]
        BE[FastAPI Backend<br/>Port 8000]
        DB[(TimescaleDB<br/>PostgreSQL 16)]
        RD[(Redis 7)]
        CR[Cron Scheduler<br/>20 pipeline jobs]
        SW[Analyst Swarm<br/>9 AI agents]
    end

    subgraph Data Sources
        YF[Yahoo Finance]
        ECB[ECB / FRED]
        CG[CoinGecko]
        INS[OpenInsider / SEC<br/>Nasdaq Nordic / FI]
        NEWS[Google News / GDELT<br/>CNBC / YLE / FT]
        MS[Morningstar / justETF<br/>Fama-French]
    end

    subgraph AI Providers
        CL[Claude Code CLI]
        OL[Ollama - Local LLMs]
    end

    FE <--> BE
    BE <--> DB
    BE <--> RD
    CR --> BE
    SW --> BE
    SW --> CL
    SW --> OL
    BE --> YF
    BE --> ECB
    BE --> CG
    BE --> INS
    BE --> NEWS
    BE --> MS

git clone https://github.com/freducom/bloomvalley.git
cd bloomvalley
cp .env.example .env        # Add your FRED_API_KEY
cp analyst-swarm/config.yaml analyst-swarm/config.local.yaml

# Generate an API key for internal service authentication
echo "API_KEY=$(openssl rand -base64 32)" >> .env

docker compose up -d --build
docker compose exec backend alembic upgrade head

Frontend changes require a rebuild: The frontend runs a production build inside Docker (not dev mode). After editing frontend code, run:

docker compose build frontend && docker compose up -d frontend

Analyst-swarm code changes require a rebuild too: analyst-swarm/swarm.py and data_digest.py are baked into the image at build time (only config.local.yaml is bind-mounted for live edits). After editing swarm code, run:

docker compose build analyst-swarm && docker compose up -d --force-recreate analyst-swarm

Backend code hot-reloads (bind-mounted + uvicorn --reload) — no rebuild needed. Alembic migrations still require an explicit docker compose exec backend alembic upgrade head.

Open http://localhost:3000. Trigger initial data fetch (include the API key from .env):

API_KEY=$(grep API_KEY .env | cut -d= -f2-)
curl -H "X-API-Key: $API_KEY" -X POST http://localhost:8000/api/v1/pipelines/yahoo_daily_prices/run
curl -H "X-API-Key: $API_KEY" -X POST http://localhost:8000/api/v1/pipelines/ecb_fx_rates/run
curl -H "X-API-Key: $API_KEY" -X POST http://localhost:8000/api/v1/pipelines/fred_macro_indicators/run
curl -H "X-API-Key: $API_KEY" -X POST http://localhost:8000/api/v1/pipelines/coingecko_prices/run

No API key needed for: Yahoo Finance, ECB, CoinGecko, Google News, OpenInsider, Nasdaq Nordic, Swedish FI, SEC EDGAR, Quiver Quantitative, Morningstar, justETF, Kenneth French, GDELT, regional RSS feeds.

Bloomvalley ships with a provider abstraction for push notifications and a bidirectional chat bot. Pick one in .env via NOTIFICATION_PROVIDER (default: signal).

Signal (default). Self-hosted bridge — your messages go through your own Signal account, no third-party servers. Setup:

1. Bring up the signal-gateway stack (its README has the one-time QR-link setup, ≈5 min).
2. Copy NOTIFY_TOKEN and ROUTER_TOKEN from signal-gateway/.env into bloomvalley's .env:

   NOTIFICATION_PROVIDER=signal
   SIGNAL_NOTIFY_TOKEN=<NOTIFY_TOKEN from signal-gateway>
   SIGNAL_ROUTER_TOKEN=<ROUTER_TOKEN from signal-gateway>
   

3. docker compose up -d — the signal-register sidecar registers the bv prefix with signal-gateway's router automatically.
4. Test outbound: curl -H "X-API-Key: $API_KEY" -X POST http://localhost:8000/api/v1/notifications/test.
5. From Signal on your phone, in Note to Self: type bv portfolio, bv brief, bv status, or just ask a question.

Telegram (alternative). Set:

NOTIFICATION_PROVIDER=telegram
TELEGRAM_BOT_TOKEN=<from @BotFather>
TELEGRAM_CHAT_ID=<your chat id>

(Get the chat ID by messaging the bot once, then visiting https://api.telegram.org/bot<TOKEN>/getUpdates.)

None. Set NOTIFICATION_PROVIDER=none to disable all notifications.

See specs/04-features/F22-notifications.md for full event taxonomy, privacy mode, and message format details.

20 automated pipelines fetch data on schedule (all times Europe/Helsinki):