# 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.