Sync Repo-docs-ADDRESS-MODULE-ARCHITECTURE from project files

Repo-docs-ADDRESS-MODULE-ARCHITECTURE.-.md

@@ -0,0 +1,133 @@
+<!-- codex-wiki-sync:df5d11314e74d6f5b0c0b43e -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-addresses/docs/ADDRESS_MODULE_ARCHITECTURE.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# GovOPlaN Addresses Module Architecture
+
+## Decision
+
+`govoplan-addresses` owns reusable contact and recipient-source data. Campaigns,
+mail, scheduling, portal, postbox, forms, reporting, and other modules consume
+address data through core-mediated capabilities and APIs, not by importing
+address-module internals.
+
+The implementation reference for contact data is vCard. CardDAV is the primary
+address-book sync protocol. LDAP/Active Directory, Exchange/Microsoft 365,
+Google Contacts, CSV/XLSX, LDIF, and batch vCard import/export are connector
+targets layered on top of the same local model and sync contracts.
+
+## Ownership
+
+`govoplan-addresses` owns:
+
+- scoped address books
+- contacts, organizations, households, and postal/email/phone address data
+- vCard import/export and vCard-compatible field mapping
+- reusable recipient sources and address lists
+- contact tags, categories, communication preferences, consent, and legal basis
+- deduplication, merge, address quality checks, and suppression lists
+- contact provenance, audit history, soft delete, and restore
+- external-source bindings, sync state, conflicts, and read-only source markers
+
+It does not own:
+
+- campaign-local recipient snapshots and evidence
+- mail transport, mailbox access, or delivery queues
+- calendar events or iCalendar event storage
+- global identity authentication or authorization decisions
+- organization structure or internal function assignments
+
+## Scopes
+
+Address books can live in these scopes:
+
+- `user`: personal address books and remembered contacts
+- `group`: team/shared address books
+- `tenant`: tenant-wide directories and approved shared lists
+- `system`: platform-wide public/shared directories where policy allows it
+
+The scope determines visibility, default permissions, sync credentials, and
+whether downstream modules may reuse or mutate entries.
+
+## Data Model Principles
+
+The canonical model should preserve enough vCard semantics to round-trip common
+fields:
+
+- name components and formatted names
+- nicknames and display names
+- email addresses, phone numbers, postal addresses, URLs, notes, categories
+- organizations, titles, roles, departments, and relationships
+- birthday/anniversary where allowed by policy
+- photos/avatars where storage and privacy policy allow them
+- calendar or scheduling addresses where present
+- source IDs, revisions, ETags, sync tokens, and provenance
+
+The model should support both normalized query fields and a preserved original
+representation for import/export and conflict handling.
+
+## Capabilities
+
+The first stable capabilities should be:
+
+- `addresses.recipientSource`: return immutable recipient snapshots for
+  campaigns, forms, reporting, and other send/build workflows.
+- `addresses.lookup`: provide read-only lookup and autocomplete for mail,
+  campaign, scheduling, postbox, portal, and case workflows.
+- `addresses.contactWriter`: create or update contacts where the caller has a
+  write permission and the target source is local or writable.
+
+Capabilities should use DTOs and source IDs. Consumers must not receive ORM
+objects or write address tables directly.
+
+## Sync Model
+
+Every synced address book should track:
+
+- connector type and external account/source
+- external address-book ID and display name
+- local address-book scope
+- sync direction: read-only, one-way import, one-way export, two-way
+- sync token, ETag/revision, last successful sync, last attempted sync
+- deleted markers/tombstones
+- conflict status and resolution decision
+- connector diagnostics and rate-limit/backoff state
+
+Sync conflict UX must show the local value, remote value, source, timestamp, and
+available action. Silent overwrite is not acceptable.
+
+## Connector Direction
+
+Implement connectors in this order:
+
+1. vCard import/export and batch import.
+2. CardDAV address books.
+3. LDAP/Active Directory read-only directories.
+4. Exchange/Microsoft 365 and Google Contacts.
+5. CSV/XLSX/LDIF import mapping profiles.
+
+Connector runtime behavior should reuse shared connector concepts where useful:
+configured endpoints, credentials, dry-run, diagnostics, rate limits, and audit
+events.
+
+## Cross-Module Integration
+
+Campaigns should consume `addresses.recipientSource` and freeze snapshots into
+campaign versions. Mail should consume `addresses.lookup` for autocomplete and
+"add contact" workflows. Scheduling should use lookup for attendees and
+organizers. Portal, postbox, cases, forms, and reporting should link to contact
+records by stable IDs while keeping their own domain evidence.
+
+## Deferred Work
+
+The following are valuable but not required for the first functional milestone:
+
+- automatic deduplication and merge suggestions
+- two-way sync conflict UI
+- Microsoft/Google connectors
+- household and relationship editing
+- advanced consent-policy automation
+- contact activity timeline across all modules