# Dev setup (conventions; code scaffolding comes next)

This doc sets the conventions we’ll implement in the first “code PRs”.

## Python + layout
- Use Python 3.x
- Source layout: `src/` + `tests/`
- Prefer type hints and docstrings

## Configuration
- Store secrets in `.env` (not committed).
- Commit a `.env.example` documenting required variables.

Expected variables (initial):
- `POTE_DB_URL` (e.g., `sqlite:///./pote.db` or Postgres URL)
- `QUIVER_API_KEY` (optional, if using QuiverQuant)
- `FMP_API_KEY` (optional, if using Financial Modeling Prep)

## Database
- Default dev: SQLite for fast local iteration.
- Support Postgres for “real” runs and larger datasets.
- Migrations: Alembic (once models are in place).

## Testing
- `pytest` for unit/integration tests
- Prefer:
  - HTTP clients tested with mocked responses
  - DB tests using SQLite in a temp file or in-memory where possible

## Logging
- Use standard `logging` with consistent, parseable messages.
- ETL jobs should log counts: fetched/inserted/updated/skipped.

## PR sizing guideline
Each PR should:
- implement one coherent piece (schema, one client, one ETL, one metric module)
- include tests
- include minimal docs updates (if it changes behavior)