Architecture
System architecture, data model, and type definitions that power Rally's engagement pipeline.
System Layers
Four layers with clear responsibilities: UI, App, Orchestration, and Transport.
User Interface
Today · Ask · Workmate
App Layer
Server Actions + API Routes
Orchestration
lib/ai/curation-agent.ts
Transport
lib/ai/braintrust.ts
External Services
Braintrust
Prompt management
Claude
Scoring + generation
Gemini
Video analysis
Apify
TikTok ingestion
Supabase
Data + auth
Core Data Model
The key entities and how they relate, organized by domain.
Brand Configuration
brands
user_id
name
niche
brand_tiktok_config
hashtags[]
topics[]
competitors
brand_briefs
voice
tone
dos/donts
Content + Analysis
trending_videos
caption
views
author
rally_score
post_analysis
composite_score
relevance
timing
reasoning
Comments
comments
status
selected_variant
comment_variants
style
text
reasoning
All tables scoped by brand_id with row-level security
Video Sources
Two source types, stored separately but processed through the same pipeline.
trending_videosHashtag-based discovery
Videos found by searching your monitored hashtags and topics. Broader discovery for finding new creators in your niche.
mentions_videosCreator-based monitoring
Videos from specific creators you track. More targeted — useful for monitoring competitors, partners, or frequent collaborators.
Both types use a polymorphic post_analysis table with video_id + video_type for unified scoring regardless of source.
Agent Lifecycle
The Workmate agent runs an autonomous cycle following an observe/evaluate/decide/act/learn pattern.
Observe
Check for new content
Evaluate
Score + threshold
Decide
What to surface
Act
Generate comments
Learn
Process feedback
Observe
Check for new content
Evaluate
Score + threshold
Decide
What to surface
Act
Generate comments
Learn
Process feedback
Comment Lifecycle
Each comment moves through a state machine from generation to user action.
Happy path
From surfaced. Feeds learning — Rally adjusts future scoring based on what you skip.
From surfaced. Triggers critique loop (max 2 iterations), then re-surfaces with new comment variants.
Observability
Every AI call is traced for debugging and iteration.
Braintrust Logging
All prompt executions wrapped in traced() spans capturing input, output, model, latency, and token count.
Prompt Management
Prompts loaded by slug, cached after first load, built with template variables. Model selection controlled from dashboard.
Graceful Fallback
Without BRAINTRUST_API_KEY, Rally falls back to direct API calls with inline prompts. Enhancement layer, not a dependency.