calendar-plugin/requirements/data.md

Data Requirements

Purpose

Define requirements for calendar data storage in WordPress and for local testing data behavior.

Scope

This document covers:

• Persistent plugin data in WordPress database
• Data model expectations for calendar entries and recurrence
• Data handling for local compatibility-harness testing

Normative Boundaries

• This document defines high-level data requirements and test-data expectations.
• Concrete schema fields, constraints, and indexing are defined in requirements/data_schema.md.
• Recurrence exception semantics are defined in requirements/recurrence_exceptions.md.
• Runtime/code separation constraints are defined in requirements/architecture.md.

Timezone Assumption

Unless explicitly overridden by a future requirement, all plugin dates and times are assumed to be in the Europe/London timezone.

WordPress Database Storage

Plugin data must be stored using WordPress-compatible database access patterns.

Requirements:

• Plugin-owned tables use WordPress table prefix conventions ($wpdb->prefix).
• Schema creation/migration uses WordPress APIs (see lifecycle requirements).
• Data access uses WordPress database APIs ($wpdb) with prepared/safe queries.
• Stored records support full CRUD and recurrence features required by editor/web UI.

Minimum Event Data Model

The stored model must support these fields (direct columns or normalized equivalents):

• Event identifier (internal primary key)
• visibility (public or private)
• title
• location
• category
• all_day_event flag
• start_datetime
• end_datetime
• repeat_type (none, daily, weekly, monthly, yearly, custom)
• Recurrence configuration (interval, range_mode, count, until_date, base unit)
• description
• Created/updated timestamps

Data Integrity Requirements

• title and start time/date must be required.
• End must not be before start.
• Recurrence values must be internally consistent (e.g., positive interval/count).
• Deletes must not leave orphaned recurrence metadata or exception records.
• Migrations must preserve existing user data.

Query and Retrieval Requirements

• Data model must support efficient retrieval by date range for day/week/month/year UI windows.
• Data model must support generation of recurrence occurrences for both web UI and ICS output.
• Queries for public UI must return only intended public event data.
• Queries for public UI/ICS/sidebar must include private events with privacy redaction (time/date shown, non-time content masked).

Local Testing Data Requirements

The local compatibility-harness test environment must support deterministic data setup and teardown.

Requirements:

• Provide seeded test data covering:
  • Single non-recurring events
  • All-day events
  • Each recurrence type
  • Custom recurrence with each range mode
  • Edge cases (month boundaries, leap year, DST transitions where relevant)
• Test runs must isolate state between cases (clean database state or controlled fixtures).
• Test data setup scripts/fixtures must be version-controlled under tests/ and/or compatibility-layer/.

Test Validation Data Requirements

Automated/local verification should include assertions for:

• CRUD persistence correctness
• Recurrence expansion correctness in 3-month preview windows
• Correct behavior of keep/remove data paths during uninstall
• Correct mapping readiness for ICS export fields

Backup and Recovery (Server Data)

• Production/test server data changes should be recoverable via normal backup processes.
• Destructive operations (e.g., uninstall data removal) require explicit intent and must be test-covered.

Documentation Requirements

Project docs must include:

• Current schema description
• Migration/versioning approach
• Local compatibility-harness usage
• Data retention behavior across install/upgrade/uninstall