# Repository Guidelines

## Project Structure & Module Organization

Prism v2 is split into a FastAPI backend and a Next.js frontend.

- `backend/app/` contains the API entrypoint, Pydantic schemas, SQLite watchlist storage, and data-service logic.
- `backend/tests/` contains pytest coverage for API and watchlist behavior.
- `frontend/app/` contains the Next.js App Router pages and global styles.
- `frontend/components/`, `frontend/lib/`, and `frontend/types/` hold reusable UI, API helpers, formatting utilities, and shared TypeScript types.
- `pytest.ini` sets `backend` on `pythonpath` so tests can import `app`.

## Build, Test, and Development Commands

Backend setup and local API:

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

The API runs at `http://localhost:8000`.

Frontend setup and local UI:

```bash
cd frontend
npm install
npm run dev
```

The UI runs at `http://localhost:3000`. Use `npm run build` to validate the production Next.js build and `npm run lint` to run ESLint.

Run backend tests from the repository root:

```bash
pytest
```

## Coding Style & Naming Conventions

Python code uses type hints, small FastAPI route functions, and snake_case for modules, functions, and variables. Keep service logic in `backend/app/services/` and persistence concerns in `backend/app/db/`.

TypeScript uses React function components, PascalCase component names, camelCase values, and the `@/` import alias for frontend modules. Keep shared API shapes in `frontend/types/api.ts` and formatting helpers in `frontend/lib/format.ts`. Frontend linting is configured in `frontend/eslint.config.mjs`.

## Testing Guidelines

Backend tests use pytest and should be named `test_*.py`. Prefer focused tests that mock external market-data calls with `monkeypatch`, as existing tests do. Add tests when changing FastAPI routes, watchlist persistence, or data normalization behavior. There is no frontend test runner yet, so use `npm run lint` and `npm run build` for frontend validation.

## Commit & Pull Request Guidelines

This checkout has no existing commit history. Use concise, imperative commit subjects such as `Add watchlist tests` or `Fix ticker history error handling`.

Pull requests should include a short summary, test results (`pytest`, `npm run lint`, `npm run build` when relevant), linked issues if applicable, and screenshots or screen recordings for visible UI changes. Note any required environment variables such as `FMP_API_KEY` or `FINNHUB_API_KEY`.

## Security & Configuration Tips

Do not commit API keys, local virtual environments, `node_modules/`, or generated SQLite data files. Optional market-data keys should be provided through the environment or a local `.env` file.