# rococroco/hackbarna-ai-compass architecture

> Architecture diagram of the GitHub repository rococroco/hackbarna-ai-compass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rococroco/hackbarna-ai-compass
- Repository: https://github.com/rococroco/hackbarna-ai-compass

## Overview

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: [`backend/app/main.py`](https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/app/main.py) (FastAPI endpoints), [`frontend/src/app/App.tsx`](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/app/App.tsx) (App routing), [`frontend/src/services/content.service.ts`](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/content.service.ts) (Content service), [`frontend/src/pages/Home/HomePage.tsx`](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/Home/HomePage.tsx) (Home screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tv["TV interface"]
  node_app["App routing<br/>[App.tsx]"]
  node_profiles["Profile selection"]
  node_home["Home screen<br/>[HomePage.tsx]"]
  node_session_ui["Session UI"]
  node_details["Content details"]
  node_remote["Remote navigation"]
  node_focus["Focus manager<br/>[FocusManager.ts]"]
  node_profiles_service["Profile service"]
  node_content_service["Content service<br/>[content.service.ts]"]
  node_recommend_service["Recommendation service"]
end

subgraph group_voice["Voice session"]
  node_voice_client["Voice client<br/>[VoiceProvider.ts]"]
  node_voice_hook["Voice session control<br/>[useVoiceAgent.ts]"]
  node_agent["Pipecat agent<br/>[run.py]"]
  node_agent_session["Session and tools<br/>[compass_session.py]"]
  node_tool_recs["Voice recommendation tools<br/>[recommendations.py]"]
end

subgraph group_backend["Recommendation backend"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_recommend["Recommendation logic<br/>[recommender.py]"]
  node_catalogue["Catalogue and schedules"]
end

subgraph group_data["Models and data"]
  node_database[("Activity database<br/>[database.py]")]
  node_models["Prediction models"]
end

node_viewer(("Viewer"))
node_speech{{"Speech services"}}

node_viewer -->|"uses"| node_app
node_app -->|"routes to"| node_profiles
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_session_ui
node_app -->|"routes to"| node_details
node_remote -->|"moves focus"| node_focus
node_remote -->|"toggles mic"| node_voice_client
node_profiles -->|"loads profiles"| node_profiles_service
node_profiles_service -->|"requests users"| node_api
node_home -->|"starts session"| node_voice_hook
node_session_ui -->|"controls session"| node_voice_hook
node_voice_hook -->|"connects and listens"| node_voice_client
node_voice_client -->|"WebRTC audio/data"| node_agent
node_agent -->|"runs session"| node_agent_session
node_agent_session -->|"processes speech"| node_speech
node_agent_session -->|"dispatches tools"| node_tool_recs
node_tool_recs -->|"requests recommendations"| node_api
node_home -->|"loads featured"| node_content_service
node_session_ui -->|"requests rounds"| node_recommend_service
node_recommend_service -->|"requests items"| node_content_service
node_content_service -->|"requests content"| node_api
node_api -->|"calls"| node_recommend
node_api -->|"reads and writes"| node_database
node_api -->|"runs predictions"| node_models
node_recommend -->|"selects content"| node_catalogue
node_recommend -->|"reads activity"| node_database
node_details -->|"reads cached details"| node_content_service

click node_app "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/app/App.tsx"
click node_profiles "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/ProfileSelection/ProfileSelectionPage.tsx"
click node_home "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/Home/HomePage.tsx"
click node_session_ui "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/RecommendationSession/RecommendationSessionPage.tsx"
click node_details "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/ContentDetails/ContentDetailsPage.tsx"
click node_remote "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/navigation/useRemoteControl.ts"
click node_focus "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/navigation/FocusManager.ts"
click node_voice_client "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/voice/VoiceProvider.ts"
click node_voice_hook "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/voice/useVoiceAgent.ts"
click node_agent "https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/run.py"
click node_agent_session "https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/runtime/compass_session.py"
click node_api "https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/app/main.py"
click node_recommend "https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/recommender/recommender.py"
click node_tool_recs "https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/tools/recommendations.py"
click node_profiles_service "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/profiles.service.ts"
click node_content_service "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/content.service.ts"
click node_recommend_service "https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/recommendations.service.ts"
click node_database "https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/db/database.py"
click node_models "https://github.com/rococroco/hackbarna-ai-compass/tree/main/backend/models"
click node_catalogue "https://github.com/rococroco/hackbarna-ai-compass/tree/main/backend/recommender"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_profiles,node_home,node_session_ui,node_details,node_remote,node_focus,node_profiles_service,node_content_service,node_recommend_service,node_viewer toneBlue
class node_voice_client,node_voice_hook,node_agent,node_agent_session,node_tool_recs toneAmber
class node_api,node_recommend,node_catalogue toneMint
class node_database,node_models toneRose
class node_speech toneIndigo
```

## Components

### TV interface

- [App routing](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Profile selection](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/ProfileSelection/ProfileSelectionPage.tsx): `frontend/src/pages/ProfileSelection/ProfileSelectionPage.tsx`
- [Home screen](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/Home/HomePage.tsx): `frontend/src/pages/Home/HomePage.tsx`
- [Session UI](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/RecommendationSession/RecommendationSessionPage.tsx): `frontend/src/pages/RecommendationSession/RecommendationSessionPage.tsx`
- [Content details](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/pages/ContentDetails/ContentDetailsPage.tsx): `frontend/src/pages/ContentDetails/ContentDetailsPage.tsx`
- [Remote navigation](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/navigation/useRemoteControl.ts): `frontend/src/navigation/useRemoteControl.ts`
- [Focus manager](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/navigation/FocusManager.ts): `frontend/src/navigation/FocusManager.ts`
- [Profile service](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/profiles.service.ts): `frontend/src/services/profiles.service.ts`
- [Content service](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/content.service.ts): `frontend/src/services/content.service.ts`
- [Recommendation service](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/services/recommendations.service.ts): `frontend/src/services/recommendations.service.ts`

### Voice session

- [Voice client](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/voice/VoiceProvider.ts): `frontend/src/voice/VoiceProvider.ts`
- [Voice session control](https://github.com/rococroco/hackbarna-ai-compass/blob/main/frontend/src/voice/useVoiceAgent.ts): `frontend/src/voice/useVoiceAgent.ts`
- [Pipecat agent](https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/run.py): `voice-agent/run.py`
- [Session and tools](https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/runtime/compass_session.py): `voice-agent/runtime/compass_session.py`
- [Voice recommendation tools](https://github.com/rococroco/hackbarna-ai-compass/blob/main/voice-agent/tools/recommendations.py): `voice-agent/tools/recommendations.py`

### Recommendation backend

- [FastAPI endpoints](https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/app/main.py): `backend/app/main.py`
- [Recommendation logic](https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/recommender/recommender.py): `backend/recommender/recommender.py`
- [Catalogue and schedules](https://github.com/rococroco/hackbarna-ai-compass/tree/main/backend/recommender): `backend/recommender`

### Models and data

- [Activity database](https://github.com/rococroco/hackbarna-ai-compass/blob/main/backend/db/database.py): `backend/db/database.py`
- [Prediction models](https://github.com/rococroco/hackbarna-ai-compass/tree/main/backend/models): `backend/models`

### Other components

- **Viewer**
- **Speech services**

## Connections

- 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