Django App Layout

Overview

The wiki/entities/b2bpaper backend follows Django's app-per-domain pattern, where each Django app owns a coherent slice of the business domain. Apps live under backend/apps/ and follow a consistent internal structure. The backend runs Django 5.x with Django REST Framework 5.x on PostgreSQL.

App Structure Convention

Every Django app follows this layout:

apps/<app_name>/
    __init__.py
    models.py           # Django models (always PostgreSQL)
    serializers.py      # DRF serializers (explicit fields, NEVER __all__)
    views.py            # ViewSets or GenericAPIView
    urls.py             # URL routing for this app
    admin.py            # Django admin configuration
    permissions.py      # Custom DRF permissions (when needed)
    filters.py          # django-filter FilterSets (when needed)
    services.py         # Pure-function business logic (when needed)
    tests/
        test_models.py
        test_api/       # API integration tests
        test_services/  # Service unit tests (when services.py exists)

Domain Apps

Based on the wiki/concepts/six-core-entities and wiki/concepts/eight-core-actions, the key domain areas are:

Key Backend Conventions

Serializers

• Always use ModelSerializer with explicit fields list
• Never use fields = '__all__' -- this is a hard rule
• Nested serializers for related data where appropriate

Views

• ViewSets for standard CRUD operations
• GenericAPIView for custom endpoints
• Views call services for business logic -- they do not contain it themselves

Database

• PostgreSQL always -- never SQLite (even in development) or MySQL
• Use select_related and prefetch_related to avoid N+1 queries
• Prices stored as integer cents, never floats

API Design

• API prefix: /api/v1/
• URL paths use kebab-case (e.g., /api/surplus-items/)
• Filtering via django-filter
• Documentation via drf-spectacular (OpenAPI/Swagger at /mvp/api/docs/)

Authentication

• Django auth + JWT tokens via djangorestframework-simplejwt
• Custom permissions for business logic authorization

Async Processing

• Celery + Redis for async tasks
• Email ingestion, matching, and newsletter generation run as Celery tasks
• See wiki/concepts/pm2-process-layout for process management

Documentation

• Google-style docstrings (Args/Returns/Raises) on all functions
• 12-factor app principles -- environment variables for all configuration

Sources

• raw/notes/systemPatterns -- entity and action definitions that map to apps
• raw/notes/techContext -- backend stack details
• raw/notes/codeGuidelines -- Django coding standards

Related

• wiki/concepts/service-layer-pattern -- how business logic is organized within apps
• wiki/concepts/six-core-entities -- the entities these apps manage
• wiki/concepts/eight-core-actions -- the actions these apps implement
• wiki/concepts/angular-frontend-stack -- the frontend that consumes these APIs
• wiki/concepts/pm2-process-layout -- how the backend processes are managed
• wiki/summaries/codeguidelines-summary -- full coding standards