Project Directory Structure
===========================

Proposed Django project layout:

.. code-block:: text

   chargesol/
   ├── manage.py
   ├── pyproject.toml
   ├── chargesol/                      # Project configuration
   │   ├── __init__.py
   │   ├── settings/
   │   │   ├── __init__.py
   │   │   ├── base.py                 # Shared settings
   │   │   ├── dev.py                  # Development overrides
   │   │   └── prod.py                 # Production settings
   │   ├── urls.py                     # Root URL configuration
   │   ├── wsgi.py
   │   └── asgi.py
   ├── apps/
   │   ├── accounts/
   │   │   ├── __init__.py
   │   │   ├── models.py               # User, Role, Team, TeamMembership, Zone
   │   │   ├── views.py                # Auth + user/team CRUD
   │   │   ├── serializers.py          # DRF serializers
   │   │   ├── urls.py                 # App URL routes
   │   │   ├── admin.py                # Admin configuration
   │   │   ├── permissions.py          # Custom permission classes
   │   │   ├── managers.py             # Custom model managers
   │   │   ├── signals.py              # Post-save signals
   │   │   └── tests/
   │   │       ├── __init__.py
   │   │       ├── test_models.py
   │   │       ├── test_views.py
   │   │       └── test_permissions.py
   │   ├── leads/
   │   │   ├── __init__.py
   │   │   ├── models.py               # Lead, LeadSource, LeadDocument
   │   │   ├── views.py                # Lead CRUD + document management
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── filters.py              # DRF filter backends
   │   │   ├── signals.py              # Status change triggers
   │   │   ├── tasks.py                # Celery: lead import, notifications
   │   │   └── tests/
   │   ├── surveys/
   │   │   ├── __init__.py
   │   │   ├── models.py               # Survey, SurveyAssignment, SurveyReport, SurveyMedia
   │   │   ├── views.py                # Survey lifecycle endpoints
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── filters.py
   │   │   ├── signals.py              # Assignment notifications
   │   │   ├── tasks.py                # Celery: reminder calls, report reminders
   │   │   └── tests/
   │   ├── installations/
   │   │   ├── __init__.py
   │   │   ├── models.py               # Installation, InstallationAssignment, Report, Media
   │   │   ├── views.py
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── filters.py
   │   │   ├── signals.py
   │   │   ├── tasks.py
   │   │   └── tests/
   │   ├── procurement/
   │   │   ├── __init__.py
   │   │   ├── models.py               # Material, Stock, Allocation, ProcurementRequest, Vendor
   │   │   ├── views.py
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── services.py             # Stock check + allocation logic
   │   │   └── tests/
   │   ├── finance/
   │   │   ├── __init__.py
   │   │   ├── models.py               # VendorPayment, JobPayout, PaymentSchedule
   │   │   ├── views.py
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── services.py             # Payment processing logic
   │   │   ├── tasks.py                # Celery: scheduled payouts
   │   │   └── tests/
   │   ├── reporting/
   │   │   ├── __init__.py
   │   │   ├── models.py               # ClosurePack, WeeklyReport, MonthlyReport
   │   │   ├── views.py
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── services.py             # Report generation logic
   │   │   ├── tasks.py                # Celery: scheduled report generation
   │   │   └── tests/
   │   ├── notifications/
   │   │   ├── __init__.py
   │   │   ├── models.py               # Notification, Template, CallLog, DeliveryReceipt
   │   │   ├── views.py
   │   │   ├── serializers.py
   │   │   ├── urls.py
   │   │   ├── admin.py
   │   │   ├── backends/               # SMS, email, WhatsApp backends
   │   │   │   ├── __init__.py
   │   │   │   ├── sms.py
   │   │   │   ├── email.py
   │   │   │   └── whatsapp.py
   │   │   ├── services.py             # Dispatch logic
   │   │   ├── tasks.py                # Celery: async dispatch
   │   │   └── tests/
   │   └── emergency/
   │       ├── __init__.py
   │       ├── models.py               # EmergencyEvent, BackupSearch, Assignment, Reschedule
   │       ├── views.py
   │       ├── serializers.py
   │       ├── urls.py
   │       ├── admin.py
   │       ├── services.py             # Backup team search algorithm
   │       └── tests/
   ├── templates/                       # Django templates (admin customization, email)
   ├── static/                          # Static assets
   └── media/                           # User-uploaded files (dev only; S3 in prod)

Key Conventions
---------------

- **App isolation**: Each app owns its models, views, serializers, and tests. Cross-app imports go through public model/service interfaces only.
- **UUID primary keys**: All domain models use ``UUIDField`` as primary key for security and distributed-friendliness. Lookup tables (Role, Zone) use ``AutoField``.
- **Split settings**: ``base.py`` for shared config, ``dev.py`` for local development (DEBUG=True, SQLite optional), ``prod.py`` for production (PostgreSQL, S3, proper secrets).
- **Service layer**: Apps with complex business logic (procurement, finance, reporting, emergency) have a ``services.py`` module to keep views thin.
- **Celery tasks**: Async operations (notifications, scheduled reports, payment processing) live in ``tasks.py`` per app.
- **Custom permissions**: Each app defines its own permission classes in ``permissions.py`` or uses role-based checks from ``accounts.permissions``.