Sync Repo-docs-ADDRESS-MODULE-ARCHITECTURE from project files
133
Repo-docs-ADDRESS-MODULE-ARCHITECTURE.-.md
Normal file
133
Repo-docs-ADDRESS-MODULE-ARCHITECTURE.-.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user