ecoloop/AGENTS.md

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.