initial commit

docs/DISTRIBUTION_LISTS_ARCHITECTURE.md

@@ -0,0 +1,98 @@
+# 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.

docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,75 @@
+# 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