How rococroco/hackbarna-ai-compass works
Compass is a voice-first TV recommendation product: viewers select a profile, describe what they want or choose a recommendation mode, and explore results while refining the conversation. The React interface provides remote-friendly navigation and session display; its voice client connects to a separate Pipecat agent, which handles speech and invokes recommendation tools against the FastAPI backend. The backend serves profiles, recommendations, catalogue content and activity data, using models and a SQLite log store. Some subsystems are documented but their implementation was not sampled, so only documented connections are shown.
Main entry points: main.py FastAPI endpoints · App.tsx App routing · content.service.ts Content service · HomePage.tsx Home screen
Components 22
TV interface
- App routing
frontend/src/app/App.tsx - Profile selection
frontend/src/pages/ProfileSelection/ProfileSelectionPage.tsx - Home screen
frontend/src/pages/Home/HomePage.tsx - Session UI
frontend/src/pages/RecommendationSession/RecommendationSessionPage.tsx - Content details
frontend/src/pages/ContentDetails/ContentDetailsPage.tsx - Remote navigation
frontend/src/navigation/useRemoteControl.ts - Focus manager
frontend/src/navigation/FocusManager.ts - Profile service
frontend/src/services/profiles.service.ts - Content service
frontend/src/services/content.service.ts - Recommendation service
frontend/src/services/recommendations.service.ts
Voice session
- Voice client
frontend/src/voice/VoiceProvider.ts - Voice session control
frontend/src/voice/useVoiceAgent.ts - Pipecat agent
voice-agent/run.py - Session and tools
voice-agent/runtime/compass_session.py - Voice recommendation tools
voice-agent/tools/recommendations.py
Recommendation backend
- FastAPI endpoints
backend/app/main.py - Recommendation logic
backend/recommender/recommender.py - Catalogue and schedules
backend/recommender
Models and data
- Activity database
backend/db/database.py - Prediction models
backend/models
Other components
- Viewer
- Speech services
Connections 27
- Viewer → App routing: uses
- App routing → Profile selection: routes to
- App routing → Home screen: routes to
- App routing → Session UI: routes to
- App routing → Content details: routes to
- Remote navigation → Focus manager: moves focus
- Remote navigation → Voice client: toggles mic
- Profile selection → Profile service: loads profiles
- Profile service → FastAPI endpoints: requests users
- Home screen → Voice session control: starts session
- Session UI → Voice session control: controls session
- Voice session control → Voice client: connects and listens
- Voice client → Pipecat agent: WebRTC audio/data
- Pipecat agent → Session and tools: runs session
- Session and tools → Speech services: processes speech
- Session and tools → Voice recommendation tools: dispatches tools
- Voice recommendation tools → FastAPI endpoints: requests recommendations
- Home screen → Content service: loads featured
- Session UI → Recommendation service: requests rounds
- Recommendation service → Content service: requests items
- Content service → FastAPI endpoints: requests content
- FastAPI endpoints → Recommendation logic: calls
- FastAPI endpoints → Activity database: reads and writes
- FastAPI endpoints → Prediction models: runs predictions
- Recommendation logic → Catalogue and schedules: selects content
- Recommendation logic → Activity database: reads activity
- Content details → Content service: reads cached details