Activity · Concepts

Activity concepts

Activity materializes product activity into timelines. Your host supplies tenant and actor identity, business meaning, and policy. Activity stores the reusable feed primitives and their derived read state.

Host product event
  └─ Post
      ├─ TimelineEntry
      ├─ Engagement
      └─ derived PostStats

Tenant and actor

Every resource carries a tenant_id. Activity applies tenant filters to its resources and never infers how a tenant maps to an account, organization, or product instance.

An actor_id is the host-owned identifier for the caller. The host authenticates the user and decides which actor it may represent before signing an Activity request.

Post

A post is the source record for one piece of activity. Its public fields include:

Field	Purpose
actor_id	Host-owned author identity from the signed request
verb	Activity type such as posted, matched, announced, or shared
object_ref	Structured reference to the host object
body	Optional display text
metadata	Product-specific structured data
render_refs	Minimal references for mentions, media, and links
visibility	public, followers, or private

Activity stores references. It does not resolve host identity, process media, or decide how a host object should render.

Follow edge

A follow edge connects the calling actor to another actor inside one tenant. Its state is active, muted, or blocked.

The graph controls Activity’s materialized feed behavior. It is not a business permission system. The host still decides whether a user may perform the corresponding product action.

Timeline entry

A timeline entry projects a post into one viewer’s home timeline. It records:

• viewer_id, the actor receiving the entry
• post_id, the projected source post
• reason, one of self, following, or repost
• ranked_at, the ordering timestamp for the materialized timeline

The pair of viewer and post is unique. Retried fan-out work converges on one timeline entry.

Engagement and statistics

Engagement records likes, reposts, and shares. The combination of post, actor, and engagement kind is unique.

PostStats is a derived, eventually consistent projection. Its counters are useful for rendering, but they are not the canonical engagement records.

Ownership boundary

Activity owns posts, follow edges, timeline materialization, engagement primitives, and post visibility enforcement exposed by its contract.

The host owns user authentication, business authorization, object truth, ranking policy outside the contract, and product rendering. Activity never calls the host application API.

Next: sign an Activity request.