# PlatPhorm Calendar Full Reference Service: platphorm-calendar Version: 1.0.0 Base URL: https://calendar.platphormnews.com API version: v1 ## Product Identity Calendar is the scheduling/event layer for PlatPhormNews. It lets humans and agents create, persist, organize, view, share, export, subscribe to, and act on events, milestones, reminders, sessions, tasks, reviews, launches, interviews, meetings, deadlines, releases, onboarding steps, coding sessions, and Kanban due dates. Calendar is when work happens: events, due dates, recurring jobs, automation windows, release gates, BrowserOps checks, Evals runs, Docs publishing cadences, and Kanban deadlines are represented as confirmable scheduling objects. ## Architecture - Framework: Next.js App Router - Language: TypeScript - Styling: Tailwind CSS and shadcn/ui - Persistence: Neon/Postgres when DATABASE_URL exists, browser IndexedDB for honest degraded local events ## Storage - Server persistence: Neon/Postgres through DATABASE_URL when configured and reachable. - Local degraded persistence: browser IndexedDB for non-sensitive local events and drafts when backend persistence or protected auth is unavailable. - Key policy: PLATPHORM_API_KEY is accepted only through Authorization bearer or X-PlatPhorm-API-Key headers and is not stored in browser persistence. - Durable platform workflow schema: scripts/003-calendar-platform-durability.sql defines event_revisions, calendar_reminders, calendar_imports, calendar_exports, automation_runs, calendar_handoffs, and handoff_receipts. Automation runs, handoff packets, and handoff receipts use database storage when DATABASE_URL is configured and required tables are present; otherwise they report runtime-local fallback or schema_missing honestly. ## Event Model Minimum event fields include id, uid, slug, title, description, location, startTime/endTime, allDay, timezone, status, visibility, source, sourceId/sourceUrl, recurrence, reminders, attendees, tags, traceId, storageMode, syncStatus, createdAt, updatedAt, and metadata. ## Shared WorkItem Model Calendar events can map to the shared WorkItem contract with id, title, description, status, priority, ownerLabel, tags, sourceService, sourceUrl, sourceArtifactId, optional kanbanCardId, optional calendarEventId, dueAt, startAt, completedAt, recurrenceRule, traceId, createdAt, and updatedAt. ## Canonical Object URLs - /calendars/{calendarIdOrSlug} - /events/{eventIdOrSlug} - /automations/{automationId} - /automations/{automationId}/runs - /automations/{automationId}/runs/{runId} - /handoffs/{handoffId} Confirmation endpoints return confirmed status, objectUrl, apiUrl, mcpResourceUri, updatedAt, traceId, warnings, and errors without fake success. ## Implemented API Routes - GET /api/health - GET /api/v1/health - GET /api/docs - GET /openapi.yaml - GET /openapi.json - GET /web/status - GET /api/web/status - GET /api/web/manifest - GET /api/web/scorecard - GET /graph.json - GET /calendar.graph.json - GET /api/v1/events - POST /api/v1/events - GET /api/v1/events/{id} - PUT /api/v1/events/{id} - DELETE /api/v1/events/{id} - PUT /api/v1/events/:id - DELETE /api/v1/events/:id - POST /api/v1/events/{id}/cancel - GET /api/v1/events/{id}/revisions - GET /api/v1/events/{id}/confirm - GET /api/v1/events/{id}/ics - GET /events/{id}.ics - GET /api/v1/events/{id}/google-link - GET /api/v1/events/{id}/outlook-link - GET /api/v1/events/{id}/trace - GET /api/v1/events/ics - GET /events.ics - GET /calendar.ics - GET /api/v1/calendars - POST /api/v1/calendars - GET /api/v1/calendars/{id} - PUT /api/v1/calendars/{id} - DELETE /api/v1/calendars/{id} - GET /api/v1/calendars/{id}/confirm - GET /api/v1/calendars/{id}/ics - GET /calendars/{id}.ics - GET /api/v1/calendars/{id}/feed - GET /webcal/{calendarId} - POST /api/v1/import/ics/preview - POST /api/v1/import/ics - POST /api/v1/import/preview - GET /api/v1/agenda/today - GET /api/v1/agenda/upcoming - GET /api/v1/agenda/range - GET /api/v1/automations - POST /api/v1/automations - GET /api/v1/automations/{id} - GET /api/v1/automations/{id}/confirm - GET /api/v1/automations/{id}/preview - POST /api/v1/automations/{id}/preview - POST /api/v1/automations/{id}/run - GET /api/v1/automations/{id}/runs - GET /api/v1/automations/{id}/runs/{runId} - POST /api/v1/handoff/{target} - GET /api/v1/handoffs/{id}/confirm - POST /api/v1/handoffs/{id}/confirm - GET /api/v1/reminders - POST /api/v1/reminders - GET /api/v1/reminders/{id} - PUT /api/v1/reminders/{id} - DELETE /api/v1/reminders/{id} - GET /api/v1/integrations/status - GET /api/v1/integrations/onboard/events - POST /api/v1/integrations/onboard/sync - GET /api/v1/integrations/jules/sessions - POST /api/v1/integrations/jules/sync - GET /api/v1/integrations/kanban/tasks - POST /api/v1/integrations/kanban/tasks - POST /api/v1/integrations/kanban/sync - GET /api/mcp - POST /api/mcp ## Discovery Routes - GET /llms.txt - GET /llms-full.txt - GET /llms-index.json - GET /robots.txt - GET /sitemap.xml - GET /sitemap-index.xml - GET /rss.xml - GET /feed.xml - GET /manifest.webmanifest - GET /.well-known/mcp.json - GET /.well-known/agents.json - GET /.well-known/ai-plugin.json - GET /.well-known/web.json - GET /.well-known/web4.json as compatibility alias only - GET /.well-known/agent-policy.json - GET /.well-known/ai-policy.json - GET /.well-known/security.txt - GET /.well-known/trust.json - GET /.well-known/provenance.json ## iCalendar, Google, Outlook - ICS event and feed export are implemented with stable UIDs and CRLF output. - ICS import preview parses VEVENT, UID, DTSTART, DTEND, SUMMARY, DESCRIPTION, LOCATION, RRULE, STATUS, CATEGORIES, all-day dates, and TZID metadata where present. - Webcal subscription URLs map to stable public-safe ICS feeds without a CalDAV claim. - Google Calendar support is public add-link generation. - Outlook/iCalendar support is .ics export and webcal-compatible feed URLs. - Direct Google API insertion and direct Outlook API sync are not claimed. ## Web Status - Canonical name: Web Status - Schema: web.status.v1 - Routes: /web/status and /api/web/status - Source-backed counts come from reachable server storage and configured automation templates; missing database state is reported as local_browser_or_public_server, not fake server success. ## Automations Configured schedule templates expose daily SearchOps crawl, weekly Evals release gate, BrowserOps smoke check, and monthly TrustOps review schedules. Preview has no side effects. Run requires PLATPHORM_API_KEY, uses idempotency keys, persists to automation_runs when database storage is schema-ready, and reports protected downstream actions as degraded unless confirmed by protected downstream receipt. ## Integrations - Onboard: https://onboard.platphormnews.com; protected item-to-event import, degraded feed status when upstream is unavailable. - Jules: https://jules.platphormnews.com; protected session-to-event import, degraded sessions list until a canonical sessions feed is available. - Kanban: https://kanban.platphormnews.com; protected event-to-task sync and task due-date import. - Jobs: https://jobs.platphormnews.com; existing deadline/interview import and sync support is preserved. - MCP: https://mcp.platphormnews.com; Calendar exposes JSON-RPC MCP at /api/mcp. - Trace: https://trace.platphormnews.com; safe spans for event CRUD, view loads, reminders, ICS, add-link generation, and integrations. - Docs: https://docs.platphormnews.com; agenda publishing handoff packets require protected downstream receipts. - Evals: https://evals.platphormnews.com; release-gate schedule packets require protected downstream receipts. - BrowserOps: https://browserops.platphormnews.com; browser journey packets require protected downstream receipts for screenshots or run artifacts. - Claws: https://claws.platphormnews.com; remediation packets require protected downstream receipts. - Sheets: https://sheets.platphormnews.com; structured report packets require protected downstream receipts. - Decks, Webhooks, Sandbox, AgentUI, Monitor, and Atlas remain integrations, not Calendar's product identity. - Handoff target execution is never reported as complete until POST /api/v1/handoffs/{id}/confirm receives PLATPHORM_API_KEY and a trusted result URL or artifact id for confirmed/completed statuses. ## Public/Protected Boundary Public: app shell, public-safe event reads, public ICS/feed/sitemap/discovery, health summaries, read-only MCP introspection. Protected: server event mutations, private calendars, private attendee/reminder mutations, Onboard/Jules/Kanban sync, webhooks, reports, and MCP tool execution. ## Known Degraded Areas - Event revision, reminder, and import/export audit tables are defined; their runtime handlers still need full audit writes. - Recurrence accepts stored rules but full recurrence expansion is not implemented in the UI. - Automation run history, handoff packets, and receipt history are durable when DATABASE_URL is configured and required tables are present; otherwise they are explicitly runtime-local or schema_missing. - Handoff routes create confirmable Calendar packets. Target receipts can be accepted, failed, confirmed, or completed; confirmed/completed receipts require trusted result evidence. Optional HMAC receipt signatures are supported through X-PlatPhorm-Receipt-Signature. - Live route and observability scores are not computed locally; health reports that as degraded instead of a fake score.