add-ideas/govoplan-addresses
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Repo-docs-ADDRESS-MODULE-ARCHITECTURE
Pages
Codex-Project-Index Codex Project Index Repo-README Repo README Repo-docs-ADDRESS-MODULE-ARCHITECTURE Repo docs ADDRESS MODULE ARCHITECTURE Repo-docs-IMPLEMENTATION-PLAN Repo docs IMPLEMENTATION PLAN
Clone
1
Repo-docs-ADDRESS-MODULE-ARCHITECTURE
zemion edited this page 2026-07-13 00:55:28 +02:00
Table of Contents

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