# Architecture

## Components

### Web application

A server-rendered PHP application provides authentication, dashboards, source CRUD, event search, conflict review, settings, mirror-target management, system health, and manual operations.

### MariaDB

MariaDB stores source configuration, encrypted credentials, normalized event instances, event-change records, conflict state, mirror targets, queued notifications, audit records, system logs, and scheduler markers.

### ICS ingestion

The scheduler retrieves due HTTPS ICS feeds with size, timeout, redirect, and network-destination controls. It parses and expands recurring events into a configured rolling window, initially 30 days back and 365 days ahead.

Each source has its own refresh cadence. ETag and Last-Modified validators reduce unnecessary transfers, while a forced full retrieval at least once per configured period advances recurring-event windows even when source content has not changed.

### Conflict engine

The engine compares active event instances across enabled sources. It suppresses exact duplicate events and evaluates:

- Actual overlaps
- Tentative overlaps
- Awaiting-response overlaps
- Virtual meeting buffers
- In-person buffers
- Fixed travel buffers when normalized physical locations differ

Conflict fingerprints preserve a conflict's lifecycle across repeated scans. Conflicts resolve automatically when absent from a later complete scan.

### Notification engine

Alert producers add deduplicated messages to a MariaDB queue. A dispatcher delivers due messages through email or a generic HTTPS webhook. Quiet-hour handling occurs when notifications are queued.

### Busy-mirror API

Each mirror target has a separate bearer token and source-selection policy. The API returns only blocking events after applying source all-day, tentative, pending, deletion, status, and transparency rules.

### Google Apps Script bridge

A standalone script inside each destination Google account polls the private mirror API. It creates, updates, and deletes private Busy events through Google's Advanced Calendar service. Private extended properties establish ownership and prevent unmanaged-event changes.

## Data flow

1. Cron starts the scheduler once per minute.
2. Due ICS sources are fetched and parsed.
3. Normalized event instances are inserted or updated.
4. Missing instances inside the synchronized window are marked deleted only after a successful complete content parse.
5. Significant event changes are recorded.
6. The conflict engine scans the configured future window.
7. Alert and digest producers enqueue deduplicated notifications.
8. The notification dispatcher sends due messages.
9. Account-local Google bridges poll target-specific Busy feeds every five minutes.
10. Bridges reconcile only application-managed private events.

## Source and target distinction

A calendar source is read into Calendar Control Center. A mirror target is a destination account/calendar that receives Busy copies.

One Google account can own several source calendars. One mirror target can include several categories while excluding all sources belonging to that destination account.

## Failure behavior

A failed or HTTP 304 feed retrieval does not mark unseen events deleted. Deletion reconciliation runs only after a successful full body parse.

A source failure is isolated to that source. Other sources, conflict scans, digests, and queued notifications continue.

The scheduler uses a MariaDB advisory lock, so overlapping cron processes do not run concurrent synchronization and conflict passes.

Notification failures are retried and recorded. Mirror bridge failures remain isolated inside the destination Apps Script project and do not grant the VPS additional permissions.

## Future extension points

- Route-based travel calculations
- Password-protected request/approval booking workflows
- Additional notification adapters
- Native read-only Google Calendar incremental synchronization where policy permits
- Source groups and account-level policy templates
- CalDAV ingestion
- Mobile push application