govoplan-campaign/docs/RECIPIENT_ADDRESS_BOUNDARY.md

Recipient And Address Management Boundary

Campaigns own campaign-local recipient entries because sending and reporting need a frozen recipient snapshot. Long-lived address management is a separate domain owned by govoplan-addresses.

govoplan-campaign Owns

• campaign-local recipient entries
• campaign-local recipient import mapping and validation
• message addressing for a concrete campaign version
• send/build/report evidence for the exact recipients used
• campaign-local exclusions, warnings, and review status
• recipient-specific attachment and template evidence

Campaign data is immutable once a version is built for sending. Later address book changes must not rewrite historical campaign evidence.

govoplan-addresses Owns

• Adrema-style address management
• reusable person, organization, household, and postal-address records
• reusable email address lists and segments
• postal-letter recipient views
• consent, legal-basis, and communication-preference metadata
• deduplication and merge workflows
• import/export of reusable address directories
• address quality checks and change history

The addresses module provides the UI/module boundary for this domain and should grow stable DTOs and capabilities that campaigns, mail, forms, reporting, portal, and postbox modules can consume without direct imports.

Current Integration Contract

The campaign module asks the platform registry for address capabilities and keeps working when they are absent. It must not import govoplan-addresses ORM models, services, or WebUI components.

When addresses.lookup is available, campaign recipient address fields use it for autocomplete. The campaign page may warm a small suggestion cache with an empty query and then query by typed text as the user edits sender, reply-to, global recipient, or per-recipient address fields.

When addresses.recipient_source is available, campaign offers a separate address-book/list import flow. This is for importing reusable recipient sources into the campaign recipient table; normal one-off address entry still happens inside the address fields while typing.

The capability should return snapshots, not live ORM objects:

• selected source id and display label
• normalized recipient rows
• provenance fields for source, segment, legal basis, and import time
• update markers so campaigns can show whether a draft is based on stale source data

Campaign stores the resolved snapshot in the campaign version. It may keep a reference to the address source for traceability, but the built campaign remains auditable even if the address source changes later.

If the source revision changes after import, campaign shows a stale-source warning and lets the user reopen the import dialog with that source preselected. The user still chooses append or replace; campaign should not silently rewrite recipient rows.

Non-Goals For Campaign

Campaign should not become the global address book. It should not own:

• deduplication across campaigns
• consent lifecycle
• master-data merge policy
• address-directory permissions beyond campaign use
• postal address normalization
• reusable segmentation rules

Those belong in govoplan-addresses or a dedicated records/identity module when the domain needs stronger governance.