Skip to content

When to call logUserActivity

ProjectActivitiesService.logUserActivity writes a lightweight audit line for the project activity feed (stored as action: USER_LOG with actor.log: verb + entity + optional metadata). The UI renders it like: “Alex updated shot · …”.

Use it when

  • A user-facing mutation should appear in the project / episode activity timeline (who did what, on which project asset).
  • You already have projectId on the document you loaded or wrote (story video, project row, etc.). Do not add an extra DB round-trip just to resolve projectId.
  • The change maps cleanly to a UserLogVerb + UserLogEntity (see sharedTypes.ts: UserLogVerb, UserLogEntity).
  • You want fire-and-forget logging: the method returns immediately; persistence runs on the next tick.

Typical call sites: model or service code that persists episodes, scenes, shots, assets, scripts, etc., where the product expects a human-readable audit trail per project.

Do not use it when

  • projectId is missing — the call is a no-op by design (avoids hidden lookups).
  • There is no authenticated actor and you did not pass actor — another no-op (e.g. unauthenticated cron); use logActivity / explicit flows if you need system attribution instead.
  • You need the rich activity row (job status, asset gen, lifecycle banners, Spine push by default) — use logActivity, logProjectLifecycleActivity, or logAssetGenJobActivityStatus as appropriate.
  • Workbench flows that already use WorkbenchService.createStoryActivity with a typed ProjectActivityAction — keep that path unless you are intentionally migrating a surface to the user-log shape.

Optional fields

  • storyId / sceneId / shotId — scope the log for deep links / filtering.
  • metadata — small structured hints (e.g. { field: 'description' }); keep it minimal.
  • actor — only when the acting user is not req.auth (rare).
  • publishToSpine: true — only if realtime fan-out is required; default is off because these logs can be high volume.
  • Implementation and contracts: projectActivities.service.ts (logUserActivity, LogUserActivityInput).
  • Verb/entity vocabulary: src/shared/sharedTypes.ts (USER_LOG, UserLogVerb, UserLogEntity).