How simonjj/containerapps-music-recommendations works
Project Type and Purpose
• This is a full-stack, containerized music recommendation service that teaches vector-database concepts and provides a user-facing UI.
• Four primary components:
1. Jupyter notebook (data-prep & embedding generation)
2. Qdrant vector database (stores embeddings, answers similarity queries)
3. Python backend (broker between UI and Qdrant, exposes REST API)
4. Java/Vaadin frontend (user interface, audio player, search & recommendation views)
File Structure Analysis
• Top-level directories:
• notebooks/ – Jupyter workflows & data prep
• backend/ – Python API (songs_api.py, requirements.txt, Dockerfile)
• frontend/ – Vaadin/Spring Boot UI (Java code under src/main/java, static assets, Dockerfile)
• misc/, lab/, .gitignore, README.md – documentation & samples
• Container assets: Dockerfiles in backend/, frontend/, notebooks/
• Backend appears to use FastAPI or Flask (check songs_api.py)
• Frontend is a Spring Boot application with Vaadin components, built via Maven/Vite/Pnpm
README Insights
• Emphasizes two deployment phases:
a. Notebook + Qdrant to generate embeddings
b. Backend + Frontend + Qdrant to serve recommendations
• Deployed on Azure Container Apps; Qdrant provided as an add-on
• Backend ingress is internal; Frontend ingress is external
Main Components & Interactions
• User (browser)
↔ Frontend container (Vaadin UI on port 8080)
• calls Backend REST endpoints (UI_BACKEND env var, port 8000)
• Backend container
↔ Qdrant vector DB (via REST/gRPC client binds)
• issues similarity searches; returns JSON of recommended songs
• Notebook container (optional data-prep)
↔ Qdrant (GPU-enabled workload profile)
• reads raw song metadata, generates embeddings, writes to Qdrant
• Qdrant (managed as Azure add-on) persists vectors and metadata
Architectural Patterns & Design Principles
• Separation of concerns: distinct data-prep, API, UI, and data-store layers
• Stateless microservices: each component runs in its own container, scales independently
• RESTful API: backend exposes simple endpoints for search & recommendation
• Vaadin component model on frontend (UI views, DTOs, client services)
• Containerized CI/CD ready (Dockerfiles, Azure CLI scripts)
Detail Level
• Keep Qdrant as a single node with “vector store + similarity search” label