Architecture

Finnhub free tier caps at 60 req/min. With 50+ watchlist tickers each needing a fresh quote every 60s, naive round-robin wastes the budget on low-priority tickers while high-volatility ones go stale.

Solution: a float-score priority queue. Each ticker is scored by recency, watchlist count, and pending alert rules. The token bucket refills at 55 tokens/min — 5 held in reserve for on-demand user calls.

score = (staleness_weight × Δt) + (watchlist_count × 0.4) + (alert_rules × 0.3)

The scheduler runs as a two-timer background loop inside the Next.js process — no separate worker service needed.

• 60s rebuild Rescores all tickers, adds new watchlist entries, removes delisted ones.
• ~1091ms drain Pops the top-scored ticker, fetches a fresh quote, writes to Redis, fires alert detection. 1091ms × 55 = 60,005ms — exactly fills the rate budget per minute.

The autocomplete layer calls Finnhub /search, then re-ranks candidates using a tag-based recommender before returning results.

• → Sector match with current watchlist tickers (+score)
• → Industry match (+score)
• → Same exchange as existing holdings (+score)
• → Common stock preferred over ADR / ETF / preferred shares

Results capped at 10, sorted by composite score. No vector DB, no ML model — pure deterministic re-ranking.

Alert detection runs on every quote fetch via afterFetchListener — up to 55 checks/minute, always on freshly cached data, with no separate polling loop.

Originally designed on OHLCV candles (RSI, EMA cross). Finnhub free tier returns 403 on /stock/candle — rewrote detection to use quote.changePct and intraday range (dayHigh − dayLow) / prevClose only.

Per-rule cooldowns in Redis prevent alert spam after a threshold is breached.

Macro news from 5 RSS feeds (Reuters, CNBC, MarketWatch, Yahoo Finance, Seeking Alpha) — free, no API key, ingested 4× daily. Company news from Finnhub /company-news — no extra quota consumed.

Sentiment scored with AFINN lexicon, normalised to [0, 1] by dividing raw sum by wordCount × 5 to remove article-length bias.

Ticker extraction uses word-boundary regex with a 2-char minimum — single-letter tickers (F, S, M) produce false positives in every financial sentence.

Composite score from four components, each normalised to [0, 100]:

No candle history required — 52-week high/low used as annual volatility proxy; PEG derived from analyst price target upside.

Standard closed-form MVO (mean-variance optimisation) requires inverting the covariance matrix — which is singular when fewer than ~30 price observations exist per ticker. Acrue uses projected gradient ascent on a utility function instead:

U = μ − A·σ² (maximise)
subject to: weights ∈ Δⁿ (simplex) via Duchi 2008

Duchi simplex projection keeps weights ≥ 0 and summing to 1 after every gradient step — O(n log n), stable for any portfolio size.

Default Next.js { server } mode intercepts all WebSocket upgrades — including /_next/webpack-hmr, breaking hot reload in development.

Solution: noServer: true — manually route upgrade events so only /ws goes to the WS server; all other paths pass to Next.js.

Auth decodes the next-auth JWT cookie directly on the upgrade request — no extra HTTP round-trip. Falls back to 60s polling on Vercel (serverless, no persistent process).

PostgreSQL via Prisma ORM. UUID primary keys throughout. Key schema decisions:

• assets Populated lazily on watchlist add — no bulk import. Profile fetched from Finnhub on first add.
• alertRules Separate table (not JSONB) — enables per-user per-ticker customisation and cooldown queries.
• UserNewsRead Compound PK join table — persistent per-user read state with cascade delete.
• simPortfolios startPrice locked at add time; live P&L computed from Redis quote cache.

Three strictly separated layers:

• app/(pages)/*/page.tsx Layout only — compose stateful components, no business logic.
• components/stateful/ Own data fetching and local state. Each maps to one use case.
• components/ui/ Stateless presentational — props only, no fetch, no side effects.

Dashboard fetches 4 endpoints in parallel with Promise.allSettled. WebSocket updates patch local state directly — no refetch on every price tick.

Vercel (serverless) for the Next.js app. PostgreSQL and Redis on Railway (persistent Node processes). WebSocket server requires a persistent process — falls back to 60s polling on Vercel automatically.

postinstall runs prisma generate before next build on every deploy. tsx in dependencies (not devDependencies) — Railway's production install skips dev deps.