39 lines
2.6 KiB
Markdown
39 lines
2.6 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
This repository is a Django REST backend organized by app domains. Core configuration lives in `config/` (`settings.py`, `urls.py`, `celery.py`). Feature apps (for example `account/`, `farm_hub/`, `sensor_catalog/`, `crop_zoning/`, `notifications/`) each contain `models.py`, `serializers.py`, `views.py`, `urls.py`, and app-specific `migrations/`.
|
||
|
||
Tests are mostly colocated in each app as `tests.py`. Mock payloads and integration fixtures are stored under `json/mock_data/` and `external_api_adapter/json/`. API collections are under `*/postman/`.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `python -m venv .venv && source .venv/bin/activate` - create and activate a virtual environment.
|
||
- `pip install -r requirements.txt` - install runtime and development dependencies.
|
||
- `python manage.py migrate` - apply database migrations.
|
||
- `python manage.py runserver` - start the local API server.
|
||
- `python manage.py test` - run the full Django test suite.
|
||
- `python manage.py test farm_hub` - run tests for a single app.
|
||
- `docker compose up --build` - run the backend and dependencies via Docker.
|
||
|
||
## Coding Style & Naming Conventions
|
||
Follow standard Django/Python conventions:
|
||
- 4-space indentation, snake_case for functions/variables, PascalCase for classes.
|
||
- Keep serializers in `serializers.py`, business logic in `services.py`, and routing in `urls.py`.
|
||
- Name management commands as verbs (for example `seed_admin_user`).
|
||
- Prefer small, app-scoped modules over cross-app imports unless shared behavior is intentional.
|
||
|
||
## Testing Guidelines
|
||
Use Django’s built-in test runner (`unittest` style). Place tests in each app’s `tests.py` (or `tests/` package if expanded). Name tests as `test_<behavior>` and cover serializers, view responses, and service edge cases. Use `unittest.mock.patch` for external integrations (AI adapters, SMS, or HTTP services).
|
||
|
||
## Commit & Pull Request Guidelines
|
||
Current history uses generic messages (`UPDATE`), but contributors should use clear, imperative commits such as `add sensor catalog seed command`.
|
||
|
||
For PRs, include:
|
||
- concise description of scope and affected apps,
|
||
- migration notes (`manage.py makemigrations`/`migrate` impact),
|
||
- test evidence (`python manage.py test ...` output),
|
||
- linked issue/task ID when available,
|
||
- request/response examples for API changes (Postman or JSON sample paths).
|
||
|
||
## Security & Configuration Tips
|
||
Copy `.env.example` to `.env` and never commit secrets. Validate CORS/JWT settings in `config/settings.py` per environment. Keep mock JSON and seed data free of production credentials or personal data.
|