Event Flows

This page shows how Google-backed calendar events move end to end:

• from UI code
• through a :~google:...:events provider row endpoint
• through Lona server row handlers
• to Google Calendar
• and back into canonical provider-backed row cells

Canonical boundary

For one Google calendar, the canonical source row key is:

:~google:{authId}:calendar:{calendarId}:events

The canonical HTTP boundary for reads and writes is:

/api/rows/:~google:{authId}:calendar:{calendarId}:events/cells

That provider row owns event state. Aggregate rows such as calendar-list should read from constituent provider rows; they should not become second event owners.

Columns

The diagrams below use these columns:

UI         Browser UI / renderer / gesture
SDK        RowHandle / events facade / aggregate list row
Row API    /api/rows/:~google:{auth}:calendar:{cal}:events/cells
Server     row-key resolution + event row services
Google     Google Calendar API
Row Store  canonical provider-row cells stored by Lona

Google events read flow

This is the complete end-to-end path for fetching events from one Google calendar provider row.

UI            SDK            Row API         Server         Google         Row Store
│             │              │               │              │              │
│ request R   │              │               │              │              │
│────────────▶│              │               │              │              │
│             │ GET /cells   │               │              │              │
│             │ range=R      │               │              │              │
│             │─────────────▶│               │              │              │
│             │              │ resolve row   │              │              │
│             │              │──────────────▶│              │              │
│             │              │               │ read local   │              │
│             │              │               │ canonical    │─────────────▶│
│             │              │               │ cells        │              │
│             │              │               │◀─────────────│              │
│             │              │               │              │              │
│             │              │               │ if stale or  │              │
│             │              │               │ missing,     │              │
│             │              │               │ sync/fetch   │─────────────▶│
│             │              │               │ from Google  │              │
│             │              │               │◀─────────────│ events       │
│             │              │               │ normalize    │              │
│             │              │               │ and persist  │─────────────▶│
│             │              │               │ canonical    │              │
│             │              │               │ event.v1     │              │
│             │              │               │ cells        │              │
│             │              │ return cells  │              │              │
│             │              │◀──────────────│              │              │
│             │ decode       │               │              │              │
│             │ event.v1     │               │              │              │
│             │ rebuild      │               │              │              │
│             │ EventsIndex  │               │              │              │
│◀────────────│ results      │               │              │              │
│             │              │               │              │              │

Read notes

• The browser does not talk to Google directly.
• The browser always hits the provider row endpoint first.
• Google data becomes canonical only after the server normalizes it onto the provider row.
• The client-side index reads decoded row cells, not raw Google payloads.

Google events write flow

This is the complete end-to-end path for create, update, delete, move, or copy, as long as the target is a Google provider row.

UI            SDK            Row API         Server         Google         Row Store
│             │              │               │              │              │
│ mutate E    │              │               │              │              │
│────────────▶│              │               │              │              │
│             │ POST /cells  │               │              │              │
│             │ with event   │               │              │              │
│             │ mutation     │──────────────▶│              │              │
│             │              │ resolve row   │              │              │
│             │              │──────────────▶│              │              │
│             │              │               │ map row key  │              │
│             │              │               │ to authId +  │              │
│             │              │               │ calendarId   │              │
│             │              │               │              │              │
│             │              │               │ call Google  │─────────────▶│
│             │              │               │ create/patch │              │
│             │              │               │ /delete/move │              │
│             │              │               │◀─────────────│ canonical    │
│             │              │               │ event result │              │
│             │              │               │ normalize    │              │
│             │              │               │ and persist  │─────────────▶│
│             │              │               │ returned     │              │
│             │              │               │ event.v1     │              │
│             │              │               │ cells        │              │
│             │              │ return        │              │              │
│             │              │ affected      │              │              │
│             │              │ cells         │◀─────────────│              │
│             │ update local │               │              │              │
│             │ row data and │               │              │              │
│             │ source index │               │              │              │
│◀────────────│ rerender     │               │              │              │
│             │              │               │              │              │

Write notes

• The target of the write is the canonical provider row endpoint.
• Google is the source of truth for the mutation result.
• Lona becomes locally canonical again only after the returned event is written onto the provider row.

Aggregate list row read flow

This is the intended architecture for calendar-list-style reads.

UI            SDK aggregate   Provider row A   Provider row B   Provider row C
│             │               │                │                │
│ request R   │               │                │                │
│────────────▶│               │                │                │
│             │ resolve       │                │                │
│             │ constituents  │                │                │
│             │──────────────▶│                │                │
│             │───────────────┼───────────────▶│                │
│             │───────────────┼────────────────┼───────────────▶│
│             │ fetch R       │                │                │
│             │◀──────────────│ cells          │                │
│             │◀──────────────┼───────────────│ cells          │
│             │◀──────────────┼────────────────┼───────────────│ cells
│             │ union decoded │                │                │
│             │ results       │                │                │
│◀────────────│               │                │                │
│             │               │                │                │

The aggregate row should own:

• constituent-row discovery
• canonical handle reuse
• range hydration across constituent rows
• unioned reads

It should not own the underlying event cells.

Quick debugging checklist

• If one calendar is wrong, inspect the provider row path first: :~google:{authId}:calendar:{calendarId}:events
• If all aggregate views are wrong, inspect constituent-row resolution and aggregate reads.
• If writes reach Google but UI stays stale, inspect the provider-row rewrite path back into canonical event.v1 cells.

Related docs

• Events
• Calendars
• Row Keys
• Row Roles & Facades