Project Directory Structure

Proposed Django project layout:

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.