govoplan-dist-lists/docs/IMPLEMENTATION_PLAN.md

GovOPlaN Distribution Lists Implementation Plan

Milestone 0: Module Seed

Goal: establish repository identity, module boundary, and installable manifest.

Tasks:

• initialize repository type and package metadata
• document boundary between address lists, distribution lists, and Umlauf
• add a no-op module manifest with durable documentation topics
• create Gitea issues for the implementation milestones

Milestone 1: Contract And DTOs

Goal: define mixed recipient entries without implementing every provider.

Tasks:

• define distribution-list, entry, expansion-plan, and expansion-result DTOs
• define source reference formats for address contacts, IDM identities/typed groups, organization units/functions, effective incumbents, Dataflow results, raw targets, and nested-list entries
• define policy/read-only explanation payloads
• define snapshot evidence shape
• add cycle detection and expansion-limit semantics

Milestone 2: Local Distribution Lists

Goal: implement local, manually maintained distribution lists.

Tasks:

• add database tables and migrations
• add CRUD routes and permissions
• add local raw email/postal entries
• add references to address contacts and address lists via capabilities
• expose dist_lists.source and dist_lists.expand
• add tests for expansion and snapshots

Milestone 3: Provider Integrations

Goal: allow distribution lists to resolve through installed modules.

Tasks:

• integrate with addresses.lookup and address-list source capability
• integrate with IDM identity and effective function-assignment resolution
• resolve typed IDM groups once govoplan-idm#7 exposes the provider contract; until then the selector and expansion return an explicit unavailable outcome
• integrate with Organizations unit/function resolution
• consume governed Datasource/Connector states through pinned Dataflow outputs
• apply Addresses preference/consent facts and explainable Policy decisions
• preserve module independence when optional providers are absent

Milestone 4: UI

Goal: make distribution lists practical for administrators and operators.

Tasks:

• add list management UI
• add mixed entry editor with provider-specific search
• show disabled/read-only entries with explanations
• show expansion preview and stale-source warnings
• expose picker components to Campaign, Templates, Reporting, and Workflow consumers

Milestone 5: AdreMa Dynamic Audiences

Goal: replace hard-coded AdreMa query branches with reusable governed definitions.

Tasks:

• add immutable static, parameterized, and dynamic definition revisions
• support include/exclude/manual-override sets with bounded policy constraints
• pin Datasource states, Connector revisions, and Dataflow definitions
• provide preview, counts, samples, and why included/excluded diagnostics
• freeze exact expansion and channel-decision evidence
• validate with a synthetic AdreMa golden flow

Milestone 6: Campaign, Reporting, And Workflow Integration

Goal: support administrative circulation workflows without confusing list definition with execution.

Tasks:

• let Campaign consume snapshots for explicit hybrid-channel routing
• let Reporting consume snapshots for parameterized tables and exports
• let Workflow consume distribution-list expansion snapshots
• support ordered participant sequences where workflow owns state
• add escalation and substitution hooks through workflow, not distribution lists
• preserve immutable recipient evidence for every execution