Configuration Guide

This guide explains how to configure Deply for your project.

Configuration File Structure

The configuration file (deply.yaml) has the following structure:

deply:
  paths:
    - /path/to/your/project

  exclude_files:
    - ".*\\.venv/.*"

  layers:
    - name: layer_name
      collectors:
        - type: collector_type
          # collector specific configuration

  ruleset:
    layer_name:
      disallow_layer_dependencies:
        - other_layer_name

Layer Definitions

Layers are the core concept in Deply. They represent different parts of your application architecture. Each layer can have multiple collectors that define which code elements belong to that layer.

A code element belongs to every layer whose collector matches it. Layer and collector order has no precedence. For each code dependency, Deply checks every unique source and target layer pair, except pairs where both layer names are the same. One code dependency can therefore produce multiple violations when multiple membership pairs are explicitly forbidden. External-import rules also apply to every matching layer.

Example Layer Configuration

layers:
  - name: models
    collectors:
      - type: class_inherits
        base_class: "django.db.models.Model"

  - name: services
    collectors:
      - type: bool
        must:
          - type: class_name_regex
            class_name_regex: ".*Service$"

Rules and Collectors

Layer Rules

Rules define how layers can interact with each other:

ruleset:
  views:
    disallow_layer_dependencies:
      - models
  domain:
    disallow_external_imports:
      - django
      - requests

Collectors

Collectors define how code elements are collected into layers. See the Collectors Reference for detailed information about each collector type.

Framework Configuration Recipes

Use these editable starting points for common Python web frameworks:

These recipes use the existing Deply configuration schema. They are not built-in presets and should be adapted to the project’s actual directories and architecture.

Architecture and Pattern Recipes

Use the Architecture Styles catalog to choose and enforce layered, inward-dependency, modular, feature-oriented, data, messaging, and presentation boundaries.

Validate Configuration

Run deply validate to check configuration syntax and schema without analyzing project files:

deply validate --config=deply.yaml

The command checks YAML parsing, supported top-level and collector keys, analysis directories, element_type values, regex validity, layer names, collector settings, rule settings, and references between rules and layers. It exits with status 0 when the configuration is valid and 1 when validation errors are found. deply analyze runs the same validation before scanning project files.

Advanced Configuration Examples

Complex Layer Definition

- name: services
  collectors:
    - type: bool
      must:
        - type: class_name_regex
          class_name_regex: ".*Service$"
      must_not:
        - type: file_regex
          regex: ".*/excluded_folder_name/.*"
        - type: decorator_usage
          decorator_name: "deprecated_service"

Multiple Layer Rules

ruleset:
  views:
    disallow_layer_dependencies:
      - models
  tasks:
    enforce_function_decorator_usage:
      - type: function_decorator_name_regex
        decorator_name_regex: "app.task"
  domain:
    disallow_external_imports:
      - django
      - sqlalchemy

Best Practices

Start with a simple configuration and gradually add complexity
Use meaningful layer names that reflect your architecture
Keep collector rules as specific as possible
Document your layer dependencies and rules
Regularly review and update your configuration as your project evolves

For more detailed information about collectors and their configuration options, please refer to the Collectors Reference.