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, IDM identities and typed groups, organization units and functions, raw addresses, Dataflow-backed rows, and other future provider capabilities.

Distribution Lists is the core GovOPlaN target for the assessed AdreMa functionality. It owns the reusable audience and expansion semantics, not the provider data, rendering, delivery, or workflow state.

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
• static, parameterized, and dynamic segment revisions
• 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
• idm_identity
• idm_group
• organization_unit
• function
• effective_function_incumbent
• dataflow_result
• distribution_list

Each entry should carry a stable source reference, display label, optional delivery-channel hints, effective time, provenance, and a policy/readiness state. Access roles are authorization facts and are not recipient types.

Organizations owns unit/function definitions. IDM owns effective-dated identity-to-function assignments and typed group relationships. Identity lifecycle status remains separate from selectable business status, which is represented by a group, function, or effective-dated relationship.

Capability Direction

The first capabilities should be:

• dist_lists.source: list visible distribution lists as reusable recipient sources.
• dist_lists.expand: expand a distribution list into immutable recipient rows.
• dist_lists.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: hybrid-channel recipient sources, routing, and delivery snapshots.
• Templates: typed render input for printable and digital output.
• Reporting: parameterized lists, drill-down, and governed export.
• Workflow: Umlauf participant lists and guided execution.
• Files/Audit: artifact references and immutable evidence.

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 and keeps reusable AdreMa selections outside Addresses.

Provider Graph

• Addresses contributes contact-point candidates, postal purposes, communication preferences, consent, suppression, and source provenance.
• Organizations contributes units, structures, and function definitions.
• IDM contributes identities, typed groups, effective memberships, and effective function incumbents.
• Datasources and Connectors contribute governed source states and immutable fingerprints.
• Dataflow contributes bounded, versioned selection and transformation results.
• Policy contributes eligibility decisions and user-readable provenance.

Expansion records the exact provider revisions and decisions. Templates, Campaign, Files, Audit, Reporting, and Workflow consume that immutable result through capabilities and never import Distribution Lists internals.