# Repository Guidelines

## Project Structure & Module Organization
`src/` contains the application code. `src/app.py` is the Flask-SocketIO entrypoint; trading logic lives in modules such as `BrighterTrades.py`, `Exchange.py`, `trade.py`, and `DataCache_v3.py`. Keep browser assets in `src/static/` and Jinja templates in `src/templates/`. Service-specific code lives under `src/brokers/`, `src/wallet/`, and `src/edm_client/`. `tests/` mirrors backend features with `test_*.py`. Treat `archived_code/` as reference-only, not active code. `markdown/` and `UML/` hold supporting docs and design notes.

## Build, Test, and Development Commands
`python -m venv .venv && source .venv/bin/activate` creates a local environment.

`pip install -r requirements.txt` installs runtime and test dependencies.

`python src/app.py` starts the app on `127.0.0.1:5002`.

`pytest` runs the default suite from `tests/` and skips `integration` tests per `pytest.ini`.

`pytest -m integration` runs tests that call external services.

`pytest -m live_testnet` runs tests that require live testnet credentials.

## Coding Style & Naming Conventions
Use 4-space indentation in Python and group imports as standard library, third-party, then local modules. Prefer `snake_case` for functions, variables, and new module names; use `PascalCase` for classes. This repository has legacy CamelCase modules such as `BrighterTrades.py` and `Exchange.py`; preserve existing naming when editing nearby code instead of renaming broadly. Keep frontend filenames descriptive, for example `formations.js` or `backtesting.js`. No formatter or linter config is committed, so keep edits focused and style-consistent with the surrounding file.

## Testing Guidelines
`pytest.ini` expects `test_*.py`, `Test*`, and `test_*`. Add tests alongside the behavior you change and mark external coverage with `@pytest.mark.integration`, `@pytest.mark.live_integration`, or `@pytest.mark.live_testnet` as appropriate. For normal PRs, include at least one automated test for each bug fix or behavior change. Prefer mocks or fakes for exchange and wallet paths unless you are intentionally covering live integrations.

## Commit & Pull Request Guidelines
Recent history favors short imperative subjects like `Fix chart sync...`, `Add Blockly integration...`, and `Improve line drawing UX...`. Keep commits scoped and descriptive. PRs should include a brief summary, affected areas, test commands run, and screenshots for UI changes in `src/static/` or `src/templates/`. Call out any new environment variables, API keys, or YAML/config updates reviewers need.

## Configuration & Security Tips
Use `src/config.example.py` as the template for local configuration and keep secrets in environment variables such as `BRIGHTER_BINANCE_API_KEY` and `BRIGHTER_ALPACA_API_KEY`. Do not commit real credentials, local database files, or live/testnet secrets.
