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