govoplan-addresses/docs/IMPLEMENTATION_PLAN.md

GovOPlaN Addresses Implementation Plan

Milestone 1: Functional Local Address Books

Goal: make govoplan-addresses useful without external sync.

Primary issue: govoplan-addresses#3.

Status: implemented. The persistent backend, router, migration, permissions, role templates, lookup endpoint, restore support, multi-value contact editor, and first WebUI are in place.

Tasks:

• add backend tables and migrations for address books, contacts, contact methods, postal addresses, tags, and provenance
• add permissions and role templates for viewing and managing address books
• implement address-book CRUD API
• implement contact CRUD API
• implement scoped WebUI views for user, group, tenant, and system books
• support soft delete
• add restore API/UI for soft-deleted address books and contacts
• expose read-only contact lookup for the WebUI

Exit criteria:

• an admin can create tenant/system books
• a user can create a personal book and contacts
• address data survives restart and appears in the address-book UI
• disabled or read-only actions explain why they are unavailable

Milestone 2: vCard Foundation

Goal: make the model standards-based before adding sync.

Primary issue: govoplan-addresses#4.

Status: implemented. The module can import and export common vCard fields for local books, preserves imported raw vCard payload and revision metadata in first-class source fields, reports field/card import issues, and has round-trip and partial-import tests. Full two-way connector conflict resolution remains in the sync milestones.

Tasks:

• define vCard-compatible DTOs
• preserve original imported vCard data and normalized query fields
• import .vcf files into a selected address book
• export contacts/address books as vCard
• add validation for common vCard fields
• add tests for round-trip import/export of names, emails, phones, postal addresses, organization fields, notes, categories, and URLs
• add field/card validation messages for batch import
• promote original payload and revision handling into first-class contact source fields

Exit criteria:

• common vCard files can be imported and exported without losing core fields
• normalized search fields are populated during import
• invalid entries produce field-level actionable validation messages

Milestone 3: Core Capabilities

Goal: allow other modules to use addresses without dependencies.

Primary issue: govoplan-addresses#5.

Tasks:

• implement addresses.lookup
• implement addresses.recipient_source
• define immutable recipient snapshot DTOs
• expose source provenance in capability responses
• expose classical address lists as addresses.recipient_source sources
• add module presence/capability tests
• document consumer rules for campaign, mail, scheduling, portal, postbox, and reporting

Exit criteria:

• campaign can request a recipient source via core-mediated capability
• mail/scheduling can request autocomplete candidates via core-mediated lookup
• consumers do not import govoplan_addresses

Milestone 4: Campaign Integration

Goal: replace campaign-local reusable address concepts with address-module sources.

Primary issue: govoplan-campaign#55.

Tasks:

• add campaign recipient-source picker when addresses.recipient_source exists
• snapshot selected address-source rows into the campaign version
• store source ID, revision, and provenance in campaign evidence
• show stale-source warnings when an address source changed after selection
• keep campaign import for one-off local recipient data
• define classical address lists as reusable address-domain sources
• add address-list selection and management UI in addresses/campaign
• define segments/dynamic filters before exposing them as campaign sources Deferred deliberately: classical address lists are stable now; dynamic segments need their own filter model, stale-source semantics, and audit evidence before campaign can snapshot them safely.

Exit criteria:

• campaign works without addresses installed
• campaign offers address-source selection when addresses is installed
• built campaigns remain auditable after source contacts change

Milestone 5: Mail And Scheduling Integration

Goal: make contacts visible where users naturally need them.

Primary issues: govoplan-mail#13 and govoplan-scheduling#2.

Tasks:

• add mail recipient/autocomplete integration through addresses.lookup at API/capability level; visible compose UI reuse follows when mail compose exists
• expose addresses.contact_writer for explicit address-book write decisions, required scopes, read-only/source reasons, and provenance
• add "add sender/contact" actions in consuming UIs by using addresses.contact_writer
• add scheduling attendee/organizer lookup integration
• preserve module independence when addresses is absent

Exit criteria:

• mail and scheduling build without addresses installed
• when addresses is installed, lookup improves recipient/attendee entry
• address write decisions expose why actions are unavailable for read-only sources, deleted books, missing scopes, or unsupported operations
• consuming UI write actions are hidden or explained with the addresses.contact_writer decision payload

Milestone 6: Sync Infrastructure

Goal: prepare external address books without committing to all connectors at once.

Primary issue: govoplan-addresses#6.

Status: implemented for the first connector path. The connector-neutral backend substrate is in place: sync sources, source status, read-only propagation, tombstones, conflicts, diagnostics, attempt transitions, dry-run preview, audit-event emission, and a first sync inspection UI.

Tasks:

• add address-source connector configuration
• add sync state, ETags, revisions, tokens, tombstones, and conflict records
• add sync diagnostics
• add audit events for sync attempts, conflicts, previews, completions, and resolutions
• support read-only and writable source flags
• add dry-run and preview for connector changes
• add admin/user UI for source status, diagnostics, tombstones, and conflicts

Exit criteria:

• a connector can report planned creates/updates/deletes before applying them
• sync failures are visible in the UI
• conflicts are persisted and do not silently overwrite data

Milestone 7: CardDAV

Goal: implement the first real standards-based sync connector.

Primary issue: govoplan-addresses#7.

Status: implemented for the first standards-based sync path. Discovery, source binding, full/sync-token inbound sync, outbound create/update/delete for writable sources, dry-run preview, diagnostics, tombstones, and persisted conflict records are implemented. Source disconnect/delete UX and conflict review are implemented; stored remote vCard payloads can be applied from the review UI, and manual per-field local/remote merge choices are supported.

Tasks:

• add CardDAV account/address-book discovery
• sync vCard resources into scoped address books
• support read-only and writable source flags
• push local creates, updates, and deletes to writable CardDAV sources with ETag preconditions
• handle ETag changes, deletes, and conflicts
• add connection discovery and diagnostics
• add source disconnect/delete UX that keeps local contacts
• add conflict review UI with local/remote field comparison
• apply stored remote vCard payloads from conflict resolution
• support manual per-field local/remote merge choices for stored vCard payloads

Exit criteria:

• a CardDAV source can be connected, synced, and inspected
• CardDAV source disconnect/delete UI
• contacts can be refreshed without duplicating entries
• conflict and permission states are visible to the user
• outbound CardDAV writes for writable remote books
• field-level conflict review UI
• manual per-field merge editing

Milestone 8: Additional Connectors And Advanced Address Features

Goal: expand beyond CardDAV after the model and sync engine are stable.

Primary issues: govoplan-addresses#8, govoplan-addresses#9, govoplan-addresses#10, and govoplan-connectors#8.

Tasks:

• LDAP/Active Directory read-only directory connector
• Exchange/Microsoft 365 contacts connector
• Google Contacts connector
• CSV/XLSX/LDIF import mapping profiles
• classical address-list UI and static/dynamic address-domain segments
• operational distribution lists move to govoplan-dist-lists
• consent, legal-basis, suppression, and communication preferences
• deduplication and merge workflow
• address quality checks and normalization
• relationship/household/organization editing

Exit criteria:

• each connector or advanced feature can be enabled independently
• users can understand where data came from and whether they may edit it
• downstream modules can safely use contacts without owning them

First Implementation Recommendation

Start with Milestone 1 and enough of Milestone 2 to define the data model correctly. Do not start CardDAV before the local vCard-compatible storage and API are stable.