Oxicloud/doc/carddav-implementation-plan.md

28 - CardDAV Implementation Plan

CardDAV is an open protocol for syncing address books and contacts across applications and devices. This plan breaks the implementation into five phases over five weeks.

Implementation Roadmap

Phase 1: Core Infrastructure (Week 1)

Database Schema -- new migration for CardDAV tables:

• address_books -- stores address book collections
• contacts -- stores contact data
• address_book_shares -- sharing between users
• contact_groups -- organizing contacts into groups
• group_memberships -- associating contacts with groups

Domain Layer -- entity models:

• Contact -- core contact entity
• AddressBook -- collection entity
• ContactGroup -- grouping contacts

Repository interfaces:

• ContactRepository -- contact CRUD
• AddressBookRepository -- address book management
• ContactGroupRepository -- group management

Testing -- unit tests for entity models and repository interface contract tests.

Phase 2: Infrastructure Layer (Week 2)

Repository Implementations -- PostgreSQL:

• ContactPgRepository
• AddressBookPgRepository
• ContactGroupPgRepository

Also implement vCard parsing/generation utilities and any data migration tools needed.

Integration -- update DI system to include new repositories and connect with existing auth system.

Testing -- repository implementation tests, vCard parsing/generation tests, integration tests with the database.

Phase 3: Application Layer (Week 3)

Services -- business logic:

• ContactService -- contact management
• AddressBookService -- address book management
• ContactGroupService -- group management

DTOs and Ports -- create DTOs for contact operations, define service interface ports, implement request/response mapping.

CardDAV Adapter -- protocol translation adapter with vCard conversion logic and XML parsing/generation utilities.

Testing -- service unit tests and integration tests for the adapter.

Phase 4: Interface Layer (Week 4)

REST API -- endpoints for address book operations, contact management, contact groups. Document with OpenAPI.

CardDAV Protocol Endpoints -- WebDAV method handlers:

• PROPFIND -- discovery and property retrieval
• REPORT -- querying contacts
• MKCOL -- creating address books
• GET/PUT/DELETE -- contact operations
• CardDAV-specific XML handling

Integration -- connect all layers, end-to-end testing, test with various CardDAV clients.

Testing -- API endpoint tests, CardDAV protocol compliance tests, client compatibility tests.

Phase 5: Refinement and Optimization (Week 5)

Performance -- caching for frequently accessed resources, query optimization, efficient sync mechanisms.

Security -- review auth, validate I/O, add rate limiting.

Final Testing -- stress testing with large address books, security testing, user acceptance testing.

Documentation -- update API docs, user guides, client setup procedures.

Technical Specifications

Database Schema

-- Address books table
CREATE TABLE IF NOT EXISTS carddav.address_books (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    owner_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    description TEXT,
    color VARCHAR(50),
    is_public BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(owner_id, name)
);

-- Address book sharing
CREATE TABLE IF NOT EXISTS carddav.address_book_shares (
    address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
    user_id VARCHAR(36) NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    can_write BOOLEAN NOT NULL DEFAULT FALSE,
    PRIMARY KEY(address_book_id, user_id)
);

-- Contacts table
CREATE TABLE IF NOT EXISTS carddav.contacts (
    id UUID PRIMARY KEY,
    address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
    uid VARCHAR(255) NOT NULL,
    full_name VARCHAR(255),
    first_name VARCHAR(255),
    last_name VARCHAR(255),
    nickname VARCHAR(255),
    email JSONB,
    phone JSONB,
    address JSONB,
    organization VARCHAR(255),
    title VARCHAR(255),
    notes TEXT,
    photo_url TEXT,
    birthday DATE,
    anniversary DATE,
    vcard TEXT NOT NULL,
    etag VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(address_book_id, uid)
);

-- Contact groups
CREATE TABLE IF NOT EXISTS carddav.contact_groups (
    id UUID PRIMARY KEY,
    address_book_id UUID NOT NULL REFERENCES carddav.address_books(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);

-- Group memberships
CREATE TABLE IF NOT EXISTS carddav.group_memberships (
    group_id UUID NOT NULL REFERENCES carddav.contact_groups(id) ON DELETE CASCADE,
    contact_id UUID NOT NULL REFERENCES carddav.contacts(id) ON DELETE CASCADE,
    PRIMARY KEY(group_id, contact_id)
);

API Endpoints

REST API

Method	Endpoint	Description
GET	/api/address-books	List all address books
POST	/api/address-books	Create a new address book
GET	/api/address-books/:id	Get a specific address book
PUT	/api/address-books/:id	Update an address book
DELETE	/api/address-books/:id	Delete an address book
GET	/api/address-books/:id/contacts	List contacts in an address book
POST	/api/address-books/:id/contacts	Create a new contact
GET	/api/address-books/:id/contacts/:contactId	Get a specific contact
PUT	/api/address-books/:id/contacts/:contactId	Update a contact
DELETE	/api/address-books/:id/contacts/:contactId	Delete a contact

CardDAV Protocol Endpoints

Method	Endpoint	Description
PROPFIND	/carddav/	List all address books
PROPFIND	/carddav/:addressBookId/	Get address book information
REPORT	/carddav/:addressBookId/	Query contacts in an address book
GET	/carddav/:addressBookId/:contactId.vcf	Get a specific contact (vCard)
PUT	/carddav/:addressBookId/:contactId.vcf	Create or update a contact
DELETE	/carddav/:addressBookId/:contactId.vcf	Delete a contact

Dependencies

• vCard parsing/generation library (e.g., vcard-rs or similar)
• XML processing (for CardDAV protocol)
• Database access (PostgreSQL)
• WebDAV base functionality

Resources Required

• Developer time: 1 full-time developer for 5 weeks
• Testing resources: multiple CardDAV clients (Apple Contacts, Thunderbird, Android)
• Server resources: test environment with PostgreSQL

Success Criteria

1. Users can create, update, and delete address books
2. Contacts can be managed within address books
3. Address books can be shared between users
4. Standard CardDAV clients can sync with the server
5. Acceptable performance with large address books (1000+ contacts)
6. Security measures properly implemented

Client Setup Guides

After implementation, setup guides will be created for:

• Apple Contacts (macOS/iOS)
• Thunderbird/Evolution
• Android (using DAVx5)
• Other common CardDAV clients

See dav-client-setup.md for general DAV client configuration.

Future Enhancements

1. Advanced contact search
2. Contact merging for duplicate detection
3. Bulk import/export
4. Contact photo management
5. Extended fields for specialized contact info
6. Integration with external systems (e.g., LDAP directories)