{"id":31144098,"url":"https://github.com/ravensakurai/harmonics-api","last_synced_at":"2025-12-30T21:22:39.422Z","repository":{"id":311343831,"uuid":"1027294431","full_name":"ryansakurai/harmonics-api","owner":"ryansakurai","description":"API for a music catalog with social media and recommendation features.","archived":false,"fork":false,"pushed_at":"2025-09-03T23:25:34.000Z","size":7382,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T01:17:55.196Z","etag":null,"topics":["flask","mongodb","neo4j","python","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryansakurai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T18:10:09.000Z","updated_at":"2025-08-30T16:15:59.000Z","dependencies_parsed_at":"2025-08-24T09:29:41.126Z","dependency_job_id":"d65347d3-277f-4937-9cff-fe35effb5fba","html_url":"https://github.com/ryansakurai/harmonics-api","commit_stats":null,"previous_names":["ryansakurai/music-catalog-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ryansakurai/harmonics-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansakurai%2Fharmonics-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansakurai%2Fharmonics-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansakurai%2Fharmonics-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansakurai%2Fharmonics-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryansakurai","download_url":"https://codeload.github.com/ryansakurai/harmonics-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansakurai%2Fharmonics-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275781222,"owners_count":25527351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","mongodb","neo4j","python","rest-api"],"created_at":"2025-09-18T14:11:39.535Z","updated_at":"2025-12-30T21:22:39.376Z","avatar_url":"https://github.com/ryansakurai.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎧 Harmonics API 🎧\n\nAPI for a music catalog with social media and recommendation features.\n\n### Table of Contents\n\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Project Structure](#project-structure)\n- [Installation](#installation)\n- [API Endpoints](#api-endpoints)\n    - [Artists](#artists)\n    - [Releases](#releases)\n    - [Users](#users)\n    - [Recommendations](#recommendations)\n- [Databases](#databases)\n    - [MongoDB Schemas](#mongodb-schemas)\n    - [Neo4j Schemas](#neo4j-schemas)\n    - [Data Population](#data-population)\n- [Authors](#authors)\n\n## Features\n\n- **Music Catalog**: Browse artist and release information\n- **User Management**: Register users, manage profiles and view social overview\n- **Social Features**: Connect with friends, follow artists and rate releases\n- **Recommendation Engine**: Get artist, release and friend suggestions based on user data\n\n## Tech Stack\n\n- **Language**: Python\n- **Backend**: Flask\n- **Databases**: \n    - MongoDB\n    - Neo4j\n\n## Project Structure\n\n```\nharmonics-api/\n├── src/harmonics_api/         # API source code\n│   ├── main.py                # Flask application entry point\n│   ├── configs/               # Database connections and errors\n│   ├── routes/                # API endpoints\n│   │   ├── artists.py         # Artist-related endpoints\n│   │   ├── releases.py        # Release-related endpoints\n│   │   ├── users.py           # User-related endpoints\n│   │   └── recs.py            # Recommendation endpoints\n│   └── utils/                 # Utility functions\n├── data/                      # Database dumps\n└── scripts/                   # Data population scripts\n```\n\n## Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/ryansakurai/harmonics-api.git\n   cd harmonics-api\n   ```\n\n2. **Install the package**:\n   ```bash\n   pip install -e .\n   ```\n\n3. **Install population dependencies** (optional, for data generation):\n\n   ```bash\n   pip install -e .[population]\n   ```\n\n4. **Set up environment variables**:\n\n   Create a `.env` file in the root directory:\n\n   ```env\n   MONGODB_URI=your_mongodb_connection_string\n   NEO4J_USERNAME=your_neo4j_username\n   NEO4J_PASSWORD=your_neo4j_password\n\n   # Population-specific\n   SPOTIFY_CLIENT_ID=your_spotify_client_id\n   SPOTIFY_CLIENT_SECRET=your_spotify_client_secret\n   GEMINI_API_KEY=your_gemini_api_key\n   ```\n\n5. **Running the API**:\n\n```bash\nharmonics-api\n```\n\n## API Endpoints\n\n### Artists\n\n- `GET /v1/artists/\u003cartist_id\u003e` - Get artist details\n- `GET /v1/artists/\u003cartist_id\u003e/tracks` - Get artist tracks\n\n### Releases\n\n- `GET /v1/releases/\u003crelease_id\u003e` - Get release details\n- `GET /v1/releases/\u003crelease_id\u003e/ratings` - Get all ratings for a release\n\n### Users\n\n- `GET /v1/users/\u003cusername\u003e` - Get user profile\n- `POST /v1/users/` - Register a new user\n- `PATCH /v1/users/\u003cusername\u003e` - Update user data\n- `DELETE /v1/users/\u003cusername\u003e` - Delete user account\n- `GET /v1/users/\u003cusername\u003e/friends` - Get user's friends\n- `POST /v1/users/\u003cusername\u003e/friends` - Add a friend\n- `DELETE /v1/users/\u003cusername\u003e/friends/\u003cfriend_username\u003e` - Remove a friend\n- `GET /v1/users/\u003cusername\u003e/ratings` - Get user's ratings\n- `POST /v1/users/\u003cusername\u003e/ratings` - Rate a release\n- `DELETE /v1/users/\u003cusername\u003e/ratings/\u003crelease_id\u003e` - Remove a rating\n- `GET /v1/users/\u003cusername\u003e/follows` - Get artists followed by user\n- `POST /v1/users/\u003cusername\u003e/follows` - Follow an artist\n- `DELETE /v1/users/\u003cusername\u003e/follows/\u003cartist_id\u003e` - Unfollow an artist\n\n### Recommendations\n\n- `GET /v1/recs/\u003cusername\u003e/artists` - Get artist recommendations by genre\n- `GET /v1/recs/\u003cusername\u003e/releases` - Get release recommendations by friends' reviews\n- `GET /v1/recs/\u003cusername\u003e/friends?by=\u003cmethod\u003e` - Get friend recommendations (method: \"genre\" or \"reviews\")\n\n## Databases\n\n### MongoDB Schemas\n\n**Artists**:\n\n```json\n{\n  \"_id\": \"string\",\n  \"name\": \"string\",\n  \"genres\": [\"string\"],\n  \"bio\": \"string\",\n  \"qt_followers\": \"int32\",\n  \"releases\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"release_date\": \"string\",\n      \"tracks\": [\n        {\n          \"track_number\": \"number\",\n          \"name\": \"string\",\n          \"duration\": \"int32\"\n        }\n      ],\n      \"ratings\": [\n        {\n          \"username\": \"string\",\n          \"rating\": \"int32\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n**Users**:\n\n```json\n{\n  \"_id\": \"objectid\",\n  \"username\": \"string\",\n  \"password\": \"string\",\n  \"name\": \"string?\",\n  \"bio\": \"string?\",\n  \"friends\": [\"string\"],\n  \"ratings\": [\n    {\n      \"id\": \"string\",\n      \"artist\": \"string\",\n      \"name\": \"string\",\n      \"rating\": \"int32\"\n    }\n  ],\n  \"follows\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\"\n    }\n  ]\n}\n```\n\n### Neo4j Schemas\n\n- **Nodes**:\n    - `User { \"username\": \"String\" }`\n    - `Artist { \"id\": \"String\", \"popularity\": \"Integer\" }`\n    - `Genre { \"name\": \"String\" }`\n    - `Release { \"id\": \"String\" }`\n- **Relationships**: \n    - `User -[:FOLLOWS]-\u003e Artist`\n    - `User -[:RATED {\"rating\": \"Integer\"}]-\u003e Release`\n    - `User -[:FRIENDS_WITH]-\u003e User`\n    - `Artist -[:BELONGS_TO]-\u003e Genre`\n    - `Artist -[:RELEASED]-\u003e Release`\n\n### Data Population\n\nThe project includes a data population script at [scripts/population.ipynb](scripts/population.ipynb).\n\n## Authors\n\n- [Caike dos Santos](https://github.com/CaikeSantos)\n- [Ryan Sakurai](https://github.com/ryansakurai)\n- [Vinicius Castro](https://github.com/vinciuscastro)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravensakurai%2Fharmonics-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravensakurai%2Fharmonics-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravensakurai%2Fharmonics-api/lists"}