# Repository Guidelines

## Project Structure & Module Organization
`app.py` is the Streamlit entrypoint and wires the sidebar, top-of-page sections, and main tabs together. UI sections live in `components/` (`overview.py`, `valuation.py`, `top_movers.py`, etc.). Data access and finance logic live in `services/`, with `data_service.py` handling most `yfinance` work and `valuation_service.py` containing DCF and EV/EBITDA calculations. Shared formatting helpers are in `utils/`. Static assets such as the logo live in `assets/`.

There is currently no dedicated `tests/` directory. If you add tests, place them under `tests/` and mirror the source layout where practical.

## Build, Test, and Development Commands
Use the local virtual environment before running anything:

```bash
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py
```

- `pip install -r requirements.txt`: installs Streamlit, Plotly, `yfinance`, and supporting libraries.
- `streamlit run app.py`: starts the dashboard locally at `http://localhost:8501`.
- `python -m py_compile app.py components/*.py services/*.py utils/*.py`: quick syntax check across the codebase.

## Coding Style & Naming Conventions
Follow existing Python style: 4-space indentation, descriptive snake_case for functions and variables, and short module-level docstrings. Keep render functions named `render_<section>()` inside `components/`. Prefer small helper functions for repeated UI patterns. Match the repo’s current approach: light comments, defensive fallbacks around API data, and `@st.cache_data` for expensive fetches.

No formatter or linter is configured in the repo today, so keep changes stylistically consistent with neighboring files.

## Testing Guidelines
There is no automated test suite yet. For UI or data-flow changes, run the app locally and verify the affected tab or section with a few tickers. At minimum, run targeted syntax checks with `python -m py_compile <file>`. If you add nontrivial finance logic, include unit tests in `tests/` and cover both normal and missing-data cases.

## Commit & Pull Request Guidelines
Use short, imperative commit messages like `Add top movers section` or `Fix EBITDA consistency bug`. Keep each commit focused on one user-visible change or bug fix.

For pull requests, include:
- a clear summary of what changed and why
- any data-source or API-key impact
- screenshots or short screen recordings for UI changes
- manual verification notes (example tickers tested, tabs checked)

## Security & Configuration Tips
Store API keys in `.env`; do not commit secrets. Prism can run partially without `FMP_API_KEY` and `FINNHUB_API_KEY`, so document any new required configuration in `README.md`.