(Awaiting Approval) Understanding the Architecture

This article provides a high-level understanding of the application's architecture, its internal synchronization engine, and its deployment topologies.

Architecture & Protocol Translation

At its core, the connector acts as a bidirectional protocol translator. Nextcloud natively relies on open standards — CalDAV for calendars and tasks, and CardDAV for contacts. In contrast, Microsoft Exchange utilizes its proprietary Exchange Web Services (EWS) or the Microsoft Graph API.

The synchronization ecosystem is divided into two distinct components to handle this translation:

1. The Nextcloud App (Frontend): A lightweight Nextcloud application that provides the User Consent UI and exposes dedicated API endpoints. It serves as the gateway to Nextcloud's internal CalDAV/CardDAV database backend.

2. The Connector Daemon (Backend): A .NET 8 worker service that runs entirely independently of the Nextcloud web server. It fetches EWS payloads from Microsoft, maps the data properties into standard CalDAV (V-Calendar) and CardDAV (V-Card) formats, and pushes them to the Nextcloud App API (and vice versa).

This decoupled architecture ensures that heavy synchronization loads and payload translations do not impact Nextcloud's web performance.

Authentication & Security Model

The connector employs a dual-authentication strategy:

• Nextcloud Side: The worker authenticates against the Nextcloud API using a dedicated service account and an App Password. All webhook and API communication between the Nextcloud frontend and the worker is cryptographically secured using a pre-configured SharedSecret.

• Exchange Side: The application operates as a background daemon using Microsoft's delegated access models.

  • For On-Premise environments (Exchange 2016/2019), it uses ApplicationImpersonation via Kerberos or Basic Authentication.

  • For Microsoft 365 (Cloud), it uses OAuth 2.0 app-only authentication with the full_access_as_app permission. This allows the system to read and write to user mailboxes based strictly on their backend identifiers.

The Synchronization Engine & Throttling

The core of the daemon is governed by configurable polling intervals (SyncIntervalInSeconds and CriticalSyncIntervalInSeconds). The engine fetches user states, processes them in manageable batches (BatchLimit, BatchSaveSize), and executes the payload mapping between EWS and CalDAV/CardDAV.

Historically, using a single service account created a severe bottleneck, as Microsoft Exchange heavily throttles concurrent Exchange Web Services (EWS) connections per identity. To resolve this, the new architecture introduces a Connection Pool powered by an external JSON configuration file.

By defining an array of service accounts in the admins.json file, the worker dynamically distributes EWS sessions across multiple administrator identities. This multiplies the available throughput, which can be fine-tuned using the MaxParallelProcessingUsers and MaxUsersPerAdmin parameters.

[
  {
    "ExchangeType": 2,
    "Username": "sync-admin-1",
    "Password": "PasswordA!"
  },
  {
    "ExchangeType": 2,
    "Username": "sync-admin-2",
    "Password": "PasswordB!"
  }
]

Sync Modes & Bitwise Configuration

Administrators control exactly which CalDAV/CardDAV objects flow through the connector using bitwise masks in the .env file. The Service__SyncMode parameter calculates the active features by summing the following base values:

• 0 = None

• 1 = Calendars (CalDAV)

• 2 = Contacts (CardDAV)

• 4 = Tasks (CalDAV)

To synchronize both Calendars and Contacts, the administrator sets the value to 3 (1 + 2).

Additionally, the Service__SyncType parameter dictates the data privacy level:

• 0 (Full): Synchronizes all event details (Titles, Descriptions, Attendees).

• 1 (Sensitive): Masks all private event details, synchronizing only the time block with a placeholder title (configurable via SensitiveTitle, usually "Busy").

# Example: Synchronizing Calendars and Contacts in Sensitive Mode
Service__SyncMode=3
Service__SyncType=1
Service__SensitiveSyncConfiguration__SensitiveTitle="Busy"

Deployment Topologies

The .NET 8 microservice is designed to be highly versatile and supports two primary deployment topologies:

1. Containerized (Docker): The preferred method for scalable environments. Using docker-compose, administrators can easily spin up the application alongside its database (PostgreSQL) and logging stack (Grafana/Loki). The variable Secondary_Replicas_Amount allows Docker to auto-scale multiple worker containers that share the load via the common database.

2. Binary Installation: For environments that do not support containerization, the pre-compiled .NET binaries can be executed directly on the host OS. This allows the application to be managed via systemd on Linux or as a standard Windows Service.

Next Step

Configuring Microsoft 365 (Cloud) OR Configuring Exchange On-Premise