Architecture and Design
=======================

This page explains how the package works beyond the API surface and why the
current module split exists.

Design goals
------------

- Keep serializer APIs close to native DRF behavior.
- Make output-shape control request-driven and explicit.
- Allow opt-in queryset optimization without hidden magic.

Module responsibilities
-----------------------

``serializers.py``
   Implements expansion, sparse fieldsets, and nested option propagation via
   ``FlexFieldsSerializerMixin`` and ``FlexFieldsModelSerializer``.

``views.py``
   Provides ``FlexFieldsMixin`` and ``FlexFieldsModelViewSet`` to control list
   action expansion and pass serializer context constraints.

``filter_backends.py``
   Provides ``FlexFieldsFilterBackend`` for queryset optimization and
   ``FlexFieldsDocsFilterBackend`` for schema parameter support.

``config.py``
   Centralizes runtime settings from ``REST_FLEX_FIELDS2`` and exports constants
   used by serializers and utilities.

``utils.py``
   Contains helper logic for parsing nested field paths and checking inclusion
   and expansion intent.

Serialization flow
------------------

1. Root serializer reads request parameters (or constructor kwargs).
2. Sparse field controls are resolved.
3. Expansion paths are validated for recursion and depth.
4. Nested serializers are constructed with propagated options.
5. Output payload is returned using resolved fields and expansions.

Key implementation choices
--------------------------

- Mixin-first design supports custom serializer base classes.
- Lazy serializer references support circular import scenarios.
- Expansion limits and recursive policies are configurable globally and per
  serializer class.
- Query optimization is optional and intentionally conservative.

Extension points
----------------

- Customize query parameter names in ``REST_FLEX_FIELDS``.
- Override serializer validation hooks for expansion policy errors.
- Restrict list expansions with ``permit_list_expands`` on viewsets.
- Pair expansion rules with explicit ``select_related`` and
  ``prefetch_related`` for predictable performance.

When changing internals
-----------------------

1. Add tests for nested expansion and sparse field interactions.
2. Update user documentation if behavior changes.
3. Update this page if module responsibilities or flow changes.