juicebox-reference-architecture

# Juicebox Reference Architecture ## Overview Production architecture for AI-powered candidate analysis integrations with Juicebox. Designed for recruiting teams needing automated dataset ingestion from job descriptions, intelligent candidate scoring and ranking, result caching for repeated searches, and seamless export to ATS platforms like Greenhouse and Lever. Key design drivers: search result freshness, candidate deduplication across sources, outreach sequencing, and analysis pipeline throughput for high-volume hiring. ## Architecture Diagram ``` Recruiter Dashboard ──→ Search Service ──→ Cache (Redis) ──→ Juicebox API ↓ /search Queue (Bull) ──→ Analysis Worker /profiles ↓ /outreach ATS Export Service ──→ Greenhouse/Lever ↓ Webhook Handler ←── Juicebox Events ``` ## Service Layer ```typescript class CandidateSearchService { constructor(private juicebox: JuiceboxClient, private cache: CacheLayer) {} async findAndRank(criteria: SearchCriteria): Promise<RankedCandidate[]> { const cacheKey = `search:${this.hashCriteria(criteria)}`; const cached = await this.cache.get(cacheKey); if (cached) return cached; const results = await this.juicebox.search(criteria); const ranked = results.profiles.map(p => ({ ...p, score: this.scoreCa...