Pulse Public Worker

The public worker serves the live Pulse UI, public JSON endpoints, embeds, and a small set of admin helper routes.

Current UI Surface

The /pulse page currently includes:

• a maintenance banner titled Under Construction
• community and source selectors
• tabs named This Week, History, Daily, Trends, and Concepts
• a footer with legal and docs links

Current banner copy warns that recent daily summaries may be incomplete while processing catches up.

If a community has no published sources, the source selector currently shows No sources available.

Query Defaults

Most public Pulse data endpoints accept community and source.

• if community is omitted, the worker defaults to ihouse-nyc
• if source is omitted, the worker currently defaults to ihouse-main-whatsapp-group

That means /pulse.json with no query string is not unscoped. It resolves to a specific default community and source.

Public Endpoints

Path	Method	What it returns	Notes
/pulse	GET	Main HTML UI	Default public experience
/pulse.json	GET	Current or requested weekly summary	Accepts weekof or week_start
/pulse/history.json	GET	Weekly history	Returns { summaries, pagination }
/pulse/daily.json	GET	Daily summaries	Returns { days, pagination }
/pulse/trends.json	GET	Trend summary plus paginated weekly breakdown	Returns { summaries, trends, pagination }
/pulse/concepts	GET	Dedicated concepts page	HTML route
/pulse/concepts.json	GET	Concept graph data	Returns { graph, metadata, available_weeks }
/pulse/embed	GET	Embeddable Pulse card	Weekly or daily modes
/pulse/communities.json	GET	Public community list	Returns { communities }
/pulse/sources.json	GET	Public source list for one community	Accepts community or community_id; returns { sources }

Response Caching

The four highest-traffic public endpoints are cached at the Cloudflare edge using the Cache API:

Endpoint	TTL
/pulse.json	5 minutes
/pulse/history.json	5 minutes
/pulse/trends.json	5 minutes
/pulse/concepts.json	5 minutes

Cache keys include the full URL with query parameters, so different community, source, limit, and offset combinations are cached independently. Only successful responses (HTTP 2xx) are stored; errors bypass the cache. To verify a cache hit, check the cf-cache-status: HIT response header.

/pulse/daily.json, /pulse/communities.json, and /pulse/sources.json are not cached — daily data changes more frequently and community/source lists are small with negligible D1 cost.

Query Performance Notes

• /pulse/history.json loads all health snapshots for the returned page in a single batch query instead of one query per week. This eliminates an O(N) pattern (20 queries per 20-row page → 1 query).
• The export_media join used for media counts in history is covered by a composite index (export_id, community_id) added in migration add_performance_indexes.sql.

Response Notes That Matter

• Weekly endpoints expose some database-style fields such as top_themes_json and tags_json as JSON strings.
• /pulse/daily.json normalizes top_themes into an array and also includes message counts, sender counts, media counts, and media-analysis status.
• /pulse/trends.json calculates trend signals from all available weekly summaries even when the returned summaries array is paginated.
• /pulse/concepts.json supports single-week, range, and aggregate views through week_start, week_end, all_weeks, aggregate, and limit.

Daily Endpoint Visibility

Older docs treated daily summaries as private-by-default. The current checked-in public worker config does not.

• apps/pulse-public/wrangler.jsonc sets PUBLIC_DAILY_DIGESTS=true
• the live public worker currently serves /pulse/daily.json without admin auth

The daily endpoint still exposes derived summaries and counts, not raw messages.

Embed Behavior

/pulse/embed currently supports these query parameters:

Param	Purpose
style	full or banner
type	weekly or daily
weekof	weekly date selector
date	daily date selector
community	community scope
source	source scope
tz	client timezone, defaulting to America/New_York in the embed script

After render, the embed posts:

{ "type": "beacon-pulse-embed-resize", "height": 123 }

The parent page must listen for that message and resize the iframe.

Admin Helpers On The Public Worker

Only a small admin-helper surface lives on the public worker itself.

Path	Method	Purpose
/admin/communities	GET, POST	List or create communities
/admin/sources	GET, POST, PUT, DELETE	Manage chat sources
/admin/exports/assign-source	POST	Attach a source to an existing export

Heavy operations such as upload, replay, regeneration, quota, media, and backfill run on the ingest worker.

/docs/* Redirects

The worker uses a fixed redirect map rather than mirroring the docs tree directly.

From	To
/docs	/
/docs/architecture	/platform/architecture
/docs/privacy	/platform/privacy
/docs/operations	/platform/operations
/docs/testing	/platform/testing
/docs/glossary	/platform/glossary
/docs/community-health	/platform/community-health-model

Verified against beacon-platform/apps/pulse-public/src/index.ts, live public responses, and the rendered /pulse UI on April 22, 2026. Caching and N+1 fixes added April 25, 2026.