Shared Calendar¶

A calendar a Circle shares. One thing they want to do — a meal, a film, a place, a link someone sent — is tracked from the moment it's mentioned until it's done.

Language¶

The people¶

Circle: The people who share one calendar, and the owner of everything in it. A Circle holds at most two Members for now; a person belongs to exactly one Circle, or to none. A Circle whose last Member goes is deleted, with everything in it. Avoid: team, household, workspace, account, tenant, couple

Member: A person who belongs to a Circle. Membership is what accepting an Invite creates and what a departure ends: Leaving, being Removed, or deleting the account. Not every person has one: someone Waiting has none yet, and someone who left has none any more. An Approved person with no Circle may start a new one, becoming its Host, or Accept an Invite. Avoid: user (that is the login), participant

Host: The Member who has been in their Circle longest. At first that's whoever founded it; when the Host goes, the role passes to whoever has now been there longest. The Host alone may Remove. Nothing else about the role differs: over Items, every Member is equal. Avoid: founder, owner, admin

Leave: A Member ending their own Membership. Always their own act; the Circle and its Items stay with whoever remains. Avoid: quit, exit

Remove: The Host ending another Member's Membership. Nobody else can remove anyone, and nobody can remove the Host. Avoid: kick, expel, ban

Approval: The decision, made by hand, whether a person who signed up at the front door is let in. A person's approval is Waiting, Approved or Rejected. Once Approved, always Approved: leaving a Circle doesn't undo it. Accepting an Invite approves the person it brings in. Avoid: activation, active/inactive, pending, status (that belongs to Items)

Waiting: Verified, and not yet decided. The only people in the approval queue. Avoid: pending, queued, applicant

Rejected: Turned away. The person is never told; to them it looks the same as Waiting. Avoid: banned, blocked, declined

Email address: What a person logs in with, and who they are to the app. A person has exactly one, and an address belongs to at most one person; capitalisation never makes two addresses different. An address is verified once its holder has proved they receive mail there — which is not the same as being let in. Anyone holding an address, verified or not, already has an account. Avoid: username, login, account

Held: Signed up while signup mail was at its limit (twenty sends in any 24 hours), so the mail that would verify the address hasn't been sent. The person is told they'll hear back; they stay unverified until the operator releases their mail by hand, or until they log in again once there's room. Not yet Waiting: that only follows verification. Avoid: queued, pending, throttled

Partner: The other Member of your Circle, from your side. A display term only: nothing in the app depends on there being exactly one. Avoid: spouse, co-owner

Invite: A Member's offer of their Circle's free seat to one Email address, good for seven days and used at most once. It is Pending until it is Accepted, Replaced by a newer Invite from the same Circle, or Expired. Nobody can invite an address that already belongs to a Member. Avoid: invitation, referral, revoke

Accept: The invitee taking up an Invite. One act verifies their Email address, Approves them, and makes them a Member of the inviting Circle; only the invited address can accept. Following the link is one way; the other is coming in at the front door with the invited address, where verifying it accepts the live Invite at login, and the operator never sees them. Avoid: redeem, claim, join

The thing itself¶

Item: One thing a Circle might do together. The only domain entity in the app; an Item belongs to exactly one Circle and carries a Kind, a Status, and optionally a date and time. Avoid: entry, activity, task, event (see below), bookmark

Kind: What sort of thing an Item is: meal, movie, place, or other. Purely descriptive — it never affects what an Item can do. Avoid: type, category, tag

Status: Where an Item has got to: Open, Scheduled, or Done. An Item has exactly one at a time. Avoid: state, stage

Open: An Item nobody has committed to a date yet. Open Items are what the wishlist shows. Avoid: pending, backlog, unscheduled, "want to"

Scheduled: An Item with a date and time attached. Scheduled Items are what the calendar shows. A Scheduled Item always has both a date and a time — never one without the other.

Done: An Item that has happened, or was marked finished by hand. Done Items appear on neither the wishlist nor the calendar. Avoid: completed, archived, closed

Deleted: An Item a Member has taken out of the app, reversibly. Not a Status but a lid over the Item: the Status underneath is untouched, so undoing a deletion returns the Item exactly as it was. Distinct from Done, which says the Item happened. Avoid: archived, removed, trashed

Added by: Who created an Item. Provenance, never permission: it says whose idea an Item was, and governs nothing — any Member may reword, delete, schedule or finish any Item in their Circle. When that person deletes their account, it reads "a former Member". Avoid: owner, author

The two views onto Items¶

Wishlist: The view of all Open Items, newest first, optionally narrowed to one Kind. Avoid: backlog, inbox, list

Calendar: The view of Scheduled Items dated today or later, in date and time order. Avoid: agenda, schedule (the noun), timeline

Event: Not a domain term. In this codebase "event" means an SSE message on a Circle's channel, nothing more. A thing on the calendar is a Scheduled Item. Avoid: using "event" for an Item. The events_page / event_quick_add URL names predate this glossary.

How Items move¶

Schedule: Giving an Open Item a date and time, moving it to Scheduled. Doing the same to an Item that already has a date is a reschedule.

Expire: The automatic move from Scheduled to Done once an Item's date is in the past. Nobody performs it; it happens on its own. Because nobody performs it, nobody is told: it is the only change to an Item that is neither broadcast nor pushed. The calendar hides past Items by date regardless, so expiry only keeps the stored Status honest (see docs/adr/0004). Avoid: lapse, auto-complete, sweep

Coming in from outside¶

Share intake: The path by which an Item arrives from another app on the phone, via the PWA share target, rather than being typed into the app. Avoid: import, capture, ingest

Share payload: The raw title / text / url an external app hands over. Not every payload yields an Item: one with no usable URL is rejected.

Item draft: An Item somebody means to add, before it exists: its Kind, title, note and link, read out of whatever they submitted — a sheet, or a Share payload — and cleaned. A draft is not stored and may yield no Item at all. Avoid: candidate, pending item, proto-item

Origin: Whether an Item was typed into the app or arrived through share intake. It changes what the other person is told, and nothing else — so it travels with the act of adding, and is never stored on the Item. Avoid: source, provenance

Telling the other person¶

Push subscription: One browser's or installed app's registration to receive push notifications. A person may have several: a laptop's browser, the installed web app and the iOS app on one phone are three. The iOS app's Push subscription ends with the login it was made under; a browser's outlives its login until it is removed. Avoid: device token, registration (as a noun of its own)

Fan-out: Sending a notification about an Item to every Push subscription belonging to a Member of that Item's Circle, except those of the Member who made the change. Nobody is notified about their own action; nobody outside the Circle is notified at all. Avoid: broadcast (that's the SSE refresh, which goes to every connected Member of the Circle, including the one who made the change)