Radar Feature Development

Radar is OpenPromo's competitor monitoring and content discovery tool. It tracks TikTok and Instagram accounts, syncs their content, detects anomalies (viral spikes, outperformers), and helps users discover trending content ideas.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Dashboard UI                            │
│  RadarPage → RadarSourcesPanel, RadarContentFeed, RadarDigest   │
└────────────────────────────┬────────────────────────────────────┘
                             │ orpc
┌────────────────────────────▼────────────────────────────────────┐
│                      Worker (orpc routes)                       │
│                   packages/dash/worker/src/orpc/routes/radar.ts │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                     Core Domain Logic                           │
│  packages/core/src/domain/radar/                                │
│  ├── entity/                                                    │
│  │   ├── EntRadarSource.ts      (tracked accounts)              │
│  │   ├── EntRadarContentItem.ts (synced posts)                  │
│  │   ├── EntRadarSavedIdea.ts   (bookmarked content)            │
│  │   └── EntRadarDigest.ts      (AI summaries)                  │
│  ├── radar-sync-service.ts      (fetches & processes content)   │
│  └── radar-digest-service.ts    (generates AI summaries)        │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                     External APIs (TikHub)                      │
│  packages/core/src/providers/tikhub/                            │
│  ├── client.ts         (HTTP client with KV caching)            │
│  ├── tikhub.ts         (unified exports)                        │
│  └── tikhub-tiktok-web.ts (TikTok Web API types)                │
└─────────────────────────────────────────────────────────────────┘

Key Files

Data Models (Drizzle)

• packages/core/src/schemas/radar.sql.ts - Table definitions
  • radarSourcesTable - Tracked accounts (TikTok, Instagram)
  • radarContentItemsTable - Synced posts/videos
  • radarSavedIdeasTable - User bookmarks
  • radarDigestsTable - AI-generated summaries

Entities

• EntRadarSource - Add/remove/pause tracked sources, validation
• EntRadarContentItem - Store/query synced content, anomaly flags
• EntRadarSavedIdea - Save/unsave content as ideas
• EntRadarDigest - Generate/store weekly digests

Services

• radar-sync-service.ts - Core sync logic
  • syncSource(source) - Fetch posts, detect anomalies, store
  • syncWorkspace(workspaceId) - Sync all sources for workspace
  • Anomaly detection: viral_spike (5x avg), outperformer (2x avg)

API Routes

• packages/dash/worker/src/orpc/routes/radar.ts
  • Sources: addSource, listSources, removeSource, pauseSource, resumeSource
  • Content: listContent, listAnomalies
  • Ideas: saveIdea, listIdeas, unsaveIdea
  • Digests: getLatestDigest, listDigests, generateDigest
  • Sync: triggerSync

UI Components

• packages/dash/ui/src/components/radar/
  • RadarPage.tsx - Main page with tabs (Anomalies, All, Saved)
  • RadarSourcesPanel.tsx - Grid of tracked source cards
  • RadarAddSourceForm.tsx - URL input to add sources
  • RadarContentFeed.tsx - Grid of content cards
  • RadarEmptyState.tsx - Empty state with onboarding
  • RadarDigestCard.tsx - AI digest display
  • radar-url-parser.ts - Parse TikTok/IG profile URLs

Query Hooks

• packages/dash/ui/src/queries/radar.ts
  • useRadarSources, useAddRadarSource, useRemoveRadarSource
  • useRadarContent, useRadarAnomalies
  • useRadarIdeas, useSaveRadarIdea, useUnsaveRadarIdea
  • useTriggerRadarSync, useGenerateRadarDigest

TikHub Integration

TikHub provides the social media APIs. API calls are cached in KV (24h TTL).

TikTok

// Get secUid from username (required for fetching posts)
TikHub.TikTokWeb.getSecUid(username)

// Get user profile
TikHub.TikTokWeb.fetchUserInfo({ user_id: secUid })

// Get user posts (returns up to 20)
TikHub.TikTokWeb.fetchUserPosts({ secUid, count: 20 })

Instagram

// Get user profile (data nested under data.data)
TikHub.InstagramV2.fetchUserInfo({ username })

// Get user posts (data nested under data.data.items)
TikHub.InstagramV2.fetchUserPosts({ username })

Important: Instagram API responses are nested under data.data, not data directly.

Adding New Source Types

1. Add type to radarSourceTypePgEnum in radar.sql.ts
2. Add validation method to TikHubPlatformValidator in EntRadarSource.ts
3. Add fetch method to TikHubPlatformFetcher in radar-sync-service.ts
4. Update fetchContent() switch in sync service
5. Update URL parser in radar-url-parser.ts
6. Update UI icons in components

Anomaly Detection

Content is flagged as anomaly based on views vs baseline:

• viral_spike: 5x+ average views (score 0.8-1.0)
• outperformer: 2x-5x average views (score 0.3-0.79)

Baseline is calculated from last 20 posts with min 5 posts required.

Sync Flow

1. User adds source via URL → EntRadarSource.add()

   • Validates account exists via TikHub API
   • Extracts profile data (avatar, stats)
   • Stores source with status: 'active'
   • Auto-triggers sync for new source

2. Sync runs (manual or cron) → radarSyncService.syncSource()

   • Fetches latest posts from platform API
   • Calculates/updates baseline metrics
   • Detects anomalies based on views
   • Upserts content items with anomaly flags
   • Updates lastSyncedAt timestamp

UI Patterns

Source Cards

<SourceCard source={source} />
// Shows: avatar, @username, platform icon, follower count, video count
// Actions: pause/resume, remove (with ConfirmDialog)

Content Cards

<RadarContentCard item={item} />
// Uses GridCard building blocks from @/components/common/grid-card
// Shows: thumbnail, metrics (views/likes/comments), anomaly badge
// Actions: Save Idea (hover), Open Original (dropdown)

Add Source Flow

1. User pastes TikTok/IG profile URL
2. URL parsed → preview card shown
3. User clicks "Add Source"
4. Source validated, created, auto-synced

Common Tasks

Debug sync issues

// Check logs for:
console.log("[radar] syncing source", { sourceId, sourceType, identifier });
console.log("[radar] fetched content", { count });
log.info("instagram posts fetched", { count });

Test API responses

Use labs route or add temp logging in validator/fetcher functions.

Clear KV cache

// Cache keys are prefixed with "tikhub:"
const key = `tikhub:${url}`;
await kv.delete(key);

Route Configuration

Route: /workspaces/:workspaceSlug/radar

Search params (zod validated):

const radarSearchSchema = z.object({
  tab: z.enum(["anomalies", "all", "saved"]).catch("anomalies"),
});