WalletStack

WalletStack is a personal finance and market-intelligence platform with live equity research, virtual trading, portfolio tracking, budgeting, goals, and AI-assisted financial insights.

Stack

• React, Vite, TanStack Query, Clerk, and Lightweight Charts
• Node.js, Express, MongoDB, Redis, and OpenRouter
• Deployed on Heroku with MongoDB Atlas (Mumbai) — see docs/DEPLOYMENT.md

Local Development

1. Copy .env.example to .env and add the backend credentials.
2. Copy frontend/.env.example to frontend/.env.
3. Install dependencies with npm ci and npm --prefix frontend ci.
4. Start the API with npm run dev.
5. Start the frontend with npm --prefix frontend run dev.

MongoDB is the durable source of truth for each authenticated workspace. On the first signed-in load, legacy Budget, Goals, Portfolio, and Simulator browser records are validated, imported once, and removed from local storage.

Private AI Knowledge (RAG)

The Simulation Lab includes an account-scoped AI Knowledge desk. With an existing OpenRouter key, this free embedding default works without another account; set the variable only when you want to pin or replace it:

RAG_EMBEDDING_MODEL=nvidia/nemotron-3-embed-1b:free

OpenRouter's URL and key are reused automatically. A custom provider can be set with RAG_EMBEDDING_BASE_URL and RAG_EMBEDDING_API_KEY; its selected model must support the /embeddings endpoint. Source text is split into bounded chunks, embedded, stored in MongoDB, and ranked with cosine similarity. The initial implementation scans at most 500 private chunks per query; introduce an Atlas Vector Search index before substantially larger corpora. Free providers may retain submitted text, so review provider data policies before uploading private or licensed material.

Tests

npm test                                  # backend API smoke + validation tests
npm --prefix frontend run test:quant      # quant engine regression suite
npm --prefix frontend run lint            # frontend lint

Production Deployment

The production target is Heroku (always-on dyno covered by GitHub Student Pack credits). In production the API serves the built React app from the same origin, so there is no separate static host and no cross-origin configuration.

Full step-by-step instructions — Atlas/Upstash setup, Clerk webhooks, config vars, custom domain DNS, and rollback commands — live in docs/DEPLOYMENT.md.

Quick summary:

heroku create walletstack-app
# set config vars per docs/DEPLOYMENT.md §5
git push heroku main                      # or connect GitHub for auto-deploys

Never commit .env files or production secrets.

Launch Security and Search

Use Node.js 22 or newer. Run npm run security:check -- --history after building to check tracked files, reachable Git history, and generated assets for common secret formats and configured backend credentials. Findings omit secret values. CI also checks dependencies, API security, privacy behavior, and frontend builds.

The market and finance APIs require a verified Clerk session. No account password is stored by WalletStack. Production errors omit internal messages and traces; API docs are disabled outside development. Public forms allow ten submissions per IP per hour. Limits use process memory: configure a shared limiter or edge protection before scaling across multiple application instances.

Before publishing:

• Set NODE_ENV=production, CLIENT_URL to exact frontend origins, and SITE_URL and VITE_SITE_URL to the actual canonical domain. Set TRUST_PROXY_HOPS=1 for Heroku or the verified proxy count for another host; keep direct access blocked.
• In MongoDB Atlas, restrict network access to the hosting network and give the application database user only the required database permissions. Enable TLS, backups, and account MFA. These cloud settings cannot be enforced by this repo.
• Use production Clerk credentials and set the Clerk legal links to /terms and /privacy. Review the legal text with the actual operator identity and applicable requirements before offering the service publicly.
• Set VITE_GA_MEASUREMENT_ID only when using GA4. Disable GA Enhanced Measurement automatic page changes, form interactions, and other automatic events in the Google data stream; the application sends sanitized public page views manually. PostHog remains supported. Both are optional and require consent; session replay is disabled. Privacy choices are available in the footer and privacy policy.
• Add GOOGLE_SITE_VERIFICATION (or VITE_GOOGLE_SITE_VERIFICATION) from Search Console, rebuild, verify ownership in Google, then submit /sitemap.xml. Sitemap and robots files are generated at build time; change the domain before building. The Express production server adds route-specific HTML metadata and real 404 status codes. A separately hosted frontend needs equivalent routing.

There is no object-storage bucket or admin portal in the current application. Do not create public storage or administrative access to satisfy a checklist. Verified customer reviews and physical locations must come from real information; the public site does not fabricate them. Terms and privacy pages describe the implemented product but are not a certification of legal compliance.

Sector Browsing and Quant Research

Dashboard sector tiles open company listings in Search. The eleven sector categories use a provider-filtered equity screener, with market selection, server-side sorting and 25-listing pages. NSE/BSE or dual listings remain separate instruments. Coverage is limited to Yahoo-reported listings; the UI shows totals, quote timestamps and missing metrics without inventing values. The heat percentages are US sector ETF proxies, not whole-market averages. No additional API key is required. The custom Yahoo screener adapter uses the installed SDK's internal authenticated fetch because its public screener API only supports predefined screens; verify this integration after SDK upgrades.

Market Lab > Backtest fetches 1-5 years of completed daily sessions separately from display charts. It rejects estimated history and executes prior-close signals at the next open. Capital, commissions and slippage are configurable. The same evaluation window and entry costs apply to the buy-and-hold benchmark. Metrics include excess return (not CAPM alpha), CAGR, Sharpe, Sortino, drawdown, closed-trade win rate, turnover, exposure and execution costs. Trade logs export signal/execution dates to CSV. Open positions are marked without forced exits. This is historical rule replay, not an out-of-sample ML experiment. Dividend cash flows, taxes, borrowing, liquidity constraints and delisted-universe coverage are not modeled. Corporate-action adjustments need dataset validation.

The existing Express/React, MongoDB, Redis and retrieval layers can support a separate Python research service. Planned stages are chronological model evaluation with train-only preprocessing and purged forward labels; return and volatility forecasts compared with statistical baselines; earnings transcript segmentation and sentiment; then options/Greeks and RL hedging benchmarks. Those trained models, transcript ingestion, experiment tracking and RL policies are not implemented by the sector/backtest update. LLM narratives should cite computed outputs, while numerical engines calculate the results.

Financial News Desk

The dashboard and Markets > Financial news provide country/territory mention search, financial topics, source links, publication times and stock-impact analysis. The country filter is a keyword search, not the publisher's location and not a promise of exhaustive coverage. RSS fallback is the English edition; NewsAPI can search English or all of its supported languages.

Get a key at https://newsapi.org/register and set these backend-only values:

NEWSAPI_KEY=your_key_here
NEWSAPI_PLAN=developer
NEWSAPI_DAILY_LIMIT=90

Restart the backend after configuration. Never use a VITE_ variable for this key. NewsAPI's Developer plan permits development/testing only, has a 24-hour article delay and a 100-request daily quota. It cannot serve staging or a public site. Use NEWSAPI_PLAN=production only with a production-eligible NewsAPI subscription. No subscription is purchased by this integration. Review the provider terms at https://newsapi.org/pricing before deployment. Without an eligible key or during an outage, the UI explicitly identifies its public Google News RSS fallback. RSS is a best-effort headline source with no uptime or completeness guarantee; publisher rights and provider terms still apply. Full article bodies are not scraped or stored.

NewsAPI responses are cached for 30 minutes on Developer and five minutes on production plans. Requests are coalesced and a per-process daily budget protects the configured quota; a shared quota counter is needed before scaling instances. The Developer result window is capped at 100 articles, with 20 per page. RSS has one page. Article metadata/excerpts are cached for one hour for evidence checks.

Stock impact uses dots-studio/dots-3-note-preview:free with reasoning disabled and a lightweight, non-demo quote lookup (without full fundamental enrichment). NEWS_IMPACT_MODELS can override the model list for this module without changing other AI features. Configured models fall back to openrouter/free within an 20-second inference budget. Responses request a strict JSON schema and are validated locally. Free-route availability, latency and rate limits vary. It returns a conditional impact hypothesis, event relevance, transmission channels, confidence, exact source excerpts and invalidation/monitoring points. The model receives only the headline/excerpt and selected stock context, not the full article. Unsupported evidence or provider failure returns an error instead of a fabricated analysis. Latest-session price change is explicitly separate from causally attributable event returns. No portfolio data is sent by this tool.