System Design
System Architecture
Understand how Cerul processes video search requests. Learn about our distributed architecture and data flow.
Guide
System Design
Built to be operator-readable before you wire in automation.
Read time
6 min read
Quick enough for onboarding, specific enough for implementation.
Focus
Practical API use
Examples, request shape, and the minimum context needed to ship.
01
Request flow
When you make a search request, it travels through several components to deliver results. Understanding this flow helps optimize your integration.
- 1. API Gateway validates your API key
- 2. Query is parsed and routed to the correct search track
- 3. Vector search retrieves matching candidates
- 4. Results are ranked and formatted
- 5. Direct video URLs are generated
- 6. Response is returned with usage tracking
02
B-roll vs Knowledge
The two search tracks use different indexing strategies and data sources, but share the same API interface.
track_comparison.txtTEXT
B-roll Track:
- Sources: Pexels, Pixabay (stock footage)
- Indexing: CLIP visual embeddings
- Results: Asset-level (entire video)
- Metadata: License, duration, resolution
Knowledge Track:
- Sources: YouTube educational content
- Indexing: Whisper + GPT-4o + CLIP
- Results: Segment-level (timestamped clips)
- Metadata: Speaker, transcript, timestamps03
Technology stack
Cerul is built on modern infrastructure designed for scalability and reliability.
- Frontend: Next.js 16 with React Server Components
- API: FastAPI with async request handling
- Database: Neon PostgreSQL with pgvector
- Search: Vector similarity with HNSW indexing
- Workers: Python for video processing and indexing
- CDN: Global edge caching for video delivery