# simonjj/containerapps-music-recommendations architecture

> Architecture diagram of the GitHub repository simonjj/containerapps-music-recommendations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonjj/containerapps-music-recommendations
- Repository: https://github.com/simonjj/containerapps-music-recommendations

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Browser"]:::user

    subgraph "Azure Container Apps"
        subgraph "Data-Prep Phase"
            Notebook["Notebook Container\n(Jupyter)"]:::compute
        end
        subgraph "Runtime Phase"
            Frontend["Frontend Container\n(Java/Vaadin)"]:::compute
            Backend["Backend Container\n(Python API)"]:::compute
        end
        Qdrant["Qdrant Vector DB\n(vector store + similarity search)"]:::db
    end

    User -->|"HTTPS"| Frontend
    Frontend -->|"REST requests"| Backend
    Backend -->|"query embeddings"| Qdrant
    Notebook -->|"write embeddings"| Qdrant

    click Notebook "https://github.com/simonjj/containerapps-music-recommendations/tree/main/notebooks/"
    click Backend "https://github.com/simonjj/containerapps-music-recommendations/tree/main/backend/"
    click Frontend "https://github.com/simonjj/containerapps-music-recommendations/tree/main/frontend/"

    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db      fill:#90EE90,stroke:#333,stroke-width:1px
    classDef user    fill:#FFD700,stroke:#333,stroke-width:1px

    linkStyle 0 stroke:#FFA500,stroke-width:2px
    linkStyle 1 stroke:#800080,stroke-width:2px
    linkStyle 2 stroke:#008080,stroke-width:2px
    linkStyle 3 stroke:#008080,stroke-width:2px,stroke-dasharray: 5 5
```
