Calendar Architecture — Current State & the One-Writer Engine

Thesis. PropFlow writes to property calendars from four independent writers, each with its own (incomplete) retry, failure-recording, and teardown rules, over a raw Microsoft Graph client with no provider abstraction and a hardcoded Denver timezone header. No ADR was ever written for any of it — every load-bearing decision lives in PR bodies and file headers, and PR #4622's own header asks for this document to exist. The fix is one structural change: a single calendar engine that owns every event mutation — generic add/edit/delete over a provider interface — with every event type (tour, vendor visit, key pickup, inspection, and new standalone vendor scheduling events) as a thin spec on top.

1 · Current state — four writers, one raw client, no owner

1.1 The coverage matrix

Retry = wrapped in calendarSyncPolicy (3 attempts, backoff, breaker). DLQ = writes a CalendarSyncFailure row on exhaustion. Every cell marked ✗ is a place where a failed calendar write disappears silently.

1.2 The provider layer

• Raw Graph, no abstraction. Every writer imports createEvent/updateEvent/deleteEvent from outlook-client.ts directly. No interface, no dispatch, no registry.
• Hardcoded timezone. graphFetch sends Prefer: outlook.timezone="America/Denver" on every request, and the client defaults writes to Denver. The availability reader derives busy minutes from local getters on the returned wall-clock — correct only while every connected property is in Denver. Latent bug for the first non-Denver customer.
• Google Calendar is half-built and refused. OAuth connect/callback/status/disconnect routes and the onboarding UI all exist and will save provider:'google' onto a property — but zero Google event code exists. Until PR #4921 this leaked Google refresh tokens to graph.microsoft.com; the provider guard now fails safe (DLQ + page) instead. The seam exists in data and UI, just not in code.
• Token chokepoint is a convention, not a fence. getCalendarToken is documented as the single entry, but the inspection writer bypasses it and calls the token layer directly. No drift test pins the convention.

1.3 The reader and the one rule that must not drift

1.4 Failure handling is write-only

• CalendarSyncFailure rows are written by two writers — and nothing ever reads them. No sweeper, no reconciler, no healer. Recovery is a Sentry page and a human.
• No idempotency anywhere. No writer sends an idempotency key; several call sites are unawaited fire-and-forget; the id-stamp after create is a best-effort write whose failure is swallowed — a lost stamp orphans one event and creates a second.
• Phantom events are a recurring class, not an incident: Yale tour phantom (#3311, hand-deleted), 22 live events on cancelled Willows WOs, create-once inspections that survive a moved move-out date, and a documented known-gap where a cleared free-form schedule re-creates the mirror from stale structured fields.

1.5 How we got here (chronology in one breath)

2026-03: Outlook client + tour sync land in one commit, no ADR. 04: calendar becomes property-scoped; Google OAuth UI ships without a writer. 05–06: hardening era (slot-ID handshake, 429 fixes, a long tail of silent wrong-time bugs — am/pm mis-detects, a parser that turns unparseable input into 10:00 AM, still live in the tour path). 07-23: #4380 sets the projection doctrine (one-way, read-only, showAs:'free'). 07-26: #4622 adds the vendor mirror after a live-demo miss and explicitly requests this doc. 07-30: #4921 provider guard after the Google token leak. 07-31: #5177 CTO ruling — vendor visits never block tours, same-unit blocking removed. 08-08: #5547 key-pickup writer, third divergent sibling. Four writers, zero ADRs, decisions scattered across seven PR bodies.

2 · The proposal — one calendar writer

Ruling this encodes (Fede, 2026-08-08): there is ONE calendar writer. A single engine owns every calendar mutation for every event type, against a generic provider interface. Nothing else in the codebase may create, edit, or delete a calendar event. Vendor scheduling additionally becomes a standalone calendar event — no work-order or PO dependency: a vendor saying "Friday 10–12, fridge in 210" produces a calendar event, full stop.

2.1 Shape

2.2 What deliberately stays out of the engine

Availability, slot tokens, holds, and booking intent stay where they are — that's the tours booking spine, and it keeps working unchanged, calling the engine for its projection writes like everyone else. The engine is the calendar's hands, not its brain. If a unified booking-intent layer (applyEventIntent) is ever built, it sits above this engine; nothing here blocks or presupposes it.

2.3 Migration order — no event type ever has two writers

1. Engine + the new standalone vendor scheduled event (greenfield first client — no legacy writer to coexist with; immediately unblocks the vendor-scheduling ticket for calls, voicemails, and email).
2. Vendor-visit mirror (messiest legacy writer; its four call sites become engine calls; the reconciler adopts its DLQ rows and cleans the 22 orphans).
3. Key pickup (gains the update/delete verbs it's missing).
4. Move-out inspection (comes inside the fence, gains update/delete; phantom inspections end).
5. Tours last — a mechanical swap of its projection calls once the engine has proven itself on everything else. Tour booking logic untouched.

Each step is one PR, one event type, old writer deleted in the same PR — the two-writers-coexisting failure mode is banned by construction.

3 · Proving it — extreme testing on Willows + real Outlook

Verdict: extend, don't build. A real chassis exists: scripts/vendor-calling/demo-loop-harness.ts already does real Graph create → read-back → update-on-reschedule → verified delete on The Willows (appfolio-45, org_sandbox), with property guards, a test-marker discipline, and a reap leg that re-GETs the event to confirm deletion. The stress family (scripts/stress-common/) has the only sweeper that can find calendar events with no DB pointer. The prod-e2e harness contributes the fidelity-ledger discipline (real vs shim, INCONCLUSIVE fails) but never touches the calendar.

What must be added for extreme-volume permutation testing

1. A test discriminator on events — a dedicated category (e.g. PropFlow Test) stamped by the harness path, so sweepers can distinguish test events from real ones. Today's vendor-visit subjects carry no marker; orphans are unreachable by any tooling.
2. An id-based reconciling sweeper — list provider events, diff against anchors by event id (not subject substring), delete orphans. This doubles as the production reconciler's first implementation, tested at volume before it ever runs on a customer calendar.
3. Permutation coverage that exists nowhere today — update is exercised on exactly one path; never tested for real: null-window→delete, word slots ("Morning"), multi-day windows, the stale-structured-window trap (all three documented production breaks, proven only against mocks).
4. Concurrency legs — two writers racing one event id; the engine's idempotency key is exactly what's under test.
5. A write budget + notification gate — Graph throttles, and every current demo-loop run pages the PM twice (email + SMS); at volume that's the first thing to switch off.
6. Token-freshness pre-flight — refresh the Willows calendar token before the first write, so a long run can't end in a silent no-token teardown failure.

4 · Decisions

5 · What this unblocks

The vendor-scheduling ticket (Trello zGuMFnUI) collapses onto step 1: inbound calls, voicemails, and vendor emails all feed one pipeline — identify vendor, extract window, book a standalone vendor scheduled event through the engine (confident) or drop a review item (fuzzy). No work-order matching, no PO lookups. The Denver Water utility-outage case is just a normal event. The 12 dropped Camellia vendor calls replay cleanly against exactly this shape.

6 · PMS calendar: the property's own calendar as a provider Proposed — pending Fede's review · 2026-10-05

Update 5 Oct, evening: the Yardi calendar is now one capability of the Yardi browser agent (architecture, options, phases, refactor list). This section stays as the calendar-specific design.

Why now. ConAm will give PropFlow one Yardi user login for Yale 25 Station and nothing else: no mailbox, no Outlook or Google calendar, IT blocked personal calendars. Tours at Yale therefore have to live where the staff already look, the property calendar inside Yardi (Voyager 8, CRM IQ). This is a general need, not a ConAm one: every PMS has a showings calendar, and a customer who books in it today should not have to connect a second calendar to use Clara. The ask today is a design and a proof-of-concept plan, not a build.

What exists today

The abstraction Fede hoped for is already there. One CalendarProvider interface (create, update, delete, get, list events) with two adapters, Outlook and Google, chosen by a factory from a provider id stored on the calendar connection. Tours pick a calendar from an ordered pool: the leasing agents' own calendars first, then the building's calendar, else the company calendar. Availability reads every required calendar and unions the busy time; booking writes one event to one destination and pins that destination on the tour. A separate, flagged, write-only path mirrors Willows tours into AppFolio as showings through the browser robot. Nothing reads a PMS calendar. Yardi has no calendar code and only a prospect stub that does nothing yet.

Before and after

The design in five rules

1. A PMS calendar is a provider id, not a new kind of calendar. New ids appfolio and yardi join outlook and google in the provider list, the guard, the factory (with an explicit branch, no more "anything else is Outlook") and the connection row's provider field. The adapter implements the same interface; event times stay local wall-clock in the property's timezone; a read that cannot reach the PMS throws, it never returns "free".
2. It attaches at the building, from the PMS credential. Today the building level is a field on the property holding Outlook or Google tokens. The PMS calendar reuses the existing "store the secret once, point at it" credential row the AppFolio sync already uses, so connecting the PMS connects its calendar. No second login, no separate token refresh.
3. Its role is explicit, per property. Using the existing selection contract: busy source only (Clara never books into it, only avoids its showings), destination (Clara books into it), or mirror (Clara books elsewhere and copies the showing in). A property can hold several at once. A required busy source that cannot be read means no slots offered, as today.
4. One writer. The existing write-only AppFolio showing mirror folds into the adapter's create, update and delete. There is then exactly one place that writes a showing to a PMS, which is this page's thesis applied to the PMS.
5. Vendor ids stop at the adapter. The showing id, agent id and unit id from AppFolio or Yardi live on the tour's PMS stamp, as the AppFolio showing id does today. The tour engine never sees them.

Yardi, honestly

Questions for ConAm's Yardi admin, to ask with the user request: does the PropFlow user get CRM IQ calendar rights at Yale 25; does it see the property calendar or only its own; is a second factor or IP allowlist on logins; are tours booked as Appointment or Show. Questions for Yardi's account manager: does an imported Appointment event land on the CRM calendar and block the agent; can the interface read future appointments. The ask to Yardi is Fede's.

Proof of concept on AppFolio: the read half

Writing showings into AppFolio already works at the Willows. What is missing to make AppFolio a calendar source is the read. The proof of concept is: list the Willows showings through the robot, wrap that in the provider interface as a read-only adapter, and show Clara refusing a slot that an AppFolio showing already occupies. A live read-only recon of the AppFolio showings screens was attempted on 5 Oct and did not get in: the robot's one login attempt from the Mac did not land, so no screen or list endpoint was captured and the attempt was not retried (a second uncoordinated login on the shared identity risks the production session). What the robot code already proves without a live run: a showing is read one at a time at GET /api/showings/<id>.json with start, end, unit, status and assigned agent, and the showing id is the plain integer our own create returns, so matching our tours is a direct id match. The open question for rung 2 is only whether a list by property and date range exists; the recon re-runs from the Mac mini on the warm session.

Yardi then repeats rungs 2 to 5 with the CRM IQ screens behind the same adapter interface, once a Yardi login exists. Which calendar a building books into is already a per-building choice (the connection row), so no new switch is added: connecting the PMS calendar at a building is the turn-on, and that connection at a customer is Fede's call.

Sources: code map of src/lib/domain/calendar and the AppFolio showing writer at origin/main 6a43724 (5 Oct), the Google calendar onboarding handoff page, Gera's portfolio architecture page (attachments, resolver, ALIGN4), the Yardi SIPP swagger in the local skill, Yardi and vendor documentation read 5 Oct, Rachel Butler's email of 24 Sep, and Fede's report of the 1 Oct call.

Status: Proposed — pending Fede's review. Session c46c9bb9 (agents/010). Evidence: three sweeps over PropFlow-Technologies/propflowai — current-state (file:line cited), harness inventory, PR/ADR chronology — recorded in the session transcript. This doc supersedes nothing; it is the first written record of the calendar architecture (requested by PR #4622's header).