Documentation source
Documentation source
Documentation source
Personalized entity feed with configurable sorting, filtering, card and compact views, for-you personalization, activity enrichment, digest summarization, and block integration.
## Overview
The feed system provides a personalized, ranked view of entities across all types in a tenant. It serves as the central discovery surface -- users see what matters most to them, ranked by recency, relevance, importance, or personalized scoring. Each feed item carries explainability: reasons why it was surfaced (high importance, recently updated, agent activity, etc.).
The feed has evolved through two versions: v1 provides basic entity listing with sorting and filtering; v2 enriches items with recent activity context, actor information, and raw entity data for card rendering. Both versions are available through the resolver, with v2 powering the current UI.
The feed also functions as a block type (`entity-feed`), enabling it to be embedded in dashboards, workspace views, and entity detail pages alongside other blocks.
## Key Concepts
### Feed Tabs
```typescript
const FEED_TABS = ["for-you", "new", "updated", "gallery"] as const;
```
- **for-you** -- Personalized ranking based on the user's ownership, interaction history, and preferred entity types.
- **new** -- Sorted by creation date, showing the most recently created entities.
- **updated** -- Sorted by last update time, showing entities with the most recent changes.
- **gallery** -- Visual grid layout emphasizing entity images and card presentation.
Tab labels are mapped via `FEED_TAB_LABELS`:
```typescript
const FEED_TAB_LABELS: Record<FeedTab, string> = {
"for-you": "For You",
new: "New",
updated: "Updated",
gallery: "Gallery",
};
```
Each tab renders a leading icon (`FEED_TAB_ICONS` in `app/(app)/feed/feed-client.tsx`
-- heart, sparkles, refresh, grid). The icon map lives in the client component,
not `types.ts`, so the shared feed types module stays free of client-only icon
imports.
### Feed Cards
Stream tabs (For You / New / Updated) render `FeedItemCard`: activity context
(actor, verb, record type, relative time) composed around `EntityCardBody`,
which resolves the per-entity-type card tier (tenant custom -> cardConfig ->
schema default). Records with a cover image show it as Twitter-style inset
media. The Gallery tab renders `FeedGalleryCard`: the full `EntityCard`
(cover image, avatar, custom body) wrapped with the same stretched-link
chrome. Both card kinds share `FeedEngagementFooter` -- bookmark
(`FavoriteButton`), heart (`LikeButton`), and comment count -- so engagement
actions are available on every feed surface, and both apply
`curateFeedCardProps` field hygiene (configured fields only, empty values
stripped before they can render as placeholder dashes).
Stream cards visually de-duplicate tags (and For You reason chips) carried by at
least 80% of a loaded page. Each page states those values once in a lead-in before
its first card; sentence reasons use "Everything here:" or "Most cards here:"
framing, while hoisted tags remain semantic links to the same `/feed?tags=` filter
target as their per-card control. Verdicts are page-local so an appended
infinite-scroll page never changes the height of earlier cards. Gallery does not
participate because `FeedGalleryCard` does not suppress those values.
#### Import the card files directly, never the `entity-card` barrel
Gallery is one of four tabs and the only one rendering the full `EntityCard`,
so `feed-client.tsx` loads `FeedGalleryCard` through `next/dynamic` to keep it
out of the three stream tabs' bundle. That deferral only works if nothing
eagerly reachable from `/feed` imports the barrel:
`@/features/entities/components/entity-card` re-exports `EntityCard` alongside
`EntityCardBody`, so a single barrel import from `feed-item-card.tsx` drags the
gallery card straight back into the eager route graph and the `dynamic()`
defers nothing.
Both halves are load-bearing -- `feed-item-card.tsx` deep-imports
`entity-card/entity-card-body`, `feed-gallery-card.tsx` deep-imports
`entity-card/entity-card` -- and `feed-client.lazy.test.ts` enforces both. This
is not hypothetical: the contract was silently hollow until the 2026-07-30
promotion review, because the original test asserted only the `dynamic()`
wrapper and never the barrel.
### Sort Options
```typescript
const FEED_SORT_OPTIONS = ["recency", "relevance", "importance", "updated"] as const;
```
- **recency** -- Sort by `created_at` descending.
- **relevance** -- Sort by `relevanceScore` descending (from entity metadata), with recency as tiebreaker.
- **importance** -- Sort by `importanceScore` descending (from entity metadata), with recency as tiebreaker.
- **updated** -- Sort by `updated_at` descending.
### Show Modes
```typescript
const FEED_SHOW_MODES = ["cards", "compact"] as const;
```
- **cards** -- Full entity cards with preview fields, tags, scores, and activity context. Uses the entity type's card configuration for rendering.
- **compact** -- Condensed list items showing title, type, and key metadata. Higher information density for scanning.
### Time Ranges
```typescript
const FEED_TIME_RANGES = ["today", "week", "month", "all"] as const;
```
Time ranges filter entities based on the active sort column (created_at for "new" tab, updated_at for "updated" tab).
### URL Query Codec
`features/feed/lib/feed-url-state.ts` is the shared boundary between feed URL
state and server-side `FeedConfig`. The feed hook uses it to keep the current
route shareable, and `GET /api/feed` uses it to resolve the same filtered,
sorted feed from URL search parameters.
The codec supports `tab`, `types`, `agents`, `time`, `q`, `tags`, `sort`,
`mode`, `limit`, `importance`, and `relevance`. Empty client state serializes
to no query string; invalid values are ignored or defaulted before reaching the
resolver.
### Feed Configuration
The `FeedConfig` schema (validated with Zod) controls all aspects of the feed:
```typescript
interface FeedConfig {
entityTypeSlugs?: string[]; // Filter to specific types
parentEntityId?: string; // Scope to children of an entity
sortBy?: FeedSortBy; // recency, relevance, importance, updated
showMode?: FeedShowMode; // cards or compact
limit?: number; // Max items (default: 20)
tags?: string[]; // Tag filter (entities with any of these tags)
minImportance?: number; // Score threshold (0-10)
minRelevance?: number; // Score threshold (0-10)
tab?: FeedTab; // Active tab
agentSlugs?: string[]; // Filter to entities updated by specific agents
timeRange?: FeedTimeRange; // today, week, month, all
offset?: number; // Pagination offset (default: 0)
search?: string; // Text search on title/description
}
```
### Feed Items
Each feed item represents an entity surfaced in the feed:
```typescript
interface FeedItem {
id: string;
entityId: string;
title: string;
description: string | null;
entityTypeSlug: string;
entityTypeName: string | null;
href: string; // Link to entity detail page
fields: Array<{ label: string; value: string }>; // Preview fields
tags: string[];
score: number | null; // Weighted scoring system score
importanceScore: number | null; // From metadata (0-10)
relevanceScore: number | null; // From metadata (0-10)
reasons: FeedItemReason[]; // Why this item was surfaced
updatedAt: string;
createdAt: string;
lastAgentSlug: string | null; // Agent that last modified this entity
}
```
### Feed Item Reasons (Explainability)
Every feed item carries reasons explaining why it was surfaced:
```typescript
interface FeedItemReason {
type:
| "high_importance" // importanceScore >= 7
| "high_relevance" // relevanceScore >= 7
| "recently_updated" // Updated in the last 24 hours
| "recently_created" // Created in the last 24 hours
| "matched_tag" // Matched a tag filter
| "matched_filter" // Matched another filter
| "agent_updated" // Updated by an AI agent
| "owned_by_you" // Viewer owns this record
| "recent_interaction" // Viewer worked on this record
| "preferred_type"; // One of the viewer's most-used record types
label: string; // Human-readable explanation
}
```
Reasons are derived from item metadata by `deriveReasons()` when not pre-populated. The thresholds are configurable constants: importance >= 7, relevance >= 7, created/updated within 24 hours.
### Feed V2 Items (Activity-Enriched)
The v2 feed extends items with activity context:
```typescript
interface FeedItemV2 extends FeedItem {
recentActivity: FeedActivityItem[]; // Last N activity entries
lastActor: FeedActor | null; // Who last touched this entity
activityCount: number; // Total activity entries
entityData: FeedEntityData; // Raw entity data for card rendering
entityTypeData: FeedEntityTypeData; // Raw type data for card rendering
}
```
Activity items include the action, actor name and type (user or agent), agent slug and icon, description, and timestamp. The `lastActor` field provides quick attribution -- who last modified this entity and whether it was a human or agent.
### Feed Digest
The digest provides a high-level summary for the feed header:
```typescript
interface FeedDigest {
stats: {
updatedToday: number;
createdToday: number;
workflowsCompleted: number;
pendingReviews: number;
};
topAgents: FeedDigestAgent[]; // Most active agents
needsAttention: FeedDigestAttentionItem[]; // Items requiring human action
aiSummaries?: string[]; // AI-generated summaries
}
```
Attention items highlight entities with pending responses awaiting review or sessions/actions waiting on human input.
## How It Works
### Feed Resolution (V2)
The `resolveFeedV2()` function is the primary resolver:
1. **Parse config** -- Validate the raw config against `FeedConfigSchema`. Invalid configs silently fall back to defaults.
2. **Build entity query** -- Start with tenant-scoped entities, then apply filters:
- `entityTypeSlugs` filters via `entity_type_slug` (denormalized column).
- `parentEntityId` filters via `parent_id`.
- `tags` uses the PostgreSQL `overlaps` operator on the tags array.
- `search` performs case-insensitive matching on title and description.
- `timeRange` filters the sort column (created_at or updated_at) to the range start.
- Tab-specific sorting: each tab maps to a sort column via `getTabSortColumn()`.
3. **Fetch data** -- Entity query and agent list execute in parallel for performance.
4. **Convert to feed items** -- Each entity row is mapped to a `FeedItem` via `rowToFeedItem()`, which extracts preview fields, scores (from entity metadata), and builds the entity detail link.
5. **Apply score filters** -- Items below `minImportance` or `minRelevance` thresholds are removed.
6. **Fetch activities** -- Recent activities for all returned entity IDs are fetched in a single query (limited to avoid excessive data). Activities are grouped by entity.
7. **Agent slug filter** -- If `agentSlugs` are specified, filter items to only those with recent activity from the specified agents. This checks the `agent_slug` field in activity metadata.
8. **Resolve actors** -- User profiles for activity actors are fetched in parallel to populate display names.
9. **Rank items** -- The ranking step depends on the tab:
- **for-you**: `loadForYouContext()` queries user ownership and interaction history, then pure scoring and `rankForYou()` sort the candidate pool.
- **Other tabs**: `rankFeedItems()` sorts by the selected sort comparator.
10. **Enrich with V2 data** -- Each ranked item is augmented with recent activity entries, last actor info, activity count, and raw entity/type data for card rendering.
### For-You Personalization
The "for-you" tab uses a seven-term scoring model. `nowMs` is captured once
per resolution and injected into the pure scoring and ranking functions, so a
request is deterministic.
1. **Fetch user context** -- In parallel, query:
- User's owned entities (`entities.owner_id = userId`).
- User's recent activities (last 30 days, up to 200 entries).
2. **Build preference signals** -- From the activity history:
- `ownedEntityIds` -- Entities the user owns (score: +3).
- `interactedEntityIds` -- Entities the user has interacted with (score: +2).
- `preferredTypeSlugs` -- Top 3 entity types by interaction count (score: +1).
3. **Compute scores** -- `computeScores()` applies these terms:
| Signal | Weight | Decay / details |
| ----------------------------- | -----: | --------------------------------------------------------------------------------------------------------- |
| Owned by the viewer | 3 | No decay |
| Interacted with by the viewer | 2 | Activity context covers the last 30 days |
| Preferred record type | 1 | The viewer's top three types by interaction count |
| Quality | 2 | `((importanceScore ?? 0) + (relevanceScore ?? 0)) / 20`; a pair of 10/10 scores contributes 2 |
| Creation recency | 2 | Exponential decay with a 7-day half-life |
| Distinct update recency | 1.5 | Exponential decay with a 3-day half-life; applies only when update is more than 60 seconds after creation |
| Agent touch | 0.75 | Exponential decay from `updatedAt` with a 3-day half-life; requires `lastAgentSlug` |
Engagement counts and favorites are deliberately excluded from the v1
personalization signal model. User signals lead among similarly aged records,
while the ambient signals can surface fresh, important, actively worked data
above stale ownership.
4. **Rank, then slice** -- The default authenticated For You tab fetches up to
500 candidates in exactly one `range(0, 499)` request, ranks the pool, then
slices it by `offset` and `limit`. `hasMore` becomes false when the next
offset reaches the ranked pool, so infinite scrolling naturally ends at the
500-record cap.
For You with an `agentSlugs` filter intentionally retains single-page
fetching and personalizes only within that page. Widening that path would
require pool-wide activity loading or a separate filter-path restructure.
The scoring function is pure (no database access) and fully testable.
`loadForYouContext()` is the authenticated, tenant-scoped database boundary and
returns plain serializable arrays. `FeedResultV2.personalized` is set only for
For You: `true` means at least one item on the resolved candidate set matched a
user-specific ownership, interaction, or preferred-type signal; `false` means
none did (including anonymous fallthrough); other tabs leave it undefined. The
flag describes page 1's result set, and the client deliberately reads
`pages[0].personalized` only.
When a tenant has no user signals, quality, distinct updates, or agent touches,
creation decay produces an order approximately equal to New. The feed states
this honestly above a non-empty result: "Not personalized yet — ranked by
recent activity. This tab learns from the records you create and edit."
### Ranking and Explainability
The `rankFeedItems()` function sorts items and attaches reasons:
```typescript
function rankFeedItems(items: FeedItem[], sortBy: FeedSortBy): FeedItem[];
```
Each comparator handles ties: importance and relevance comparators fall back to
recency. For You adds an entity-ID-descending final tiebreak after score and
creation time, matching the SQL order and making pooled pagination a total
order.
After sorting, `deriveReasons()` generates explanation labels for items that do not already have reasons. Reasons are computed from the item's metadata:
- `importanceScore >= 7` generates a "High importance (X.X)" reason.
- `relevanceScore >= 7` generates a "High relevance (X.X)" reason.
- Created within 24 hours generates "Recently created."
- Updated within 24 hours generates "Recently updated."
- Non-null `lastAgentSlug` generates a humanized "Updated by \{agent name\}."
Personalized reasons are prepended in strongest-first order so the first two
card pills explain the rank:
| Type | User-facing label |
| -------------------- | --------------------------- |
| `owned_by_you` | Owned by you |
| `recent_interaction` | You worked on this |
| `preferred_type` | A record type you use often |
### URL State Persistence
Feed configuration (tab, sort, show mode, filters) is persisted in URL search
parameters. This enables sharing feed views via URL and preserving state across
navigation. The feed client component reads from and writes to URL state through
the shared query codec, and the feed API parses the same URL shape for direct
server-side resolution.
## API Reference
### Server Actions (`features/feed/server/resolve.ts`)
| Function | Signature | Description |
|----------|-----------|-------------|
| `resolveFeed` | `(rawConfig?: unknown) => Promise<FeedResult>` | V1 resolver: entities with sorting and filtering. |
| `resolveFeedV2` | `(rawConfig?: unknown) => Promise<FeedResultV2>` | V2 resolver: activity-enriched items with card data. |
### Pure Functions (`features/feed/lib/rank.ts`)
| Function | Signature | Description |
|----------|-----------|-------------|
| `rankFeedItems` | `(items: FeedItem[], sortBy?: FeedSortBy) => FeedItem[]` | Sort items and attach reasons. |
| `rankForYou` | `(items, scores, reasonsByEntity?, nowMs?) => FeedItem[]` | Sort by personalized scores with recency and entity-ID tiebreakers. |
| `deriveReasons` | `(item: FeedItem, nowMs?: number) => FeedItemReason[]` | Compute explainability reasons from item metadata. |
### URL Helpers (`features/feed/lib/feed-url-state.ts`)
| Function | Signature | Description |
|----------|-----------|-------------|
| `parseFeedUrlState` | `(params) => FeedUrlState` | Parse URL params into client feed state with UI defaults. |
| `serializeFeedUrlState` | `(state) => URLSearchParams` | Serialize feed state while omitting default/empty values. |
| `feedConfigFromSearchParams` | `(params) => FeedConfig` | Parse URL params into a server resolver config. |
| `buildFeedHref` | `(config, basePath?) => string` | Build a shareable feed URL from a feed config. |
### Personalization (`features/feed/lib/for-you-scoring.ts`)
| Function | Signature | Description |
| --------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| `computeScores` | `(items, context, nowMs) => Map<string, number>` | Pure deterministic personalization scoring. |
| `decay01` | `(iso, nowMs, halfLifeDays) => number` | Compute exponential recency decay in `(0, 1]`. |
| `deriveForYouReasons` | `(item, context) => FeedItemReason[]` | Build user-signal reason labels in rank-explanation order. |
### Personalization DB Layer (`features/feed/server/resolve-for-you.ts`)
| Function | Signature | Description |
| ------------------- | ------------------------------ | --------------------------------------------------------------------- |
| `loadForYouContext` | `() => Promise<ForYouContext>` | Loads authenticated, tenant-scoped ownership and interaction context. |
### Result Types
```typescript
interface FeedResult {
items: FeedItem[];
total: number;
config: FeedConfig;
hasMore: boolean;
}
interface FeedResultV2 {
items: FeedItemV2[];
total: number;
config: FeedConfig;
hasMore: boolean;
personalized?: boolean; // For You only; client reads page 1
}
```
## For Agents
The feed system does not expose direct agent tools. However, agents influence the feed indirectly:
- **Entity updates by agents** -- When agents create or update entities (via `createEntity`, `updateEntity` tools), those entities appear in the feed with "Updated by \{agentSlug\}" attribution.
- **Activity tracking** -- All agent actions that produce activities affect the feed's activity enrichment layer. The `agentSlugs` filter lets users see entities touched by specific agents.
- **Importance and relevance scores** -- Agents can set `importanceScore` and `relevanceScore` in entity metadata, which directly influences feed ranking.
- **Feed as a block** -- The `entity-feed` block type renders a feed within views. Agents authoring views via `manageView` can configure feed blocks with specific filters and sort orders.
## Design Decisions
**Two-phase resolution.** Entities are fetched first with broad filtering, then activities are fetched in a second pass scoped to the returned entity IDs. This avoids complex joins between entities and activities while keeping query performance predictable. The activity query limits total rows to prevent runaway fetches.
**UUID suppression in preview fields.** `rowToFeedItem()` skips any content field whose string value matches the UUID regex (`/^[0-9a-f]{8}-...-[0-9a-f]{12}$/i`) when building the card's `fields` preview array. Entity schemas frequently place relation reference fields (e.g. `company_id`) early in the property order; without this filter, those fields would occupy one of the three preview slots, showing a meaningless ID instead of an actual attribute. The loop now scans the full property list and stops after collecting three non-UUID, non-empty values.
**Pure scoring function.** The for-you personalization scoring is implemented
as a pure function (`computeScores`) with no database access or ambient clock.
This enables comprehensive unit testing of the scoring model without mocking.
The DB layer (`loadForYouContext`) resolves authenticated tenant/user identity
internally and returns only serializable context.
**Explainability as a first-class concept.** Every feed item carries `reasons` explaining why it was surfaced. Rather than being a debugging afterthought, reasons are part of the item schema and rendered in the UI. This builds user trust in the ranking system and helps users understand what the platform considers important.
**Denormalized entity_type_slug.** Feed queries filter by `entity_type_slug` directly on the entities table instead of joining through `entity_types`. This denormalized column (synced via trigger) eliminates a join and enables index-only filtering.
**Activity-enriched V2.** The V2 resolver adds activity context because the feed UI evolved from "list of entities" to "what is happening with entities." The V1 resolver is maintained for backward compatibility and simpler use cases (like block embedding).
**URL state over local state.** Feed configuration is stored in URL search parameters rather than component state or localStorage. This makes feed views shareable and bookmarkable, and ensures the feed state survives navigation without additional persistence logic.
**Agent slug filtering on activity metadata.** Rather than adding an `agent_id` column to entities, agent attribution is tracked in the activities table's metadata. The `agentSlugs` filter checks `metadata.agent_slug` on activities, which is more flexible (an entity can be touched by multiple agents) but requires a secondary query.
## Related Modules
- **Entity System** (`features/entities/`) -- The feed queries and displays entities with their types, content, and metadata.
- **Activity System** -- Activities provide the enrichment layer for V2 feed items and drive the "updated" tab sorting.
- **Agent System** (`features/agents/`) -- Agent information (name, icon, slug) is resolved for activity attribution.
- **Block System** (`features/blocks/`) -- The `entity-feed` block type renders a feed within views and dashboards.
- **Scoring** -- Entity scoring criteria (from `EntityTypeConfig.scoring`) provide the `score` field; `importanceScore` and `relevanceScore` come from entity metadata.
- **Views System** (`features/views/`) -- Feed blocks can be configured within workspace and list views.