125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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.
|