1 files changed, 140 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9f1de30
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# Prism v2
+
+Prism v2 is a monorepo rewrite of Prism's Overview experience with a FastAPI backend and a Next.js frontend. This first slice covers:
+
+- ticker search
+- selected ticker profile and quote
+- market bar
+- historical price chart
+- overview signal and stat cards
+- persisted watchlist backed by SQLite
+
+The implementation copies and adapts finance logic from Prism v1 into `backend/`; it does not import code from the old repo at runtime.
+
+## Repo Layout
+
+- `backend/`
+  - `app/main.py` FastAPI application and routes
+  - `app/services/data_service.py` yfinance-backed Overview service layer with TTL caching
+  - `app/db/watchlist.py` SQLite persistence for the default local profile
+  - `data/prism.db` local watchlist database
+  - `tests/` backend unit and API smoke tests
+- `frontend/`
+  - `app/page.tsx` Overview shell
+  - `components/PriceChart.tsx` Plotly price chart
+  - `lib/api.ts` typed REST client
+  - `types/api.ts` shared frontend response types
+- `.env.example` optional environment variables
+- `pytest.ini` backend pytest import path config
+
+## Requirements
+
+- Python 3.14+
+- Node.js 20+
+- npm
+
+## Environment
+
+Copy `.env.example` to `.env` if you want to set optional keys.
+
+Supported variable names are unchanged from Prism v1:
+
+- `FMP_API_KEY`
+- `FINNHUB_API_KEY`
+- `NEXT_PUBLIC_API_BASE_URL`
+
+The current Overview slice works without FMP or Finnhub keys because it relies on yfinance for the active endpoints.
+
+## Backend Setup
+
+```bash
+cd backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Run the API:
+
+```bash
+.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8001
+```
+
+Primary endpoints:
+
+- `GET /health`
+- `GET /api/search?q=...`
+- `GET /api/market/indices`
+- `GET /api/tickers/{symbol}/overview`
+- `GET /api/tickers/{symbol}/history?period=1m|3m|6m|1y|5y`
+- `GET /api/watchlist`
+- `POST /api/watchlist/{symbol}`
+- `DELETE /api/watchlist/{symbol}`
+
+Notes:
+
+- SQLite lives at `backend/data/prism.db`
+- the backend seeds one `default` profile automatically
+- watchlist symbols are normalized to uppercase
+- watchlist size is capped at 10 symbols
+
+## Frontend Setup
+
+```bash
+cd frontend
+npm install
+```
+
+Run the frontend against the local backend:
+
+```bash
+NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8001 npm run dev -- --hostname 127.0.0.1 --port 3001
+```
+
+The UI stores the selected ticker in the URL, for example `/?ticker=AAPL`.
+
+## Quick Start
+
+Start the whole local stack:
+
+```bash
+./scripts/start-stack.sh
+```
+
+Stop both services:
+
+```bash
+./scripts/stop-stack.sh
+```
+
+Notes:
+
+- the scripts expect `backend/.venv` and `frontend/node_modules` to already exist
+- default ports are backend `8001` and frontend `3001`
+- logs are written to `.run/logs/`
+
+## Verification
+
+Backend:
+
+```bash
+backend/.venv/bin/python -m py_compile backend/app/main.py backend/app/schemas.py backend/app/services/data_service.py backend/app/db/watchlist.py
+backend/.venv/bin/python -m pytest backend/tests
+```
+
+Frontend:
+
+```bash
+cd frontend
+npm run lint
+npm run build
+```
+
+## Current Local URLs
+
+If port `8000` is already occupied on your machine, use:
+
+- backend: `http://127.0.0.1:8001`
+- frontend: `http://127.0.0.1:3001`
+
+Those are the ports used by the current local bootstrap.