CommonCents

Stock & Wealth Toolkit for Everyday Retail — FastAPI + React (Vite) app for equity research and wealth planning.

Requirements

• Backend: Python 3.11–3.14 (3.14 needs recent pydantic wheels; if install fails, use 3.12).
• Frontend: Node.js 18+ and npm (for npm install, npm run dev, npm test).

Quick start (Windows)

From the repo root:

start-commoncents.bat

Or double-click start-commoncents.bat. This opens the API (port 8080) and the Vite dev server (port 5173).
Legacy: start-steter.bat forwards to start-commoncents.bat.

Backend

cd backend
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
# optional: set ANTHROPIC_API_KEY, FRED_API_KEY

Use run-server.bat or run-server.ps1 (defaults to port 8080, override with env var COMMONCENTS_PORT).

• API docs: http://127.0.0.1:8080/docs

Backend tests

cd backend
.\venv\Scripts\activate
pytest

Frontend

cd frontend
npm install
npm run dev

• App: http://localhost:5173 (proxies /api to 8080 by default)

Override the API proxy target when running Vite:

COMMONCENTS_API_URL=http://127.0.0.1:8080

Frontend tests

cd frontend
npm test

What was implemented

• Equity: ticker search, research card (EDGAR + yfinance + FRED), compare (2–3 tickers), SQLite research cache, deterministic signals, template or optional Anthropic summary (ANTHROPIC_MODEL in .env).
• Wealth: questionnaire, profile scoring, allocations, goals, net worth snapshots, portfolio build with simulated projections.
• No authentication: user_id is a UUID in localStorage (commoncents_user_id).

PRD vs engineering spec

The PRD quiz score bands may differ from the Project Directory; this build follows the Project Directory thresholds.