StockInfo

A small app that serves stock and ETF quotes via a REST API and caches them in a SQLite database. Query by ISIN or by symbol + exchange; the response is JSON with price, currency, timestamp, name and — for ETFs — extras such as TER, provider and fund size.

It ships with a web dashboard (Vue): asset overview with sortable columns, configuration view, exchange legend, 8 switchable themes, German/English UI, a price chart (intraday and real end-of-day closes) that docks at the bottom of the viewport, plus per-asset actions (refresh, delete, add ISIN) and links (extraETF, Yahoo Finance, JSON export).

What's new in 0.6.0

• All eight ETF metrics are maintainable by hand — provider, replication, fund size, fund domicile and fund currency join TER, volatility and accumulating. Maintained in an expandable detail area per row, not in the table cell.

  

• Stored metrics survive an outage. A failed justETF request no longer wipes what was already there — "asked and empty" is now distinguishable from "could not ask". METADATA_TTL_DAYS finally does what it always claimed: justETF is scraped once per cycle instead of on every quote.

• Merging duplicate instruments no longer loses data. Manual values and the daily-sync watermark move to the surviving row instead of being cascaded away.

• /ready — a readiness probe that actually touches the database; /health stays cheap. The Docker healthcheck now uses /ready.

• Stricter API contract — symbols and time ranges are validated (422 instead of a wrong result), and an unresolvable ISIN answers 404 instead of 502.

Contents

• What can it do?
• How quotes are fetched
• Requirements
• Quick start
• Security model
• The REST API
• Configuration (.env)
• Dashboard
• Docker
• Unraid
• Tests
• Project layout
• License

What can it do?

• Fetch quotes — European and US stocks/ETFs, by ISIN or symbol.
• Cache — every response is stored in SQLite; repeated requests are served from the cache instead of hitting the internet again.
• Stay up to date automatically — a background job refreshes all known instruments at a configurable interval.
• History — two views: the intraday curve built from collected ticks, and real end-of-day closes (EOD from Yahoo, cached incrementally — each request only fetches the missing delta).
• Rich data — besides price and timestamp: name, currency, volume, volatility, and for ETFs TER, provider, replication method, fund size, fund domicile, fund currency and accumulating/distributing.
• Fill the gaps yourself — whatever justETF does not deliver can be entered by hand in the expandable detail area of a row. The source always wins: a manual value fills a gap, it never overwrites. It stays stored while the source covers it and applies again as soon as the source goes quiet.
• Dashboard — overview with column sorting, docked price chart, 8 themes, German/English UI, exchange legend, profile links, JSON export.

↑ Contents

How quotes are fetched

The app combines three free data sources:

A note on currency: the exchange suffix selects the exchange, not the currency — the currency always comes from the live quote. Example: the same ISIN trades on Xetra in EUR, in London often in pence (GBp). The app returns the currency verbatim.

↑ Contents

Requirements

• Python 3.11+ (the app creates its own .venv)
• make (drives start/stop of the services)
• optional Docker (to run the container)
• optional Node.js 20+ (dashboard only)

The project uses shared ecosystem helpers under .libs/ (MakeLib, BashLib). For the Makefile the environment variable DEV_MAKE must point to the MakeLib.

↑ Contents

Quick start

# 1. Create the configuration
cp .env.example .env

# 2. Install dependencies (once)
python3.11 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt

# 3. Start the server
make dev            # backend only, foreground (auto-reload)
#   or
make start          # backend only, background   →  make stop / make logs

The whole stack (backend and dashboard) at once — via overmind:

make dev-up         # backend :8000 + dashboard :5173
make dev-down       # stop both   ·   make dev-logs for logs

The server then runs at http://localhost:8000. Interactive API docs (Swagger UI, dark theme) live at http://localhost:8000/docs (use http:// in the browser, not https://).

First query:

curl http://localhost:8000/quote/IE00B3RBWM25

make help lists all available commands, make hints shows useful URLs.

↑ Contents

Security model

StockInfo has no authentication, and it is not meant to have one. Every endpoint is open to anyone who can reach the port — including the ones that change or destroy data:

• DELETE /instruments/{isin} removes an instrument together with its entire price history.
• PUT /instruments/{symbol}/isin and PUT /instruments/{symbol}/overrides change stored data.
• POST /refresh and GET /analyze trigger live requests to Yahoo and justETF and write their results to the database.

The default bind address is 0.0.0.0, so in Docker the port is reachable from the whole network the container is attached to.

Run it on a network you trust. In practice that means one of:

• bind it to loopback only (HOST=127.0.0.1) and reach it through an SSH tunnel;
• keep the published port inside your LAN and off the internet (the usual Unraid setup);
• or put an authenticating reverse proxy in front of it if it must be exposed.

CORS_ORIGINS is not a protection. It restricts what a browser on another origin may do — it does nothing about curl, a script, or any server-to-server call.

Two limits do exist, and they are about load rather than access: the global refresh takes a non-blocking lock so two runs cannot overlap, and justETF is only scraped once every METADATA_TTL_DAYS (an explicit single refresh still forces it).

↑ Contents

The REST API

For instruments without an ISIN there is a …/by-symbol/{symbol} variant of each endpoint (quote, history, daily, refresh, delete).

Example response (GET /quote/IE00B3RBWM25):

{
  "isin": "IE00B3RBWM25",
  "symbol": "VGWL.DE",
  "exchange": "Xetra",
  "name": "Vanguard FTSE All-World UCITS ETF",
  "type": "etf",
  "currency": "EUR",
  "price": 160.98,
  "quote_time": "2026-07-10T15:35:46+00:00",
  "volume": 14403,
  "ter": 0.19,
  "provider": "Vanguard",
  "replication": "Physical(Optimized sampling)",
  "fund_size": 22638.0,
  "volatility": 9.95,
  "accumulating": false,
  "source": "yfinance+justetf",
  "cached": false,
  "stale": false,
  "fetched_at": "2026-07-12T18:16:28+00:00"
}

volatility is the 1-year volatility in percent — from justETF for ETFs, otherwise computed (annualized) from the cached EOD closes. accumulating states whether an ETF accumulates (true) or distributes (false).

Fields that cannot be determined are null (e.g. ter for individual stocks). If a live fetch fails but an old value exists in the cache, that value is returned with "stale": true instead of an error. Unknown ISIN → 404.

↑ Contents

Configuration (.env)

All values can be overridden via .env (cp .env.example .env):

↑ Contents

Dashboard

A standalone web frontend lives in dashboard/ (Vue 3 + Vite + TypeScript + SCSS) with a fixed header (deep-linkable tab navigation, DE/EN language switch — persisted, initial language follows the browser) and a status bar (health traffic light green/orange/red + version):

• Assets — overview with the latest quote and sortable columns (click a header: ascending → descending → off; persisted); add (ISIN/symbol), refresh, delete, add ISIN; per row links to extraETF, Yahoo Finance and a JSON popup (URL + result copyable — works on plain http:// too).
• Chart — selecting a row docks the price history at the bottom of the viewport (always visible, even with long asset lists). Range switch 1D · 1W · 1M · 3M · 1Y · Max: 1D = intraday curve (collected ticks), the rest are real end-of-day closes (EOD). True time axis, compact ticks.
• Exchanges — legend of the Yahoo suffixes (exchange, region, currency).
• Environment — current configuration incl. a note on the automatic refresh; Themes — 8 selectable, persisted themes.

cd dashboard
npm install
npm run dev                # http://localhost:5173

The Vite dev proxy forwards API requests to the backend (http://localhost:8000) automatically — VITE_API_BASE_URL is not needed in dev (optionally overridable, see dashboard/vite.config.ts).

The backend must run in parallel. Both together: make dev-up (see Quick start).

↑ Contents

Docker

Backend and dashboard run in a single image on one port. Built with docker/build.sh (ecosystem convention, versioned via gitDockerTag):

make build     # build the image (docker/build.sh --build)
make up        # start the container → http://localhost:8000/
make down      # stop & remove
make docker-logs   # follow logs

FastAPI serves the dashboard itself (relative API calls) — no separate web server required. The cache lives in the stockinfo-data volume (/data inside the container). The container runs as a non-root user (UID 99 / GID 100 — Unraid's nobody:users).

Push to a registry:

make push                     # docker/build.sh --push   (TARGET=dockerhub, default)
TARGET=ghcr make push         # alternatively GitHub Container Registry

↑ Contents

Unraid

A ready-made container template lives in the dedicated CA repo MikeMitterer/unraid-templates — image mangolila/stockinfo:latest (Docker Hub), WebUI port 8000, path /mnt/user/appdata/stockinfo → /data, plus the most important settings as variables (refresh interval, TTLs, exchange, OpenFIGI key, timezone).

Install it as a user template (run on the Unraid box):

wget -O /boot/config/plugins/dockerMan/templates-user/my-stockinfo.xml https://raw.githubusercontent.com/MikeMitterer/unraid-templates/master/templates/stockinfo.xml

Then: Docker → Add Container → pick “stockinfo” under User templates. Support: GitHub Issues.

↑ Contents

Tests

make test                       # backend (pytest)
cd dashboard && npm run test    # dashboard (Vitest)

The tests run without network access — external data sources are mocked.

↑ Contents

Project layout

app/                    # FastAPI backend
  main.py               #   app setup, routes, scheduler startup
  config.py             #   configuration (.env)
  db.py, repository.py  #   SQLite: schema and data access
  resolver.py           #   ISIN → symbol/exchange (OpenFIGI + Yahoo)
  providers/            #   data sources: yfinance, justETF, OpenFIGI
  services/             #   quote fetching + cache/TTL logic
  scheduler.py          #   periodic background refresh
  routers/              #   HTTP endpoints (quotes, dashboard)
  docs.py               #   dark-themed Swagger UI (/docs)
dashboard/              # Vue dashboard (standalone app)
tests/                  # backend tests (pytest)
docker/                 # Dockerfile, build.sh (single-image build)
unraid/screenshots/     # dashboard, detail area + swagger (README + CA template)
Makefile                # service start/stop (make help)

Technical details and design decisions: see docs/superpowers/specs/.

↑ Contents

License

MIT © Mike Mitterer

↑ Contents