User cache lifecycle

Role

User cache supports resolving user display fields (e.g. name, profile picture URL) for relatedUsers enrichment on maintenance (and other domains), without storing denormalized user data on domain rows.

DB: User references on maintenance_requests are IDs only (submittedBy, approvedBy, assignedBy, assignedTo).

---

Read path (active / open tasks)

1. Collect distinct user IDs needed for the request.

2. Resolve each via central user cache (implementation: Durable Objects / KV per platform architecture).

3. Use Promise.all (or batched reads) to resolve in parallel.

4. Build relatedUsers with:

   • id, name, role, type, profilePic
   • canViewProfile — computed server-side from viewer + target (see ../maintenance/permissions-matrix.md).

No email in relatedUsers (locked).

---

Closed tasks

For status ∈ { completed, cancelled, declined }, display authority for people and structure comes from finalSnapshot — not a live rebuild from user cache for the snapshot payload.

See ../maintenance/snapshot-behavior.md.

---

Staleness and invalidation

When a user updates display name or avatar:

• Cache entries for that user should be invalidated or refreshed so open tasks show current data on next read.
• Closed tasks are unaffected (snapshot is immutable).

---

Missing users

If a user ID does not resolve (deleted user, cache miss policy):

Use the structured fallback in ../maintenance/snapshot-behavior.md (isMissing, missingReason, etc.).

---

Related documentation

• maintenance.md — maintenance cache invalidation.
• ../maintenance/README.md — maintenance overview.