Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
BrowsingSignal is an append-only infrastructure entity that records hourly deltas of provider-domain visits flushed by the Chrome extension. Each row represents one (workspace, domain, hour-bucket) tuple: the count of visits accumulated since the last successful flush from that extension session. The provider-scoring pipeline aggregates rows within a 24-hour window to produce the signal_boost factor that ranks providers higher for workspaces that recently visited their domain. Rows have no soft-delete column and are pruned by the daily rescore cron after 90 days. The table is not exposed via Hasura and is internal-only.
| Naming | Value |
|---|
| Object | BrowsingSignal |
Resource type (JSON:API type) | browsing_signal |
| Collection / records root | — (not a records root) |
| REST base | /v1/browsing-signals |
| Entity class | BrowsingSignal |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/browsing-signals | 🟡 Planned |
| Retrieve | GET /v1/browsing-signals/{id} | 🟡 Planned |
| Create | POST /v1/browsing-signals | 🟡 Planned |
| Update | PATCH /v1/browsing-signals/{id} | 🟡 Planned |
| Delete | DELETE /v1/browsing-signals/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| browsing_signal_id | 🔒 system — UUID (string) | ✅ Yes | UNIQUE; generated via gen_random_uuid() at INSERT | Any valid UUID v4 | Public-facing stable identifier for this browsing signal row. Generated by the database on insert; never supplied by callers. |
| domain | string (text) | ✅ Yes | NOT NULL; no max-length constraint at the DB level | — | The provider domain that was visited (e.g. pennylane.com, stripe.com). Written by the Chrome extension flush handler; identifies which provider the workspace was browsing. |
| visit_count | integer | ✅ Yes | NOT NULL; column type int | — | Delta of visits to this domain recorded since the last successful flush from the Chrome extension. Used by the provider-scoring pipeline as the raw signal weight before aggregation. |
| last_visited_at | timestamptz | ✅ Yes | NOT NULL | — | Timestamp of the most recent visit to this domain within the flush batch. Used to bound recency windows in the 24-hour aggregation pass. |
| created_at | 🔒 system — timestamptz | ⚪ No (defaulted) | DEFAULT now(); set by DB on insert; also set via MikroORM onCreate hook | — | Wall-clock timestamp of row insertion. Used as the composite index key for workspace-scoped time-range queries and as the pruning anchor for the 90-day cron cleanup. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | ✅ Yes | The workspace whose Chrome extension produced this signal. Foreign key stored as workspace_pk with ON DELETE CASCADE — deleting a workspace removes all its browsing signals. This is the tenant scope anchor for every query on the table. |
System-computed
- browsing_signal_id: generated via gen_random_uuid() at INSERT — never supplied by the caller
- created_at: set to now() by the database DEFAULT and additionally via MikroORM onCreate hook — not user-supplied
- No soft-delete (deleted_at column is absent): this is an append-only table; rows are pruned physically by the daily rescore cron after 90 days, not soft-deleted
- No updated_at column: the entity is append-only by design; rows are never mutated after insertion
- pk: internal serial primary key — exposed only in the composite index definitions; never surfaced in the API response
- workspace_pk: FK column written by MikroORM from the workspace relationship — never set directly by the caller
- Two composite indexes maintained automatically by Postgres: idx_browsing_signals_workspace_created (workspace_pk, created_at DESC) and idx_browsing_signals_workspace_last_visited (workspace_pk, last_visited_at DESC)
Example
{
"data": {
"type": "browsing_signal",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"browsing_signal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"domain": "pennylane.com",
"visit_count": 4,
"last_visited_at": "2026-06-02T08:45:00.000Z",
"created_at": "2026-06-02T09:00:00.000Z"
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "ws_9f3a8b2c-1234-5678-abcd-000000000001" }
}
}
}
}
apps/api/src/database/entities/BrowsingSignal.ts · domain: ingestion · tier: Infrastructure
