https://github.com/quentingenet/vinylkeeper
When music and code spin together, cool happens.
https://github.com/quentingenet/vinylkeeper
alembic fastapi material-ui postgresql pydantic python react sqlalchemy typescript
Last synced: 5 months ago
JSON representation
When music and code spin together, cool happens.
- Host: GitHub
- URL: https://github.com/quentingenet/vinylkeeper
- Owner: quentingenet
- License: gpl-3.0
- Created: 2024-08-03T07:35:25.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-13T07:21:54.000Z (5 months ago)
- Last Synced: 2026-01-13T10:32:19.821Z (5 months ago)
- Topics: alembic, fastapi, material-ui, postgresql, pydantic, python, react, sqlalchemy, typescript
- Language: Python
- Homepage: https://vinylkeeper.org
- Size: 8.83 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vinyl Keeper
**VinylKeeper** is a free and open-source application released under the Copyleft license.
This is your go-to solution to effortlessly manage your vinyl collection, while fully respecting your privacy and data ownership.
[VinylKeeper.org](https://vinylkeeper.org/)
## Features and Upcoming / In Progress
📊 **Dashboard**
Get a quick overview of your collection with insightful stats: genres, decades, top artists, and more.
📀 **Collections**
Browse and manage your vinyl records, organized to your preferences.
➕ **Add Vinyls**
Add new vinyls manually or search via Deezer integration.
🔍 **Explore**
Discover artists and albums using a powerful search connected to the Deezer API.
🎯 **Suggestions**
Smart recommendations based on your library and listening habits.
💖 **Wishlist**
Keep track of the vinyls you’d love to add to your collection someday.
🔄 **Loans**
Manage borrowed vinyls—know what you lent, to whom, and when.
⚙️ **Settings**
Customize your profile, preferences, and account options.
🌍 **Interactive map**
Discover & share vinyl places around the world with the community.
👥 **Community**
See other users' collections, follow vinyl lovers, share discoveries and messages.
🔐 **Secure Authentication**
JWT-based login, with refresh token handling via secure HTTPOnly cookies.
📱 **Responsive & PWA-ready**
Fully responsive UI, optimized for desktop and mobile, with Capacitor support for Progressive Web App deployment.
🛠️ **Modern Architecture**
React + TypeScript frontend (Vite), FastAPI backend (Python), PostgreSQL database.
## Technologies
**VinylKeeper** is developed using:
- **[Python](https://www.python.org/)** with **[FastAPI](https://fastapi.tiangolo.com/)** for the main API.
- **[React](https://reactjs.org)** and **[TypeScript](https://www.typescriptlang.org/)** with **[Vite.js](https://vitejs.dev/)** for the frontend
- **[PostgreSQL](https://www.postgresql.org/)** for the database
## How to run the project? (API Python & FastAPI)
### Prerequisites
Ensure the following are installed on your machine:
- [Node.js](https://nodejs.org/)
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
- [Vite.js](https://vitejs.dev/)
- [Python](https://www.python.org/)
- [FastAPI](https://fastapi.tiangolo.com/)
- [Poetry](https://python-poetry.org/)
- [Docker and Docker compose](https://docs.docker.com/)
### Clone the repository
```bash
git clone https://github.com/quentingenet/vinylkeeper.git
```
**⚠️ Don't forget to create your own `.env.development` file using the provided `.env.template.contributors` as a reference.**
### Backend Setup
Navigate to the backend folder, install dependencies, and run migrations:
```bash
cd vinylkeeper/vinylkeeper_back
poetry install
# Run database migrations
poetry run alembic upgrade head
# Start the server
poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
The backend server runs at **http://localhost:8000**
- API documentation: **http://localhost:8000/docs**
- Alternative docs: **http://localhost:8000/redoc**
### Frontend Setup
In a separate terminal, navigate to the frontend folder, install dependencies, and start the server:
```bash
cd vinylkeeper/vinylkeeper_front
npm install
npm run dev
```
Visit **http://localhost:5173** in your browser to access the VinylKeeper application.
## How to contribute?
We welcome contributions to improve Vinyl Keeper! To contribute:
1. Fork this repository.
2. Create a feature branch **from develop** (`git checkout -b feat/amazing-feature`).
3. Commit your changes (`git commit -m 'Add some amazing feature'`).
4. Push to the branch (`git push origin feat/amazing-feature`).
5. Open a Pull Request.
The project promotes the four essential freedoms:
1. Freedom to use the software.
2. Freedom to modify the software.
3. Freedom to share the software.
4. Freedom to share your modifications.
## Author and contributors
- Quentin GENET
- If you love vinyl, music, and web development, and are motivated to contribute seriously — we'd love to hear from you! 😄🚀