Stocktuitive

Full-stack guided fundamental analysis for public equities — React UI, FastAPI analysis engine, and a cached public demo deployable without backend hosting or API keys.

Live Demo	https://stocktuitive.vercel.app/demo
Portfolio Case Study	https://sampotozkin.com/projects/stocktuitive
Case study & review path	PORTFOLIO.md

Educational demo only — not financial advice. The public demo replays cached NVDA analysis output; it does not call live market APIs.

---

What lives where

This GitHub repository contains the full monorepo source — frontend, backend, tests, fixtures, and documentation — so reviewers can explore the complete engineering scope.

Vercel (or Netlify) hosts only the public portfolio demo: a static build of Stocktuitve_frontend with cached fixtures. No Python backend is deployed, no API keys are required at build time, and demo routes never call /api.

Surface	What it is	Backend required?	API keys required?
GitHub (this repo)	Full-stack source for local development and code review	For full app locally	For live data locally (see backend .env)
Vercel /demo	Cached NVDA walkthrough (VITE_DEMO_MODE=true)	No	No
Full product (local)	Wayfinder, guided analysis, live yfinance/FMP	Yes	Optional (FMP, OpenAI for some features)

---

Repository structure

STOCKTUITIVE/
├── Stocktuitve_frontend/          # React + TypeScript + Vite (note folder spelling)
│   ├── src/
│   │   ├── demo/fixtures/nvda/  # Cached NVDA JSON for public demo
│   │   ├── config/demo.ts       # VITE_DEMO_MODE / VITE_PORTFOLIO_MODE flags
│   │   └── …                    # Guided analysis, results, profile UI
│   ├── vercel.json              # Demo build + SPA routing (Vercel root = this folder)
│   ├── netlify.toml             # Same demo build for Netlify
│   └── scripts/capture-demo-fixtures.mjs
│
├── Stocktuitive_backend/        # FastAPI analysis API (local / full product)
│   ├── app/                     # Routes, services, metric engine
│   └── tests/                   # pytest suite
│
├── docs/                        # Portfolio assets (screenshots checklist, video script)
├── PORTFOLIO.md                 # Case study, architecture, reviewer checklist
└── README.md                    # This file

---

Public demo (matches Vercel deploy)

The demo is limited to NVDA and runs entirely from cached fixtures in the browser.

Entry points:

• /demo — intro hub
• /demo/analysis/NVDA/guided/current-ratio — guided metric walkthrough
• /demo/results/NVDA — results summary
• /demo/analysis/NVDA/profile — company profile

Run locally (no backend)

cd Stocktuitve_frontend
VITE_DEMO_MODE=true VITE_PORTFOLIO_MODE=true npm run dev
# → http://localhost:5173/demo

Production-style demo build

cd Stocktuitve_frontend
npm run build:demo
npm run preview
# → http://localhost:4173/demo

---

Full app (local development)

The backend is part of the full development build — it powers live analysis, financials, company profile, and price data when you run the product locally. It is not deployed to Vercel.

Terminal 1 — backend (port 8001 matches the Vite dev proxy):

cd Stocktuitive_backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# Copy .env.example → .env and add keys only on your machine (never commit .env)
uvicorn app.main:app --reload --host 127.0.0.1 --port 8001

Terminal 2 — frontend (full app, not demo mode):

cd Stocktuitve_frontend
npm install
npm run dev
# → http://localhost:5173

Use the dev Auth / plan switcher (bottom-left in dev) and set Pro to unlock the full analysis locally.

---

Deploy public demo to Vercel

Vercel must deploy only Stocktuitve_frontend — not the monorepo root or backend.

1. Import this repository in Vercel.
2. Set Root Directory → Stocktuitve_frontend
3. Build Command → npm run build:demo (already in vercel.json)
4. Output Directory → dist
5. No environment variables required for the public demo (demo flags are baked into build:demo).

vercel.json redirects / → /demo and rewrites SPA routes so deep links work.

Netlify: use Stocktuitve_frontend as the base directory and netlify.toml in that folder.

After deploy, replace PASTE_VERCEL_URL at the top of this README with your production URL.

---

Backend in a public repo

The FastAPI backend is safe to publish as source code:

• API keys are read from environment variables at runtime (FMP_API_KEY, OPENAI_SUMMARY_API_KEY, etc.) — never committed.
• .env, venv/, and shell config files (e.g. .zshrcc) are gitignored.
• The legacy Financial Analysis Tool MkV/ subtree uses the same pattern (os.getenv(...)).
• Tracked files like resp.json are sample API responses (public financial data), not credentials.

Cloning and running the backend locally is optional and intended for developers who want the full live product — not for public demo visitors.

---

Security & hygiene

Do not commit:

• .env, .env.local, or any file containing real API keys
• node_modules/, dist/, venv/, .venv/
• .zshrcc or other shell configs that may hold secrets

Only Stocktuitve_frontend/.env.example is tracked (placeholders and comments, no secrets).

---

Tests

# Frontend (demo-related unit tests)
cd Stocktuitve_frontend && npm test

# Backend
cd Stocktuitive_backend && pytest

---

Related documentation

• PORTFOLIO.md — architecture, demo path, verification checklist
• docs/portfolio-assets.md — screenshots, video script, external page copy
• Stocktuitive_backend/README.md — backend API overview