Bandmap

music.heap.fi

Discover new music through similar artists you already like. A hobby project, currently in invite-only alpha testing.

Uses Last.fm and MusicBrainz data, but does not require accounts there.

Main components

• Frontend (packages/web): Vite SPA for artist search, ratings, todo list, recommendations as well as sign-up and login process
• Backend (packages/backend): Two AWS Lambda handlers behind API Gateway — the main API serves auth, cached remote API data, ratings, and recommendations; a dedicated invite API manages user invite creation, validation, and sign-up
• Authentication (AWS Cognito): Username/password sign-in via a Cognito user pool and app client. Self-sign-up is disabled; new users are provisioned through invite redemption, and admins can create invite links via the admin Cognito group
• Data (DynamoDB): Stores app users, invites, cached Last.fm responses, ratings, recommendations, and cached searches
• Infrastructure (packages/infra): AWS CDK stacks for backend API, DynamoDB tables, Cognito resources, and separate frontend hosting
• Shared types (packages/shared): TypeScript types and constants shared between frontend and backend

Detailed backend route and DynamoDB schema documentation is in doc/backend-api-and-data-model.md.

DynamoDB schema

The application data model is stored in DynamoDB tables with logical relationships managed in application code.

erDiagram
	USER ||--o{ INVITE : creates
	USER ||--o{ RATING : owns
	ARTIST ||--o{ RATING : is_rated_in
	USER ||--o{ RECOMMENDATION : receives
	ARTIST ||--o{ RECOMMENDATION : is_recommended_in
	ARTIST ||--o{ RECOMMENDATION : seeds
	ARTIST ||--o{ RELATED_ARTIST : source
	ARTIST ||--o{ RELATED_ARTIST : target
	SEARCH_CACHE

Loading

Prerequisites

• Node.js >= 24
• A Last.fm API key (for deployment)
• AWS account + credentials (for deployment)

Install dependencies

npm install

Build

npm run build

Run unit tests, linter and autoformatter

npm run test
npm run lint
npm run format

Run the frontend locally

You can directly serve the frontend without building it first:

npm run serve

Then open http://localhost:5173 in your browser and login.

Run integration tests

Integration tests make live, rate-limited requests to Last.fm and MusicBrainz, so they are not included in npm run test.

LASTFM_API_KEY=your_api_key_here npm run test:integration

Deploy to AWS

To deploy the backend AWS infra resources and the backend Lambda code:

npm run deploy:backend

To deploy the frontend hosting infra:

npm run deploy:frontend

To upload the static frontend assets to the CDN:

npm run deploy:assets