# GovOPlaN Distribution Lists Implementation Plan

## Milestone 0: Module Seed

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

Tasks:

- [x] initialize repository type and package metadata
- [x] document boundary between address lists, distribution lists, and Umlauf
- [x] 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 format for address, identity, organization, group,
  function, role, raw, 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 `distLists.source` and `distLists.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 identity/principal resolution
- integrate with organizations/groups/functions once those modules expose
  provider capabilities
- 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 hover explanations
- show expansion preview and stale-source warnings
- expose picker components to campaign, mail, postbox, notifications,
  scheduling, poll, and workflow consumers

## Milestone 5: Umlauf Integration

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

Tasks:

- let workflow/tasks 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