govoplan-dist-lists/docs/DISTRIBUTION_LISTS_ARCHITECTURE.md

GovOPlaN Distribution Lists Architecture

Decision

govoplan-dist-lists owns reusable operational distribution lists (Verteiler). This module is deliberately separate from govoplan-addresses: address lists are plain address-domain groupings, while distribution lists are cross-module recipient definitions that may resolve through address books, identity, organizations, groups, functions, roles, raw addresses, and other future provider capabilities.

Vocabulary

• Address book: stores contacts and contact points such as email and postal addresses.
• Address list: an address-owned list of contacts/contact methods from address books.
• Distribution list / Verteiler: a reusable operational recipient definition with mixed entry types.
• Umlauf: an execution workflow over recipients or actors with order, state, deadlines, decisions, and escalation. Distribution lists define who; workflow/tasks define what happens.
• Snapshot: immutable expansion evidence stored by the consuming module at send, publish, decision, notification, or execution time.

Ownership

Distribution Lists owns:

• distribution-list definitions
• mixed recipient entries
• provider-neutral recipient entry DTOs
• expansion plans and expansion results
• immutable expansion snapshots and stale-source warnings
• nested-list handling, cycle detection, and expansion limits
• source provenance and traceability
• policy/read-only explanation payloads for unavailable entries

It does not own:

• contact storage or vCard/CardDAV sync
• identity or organization master data
• delivery transports
• campaign versioning
• workflow task execution

Entry Types

Initial supported entry types should be provider-neutral:

• address_contact
• address_email
• raw_email
• raw_postal_address
• identity_principal
• organization_unit
• group
• function
• role
• distribution_list

Each entry should carry a stable source reference, display label, optional delivery-channel hints, provenance, and a policy/readiness state.

Capability Direction

The first capabilities should be:

• distLists.source: list visible distribution lists as reusable recipient sources.
• distLists.expand: expand a distribution list into immutable recipient rows.
• distLists.writer: explain whether a caller can create or change a list.

Consumers must resolve those capabilities through core and must not import distribution-list ORM or service internals.

Consumers

Likely consumers:

• Campaign: campaign recipient sources and send snapshots.
• Mail: ad-hoc recipient picking and reusable send groups.
• Postbox: recipient routing and publish snapshots.
• Notifications: notification target groups.
• Scheduling: invitation target groups.
• Poll/Evaluation/Consultation: invited participants and response audiences.
• Workflow/Tasks: Umlauf participant lists and escalation targets.
• Cases/Permits: case routing and responsible-function targeting.

Relationship To Address Lists

govoplan-addresses should implement classical address lists first. A distribution list may later include an address list as an entry, but the address module remains the owner of contact records and address-only grouping.

The distribution-list module owns mixed operational routing. This prevents campaign-specific recipient logic from becoming the platform's de facto Verteiler implementation.