CitySounds is an interactive 3D globe application that connects cities with their musical heritage and culture. By clicking on any of 50 major cities around the world, you will find curated tracks from artists who shaped that city's sound via the Spotify web API, rendered in 3D using Globe.GL.
Live Demo (It may take time to spin up the website due to render's deployment specifications)
CitySounds is a full-stack Java Spring Boot application that visualizes the relationship between geography and music. The app displays a 3D interactive globe where each city is connected to others through intelligent musical relationships:
- Genre Connections (red arcs): Cities sharing the same music genre; connect to their nearest neighbor
- Cross-Genre Connections (blue arcs): Cities with different genres; show musical diversity and cultural exchange
When you click a city, you get:
- A Spotify track preview from a local artist
- Information about the city's primary music genre
- A list of connected cities you can explore
- GPS coordinates
This application combines data persistence, external API integration, 3D Frontend Modules, and RESTful architecture into one project.
- Java 25
- Spring Boot 4.0.1 - Application framework
- Spring Data JPA / Hibernate - ORM (Object Relational Mapping) for database interactions
- PostgreSQL - Industry Standard Relational database
- Maven - Build and dependency management manager
- Gson - JSON parsing for Spotify API responses
- HTML / CSS - Structure and styling
- Vanilla JavaScript
- Three.js - 3D rendering engine
- Globe.GL - 3D globe visualization library
- Spotify Embed API - Music player integration
- TopoJSON - World map topology data
- Spotify Web API - Artist search and track retrieval
CitySounds follows Java Springboots Model-View-Controller (MVC) pattern, with a clear separation between the backend (Spring Boot) and frontend (JavaScript). Here's how each layer works:
The backend is built with Spring Boot and follows a clean, layered architecture. Let me break down each component:
The models represent the database schema and map directly to PostgreSQL tables via JPA annotations (such as @Entity, @ID, etc....)
@Entity
@Table(name = "cities")
public class City {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name; // "New York"
private String country; // "United States"
private String countryCode; // "US" (ISO 2-letter)
private Double latitude; // 40.7128
private Double longitude; // -74.0060
private String musicGenre; // "Hip Hop"
}Purpose: Stores geographic and musical metadata for 50 major cities worldwide.
@Entity
@Table(name = "city_artists")
public class CityArtist {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private Long cityId; // Foreign key to cities table
private String artistName; // "Jay-Z"
private String spotifyArtistId; // "3nFkdlSjzX9mRTtwJOzDYB"
}Purpose: Maps artists to their cities. Each city has 4-6 artists. The spotifyArtistId enables direct lookups in Spotify's catalog.
Repositories handle all database operations using Spring Data JPA. They extend JpaRepository, which provides built-in CRUD methods.
@Repository
public interface CityRepository extends JpaRepository<City, Long> {
// Inherits: findAll(), findById(), save(), delete(), etc.
}Methods Used:
findAll()- Retrieves all 50 cities (used to populate the globe)findById(Long id)- Retrieves a single city by ID (used when user clicks a city)
@Repository
public interface CityArtistRepository extends JpaRepository<CityArtist, Long> {
List<CityArtist> findByCityId(Long cityId);
}Custom Method:
findByCityId(Long cityId)- Returns all artists associated with a specific city. This is a derived query method—Spring automatically generates the SQL based on the method name.
Services contain the core business logic and handle interactions with external APIs. The "intelligence" of the application is here.
This service is the heart of the primary function of the curation system. It integrates with Spotify's API to deliver personalized tracks for each city.
Key Method: getCuratedCityTrack(Long cityId, String countryCode)
Work Flow:
- Fetch artists for the city from the database using
CityArtistRepository - Randomly select one artist from the city's roster
- Search Spotify for the artist's Spotify ID
- Retrieve the artist's top tracks in the specified country
- Return a random track ID
public String getCuratedCityTrack(Long cityId, String countryCode) {
List<CityArtist> artists = cityArtistRepository.findByCityId(cityId);
if (artists.isEmpty()) return null;
// Pick a random artist
CityArtist randomArtist = artists.get(new Random().nextInt(artists.size()));
// Search Spotify
String artistId = searchArtistId(randomArtist.getArtistName());
if (artistId == null) return null;
// Get top tracks
return getArtistTopTrack(artistId, countryCode);
}Authentication: getAccessToken()
Spotify requires OAuth2 authentication. This method:
- Uses the Client Credentials Flow (app-to-app auth)
- Caches the access token in memory
- Only refreshes when the token expires (~1 hour)
private String getAccessToken() {
if (cachedAccessToken != null && !isTokenExpired()) {
return cachedAccessToken; // Return cached token
}
// Request new token from Spotify
// POST https://accounts.spotify.com/api/token
// Returns: { "access_token": "...", "expires_in": 3600 }
}Why caching matters: Without caching, we'd make an auth request for every single track fetch and could hit rate limits. By caching, API calls reduce alot...
Other Service Methods:
searchArtistId(String artistName)- Searches Spotify's catalog for an artist, returns their Spotify IDgetArtistTopTrack(String artistId, String countryCode)- Fetches an artist's top tracks in a specific market (e.g., US, BR, JP)
External API Endpoints Used:
https://accounts.spotify.com/api/token- OAuth2 authenticationhttps://api.spotify.com/v1/search?q={artist}&type=artist- Artist searchhttps://api.spotify.com/v1/artists/{id}/top-tracks?market={country}- Top tracks retrieval
Controllers expose endpoints that the frontend can call. They handle HTTP requests and return responses.
@Controller
public class HomeController {
@GetMapping("/")
public String home() {
return "index.html"; // Serves the main frontend
}
}This is a @RestController, meaning all methods return JSON (or plain text) instead of HTML views.
Endpoint 1: GET /api/cities
@GetMapping("/api/cities")
public List<City> getAllCities() {
return cityRepository.findAll();
}Returns: JSON array of all 50 cities Used by: Frontend during initialization to populate the globe with city points
Endpoint 2: GET /api/cities/{id}
@GetMapping("/api/cities/{id}")
public ResponseEntity<City> getCityById(@PathVariable Long id) {
return cityRepository.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}Returns: JSON object of a single city (or 404 if not found) Used by: Frontend when user clicks a city (though currently the frontend uses the cached city data)
Endpoint 3: GET /api/cities/{id}/music
@GetMapping("/api/cities/{id}/music")
public ResponseEntity<String> getCityMusic(
@PathVariable Long id,
@RequestParam(defaultValue = "US") String country
) {
String trackId = spotifyService.getCuratedCityTrack(id, country);
return trackId != null
? ResponseEntity.ok(trackId)
: ResponseEntity.notFound().build();
}Returns: Plain text Spotify track ID (e.g., "3nFkdlSjzX9mRTtwJOzDYB")
Used by: Frontend when displaying music for a city
Note: Accepts optional country query parameter to localize tracks (defaults to "US")
The frontend is a single-page application with no frameworks—just clean, vanilla JavaScript. It's roughly 500 lines of code that handle 3D rendering, user interaction, and API calls.
The HTML file sets up the structure and loads external libraries:
Key Components:
- Welcome Screen: Initial overlay with "Click Here to Begin" button
- Globe Container: Canvas element where Three.js renders the 3D globe
- Info Panel: Sliding sidebar on the right that displays:
- City name, country, flag emoji
- Music genre badge
- Embedded Spotify player
- List of connected cities (clickable)
- GPS coordinates
- Legend: Explains the difference between genre connections (red) vs. cross-genre (blue)
- Instructions: Persistent hint at the bottom ("Click on any city to explore its music scene")
Styling Highlights:
- Dark theme (midnight blue background, red accents)
- Custom CSS for responsive layout
- Globe takes up full viewport height
- Panel slides in from right with smooth transitions
This is where all the scripting and interactions occur.
1. Globe Initialization
const globe = Globe()
.globeImageUrl('//unpkg.com/three-globe/example/img/earth-night.jpg')
.backgroundImageUrl('//unpkg.com/three-globe/example/img/night-sky.png')
.pointAltitude(0.02) // How much cities "float" above surface
.pointColor(() => '#ff4444') // Red city points
.labelColor(() => 'white')
.labelSize(1.5)
.arcColor('color') // Use the 'color' property from arc data
.arcStroke(0.5)
.arcAltitude(0.3);This creates the 3D globe using Globe.GL. It sets:
- Earth texture (night-time satellite imagery)
- Star field background
- Point colors for cities
- Arc rendering properties
2. Data Fetching & City Placement
fetch('/api/cities')
.then(res => res.json())
.then(cities => {
// Store cities globally
allCities = cities;
// Add points to globe
globe.pointsData(cities);
// Add country polygons with labels
globe.polygonsData(/* TopoJSON world data */);
// Calculate and render connection arcs
const arcs = generateArcs(cities);
globe.arcsData(arcs);
});When the app loads, it fetches all cities from the backend and:
- Stores them in a global array for later reference
- Renders city points on the globe using latitude/longitude
- Draws country borders and labels
- Generates intelligent connection arcs
3. Intelligent Arc Connections
This is one of the coolest features. The generateArcs() function creates visual connections between cities based on musical relationships:
function generateArcs(cities) {
const arcs = [];
cities.forEach(city => {
// GENRE CONNECTIONS (red)
// Find nearest city with SAME genre
const sameGenreCities = cities.filter(c =>
c.id !== city.id && c.musicGenre === city.musicGenre
);
const nearestSameGenre = findNearest(city, sameGenreCities);
if (nearestSameGenre) {
arcs.push({
startLat: city.latitude,
startLng: city.longitude,
endLat: nearestSameGenre.latitude,
endLng: nearestSameGenre.longitude,
color: '#ff4444' // Red
});
}
// CROSS-GENRE CONNECTIONS (blue)
// Find nearest city with DIFFERENT genre
const differentGenreCities = cities.filter(c =>
c.id !== city.id && c.musicGenre !== city.musicGenre
);
const nearestDifferent = findNearest(city, differentGenreCities);
if (nearestDifferent) {
arcs.push({
startLat: city.latitude,
startLng: city.longitude,
endLat: nearestDifferent.latitude,
endLng: nearestDifferent.longitude,
color: '#4444ff' // Blue
});
}
});
return arcs;
}The Algorithm:
- For each city, find its nearest neighbor with the same genre → red arc
- Find its nearest neighbor with a different genre → blue arc
- Prevents arcs that would pass through Earth
Result: You get clusters of similar genres (e.g., Hip Hop cities connected in red) while also seeing cross-cultural influences (blue arcs between Hip Hop and Jazz, or K-Pop and J-Pop).
4. City Click Handler
When you click a city point:
globe.onPointClick((city) => {
// Animate camera to city
globe.pointOfView({
lat: city.latitude,
lng: city.longitude,
altitude: 1.5
}, 1000); // 1 second animation
// Update info panel
document.getElementById('city-name').textContent = city.name;
document.getElementById('music-genre').textContent = city.musicGenre;
// Fetch music for this city
fetch(`/api/cities/${city.id}/music?country=${city.countryCode}`)
.then(res => res.text())
.then(trackId => {
loadSpotifyPlayer(trackId);
animatePulsingRings(city); // Visual effect
});
// Show connected cities
displayConnectedCities(city);
// Open info panel
infoPanel.classList.add('open');
});What happens:
- Camera smoothly flies to the clicked city
- Info panel slides in with city details
- Fetches a curated track from the backend
- Loads Spotify player with the track
- Displays pulsing ring animation at the city location
- Shows list of connected cities (clickable for navigation)
5. Spotify Player Integration
The app uses Spotify's Embed API (not the full Playback SDK) for simplicity:
function loadSpotifyPlayer(trackId) {
const iframe = document.createElement('iframe');
iframe.src = `https://open.spotify.com/embed/track/${trackId}`;
iframe.width = '100%';
iframe.height = '80';
iframe.frameBorder = '0';
iframe.allow = 'encrypted-media';
playerContainer.innerHTML = '';
playerContainer.appendChild(iframe);
}This creates an embedded player that works without requiring user authentication. Users can play/pause directly in the app.
6. Pulsing Ring Animation
When music plays, a visual effect appears on the globe:
function animatePulsingRings(city) {
// Creates expanding concentric rings at city location
// Uses Three.js RingGeometry
// Fades out and removes after animation completes
}7. Connected Cities Display
The info panel shows which cities are connected to the current city via arcs:
function displayConnectedCities(city) {
const connectedCities = arcs
.filter(arc => arc.startLat === city.latitude)
.map(arc => findCityByCoords(arc.endLat, arc.endLng));
// Render as clickable list
connectedCities.forEach(connectedCity => {
const li = document.createElement('li');
li.textContent = `${connectedCity.name} (${connectedCity.musicGenre})`;
li.onclick = () => globe.onPointClick(connectedCity); // Navigate
list.appendChild(li);
});
}This creates a navigation mechanism—you can hop from city to city by clicking connected cities
8. Panel Resizing
The info panel is resizable—users can drag the left edge to make it wider or narrower:
let isResizing = false;
panelResizeHandle.addEventListener('mousedown', () => {
isResizing = true;
});
document.addEventListener('mousemove', (e) => {
if (isResizing) {
const newWidth = window.innerWidth - e.clientX;
infoPanel.style.width = `${newWidth}px`;
}
});
document.addEventListener('mouseup', () => {
isResizing = false;
});A small UX touch that makes the interface feel polished.
Building CitySounds taught me a ton about full-stack development, API integration, and 3D graphics. Here are the key takeaways:
- Separation of concerns: Keeping models, repositories, services, and controllers distinct makes the codebase maintainable and testable. If I need to swap Spotify for another music API, I only touch the service layer.
- Spring Data JPA magic: Derived query methods like
findByCityId()are incredibly powerful. Spring generates the SQL for you based on method names—no need to write raw queries.
- OAuth2 flows: Implementing the Client Credentials flow taught me how app-to-app authentication works. Managing token expiration and caching was crucial for performance.
- Rate limiting considerations: Caching the access token reduced API calls dramatically, a good thing
- Normalization: Splitting cities and artists into separate tables prevents data duplication. The
city_artistsjunction table creates a clean many-to-many relationship (one city → many artists, one artist → potentially many cities). - Indexing matters: Adding an index on
city_artists.city_idimproved query performance significantly when fetching artists for a city.
- Vanilla JS is powerful: With modern features, vanilla JavaScript handles state management, DOM manipulation, and async operations beautifully.
- Three.js/Globe.GL: Working with 3D graphics was challenging but rewarding. Understanding concepts like camera positioning, altitude, and arc rendering opened up a new dimension (literally) of web development.
- Performance optimization: Rendering 50 cities, 100+ arcs, and country polygons requires efficient rendering. Globe.GL handles this, but I learned to minimize re-renders and cache data where possible.
- Progressive disclosure: The welcome screen → globe → info panel flow guides users naturally through the experience.
- Visual feedback: Pulsing rings, camera animations, and smooth transitions make the app feel alive and responsive.
- Maven dependency management: Managing Spring Boot dependencies, JDBC drivers, and Gson with Maven taught me about build systems and version compatibility.
- Environment configuration: Using
application.properties.templatekeeps sensitive credentials out of version control while documenting what's needed to run the app.
- CORS issues: Working with Spotify's API required understanding CORS policies and how browsers handle cross-origin requests.
- Async JavaScript: Managing multiple async operations (fetch city data, fetch music, load Spotify player) required careful promise handling and error management.
Getting Started to run locally/ by yourself (else it is running on render.com under the description of the repository)
- Java 17+ (project uses Java 25)
- PostgreSQL database
- Spotify Developer Account (free at developer.spotify.com)
- Maven (included via Maven wrapper)
git clone https://github.com/yourusername/CitySounds.git
cd CitySounds- Create a PostgreSQL database:
psql -U postgres
CREATE DATABASE citysounds;
\q- Run the SQL scripts (in order):
psql -U postgres -d citysounds -f src/main/resources/create_tables.sql
psql -U postgres -d citysounds -f src/main/resources/citiesData.sql
psql -U postgres -d citysounds -f src/main/resources/cityArtistsData.sqlThis creates the cities and city_artists tables and populates them with 50 cities and ~300 artists.
- Go to developer.spotify.com/dashboard
- Log in (or create an account)
- Click "Create App"
- Fill in:
- App Name:
CitySounds - App Description:
Music exploration app - Redirect URI:
http://localhost:8080(not used, but required)
- App Name:
- Click "Create"
- Copy your Client ID and Client Secret
- Copy the template:
cp src/main/resources/application.properties.template src/main/resources/application.properties- Edit
application.properties:
# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/citysounds
spring.datasource.username=postgres
spring.datasource.password=your_password_here
# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=none
spring.jpa.show-sql=true
# Spotify API
spotify.client-id=your_spotify_client_id_here
spotify.client-secret=your_spotify_client_secret_here
# Server
server.port=8080On Mac/Linux:
./mvnw spring-boot:runOn Windows:
mvnw.cmd spring-boot:runThe app will start on http://localhost:8080
- Open your browser to http://localhost:8080
- Click "Click Here to Begin"
- Click on any city on the globe
- Listen to curated tracks from local artists
- Navigate between connected cities
Interactive 3D globe with 50 major world cities Real-time Spotify integration for music playback Intelligent arc connections showing musical relationships Genre-based clustering (Hip Hop, Jazz, K-Pop, etc.) Responsive info panel with city details Clickable connected cities for exploration Smooth camera animations and visual effects Resizable UI panels
CitySounds/
├── src/
│ ├── main/
│ │ ├── java/com/citysounds/
│ │ │ ├── CitySoundsApplication.java
│ │ │ ├── controllers/
│ │ │ │ ├── HomeController.java
│ │ │ │ └── CityController.java
│ │ │ ├── models/
│ │ │ │ ├── City.java
│ │ │ │ └── CityArtist.java
│ │ │ ├── repository/
│ │ │ │ ├── CityRepository.java
│ │ │ │ └── CityArtistRepository.java
│ │ │ └── services/
│ │ │ └── SpotifyService.java
│ │ └── resources/
│ │ ├── application.properties.template
│ │ ├── create_tables.sql
│ │ ├── citiesData.sql
│ │ ├── cityArtistsData.sql
│ │ └── static/
│ │ ├── index.html
│ │ └── app.js
├── Dockerfile # Docker build configuration
├── docker-compose.yml # Local Docker deployment
├── .dockerignore
├── .env.example # Template for environment variables
├── .gitignore # Prevents secrets in version control
├── pom.xml
├── README.md
└── README-DOCKER.md # Comprehensive Docker guide
This project is fully Dockerized for easy deployment to render.
This project is open source and available under the MIT License.
Built by Isaac Keninger GitHub: @IsaacKeninger LinkedIn: Isaac Keninger