# Repository Guidelines

## Project Structure & Module Organization
- `ecoloop/`: Django project settings, URLs, WSGI/ASGI.
- `api/`: Public API (profiles, matching, leaderboard) and router.
- `recycle_core/`: Domain models and APIs (organizations, customers, materials, pricing, pickups, weighing, invoices, payouts, bidding).
- `frontend/`, `admin_frontend/`, `cms/`, `settings/`: UI/admin apps and site pages.
- `templates/`, `static/`, `staticfiles/`, `media/`: assets and uploads.
- Entrypoints: `manage.py`, `docker-compose.yml`, `Dockerfile`.

## Build, Test, and Development Commands
- Local (Python):
  - `python manage.py migrate` — apply DB migrations.
  - `python manage.py runserver` — start dev server at `http://127.0.0.1:8000`.
  - `python manage.py seed_ecoloop` — seed demo org, users, materials, pickup, weigh ticket, invoice, and a sample listing/bid.
  - `python manage.py ecoloop_auto_close_award` — auto-close and award expired listings.
- Docker (recommended):
  - `docker-compose up --build` — start web (port 8024) and Postgres.
- Tests:
  - `python manage.py test` — run Django/DRF tests.

## Coding Style & Naming Conventions
- Python 3.11, Django 4.x, DRF.
- 4-space indentation, PEP 8; prefer type hints (`from __future__ import annotations`).
- Django/DRF structure: models → serializers → viewsets → `api/urls.py` router.
- Migrations: one logical change per migration; descriptive names.
- API routes: kebab-case resources (e.g., `scrap-listings`, `weigh-tickets`).

## Testing Guidelines
- Use Django TestCase/APITestCase patterns; name files `tests.py` or `tests/test_*.py`.
- Cover model integrity, permissions, and key endpoints (create/list/detail/actions).
- Seed-independent: avoid relying on `seed_ecoloop` inside tests.
- Run `python manage.py test` locally and in CI (if configured).

## Commit & Pull Request Guidelines
- Commits: concise, imperative subject; scope where helpful (e.g., `core: add ScrapListing bids`).
- Include rationale and migration notes in the body when relevant.
- PRs: clear description, screenshots (if UI), steps to reproduce/verify, and linked issues.
- Ensure: migrations included, tests updated, local run (`runserver`/docker-compose) verified.

## Security & Configuration Tips
- Configure `.env`: `SECRET_KEY`, `DEBUG`, `DB_*`, `ALLOWED_HOSTS`, JWT settings.
- Never commit secrets; production `DEBUG=0` and database backed by managed Postgres.
- File uploads stored under `MEDIA_ROOT`; restrict who can upload and access.