Users Microservice

A comprehensive microservice for managing user authentication, profiles, and social interactions in the Melodia music streaming platform.

Table of Contents

• Overview
• Getting Started
• Development Workflow
• Project Structure

Overview

The Users Microservice is a Python-based service that handles all user-related operations for the Melodia platform. Built with FastAPI, SQLAlchemy, and PostgreSQL, it provides a robust and scalable solution for managing:

• Authentication: User registration, login, and JWT-based authentication
• User Profiles: Profile management with avatar support and customization
• Social Features: Follow system, user search, and social interactions
• Password Management: Forgot password and reset password flows with email notifications
• Admin Tools: User management, status control, and administrative operations
• Integration: Coordination with artist service for artist account management

Key Features

• Complete user authentication and authorization
• Profile management with AWS S3 integration for avatars
• Follow/unfollow system for user interactions
• Advanced user search functionality
• Email service for password recovery
• Comprehensive API documentation (OpenAPI/Swagger)
• High test coverage with pytest
• Automatic database migrations with Alembic

Getting Started

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Docker and Docker Compose - Download
• Git - Download

1. Clone the Repository

git clone https://github.com/MelodiApp/users-microservice.git
cd users-microservice

2. Environment Setup

Copy the example environment file and configure your environment variables:

cp .env.example .env

Edit the .env file with your configuration. Key variables to review:

• Email Configuration: Set EMAIL_USER and EMAIL_PASSWORD for password recovery features

3. Setup Docker Network

The microservice uses a shared Docker network to communicate with other services:

docker network create melodiapp-net

4. Start Development Environment

Start the application and database using Docker Compose:

docker compose up --build -d

The application will be available at http://localhost:8092

Note: The entrypoint.sh script automatically applies pending migrations when the container starts. You don't need to run migrations manually on startup.

5. Verify Installation

Once the services are running, you can verify the installation:

# Check if the API is responding
curl http://localhost:8092/health

# Or open the interactive API documentation in your browser
open http://localhost:8092/docs

Development Workflow

Running the Application

The service is configured with hot-reload enabled. Any code changes will automatically restart the server:

# Start the development environment
docker compose up -d

# View logs in real-time
docker compose logs -f users-microservice

# Stop the services
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v

Working with Database Schema

When Pulling Changes from Git

If a teammate has added new migrations, simply restart the container. Migrations are applied automatically on startup:

docker compose restart users-microservice

When YOU Modify the Schema Locally

If you make changes to app/models.py, follow these steps:

1. Create a new migration with a descriptive name:

   docker compose exec users-microservice python -m alembic revision --autogenerate -m "add_user_status_field"
   
   # Example names:
   # -m "add_user_bio_field"
   # -m "create_followers_table"
   # -m "update_user_relationships"

2. Review the generated migration in the alembic/versions/ directory to ensure it's correct.

3. The migration is automatically applied on the next container restart, or you can apply it manually:

   docker compose exec users-microservice python -m alembic upgrade head

Resolving Migration Conflicts

If you encounter multiple heads in migrations after pulling changes:

# Create a merge migration (replace IDs with your specific ones)
docker compose exec users-microservice python -m alembic merge -m "merge branches" <head1_id> <head2_id>

# Apply the merge migration
docker compose exec users-microservice python -m alembic upgrade head

File Storage

The microservice uses AWS S3 for storing user avatars. Configure your S3 credentials in the .env file, or use LocalStack for local development.

For LocalStack setup, refer to the LocalStack repository.

Code Quality

# Format code with Ruff
docker compose exec users-microservice ruff format .

# Check code with Ruff
docker compose exec users-microservice ruff check .

# Auto-fix linting issues
docker compose exec users-microservice ruff check . --fix

Testing

# Run all tests
docker compose exec users-microservice pytest

# Run tests with coverage
docker compose exec users-microservice pytest --cov=app --cov-report=term-missing

# Run specific test files
docker compose exec users-microservice pytest tests/test_auth.py

# Access container shell for debugging
docker compose exec users-microservice bash

Project Structure

.
├── .env.example           # Environment variables template
├── .gitignore             # Git ignore rules
├── docker-compose.yml     # Docker services configuration
├── Dockerfile             # Docker image build instructions
├── entrypoint.sh          # Container startup script (applies migrations)
├── requirements.txt       # Python dependencies
├── requirements-dev.txt   # Development dependencies
├── alembic.ini            # Alembic configuration
├── migrate.py             # Migration utility script
├── seed.py                # Database seeding script
├── pyproject.toml         # Project configuration (Ruff, coverage)
├── README.md              # This file
│
├── alembic/
│   ├── env.py             # Alembic environment configuration
│   └── versions/          # Migration history (auto-generated)
│
└── app/
    ├── __init__.py
    ├── main.py            # FastAPI application entry point
    ├── db.py              # Database session management
    ├── models.py          # SQLAlchemy database models
    ├── schemas.py         # Pydantic schemas for validation
    ├── dependencies.py    # Dependency injection utilities
    ├── exceptions.py      # Custom exception definitions
    ├── exceptions_handlers.py  # Exception handlers
    ├── initial_data.py    # Initial data setup
    ├── logger.py          # Logging configuration
    │
    ├── core/              # Core utilities
    │   ├── config.py      # Configuration management
    │   ├── security.py    # Password hashing
    │   ├── jwt.py         # JWT token management
    │   └── aws_client.py  # AWS S3 client
    │
    ├── crud/              # Database operations
    │   ├── base.py
    │   ├── users.py
    │   └── follow.py
    │
    ├── routers/           # API endpoints
    │   ├── auth.py        # Authentication endpoints
    │   ├── users.py       # User management endpoints
    │   ├── admin.py       # Admin endpoints
    │   ├── follow.py      # Follow system endpoints
    │   └── search.py      # Search endpoints
    │
    ├── services/          # Business logic
    │   └── artist_service.py
    │
    ├── utils/             # Utilities
    │   └── mail_service/  # Email service
    │
    └── tests/             # Test files
        ├── conftest.py
        ├── test_auth.py
        ├── test_users.py
        ├── test_admin.py
        ├── test_follow.py
        └── test_search.py

License

This project is part of the Melodia platform.

Team

MelodiApp Development Team

Name	Last Name	Email
Ian	von der Heyde	ivon@fi.uba.ar
Valentin	Schneider	vschneider@fi.uba.ar
Daniela	Ojeda	dojeda@fi.uba.ar
Alan	Cantero	acantero@fi.uba.ar
Ezequiel	Lazarte	ezlazarte@fi.uba.ar

Related Services

• Mobile Frontend - Melodia mobile application
• Web Frontend - Melodia backoffice application
• API Gateway - Centralized API routing and authentication
• Artists Service - Manages artists, songs, and albums
• Libraries Service - Manages user playlists and saved content
• Metrics Service - Handles play counts and analytics
• Notifications Service - Sends notifications for new releases
• LocalStack - Local AWS cloud stack for development