Table of Contents
Mirrored from
/mnt/DATA/git/govoplan-addresses/README.md. Origin:repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
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 also supports classical address lists: reusable groupings of
contacts or specific contact methods within one address book. Broader
operational Verteiler with mixed users, identities, groups, functions, raw
recipients, and nested lists belong in govoplan-dist-lists.
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/
Verteilerwith 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.
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.