GovOPlaN Addresses

Repository type: module (domain).

govoplan-addresses is the reusable address and recipient-source module. It owns long-lived address directories and makes them available to campaigns, mail, forms, reporting, portal, and postbox modules through platform capabilities.

The campaign module may import campaign-local recipient tables, but reusable address management belongs here.

Current State

Milestone 1 is implemented. The module now owns persistent local address books and contact CRUD under /api/v1/addresses, contributes /address-book to the WebUI, and registers address permissions, role templates, database migrations, tenant summaries, and uninstall guards.

The first UI supports user, group, tenant, and system-scoped address books, multi-value contact methods, soft deletion, restore, read-only lookup/search, and vCard import/export for common contact fields. Imported vCards preserve source payload and revision metadata for later sync/conflict work.

The backend and WebUI also support classical address lists: reusable groupings of contacts or specific contact methods within one address book. Campaigns can import address books and address lists through the core-mediated addresses.recipient_source capability without importing address-module internals. Broader operational Verteiler with mixed users, identities, groups, functions, raw recipients, and nested lists belong in govoplan-dist-lists.

The backend now also contains connector-neutral sync infrastructure. Address books can be bound to external sources, sync attempts can record status, tokens, ETags, revisions, diagnostics, tombstones, and conflicts, and read-only or one-way-import sources make the owning address book read-only for normal write paths. CardDAV discovery, source binding, dry-run preview, inbound vCard sync, outbound create/update/delete for writable CardDAV sources, diagnostics, tombstones, conflict persistence, source disconnect/delete UX, and a first sync inspection UI are implemented. The conflict review UI compares stored local and remote field payloads, can apply a stored remote vCard payload, and supports manual per-field local/remote merge choices.

Boundary

govoplan-addresses owns:

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

It must not own:

• campaign-local recipient snapshots
• delivery queues or send attempts
• SMTP/IMAP transport
• file storage
• global identity authentication or RBAC evaluation
• operational distribution lists/Verteiler with mixed recipient types

First Capabilities

The module exposes three core-mediated capabilities:

• addresses.lookup: read-only contact/recipient lookup for autocomplete.
• addresses.recipient_source: immutable recipient snapshots for campaign, reporting, mail-build, forms, portal, and postbox workflows.
• addresses.contact_writer: address-book-scoped write decisions and contact creation for local or otherwise writable sources.

addresses.recipient_source returns:

• source id and display label
• normalized recipient rows
• email recipient fields
• source update marker
• provenance fields suitable for audit and campaign reports

Recipient sources currently include complete address books and classical address lists. Address-list source IDs use addresses:address_list:<id> and preserve the address-list entry ID in recipient provenance. Address-list entries may point at a whole contact, a concrete email address, or a concrete postal address. Email-oriented consumers snapshot email targets and whole-contact entries with a usable email address; postal-only entries remain valid list members for later postal/document workflows.

Consumers must store their own immutable snapshot when they need historical evidence. The addresses module remains the owner of the reusable source, not of the consumer's historical records. Consumers must resolve these capabilities through the platform registry and must not import address ORM/service internals.

addresses.contact_writer returns an explicit decision before a consumer shows or executes write actions: allowed/blocked, reason, user-facing message, required scopes, source kind, read-only state, and provenance. The decision is address-book specific; broader policy modules may later contribute to the same decision path, but consumers should not import or duplicate policy logic.

Design Documents

• Address module architecture
• Implementation plan